[FFmpeg-devel] [PATCH] document rtsp.h

[Michael Niedermayer]

On Thu, Feb 05, 2009 at 09:24:21AM -0500, Ronald S. Bultje wrote:
> Hi,
> 
> new thread, otherwise the subject line doesn't make any sense.
> Attached patch fully (I think) documents rtsp.h. The changes are sort
> of, ehm, well, everywhere, so I basically just didn't bother too much
> to distinguish "move comment to new line" or "align comment /
> whitespace" or "add new comment" in separate patches, because in the
> end I pretty much touch every single line out there anyway. I didn't
> add any newlines between commented items:
> 

> /** bla */
> int var1;
>   <- there is no newline here, although AVCodecContext does have that
> /** bla2 */
> char var2;
> 
> I can add more newlines if you think it's unreadable this way, but

please do


> regardless, I think this is better than what it was.
> 
> Ronald

> Index: ffmpeg-svn/libavformat/rtsp.h
> ===================================================================
> --- ffmpeg-svn.orig/libavformat/rtsp.h	2009-02-05 09:10:30.000000000 -0500
> +++ ffmpeg-svn/libavformat/rtsp.h	2009-02-05 09:18:10.000000000 -0500
> @@ -27,19 +27,30 @@
>  #include "rtp.h"
>  #include "network.h"
>  
> +/**
> + * Network layer over which RTP packet data will be transported.
> + */
>  enum RTSPLowerTransport {

only RTP? not also RDT, ...



> -    RTSP_LOWER_TRANSPORT_UDP = 0,
> -    RTSP_LOWER_TRANSPORT_TCP = 1,
> -    RTSP_LOWER_TRANSPORT_UDP_MULTICAST = 2,
> +    RTSP_LOWER_TRANSPORT_UDP = 0,           /**< UDP/unicast */
> +    RTSP_LOWER_TRANSPORT_TCP = 1,           /**< TCP; interleaved in RTSP */
> +    RTSP_LOWER_TRANSPORT_UDP_MULTICAST = 2, /**< UDP/multicast */
>      /**
>       * This is not part of public API and shouldn't be used outside of ffmpeg.
>       */

>      RTSP_LOWER_TRANSPORT_LAST

this is still a poor name
RTSP_LOWER_TRANSPORT_NB or _COUNT seems better


>  };
>  
> +/**
> + * Packet protocol

is this a standard term? or self invented?


> of the data that we will be receiving. Real servers
> + * commonly send RDT (although they can sometimes send RTP as well),
> + * whereas most others will send RTP.
> + */
>  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

this stateent makes it look like the rest is part of the public API, is
it so?


[...]
> +    /** UDP multicast port range; the ports to which we should connect to
> +     * receive multicast UDP data. */
> +    int port_min, port_max;

shouldnt the words "udp" and "multi" occur in the names?


> +    /** UDP client ports; these should be the local ports of the UDP RTP
> +     * (and RTCP) sockets over which we receive RTP/RTCP data. */
> +    int client_port_min, client_port_max;

what about TCP?


> +    /** UDP unicast server port range; the ports to which we should connect
> +     * to receive unicast UDP RTP/RTCP data. */
> +    int server_port_min, server_port_max;
> +    /** time-to-live value (required for multicast); the amount of HOPs that
> +     * packets will be allowed to make before being discarded. */
> +    int ttl;
>      uint32_t destination; /**< destination IP address */
> +    /** data/packet transport protocol; e.g. RTP or RDT */
>      enum RTSPTransport transport;
> +    /** network layer transport protocol; e.g. TCP or UDP uni-/multicast */
>      enum RTSPLowerTransport lower_transport;
>  } RTSPTransportField;
>  

> +/**
> + * This describes the server response to each RTSP command.
> + */

>  typedef struct RTSPHeader {

poor name ...


> +    /** length of the data following this header */
>      int content_length;

>      enum RTSPStatusCode status_code; /**< response code from server */

server_response?


[...]
> +    /**< the "RealChallenge1:" field from the server */
> +    char real_challenge[64];

/**< ?


> +    /** the "Server: field, which can be used to identify some special-case
> +     * servers that are not 100% standards-compliant. We use this to identify
> +     * Windows Media Server, which has a value "WMServer/v.e.r.sion", where
> +     * version is a sequence of digits (e.g. 9.0.0.3372). Helix/Real servers
> +     * use something like "Helix [..] Server Version v.e.r.sion (platform)
> +     * (RealServer compatible)" or "RealServer Version v.e.r.sion (platform)",
> +     * where platform is the output of $uname -msr | sed 's/ /-/g'. */
>      char server[64];
>  } RTSPHeader;
>  
> +/**
> + * Client state, i.e. whether we are currently streaming data (PLAYING) or
> + * setup-but-not-streaming (PAUSED). State can be changed in applications
> + * by calling av_read_play/pause().
> + */
>  enum RTSPClientState {
> -    RTSP_STATE_IDLE,
> -    RTSP_STATE_PLAYING,
> -    RTSP_STATE_PAUSED,
> +    RTSP_STATE_IDLE,    /**< not initialized */

> +    RTSP_STATE_PLAYING, /**< initialized and streaming data */
> +    RTSP_STATE_PAUSED,  /**< initialized, but not streaming data */

s/streaming/receiving/ ?


>  };
>  
> +/**
> + * Identifies particular servers that require special handling, such as

> + * standards-incompliant Transport: lines in the SETUP request.

"Transport:"


> + */
>  enum RTSPServerType {
>      RTSP_SERVER_RTP,  /**< Standards-compliant RTP-server */
>      RTSP_SERVER_REAL, /**< Realmedia-style server */
>      RTSP_SERVER_WMS,  /**< Windows Media server */

> +    /**
> +     * This is not part of the public API and shouldn't be used outside ffmpeg.
> +     */
>      RTSP_SERVER_LAST

same issues


[...]
> +    /** whether we are currently receiving data from the server */
>      enum RTSPClientState state;

what is state?
whether we are currently receiving data from the server

didnt work out

[...]
> +    /** The following are used for dynamic/private protocols (payloads) */
> +    //@{
> +    /** handler structure */
> +    RTPDynamicProtocolHandler *dynamic_handler;
> +    /** private data associated with the dynamic protocol */
> +    PayloadContext *dynamic_protocol_context;
> +    //@}

whats a dynamic/private protocol ?

[...]
-- 
Michael     GnuPG fingerprint: 9FF2128B147EF6730BADF133611EC787040B0FAB

Breaking DRM is a little like attempting to break through a door even
though the window is wide open and the only thing in the house is a bunch
of things you dont want and which you would get tomorrow for free anyway
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
URL: <http://lists.mplayerhq.hu/pipermail/ffmpeg-devel/attachments/20090205/5af8ce64/attachment.pgp>