Fix some more RTSP docs.

Original commit message from CVS:
* docs/libs/gst-plugins-base-libs-sections.txt:
* gst-libs/gst/rtsp/gstrtspdefs.h:
* gst-libs/gst/rtsp/gstrtspmessage.c: (key_value_foreach),
(gst_rtsp_message_get_type), (gst_rtsp_message_parse_request),
(gst_rtsp_message_init_response),
(gst_rtsp_message_parse_response), (gst_rtsp_message_new_data),
(gst_rtsp_message_parse_data), (gst_rtsp_message_add_header),
(gst_rtsp_message_remove_header), (gst_rtsp_message_get_header),
(gst_rtsp_message_append_headers), (gst_rtsp_message_set_body),
(gst_rtsp_message_get_body), (dump_key_value):
* gst-libs/gst/rtsp/gstrtspmessage.h:
* gst-libs/gst/rtsp/gstrtsprange.c: (parse_npt_time),
(parse_npt_range), (parse_clock_range), (parse_smpte_range),
(gst_rtsp_range_parse):
* gst-libs/gst/rtsp/gstrtsprange.h:
* gst-libs/gst/rtsp/gstrtsptransport.c:
* gst-libs/gst/rtsp/gstrtspurl.c:
Fix some more RTSP docs.
Add some missing methods for dealing with messages.

ChangeLog

@@ -1,3 +1,25 @@
+2007-07-25  Wim Taymans  <wim.taymans@gmail.com>
+
+	* docs/libs/gst-plugins-base-libs-sections.txt:
+	* gst-libs/gst/rtsp/gstrtspdefs.h:
+	* gst-libs/gst/rtsp/gstrtspmessage.c: (key_value_foreach),
+	(gst_rtsp_message_get_type), (gst_rtsp_message_parse_request),
+	(gst_rtsp_message_init_response),
+	(gst_rtsp_message_parse_response), (gst_rtsp_message_new_data),
+	(gst_rtsp_message_parse_data), (gst_rtsp_message_add_header),
+	(gst_rtsp_message_remove_header), (gst_rtsp_message_get_header),
+	(gst_rtsp_message_append_headers), (gst_rtsp_message_set_body),
+	(gst_rtsp_message_get_body), (dump_key_value):
+	* gst-libs/gst/rtsp/gstrtspmessage.h:
+	* gst-libs/gst/rtsp/gstrtsprange.c: (parse_npt_time),
+	(parse_npt_range), (parse_clock_range), (parse_smpte_range),
+	(gst_rtsp_range_parse):
+	* gst-libs/gst/rtsp/gstrtsprange.h:
+	* gst-libs/gst/rtsp/gstrtsptransport.c:
+	* gst-libs/gst/rtsp/gstrtspurl.c:
+	Fix some more RTSP docs.
+	Add some missing methods for dealing with messages.
+
 2007-07-24  Wim Taymans  <wim.taymans@gmail.com>
 
 	* docs/libs/gst-plugins-base-libs-docs.sgml:

docs/libs/gst-plugins-base-libs-sections.txt

@@ -1031,15 +1031,21 @@ gst_rtsp_connection_set_auth
 <FILE>gstrtspmessage</FILE>
 <INCLUDE>gst/rtsp/gstrtspmessage.h</INCLUDE>
 GstRTSPMsgType
+GstRTSPMessage
 gst_rtsp_message_new
 gst_rtsp_message_init
-gst_rtsp_message_new_request
-gst_rtsp_message_init_request
-gst_rtsp_message_new_response
-gst_rtsp_message_init_response
-gst_rtsp_message_init_data
 gst_rtsp_message_unset
 gst_rtsp_message_free
+gst_rtsp_message_get_type
+gst_rtsp_message_new_request
+gst_rtsp_message_init_request
+gst_rtsp_message_parse_request
+gst_rtsp_message_new_response
+gst_rtsp_message_init_response
+gst_rtsp_message_parse_response
+gst_rtsp_message_new_data
+gst_rtsp_message_init_data
+gst_rtsp_message_parse_data
 gst_rtsp_message_add_header
 gst_rtsp_message_remove_header
 gst_rtsp_message_get_header

gst-libs/gst/rtsp/gstrtspdefs.h

@@ -61,6 +61,27 @@ G_STMT_START { \
     goto label; \
 } G_STMT_END
 
+/**
+ * GstRTSPResult:
+ * @GST_RTSP_OK: no error
+ * @GST_RTSP_ERROR: some unspecified error occured
+ * @GST_RTSP_EINVAL: invalid arguments were provided to a function
+ * @GST_RTSP_EINTR: an operation was canceled
+ * @GST_RTSP_ENOMEM: no memory was available for the operation
+ * @GST_RTSP_ERESOLV: a host resolve error occured
+ * @GST_RTSP_ENOTIMPL: function not implemented
+ * @GST_RTSP_ESYS: a system error occured, errno contains more details
+ * @GST_RTSP_EPARSE: a persing error occured
+ * @GST_RTSP_EWSASTART: windows networking could not start
+ * @GST_RTSP_EWSAVERSION: windows networking stack has wrong version
+ * @GST_RTSP_EEOF: end-of-file was reached
+ * @GST_RTSP_ENET: a network problem occured, h_errno contains more details
+ * @GST_RTSP_ENOTIP: the host is not an IP host
+ * @GST_RTSP_ETIMEOUT: a timeout occured
+ * @GST_RTSP_ELAST: last error
+ *
+ * Result codes from the RTSP functions.
+ */
 typedef enum {
   GST_RTSP_OK          =  0,
   /* errors */
@@ -82,12 +103,31 @@ typedef enum {
   GST_RTSP_ELAST       = -15,
 } GstRTSPResult;
 
+/**
+ * GstRTSPFamily:
+ * @GST_RTSP_FAM_NONE: unknown network family
+ * @GST_RTSP_FAM_INET: internet
+ * @GST_RTSP_FAM_INET6: internet V6
+ *
+ * The possible network families.
+ */
 typedef enum {
   GST_RTSP_FAM_NONE,
   GST_RTSP_FAM_INET,
   GST_RTSP_FAM_INET6,
 } GstRTSPFamily;
 
+/**
+ * GstRTSPState:
+ * @GST_RTSP_STATE_INVALID: invalid state
+ * @GST_RTSP_STATE_INIT: initializing
+ * @GST_RTSP_STATE_READY: ready for operation
+ * @GST_RTSP_STATE_SEEKING: seeking in progress
+ * @GST_RTSP_STATE_PLAYING: playing
+ * @GST_RTSP_STATE_RECORDING: recording
+ *
+ * The different RTSP states.
+ */
 typedef enum {
   GST_RTSP_STATE_INVALID,
   GST_RTSP_STATE_INIT,
@@ -97,11 +137,35 @@ typedef enum {
   GST_RTSP_STATE_RECORDING,
 } GstRTSPState;
 
+/**
+ * GstRTSPVersion:
+ * @GST_RTSP_VERSION_INVALID: unknown/invalid version
+ * @GST_RTSP_VERSION_1_0: version 1.0
+ *
+ * The supported RTSP versions.
+ */
 typedef enum {
   GST_RTSP_VERSION_INVALID = 0x00,
   GST_RTSP_VERSION_1_0     = 0x10,
 } GstRTSPVersion;
 
+/**
+ * GstRTSPMethod:
+ * @GST_RTSP_INVALID: invalid method
+ * @GST_RTSP_DESCRIBE: the DESCRIBE method
+ * @GST_RTSP_ANNOUNCE: the ANNOUNCE method
+ * @GST_RTSP_GET_PARAMETER: the GET_PARAMETER method
+ * @GST_RTSP_OPTIONS: the OPTIONS method
+ * @GST_RTSP_PAUSE: the PAUSE method
+ * @GST_RTSP_PLAY: the PLAY method
+ * @GST_RTSP_RECORD: the RECORD method
+ * @GST_RTSP_REDIRECT: the REDIRECT method
+ * @GST_RTSP_SETUP: the SETUP method
+ * @GST_RTSP_SET_PARAMETER: the SET_PARAMETER method
+ * @GST_RTSP_TEARDOWN: the TEARDOWN method
+ *
+ * The different supported RTSP methods. 
+ */
 typedef enum {
   GST_RTSP_INVALID          = 0,
   GST_RTSP_DESCRIBE         = (1 <<  0),
@@ -117,14 +181,25 @@ typedef enum {
   GST_RTSP_TEARDOWN         = (1 << 10),
 } GstRTSPMethod;
 
-/* Authentication methods, ordered by strength */
+/**
+ * GstRTSPAuthMethod:
+ * @GST_RTSP_AUTH_NONE: no authentication
+ * @GST_RTSP_AUTH_BASIC: basic authentication
+ * @GST_RTSP_AUTH_DIGEST: digest authentication
+ *
+ * Authentication methods, ordered by strength
+ */
 typedef enum {
   GST_RTSP_AUTH_NONE    = 0x00,
   GST_RTSP_AUTH_BASIC   = 0x01,
   GST_RTSP_AUTH_DIGEST  = 0x02
 } GstRTSPAuthMethod;
 
-/* Strongest available authentication method */
+/**
+ * GST_RTSP_AUTH_MAX:
+ *
+ * Strongest available authentication method 
+ */
 #define GST_RTSP_AUTH_MAX GST_RTSP_AUTH_DIGEST
 
 typedef enum {
@@ -190,8 +265,6 @@ typedef enum {
   GST_RTSP_HDR_MAX_ASM_WIDTH,       /* SupportsMaximumASMBandwidth */
   GST_RTSP_HDR_LANGUAGE,            /* Language */
   GST_RTSP_HDR_PLAYER_START_TIME,   /* PlayerStarttime */
-
-
 } GstRTSPHeaderField;
 
 typedef enum {

gst-libs/gst/rtsp/gstrtspmessage.c

@@ -41,6 +41,20 @@
  * SOFTWARE.
  */
 
+/**
+ * SECTION:gstrtspmessage
+ * @short_description: RTSP messages
+ * @see_also: gstrtspconnection
+ *  
+ * <refsect2>
+ * <para>
+ * Provides methods for creating and parsing request, response and data messages.
+ * </para>
+ * </refsect2>
+ *  
+ * Last reviewed on 2007-07-25 (0.10.14)
+ */
+
 #include <string.h>
 
 #include "gstrtspmessage.h"
@@ -63,6 +77,14 @@ key_value_foreach (GArray * array, GFunc func, gpointer user_data)
   }
 }
 
+/**
+ * gst_rtsp_message_new:
+ * @msg: a location for the new #GstRTSPMessage
+ *
+ * Create a new initialized #GstRTSPMessage.
+ *
+ * Returns: a #GstRTSPResult. Free with gst_rtsp_message_free().
+ */
 GstRTSPResult
 gst_rtsp_message_new (GstRTSPMessage ** msg)
 {
@@ -77,6 +99,15 @@ gst_rtsp_message_new (GstRTSPMessage ** msg)
   return gst_rtsp_message_init (newmsg);
 }
 
+/**
+ * gst_rtsp_message_init:
+ * @msg: a #GstRTSPMessage
+ *
+ * Initialize @msg. This function is mostly used when @msg is allocated on the
+ * stack. The reverse operation of this is gst_rtsp_message_unset().
+ *
+ * Returns: a #GstRTSPResult.
+ */
 GstRTSPResult
 gst_rtsp_message_init (GstRTSPMessage * msg)
 {
@@ -90,6 +121,33 @@ gst_rtsp_message_init (GstRTSPMessage * msg)
   return GST_RTSP_OK;
 }
 
+/**
+ * gst_rtsp_message_get_type:
+ * @msg: a #GstRTSPMessage
+ *
+ * Get the message type of @msg.
+ *
+ * Returns: the message type.
+ */
+GstRTSPMsgType
+gst_rtsp_message_get_type (GstRTSPMessage * msg)
+{
+  g_return_val_if_fail (msg != NULL, GST_RTSP_EINVAL);
+
+  return msg->type;
+}
+
+/**
+ * gst_rtsp_message_new_request:
+ * @msg: a location for the new #GstRTSPMessage
+ * @method: the request method to use
+ * @uri: the uri of the request
+ *
+ * Create a new #GstRTSPMessage with @method and @uri and store the result
+ * request message in @msg. 
+ *
+ * Returns: a #GstRTSPResult. Free with gst_rtsp_message_free().
+ */
 GstRTSPResult
 gst_rtsp_message_new_request (GstRTSPMessage ** msg, GstRTSPMethod method,
     const gchar * uri)
@@ -106,6 +164,17 @@ gst_rtsp_message_new_request (GstRTSPMessage ** msg, GstRTSPMethod method,
   return gst_rtsp_message_init_request (newmsg, method, uri);
 }
 
+/**
+ * gst_rtsp_message_init_request:
+ * @msg: a #GstRTSPMessage
+ * @method: the request method to use
+ * @uri: the uri of the request
+ *
+ * Initialize @msg as a request message with @method and @uri. To clear @msg
+ * again, use gst_rtsp_message_unset().
+ *
+ * Returns: a #GstRTSPResult.
+ */
 GstRTSPResult
 gst_rtsp_message_init_request (GstRTSPMessage * msg, GstRTSPMethod method,
     const gchar * uri)
@@ -124,6 +193,55 @@ gst_rtsp_message_init_request (GstRTSPMessage * msg, GstRTSPMethod method,
   return GST_RTSP_OK;
 }
 
+/**
+ * gst_rtsp_message_parse_request:
+ * @msg: a #GstRTSPMessage
+ * @method: location to hold the method
+ * @uri: location to hold the uri
+ * @version: location to hold the version
+ *
+ * Parse the request message @msg and store the values @method, @uri and
+ * @version. The result locations can be #NULL if one is not interested in its
+ * value.
+ *
+ * @uri remains valid for as long as @msg is valid and unchanged.
+ *
+ * Returns: a #GstRTSPResult.
+ */
+GstRTSPResult
+gst_rtsp_message_parse_request (GstRTSPMessage * msg,
+    GstRTSPMethod * method, const gchar ** uri, GstRTSPVersion * version)
+{
+  g_return_val_if_fail (msg != NULL, GST_RTSP_EINVAL);
+  g_return_val_if_fail (msg->type != GST_RTSP_MESSAGE_REQUEST, GST_RTSP_EINVAL);
+
+  if (method)
+    *method = msg->type_data.request.method;
+  if (uri)
+    *uri = msg->type_data.request.uri;
+  if (version)
+    *version = msg->type_data.request.version;
+
+  return GST_RTSP_OK;
+}
+
+/**
+ * gst_rtsp_message_new_response:
+ * @msg: a location for the new #GstRTSPMessage
+ * @code: the status code
+ * @reason: the status reason or #NULL
+ * @request: the request that triggered the response or #NULL
+ *
+ * Create a new response #GstRTSPMessage with @code and @reason and store the
+ * result message in @msg. 
+ *
+ * When @reason is #NULL, the default reason for @code will be used.
+ *
+ * When @request is not #NULL, the relevant headers will be copied to the new
+ * response message.
+ *
+ * Returns: a #GstRTSPResult. Free with gst_rtsp_message_free().
+ */
 GstRTSPResult
 gst_rtsp_message_new_response (GstRTSPMessage ** msg, GstRTSPStatusCode code,
     const gchar * reason, const GstRTSPMessage * request)
@@ -139,6 +257,22 @@ gst_rtsp_message_new_response (GstRTSPMessage ** msg, GstRTSPStatusCode code,
   return gst_rtsp_message_init_response (newmsg, code, reason, request);
 }
 
+/**
+ * gst_rtsp_message_init_response:
+ * @msg: a #GstRTSPMessage
+ * @code: the status code
+ * @reason: the status reason or #NULL
+ * @request: the request that triggered the response or #NULL
+ *
+ * Initialize @msg with @code and @reason.
+ *
+ * When @reason is #NULL, the default reason for @code will be used.
+ *
+ * When @request is not #NULL, the relevant headers will be copied to the new
+ * response message.
+ *
+ * Returns: a #GstRTSPResult.
+ */
 GstRTSPResult
 gst_rtsp_message_init_response (GstRTSPMessage * msg, GstRTSPStatusCode code,
     const gchar * reason, const GstRTSPMessage * request)
@@ -185,6 +319,73 @@ gst_rtsp_message_init_response (GstRTSPMessage * msg, GstRTSPStatusCode code,
   return GST_RTSP_OK;
 }
 
+
+/**
+ * gst_rtsp_message_parse_response:
+ * @msg: a #GstRTSPMessage
+ * @code: location to hold the status code
+ * @reason: location to hold the status reason
+ * @version: location to hold the version
+ *
+ * Parse the response message @msg and store the values @code, @reason and
+ * @version. The result locations can be #NULL if one is not interested in its
+ * value.
+ *
+ * @reason remains valid for as long as @msg is valid and unchanged.
+ *
+ * Returns: a #GstRTSPResult.
+ */
+GstRTSPResult
+gst_rtsp_message_parse_response (GstRTSPMessage * msg,
+    GstRTSPStatusCode * code, const gchar ** reason, GstRTSPVersion * version)
+{
+  g_return_val_if_fail (msg != NULL, GST_RTSP_EINVAL);
+  g_return_val_if_fail (msg->type != GST_RTSP_MESSAGE_RESPONSE,
+      GST_RTSP_EINVAL);
+
+  if (code)
+    *code = msg->type_data.response.code;
+  if (reason)
+    *reason = msg->type_data.response.reason;
+  if (version)
+    *version = msg->type_data.response.version;
+
+  return GST_RTSP_OK;
+}
+
+/**
+ * gst_rtsp_message_new_data:
+ * @msg: a location for the new #GstRTSPMessage
+ * @channel: the channel
+ *
+ * Create a new data #GstRTSPMessage with @channel and store the
+ * result message in @msg. 
+ *
+ * Returns: a #GstRTSPResult. Free with gst_rtsp_message_free().
+ */
+GstRTSPResult
+gst_rtsp_message_new_data (GstRTSPMessage ** msg, guint8 channel)
+{
+  GstRTSPMessage *newmsg;
+
+  g_return_val_if_fail (msg != NULL, GST_RTSP_EINVAL);
+
+  newmsg = g_new0 (GstRTSPMessage, 1);
+
+  *msg = newmsg;
+
+  return gst_rtsp_message_init_data (newmsg, channel);
+}
+
+/**
+ * gst_rtsp_message_init_data:
+ * @msg: a #GstRTSPMessage
+ * @channel: a channel
+ *
+ * Initialize a new data #GstRTSPMessage for @channel.
+ *
+ * Returns: a #GstRTSPResult.
+ */
 GstRTSPResult
 gst_rtsp_message_init_data (GstRTSPMessage * msg, guint8 channel)
 {
@@ -198,6 +399,38 @@ gst_rtsp_message_init_data (GstRTSPMessage * msg, guint8 channel)
   return GST_RTSP_OK;
 }
 
+/**
+ * gst_rtsp_message_parse_data:
+ * @msg: a #GstRTSPMessage
+ * @channel: location to hold the channel
+ *
+ * Parse the data message @msg and store the channel in @channel.
+ *
+ * Returns: a #GstRTSPResult.
+ */
+GstRTSPResult
+gst_rtsp_message_parse_data (GstRTSPMessage * msg, guint8 * channel)
+{
+  g_return_val_if_fail (msg != NULL, GST_RTSP_EINVAL);
+  g_return_val_if_fail (msg->type != GST_RTSP_MESSAGE_DATA, GST_RTSP_EINVAL);
+
+  if (channel)
+    *channel = msg->type_data.data.channel;
+
+  return GST_RTSP_OK;
+}
+
+/**
+ * gst_rtsp_message_unset:
+ * @msg: a #GstRTSPMessage
+ *
+ * Unset the concents of @msg so that it becomes an uninitialized
+ * #GstRTSPMessage again. This function is mostly used in combination with 
+ * gst_rtsp_message_init_request(), gst_rtsp_message_init_response() and
+ * gst_rtsp_message_init_data() on stack allocated #GstRTSPMessage structures.
+ *
+ * Returns: #GST_RTSP_OK.
+ */
 GstRTSPResult
 gst_rtsp_message_unset (GstRTSPMessage * msg)
 {
@@ -229,6 +462,14 @@ gst_rtsp_message_unset (GstRTSPMessage * msg)
   return GST_RTSP_OK;
 }
 
+/**
+ * gst_rtsp_message_free:
+ * @msg: a #GstRTSPMessage
+ *
+ * Free the memory used by @msg.
+ *
+ * Returns: a #GstRTSPResult.
+ */
 GstRTSPResult
 gst_rtsp_message_free (GstRTSPMessage * msg)
 {
@@ -243,6 +484,16 @@ gst_rtsp_message_free (GstRTSPMessage * msg)
   return res;
 }
 
+/**
+ * gst_rtsp_message_add_header:
+ * @msg: a #GstRTSPMessage
+ * @field: a #GstRTSPHeaderField
+ * @value: the value of the header
+ *
+ * Add a header with key @field and @value to @msg.
+ *
+ * Returns: a #GstRTSPResult.
+ */
 GstRTSPResult
 gst_rtsp_message_add_header (GstRTSPMessage * msg, GstRTSPHeaderField field,
     const gchar * value)
@@ -257,10 +508,20 @@ gst_rtsp_message_add_header (GstRTSPMessage * msg, GstRTSPHeaderField field,
 
   g_array_append_val (msg->hdr_fields, key_value);
 
-
   return GST_RTSP_OK;
 }
 
+/**
+ * gst_rtsp_message_remove_header:
+ * @msg: a #GstRTSPMessage
+ * @field: a #GstRTSPHeaderField
+ * @indx: the index of the header
+ *
+ * Remove the @indx header with key @field from @msg. If @indx equals -1, all
+ * headers will be removed.
+ *
+ * Returns: a #GstRTSPResult.
+ */
 GstRTSPResult
 gst_rtsp_message_remove_header (GstRTSPMessage * msg, GstRTSPHeaderField field,
     gint indx)
@@ -283,10 +544,21 @@ gst_rtsp_message_remove_header (GstRTSPMessage * msg, GstRTSPHeaderField field,
       i++;
     }
   }
-
   return res;
 }
 
+/**
+ * gst_rtsp_message_get_header:
+ * @msg: a #GstRTSPMessage
+ * @field: a #GstRTSPHeaderField
+ * @value: pointer to hold the result
+ * @indx: the index of the header
+ *
+ * Get the @indx header value with key @field from @msg.
+ *
+ * Returns: #GST_RTSP_OK when @field was found, #GST_RTSP_ENOTIMPL if the key
+ * was not found.
+ */
 GstRTSPResult
 gst_rtsp_message_get_header (const GstRTSPMessage * msg,
     GstRTSPHeaderField field, gchar ** value, gint indx)
@@ -309,6 +581,16 @@ gst_rtsp_message_get_header (const GstRTSPMessage * msg,
   return GST_RTSP_ENOTIMPL;
 }
 
+/**
+ * gst_rtsp_message_append_headers:
+ * @msg: a #GstRTSPMessage
+ * @str: a string
+ *
+ * Append the currently configured headers in @msg to the #GString @str suitable
+ * for transmission.
+ *
+ * Returns: #GST_RTSP_OK.
+ */
 GstRTSPResult
 gst_rtsp_message_append_headers (const GstRTSPMessage * msg, GString * str)
 {
@@ -326,6 +608,16 @@ gst_rtsp_message_append_headers (const GstRTSPMessage * msg, GString * str)
   return GST_RTSP_OK;
 }
 
+/**
+ * gst_rtsp_message_set_body:
+ * @msg: a #GstRTSPMessage
+ * @data: the data
+ * @size: the size of @data
+ *
+ * Set the body of @msg to a copy of @data.
+ *
+ * Returns: #GST_RTSP_OK.
+ */
 GstRTSPResult
 gst_rtsp_message_set_body (GstRTSPMessage * msg, const guint8 * data,
     guint size)
@@ -335,6 +627,17 @@ gst_rtsp_message_set_body (GstRTSPMessage * msg, const guint8 * data,
   return gst_rtsp_message_take_body (msg, g_memdup (data, size), size);
 }
 
+/**
+ * gst_rtsp_message_take_body:
+ * @msg: a #GstRTSPMessage
+ * @data: the data
+ * @size: the size of @data
+ *
+ * Set the body of @msg to @data and @size. This method takes ownership of
+ * @data.
+ *
+ * Returns: #GST_RTSP_OK.
+ */
 GstRTSPResult
 gst_rtsp_message_take_body (GstRTSPMessage * msg, guint8 * data, guint size)
 {
@@ -350,6 +653,17 @@ gst_rtsp_message_take_body (GstRTSPMessage * msg, guint8 * data, guint size)
   return GST_RTSP_OK;
 }
 
+/**
+ * gst_rtsp_message_get_body:
+ * @msg: a #GstRTSPMessage
+ * @data: location for the data
+ * @size: location for the size of @data
+ *
+ * Get the body of @msg. @data remains valid for as long as @msg is valid and
+ * unchanged.
+ *
+ * Returns: #GST_RTSP_OK.
+ */
 GstRTSPResult
 gst_rtsp_message_get_body (const GstRTSPMessage * msg, guint8 ** data,
     guint * size)
@@ -364,6 +678,17 @@ gst_rtsp_message_get_body (const GstRTSPMessage * msg, guint8 ** data,
   return GST_RTSP_OK;
 }
 
+/**
+ * gst_rtsp_message_steal_body:
+ * @msg: a #GstRTSPMessage
+ * @data: location for the data
+ * @size: location for the size of @data
+ *
+ * Take the body of @msg and store it in @data and @size. After this method,
+ * the body and size of @msg will be set to #NULL and 0 respectively.
+ *
+ * Returns: #GST_RTSP_OK.
+ */
 GstRTSPResult
 gst_rtsp_message_steal_body (GstRTSPMessage * msg, guint8 ** data, guint * size)
 {
@@ -420,6 +745,14 @@ dump_key_value (gpointer data, gpointer user_data)
       gst_rtsp_header_as_text (key_value->field), key_value->value);
 }
 
+/**
+ * gst_rtsp_message_dump:
+ * @msg: a #GstRTSPMessage
+ *
+ * Dump the contents of @msg to stdout.
+ *
+ * Returns: #GST_RTSP_OK.
+ */
 GstRTSPResult
 gst_rtsp_message_dump (GstRTSPMessage * msg)
 {

gst-libs/gst/rtsp/gstrtspmessage.h

@@ -66,13 +66,16 @@ typedef enum
   GST_RTSP_MESSAGE_DATA,
 } GstRTSPMsgType;
 
+typedef struct _GstRTSPMessage GstRTSPMessage;
+
 /**
  * GstRTSPMessage:
  * @type: the message type
  *
- * An RTSP message containing request, response or data messages.
+ * An RTSP message containing request, response or data messages. Depending on
+ * the @type, the appropriate structure may be accessed.
  */
-typedef struct _GstRTSPMessage
+struct _GstRTSPMessage
 {
   GstRTSPMsgType    type;
 
@@ -97,19 +100,29 @@ typedef struct _GstRTSPMessage
 
   guint8        *body;
   guint          body_size;
+};
 
-} GstRTSPMessage;
+/* memory management */
-
 GstRTSPResult      gst_rtsp_message_new             (GstRTSPMessage **msg);
 GstRTSPResult      gst_rtsp_message_init            (GstRTSPMessage *msg);
+GstRTSPResult      gst_rtsp_message_unset           (GstRTSPMessage *msg);
+GstRTSPResult      gst_rtsp_message_free            (GstRTSPMessage *msg);
 
+GstRTSPMsgType     gst_rtsp_message_get_type        (GstRTSPMessage *msg);
+
+/* request */
 GstRTSPResult      gst_rtsp_message_new_request     (GstRTSPMessage **msg,
                                                      GstRTSPMethod method,
                                                      const gchar *uri);
 GstRTSPResult      gst_rtsp_message_init_request    (GstRTSPMessage *msg,
                                                      GstRTSPMethod method,
                                                      const gchar *uri);
+GstRTSPResult      gst_rtsp_message_parse_request   (GstRTSPMessage *msg,
+                                                     GstRTSPMethod *method,
+                                                     const gchar **uri,
+						     GstRTSPVersion *version);
 
+/* response */
 GstRTSPResult      gst_rtsp_message_new_response    (GstRTSPMessage **msg,
                                                      GstRTSPStatusCode code,
                                                      const gchar *reason,
@@ -118,14 +131,19 @@ GstRTSPResult      gst_rtsp_message_init_response   (GstRTSPMessage *msg,
                                                      GstRTSPStatusCode code,
                                                      const gchar *reason,
                                                      const GstRTSPMessage *request);
-
+GstRTSPResult      gst_rtsp_message_parse_response  (GstRTSPMessage *msg,
+                                                     GstRTSPStatusCode *code,
+                                                     const gchar **reason,
+                                                     GstRTSPVersion *version);
+/* data */
+GstRTSPResult      gst_rtsp_message_new_data        (GstRTSPMessage **msg,
+                                                     guint8 channel);
 GstRTSPResult      gst_rtsp_message_init_data       (GstRTSPMessage *msg,
                                                      guint8 channel);
+GstRTSPResult      gst_rtsp_message_parse_data      (GstRTSPMessage *msg,
+                                                     guint8 *channel);
 
-GstRTSPResult      gst_rtsp_message_unset           (GstRTSPMessage *msg);
+/* headers */
-GstRTSPResult      gst_rtsp_message_free            (GstRTSPMessage *msg);
-
-
 GstRTSPResult      gst_rtsp_message_add_header      (GstRTSPMessage *msg,
                                                      GstRTSPHeaderField field,
                                                      const gchar *value);
@@ -136,10 +154,10 @@ GstRTSPResult      gst_rtsp_message_get_header      (const GstRTSPMessage *msg,
                                                      GstRTSPHeaderField field,
                                                      gchar **value,
                                                      gint indx);
-
 GstRTSPResult      gst_rtsp_message_append_headers  (const GstRTSPMessage *msg,
                                                      GString *str);
 
+/* handling the body */
 GstRTSPResult      gst_rtsp_message_set_body        (GstRTSPMessage *msg,
                                                      const guint8 *data,
                                                      guint size);
@@ -153,6 +171,7 @@ GstRTSPResult      gst_rtsp_message_steal_body      (GstRTSPMessage *msg,
                                                      guint8 **data,
                                                      guint *size);
 
+/* debug */
 GstRTSPResult      gst_rtsp_message_dump            (GstRTSPMessage *msg);
 
 G_END_DECLS

gst-libs/gst/rtsp/gstrtsprange.c

@@ -40,6 +40,20 @@
  * SOFTWARE.
  */
 
+/**
+ * SECTION:gstrtsprange
+ * @short_description: dealing with time ranges
+ *  
+ * <refsect2>
+ * <para>
+ * Provides helper functions to deal with time ranges.
+ * </para>
+ * </refsect2>
+ *  
+ * Last reviewed on 2007-07-25 (0.10.14)
+ */
+
+
 #include <stdio.h>
 #include <string.h>
 

gst-libs/gst/rtsp/gstrtsprange.h

@@ -51,11 +51,11 @@ G_BEGIN_DECLS
 
 /**
  * GstRTSPRangeUnit:
- * @GST_RTSP_RANGE_SMPTE:
+ * @GST_RTSP_RANGE_SMPTE: SMPTE timecode
- * @GST_RTSP_RANGE_SMPTE_30_DROP:
+ * @GST_RTSP_RANGE_SMPTE_30_DROP: 29.97 frames per second
- * @GST_RTSP_RANGE_SMPTE_25:
+ * @GST_RTSP_RANGE_SMPTE_25: 25 frames per second
- * @GST_RTSP_RANGE_NPT:
+ * @GST_RTSP_RANGE_NPT: Normal play time 
- * @GST_RTSP_RANGE_CLOCK:
+ * @GST_RTSP_RANGE_CLOCK: Absolute time expressed as ISO 8601 timestamps
  *
  * Different possible time range units.
  */
@@ -71,17 +71,40 @@ typedef enum
 typedef struct _GstRTSPTimeRange GstRTSPTimeRange;
 typedef struct _GstRTSPTime GstRTSPTime;
 
+/**
+ * GstRTSPTimeType:
+ * @GST_RTSP_TIME_SECONDS: seconds
+ * @GST_RTSP_TIME_NOW: now
+ * @GST_RTSP_TIME_END: end
+ *
+ * Possible time types.
+ */
 typedef enum {
   GST_RTSP_TIME_SECONDS,
   GST_RTSP_TIME_NOW,
   GST_RTSP_TIME_END
 } GstRTSPTimeType;
 
+/**
+ * GstRTSPTime:
+ * @type: the time of the time
+ * @seconds: seconds when @type is GST_RTSP_TIME_SECONDS 
+ *
+ * A time indication.
+ */
 struct _GstRTSPTime {
   GstRTSPTimeType type;
   gdouble         seconds;
 };
 
+/**
+ * GstRTSPTimeRange:
+ * @unit: the time units used
+ * @min: the minimum interval
+ * @max: the maximum interval
+ *
+ * A time range.
+ */
 struct _GstRTSPTimeRange {
   GstRTSPRangeUnit unit;
 

gst-libs/gst/rtsp/gstrtsptransport.c

@@ -41,6 +41,19 @@
  * SOFTWARE.
  */
 
+/**
+ * SECTION:gstrtsptransport
+ * @short_description: dealing with RTSP transports
+ *  
+ * <refsect2>
+ * <para>
+ * Provides helper functions to deal with RTSP transport strings.
+ * </para>
+ * </refsect2>
+ *  
+ * Last reviewed on 2007-07-25 (0.10.14)
+ */
+
 #include <string.h>
 #include <stdlib.h>
 
@@ -111,6 +124,15 @@ G_STMT_START {                                    \
   transport_params |= (param);                    \
 } G_STMT_END
 
+/**
+ * gst_rtsp_transport_new:
+ * @transport: location to hold the new #GstRTSPTransport
+ *
+ * Allocate a new initialized #GstRTSPTransport. Use gst_rtsp_transport_free()
+ * after usage.
+ *
+ * Returns: a #GstRTSPResult. 
+ */
 GstRTSPResult
 gst_rtsp_transport_new (GstRTSPTransport ** transport)
 {
@@ -125,6 +147,14 @@ gst_rtsp_transport_new (GstRTSPTransport ** transport)
   return gst_rtsp_transport_init (trans);
 }
 
+/**
+ * gst_rtsp_transport_init:
+ * @transport: a #GstRTSPTransport
+ *
+ * Initialize @transport so that it can be used.
+ *
+ * Returns: #GST_RTSP_OK. 
+ */
 GstRTSPResult
 gst_rtsp_transport_init (GstRTSPTransport * transport)
 {
@@ -152,6 +182,16 @@ gst_rtsp_transport_init (GstRTSPTransport * transport)
   return GST_RTSP_OK;
 }
 
+/**
+ * gst_rtsp_transport_get_mime:
+ * @trans: a #GstRTSPTransMode
+ * @mime: location to hold the result
+ *
+ * Get the mime type of the transport mode @trans. This mime type is typically
+ * used to generate #GstCaps on buffers.
+ *
+ * Returns: #GST_RTSP_OK. 
+ */
 GstRTSPResult
 gst_rtsp_transport_get_mime (GstRTSPTransMode trans, const gchar ** mime)
 {
@@ -167,6 +207,23 @@ gst_rtsp_transport_get_mime (GstRTSPTransMode trans, const gchar ** mime)
   return GST_RTSP_OK;
 }
 
+/**
+ * gst_rtsp_transport_get_manager:
+ * @trans: a #GstRTSPTransMode
+ * @manager: location to hold the result
+ * @option: option index.
+ *
+ * Get the #GStreamer element that can handle the buffers transported over
+ * @trans.
+ *
+ * It is possible that there are several managers available, use @option to
+ * selected one.
+ *
+ * @manager will contain an element name or #NULL when no manager is
+ * needed/available for @trans.
+ *
+ * Returns: #GST_RTSP_OK. 
+ */
 GstRTSPResult
 gst_rtsp_transport_get_manager (GstRTSPTransMode trans, const gchar ** manager,
     guint option)
@@ -287,6 +344,15 @@ rtsp_transport_ltrans_as_text (const GstRTSPTransport * transport)
   return NULL;
 }
 
+/**
+ * gst_rtsp_transport_parse:
+ * @str: a transport string
+ * @transport: a #GstRTSPTransport
+ *
+ * Parse the RTSP transport string @str into @transport.
+ *
+ * Returns: a #GstRTSPResult.
+ */
 GstRTSPResult
 gst_rtsp_transport_parse (const gchar * str, GstRTSPTransport * transport)
 {
@@ -432,6 +498,16 @@ invalid_transport:
   }
 }
 
+/**
+ * gst_rtsp_transport_as_text:
+ * @transport: a #GstRTSPTransport
+ *
+ * Convert @transport into a string that can be used to signal the transport in
+ * an RTSP SETUP response.
+ *
+ * Returns: a string describing the RTSP transport or #NULL when the transport
+ * is invalid.
+ */
 gchar *
 gst_rtsp_transport_as_text (GstRTSPTransport * transport)
 {
@@ -577,6 +653,14 @@ invalid_transport:
   }
 }
 
+/**
+ * gst_rtsp_transport_free:
+ * @transport: a #GstRTSPTransport
+ *
+ * Free the memory used by @transport.
+ *
+ * Returns: #GST_RTSP_OK.
+ */
 GstRTSPResult
 gst_rtsp_transport_free (GstRTSPTransport * transport)
 {

gst-libs/gst/rtsp/gstrtspurl.c

@@ -40,6 +40,19 @@
  * SOFTWARE.
  */
 
+/**
+ * SECTION:gstrtspurl
+ * @short_description: handling RTSP urls
+ *  
+ * <refsect2>
+ * <para>
+ * Provides helper functions to handle RTSP urls.
+ * </para>
+ * </refsect2>
+ *  
+ * Last reviewed on 2007-07-25 (0.10.14)
+ */
+
 #include <stdlib.h>
 #include <string.h>
 
@@ -54,6 +67,16 @@
 
 /* format is rtsp[u]://[user:passwd@]host[:port]/abspath[?query] */
 
+/**
+ * gst_rtsp_url_parse:
+ * @urlstr: the url string to parse
+ * @url: location to hold the result.
+ *
+ * Parse the RTSP @urlstr into a newly allocated #GstRTSPUrl. Free after usage
+ * with gst_rtsp_url_free().
+ *
+ * Returns: a #GstRTSPResult.
+ */
 GstRTSPResult
 gst_rtsp_url_parse (const gchar * urlstr, GstRTSPUrl ** url)
 {
@@ -153,6 +176,12 @@ invalid:
   }
 }
 
+/**
+ * gst_rtsp_url_free:
+ * @url: a #GstRTSPUrl
+ *
+ * Free the memory used by @url.
+ */
 void
 gst_rtsp_url_free (GstRTSPUrl * url)
 {
@@ -167,6 +196,15 @@ gst_rtsp_url_free (GstRTSPUrl * url)
   g_free (url);
 }
 
+/**
+ * gst_rtsp_url_set_port:
+ * @url: a #GstRTSPUrl
+ * @port: the port
+ *
+ * Set the port number in @url to @port.
+ *
+ * Returns: #GST_RTSP_OK.
+ */
 GstRTSPResult
 gst_rtsp_url_set_port (GstRTSPUrl * url, guint16 port)
 {
@@ -177,6 +215,15 @@ gst_rtsp_url_set_port (GstRTSPUrl * url, guint16 port)
   return GST_RTSP_OK;
 }
 
+/**
+ * gst_rtsp_url_get_port:
+ * @url: a #GstRTSPUrl
+ * @port: location to hold the port
+ *
+ * Get the port number of @url.
+ *
+ * Returns: #GST_RTSP_OK.
+ */
 GstRTSPResult
 gst_rtsp_url_get_port (GstRTSPUrl * url, guint16 * port)
 {
@@ -192,6 +239,14 @@ gst_rtsp_url_get_port (GstRTSPUrl * url, guint16 * port)
   return GST_RTSP_OK;
 }
 
+/**
+ * gst_rtsp_url_get_request_uri:
+ * @url: a #GstRTSPUrl
+ *
+ * Get a newly allocated string describing the request URI for @url. 
+ *
+ * Returns: a string with the request URI. g_free() after usage.
+ */
 gchar *
 gst_rtsp_url_get_request_uri (GstRTSPUrl * url)
 {