[FFmpeg-devel] [PATCH] RTSP-MS 10/15: ASF header parsing

[Ronald S. Bultje]

Hi,

On Wed, Feb 4, 2009 at 9:01 AM, Ronald S. Bultje <rsbultje at gmail.com> wrote:
[..]

Updated add-comments.patch after move-transport.patch.

Ronald
-------------- next part --------------
Index: ffmpeg-svn/libavformat/rtsp.h
===================================================================
--- ffmpeg-svn.orig/libavformat/rtsp.h	2009-02-04 09:05:21.000000000 -0500
+++ ffmpeg-svn/libavformat/rtsp.h	2009-02-04 09:06:31.000000000 -0500
@@ -38,8 +38,11 @@
 };
 
 enum RTSPTransport {
-    RTSP_TRANSPORT_RTP,
-    RTSP_TRANSPORT_RDT,
+    RTSP_TRANSPORT_RTP, /**< Standards-compliant RTP */
+    RTSP_TRANSPORT_RDT, /**< Realmedia Data Transport */
+    /**
+     * This is not part of the public API and shouldn't be used outside ffmpeg.
+     */
     RTSP_TRANSPORT_LAST
 };
 
@@ -51,6 +54,10 @@
 #define RTSP_RTP_PORT_MIN 5000
 #define RTSP_RTP_PORT_MAX 10000
 
+/**
+ * This describes the Transport: line of a single stream as negotiated
+ * by the SETUP RTSP command.
+ */
 typedef struct RTSPTransportField {
     int interleaved_min, interleaved_max;  /**< interleave ids, if TCP transport */
     int port_min, port_max; /**< RTP ports */
@@ -58,10 +65,13 @@
     int server_port_min, server_port_max; /**< RTP ports */
     int ttl; /**< ttl value */
     uint32_t destination; /**< destination IP address */
-    enum RTSPTransport transport;
-    enum RTSPLowerTransport lower_transport;
+    enum RTSPTransport transport;            /**< RTP or RDT (Real) */
+    enum RTSPLowerTransport lower_transport; /**< TCP/UDP uni-/multicast */
 } RTSPTransportField;
 
+/**
+ * This describes the server response to each RTSP command.
+ */
 typedef struct RTSPHeader {
     int content_length;
     enum RTSPStatusCode status_code; /**< response code from server */
@@ -70,9 +80,11 @@
     int64_t range_start, range_end;
     RTSPTransportField transports[RTSP_MAX_TRANSPORTS];
     int seq; /**< sequence number */
-    char session_id[512];
+    char session_id[512];            /**< The Session field, value is set
+                                      * by the server and re-transmitted by
+                                      * the client in every RTSP command. */
     char real_challenge[64]; /**< the RealChallenge1 field from the server */
-    char server[64];
+    char server[64];                 /**< the Server field, to identify WMS */
 } RTSPHeader;
 
 enum RTSPClientState {
@@ -81,6 +93,10 @@
     RTSP_STATE_PAUSED,
 };
 
+/**
+ * Identifies particular servers that require special handling, such as
+ * standards-incompliant Transport: lines in the SETUP request.
+ */
 enum RTSPServerType {
     RTSP_SERVER_RTP,  /**< Standards-compliant RTP-server */
     RTSP_SERVER_REAL, /**< Realmedia-style server */
@@ -88,28 +104,44 @@
     RTSP_SERVER_LAST
 };
 
+/**
+ * Private data for the RTSP demuxer.
+ */
 typedef struct RTSPState {
     URLContext *rtsp_hd; /* RTSP TCP connexion handle */
     int nb_rtsp_streams;
-    struct RTSPStream **rtsp_streams;
+    struct RTSPStream **rtsp_streams; /**< streams in this session */
 
-    enum RTSPClientState state;
-    int64_t seek_timestamp;
+    enum RTSPClientState state;       /**< whether we are currently receiving
+                                       * data or not from the server */
+    int64_t seek_timestamp;           /**< the seek value requested when
+                                       * calling av_seek_frame(). This way,
+                                       * the seek value is saved if we are
+                                       * currently paused, and it can be
+                                       * transmitted at the next PLAY.
+                                       * See rtsp_read_play(). */
 
     /* XXX: currently we use unbuffered input */
     //    ByteIOContext rtsp_gb;
     int seq;        /* RTSP command sequence number */
-    char session_id[512];
-    enum RTSPTransport transport;
-    enum RTSPLowerTransport lower_transport;
-    enum RTSPServerType server_type;
+    char session_id[512];             /**< same as RTSPHeader->session_id */
+    enum RTSPTransport transport;     /**< RTP or RDT */
+    enum RTSPLowerTransport lower_transport; /**< TCP/UDP uni-/multicast */
+    enum RTSPServerType server_type;  /**< brand of server (WMS/REAL/other) */
     char last_reply[2048]; /* XXX: allocate ? */
-    void *cur_tx;
+    void *cur_tx;                     /**< RTSPStream->tx_ctx of the last
+                                       * stream that we read a packet from. */
     int need_subscription;
     enum AVDiscard real_setup_cache[MAX_STREAMS];
     char last_subscription[1024];
 } RTSPState;
 
+/**
+ * Describes a single stream, as identified by a single m= line block in the
+ * SDP content. In the case of RDT, one RTSPStream can represent multiple
+ * AVStreams. In this case, each AVStream in this set has similar content
+ * (but different codec/bitrate).
+ */
 typedef struct RTSPStream {
     URLContext *rtp_handle; /* RTP stream handle */
     void *tx_ctx; /* RTP/RDT parse context */