From 77c284a31feb4b4863ad1719e858c8455263cb78 Mon Sep 17 00:00:00 2001 From: Wim Taymans Date: Wed, 25 Jul 2007 11:22:30 +0000 Subject: [PATCH] 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 | 22 ++ docs/libs/gst-plugins-base-libs-sections.txt | 10 +- gst-libs/gst/rtsp/gstrtspdefs.h | 81 ++++++- gst-libs/gst/rtsp/gstrtspmessage.c | 337 ++++++++++++++++++++++++++- gst-libs/gst/rtsp/gstrtspmessage.h | 39 +++- gst-libs/gst/rtsp/gstrtsprange.c | 14 ++ gst-libs/gst/rtsp/gstrtsprange.h | 33 ++- gst-libs/gst/rtsp/gstrtsptransport.c | 84 +++++++ gst-libs/gst/rtsp/gstrtspurl.c | 55 +++++ 9 files changed, 652 insertions(+), 23 deletions(-) diff --git a/ChangeLog b/ChangeLog index 0bc0d83..3b17f69 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,25 @@ +2007-07-25 Wim Taymans + + * 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 * docs/libs/gst-plugins-base-libs-docs.sgml: diff --git a/docs/libs/gst-plugins-base-libs-sections.txt b/docs/libs/gst-plugins-base-libs-sections.txt index a4aadb5..416ddf6 100644 --- a/docs/libs/gst-plugins-base-libs-sections.txt +++ b/docs/libs/gst-plugins-base-libs-sections.txt @@ -1031,15 +1031,21 @@ gst_rtsp_connection_set_auth gstrtspmessage gst/rtsp/gstrtspmessage.h GstRTSPMsgType +GstRTSPMessage gst_rtsp_message_new gst_rtsp_message_init +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_unset -gst_rtsp_message_free +gst_rtsp_message_parse_data gst_rtsp_message_add_header gst_rtsp_message_remove_header gst_rtsp_message_get_header diff --git a/gst-libs/gst/rtsp/gstrtspdefs.h b/gst-libs/gst/rtsp/gstrtspdefs.h index 2e79028..b6d9dfa 100644 --- a/gst-libs/gst/rtsp/gstrtspdefs.h +++ b/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 { diff --git a/gst-libs/gst/rtsp/gstrtspmessage.c b/gst-libs/gst/rtsp/gstrtspmessage.c index 15f189f..10f1ff2 100644 --- a/gst-libs/gst/rtsp/gstrtspmessage.c +++ b/gst-libs/gst/rtsp/gstrtspmessage.c @@ -41,6 +41,20 @@ * SOFTWARE. */ +/** + * SECTION:gstrtspmessage + * @short_description: RTSP messages + * @see_also: gstrtspconnection + * + * + * + * Provides methods for creating and parsing request, response and data messages. + * + * + * + * Last reviewed on 2007-07-25 (0.10.14) + */ + #include #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) { diff --git a/gst-libs/gst/rtsp/gstrtspmessage.h b/gst-libs/gst/rtsp/gstrtspmessage.h index d78c7a0..1dd2c34 100644 --- a/gst-libs/gst/rtsp/gstrtspmessage.h +++ b/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); -GstRTSPResult gst_rtsp_message_free (GstRTSPMessage *msg); - - +/* headers */ 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 diff --git a/gst-libs/gst/rtsp/gstrtsprange.c b/gst-libs/gst/rtsp/gstrtsprange.c index daa914e..2c998be 100644 --- a/gst-libs/gst/rtsp/gstrtsprange.c +++ b/gst-libs/gst/rtsp/gstrtsprange.c @@ -40,6 +40,20 @@ * SOFTWARE. */ +/** + * SECTION:gstrtsprange + * @short_description: dealing with time ranges + * + * + * + * Provides helper functions to deal with time ranges. + * + * + * + * Last reviewed on 2007-07-25 (0.10.14) + */ + + #include #include diff --git a/gst-libs/gst/rtsp/gstrtsprange.h b/gst-libs/gst/rtsp/gstrtsprange.h index d18e464..c00658d 100644 --- a/gst-libs/gst/rtsp/gstrtsprange.h +++ b/gst-libs/gst/rtsp/gstrtsprange.h @@ -51,11 +51,11 @@ G_BEGIN_DECLS /** * GstRTSPRangeUnit: - * @GST_RTSP_RANGE_SMPTE: - * @GST_RTSP_RANGE_SMPTE_30_DROP: - * @GST_RTSP_RANGE_SMPTE_25: - * @GST_RTSP_RANGE_NPT: - * @GST_RTSP_RANGE_CLOCK: + * @GST_RTSP_RANGE_SMPTE: SMPTE timecode + * @GST_RTSP_RANGE_SMPTE_30_DROP: 29.97 frames per second + * @GST_RTSP_RANGE_SMPTE_25: 25 frames per second + * @GST_RTSP_RANGE_NPT: Normal play time + * @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; diff --git a/gst-libs/gst/rtsp/gstrtsptransport.c b/gst-libs/gst/rtsp/gstrtsptransport.c index 080167e..c6c5e51 100644 --- a/gst-libs/gst/rtsp/gstrtsptransport.c +++ b/gst-libs/gst/rtsp/gstrtsptransport.c @@ -41,6 +41,19 @@ * SOFTWARE. */ +/** + * SECTION:gstrtsptransport + * @short_description: dealing with RTSP transports + * + * + * + * Provides helper functions to deal with RTSP transport strings. + * + * + * + * Last reviewed on 2007-07-25 (0.10.14) + */ + #include #include @@ -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) { diff --git a/gst-libs/gst/rtsp/gstrtspurl.c b/gst-libs/gst/rtsp/gstrtspurl.c index 34ce971..1a7a3e1 100644 --- a/gst-libs/gst/rtsp/gstrtspurl.c +++ b/gst-libs/gst/rtsp/gstrtspurl.c @@ -40,6 +40,19 @@ * SOFTWARE. */ +/** + * SECTION:gstrtspurl + * @short_description: handling RTSP urls + * + * + * + * Provides helper functions to handle RTSP urls. + * + * + * + * Last reviewed on 2007-07-25 (0.10.14) + */ + #include #include @@ -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) { -- 2.7.4