gstrtspmessage

## gstrtspmessage gstrtspmessage — RTSP messages |

## Synopsis

    #include <gst/rtsp/gstrtspmessage.h>

    enum                GstRTSPMsgType;
    struct              GstRTSPMessage;
    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);
    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);
    GstRTSPResult       gst_rtsp_message_new_response       (GstRTSPMessage **msg,
                                                             GstRTSPStatusCode code,
                                                             const gchar *reason,
                                                             const GstRTSPMessage *request);
    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);
    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_add_header         (GstRTSPMessage *msg,
                                                             GstRTSPHeaderField field,
                                                             const gchar *value);
    GstRTSPResult       gst_rtsp_message_take_header        (GstRTSPMessage *msg,
                                                             GstRTSPHeaderField field,
                                                             gchar *value);
    GstRTSPResult       gst_rtsp_message_remove_header      (GstRTSPMessage *msg,
                                                             GstRTSPHeaderField field,
                                                             gint indx);
    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);
    GstRTSPResult       gst_rtsp_message_set_body           (GstRTSPMessage *msg,
                                                             const guint8 *data,
                                                             guint size);
    GstRTSPResult       gst_rtsp_message_take_body          (GstRTSPMessage *msg,
                                                             guint8 *data,
                                                             guint size);
    GstRTSPResult       gst_rtsp_message_get_body           (const GstRTSPMessage *msg,
                                                             guint8 **data,
                                                             guint *size);
    GstRTSPResult       gst_rtsp_message_steal_body         (GstRTSPMessage *msg,
                                                             guint8 **data,
                                                             guint *size);
    GstRTSPResult       gst_rtsp_message_dump               (GstRTSPMessage *msg);

## Description

Provides methods for creating and parsing request, response and data messages. Last reviewed on 2007-07-25 (0.10.14)

## Details

### enum GstRTSPMsgType

    typedef enum {
      GST_RTSP_MESSAGE_INVALID,
      GST_RTSP_MESSAGE_REQUEST,
      GST_RTSP_MESSAGE_RESPONSE,
      GST_RTSP_MESSAGE_HTTP_REQUEST,
      GST_RTSP_MESSAGE_HTTP_RESPONSE,
      GST_RTSP_MESSAGE_DATA
    } GstRTSPMsgType;

The type of a message.

`GST_RTSP_MESSAGE_INVALID` | invalid message type
`GST_RTSP_MESSAGE_REQUEST` | RTSP request message
`GST_RTSP_MESSAGE_RESPONSE` | RTSP response message
`GST_RTSP_MESSAGE_HTTP_REQUEST` | HTTP request message.
`GST_RTSP_MESSAGE_HTTP_RESPONSE` | HTTP response message.
`GST_RTSP_MESSAGE_DATA` | data message

### struct GstRTSPMessage

    struct GstRTSPMessage {
      GstRTSPMsgType    type;

      union {
        struct {
          GstRTSPMethod      method;
          gchar             *uri;
          GstRTSPVersion     version;
        } request;
        struct {
          GstRTSPStatusCode  code;
          gchar             *reason;
          GstRTSPVersion     version;
        } response;
        struct {
          guint8             channel;
        } data;
      } type_data;
    };

An RTSP message containing request, response or data messages. Depending on the `type`, the appropriate structure may be accessed.

GstRTSPMsgType `type`; | the message type

### gst_rtsp_message_new ()

    GstRTSPResult       gst_rtsp_message_new                (GstRTSPMessage **msg);

Create a new initialized GstRTSPMessage. Free with `gst_rtsp_message_free()`.

`msg` : | a location for the new GstRTSPMessage. [out][transfer full]
Returns : | a GstRTSPResult.

### gst_rtsp_message_init ()

    GstRTSPResult       gst_rtsp_message_init               (GstRTSPMessage *msg);

Initialize `msg`. This function is mostly used when `msg` is allocated on the stack. The reverse operation of this is `gst_rtsp_message_unset()`.

`msg` : | a GstRTSPMessage
Returns : | a GstRTSPResult.

### gst_rtsp_message_unset ()

    GstRTSPResult       gst_rtsp_message_unset              (GstRTSPMessage *msg);

Unset the contents 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.

`msg` : | a GstRTSPMessage
Returns : | GST_RTSP_OK.

### gst_rtsp_message_free ()

    GstRTSPResult       gst_rtsp_message_free               (GstRTSPMessage *msg);

Free the memory used by `msg`.

`msg` : | a GstRTSPMessage
Returns : | a GstRTSPResult.

### gst_rtsp_message_get_type ()

    GstRTSPMsgType      gst_rtsp_message_get_type           (GstRTSPMessage *msg);

Get the message type of `msg`.

`msg` : | a GstRTSPMessage
Returns : | the message type.

### gst_rtsp_message_new_request ()

    GstRTSPResult       gst_rtsp_message_new_request        (GstRTSPMessage **msg,
                                                             GstRTSPMethod method,
                                                             const gchar *uri);

Create a new GstRTSPMessage with `method` and `uri` and store the result request message in `msg`. Free with `gst_rtsp_message_free()`.

`msg` : | a location for the new GstRTSPMessage. [out][transfer full]
`method` : | the request method to use
`uri` : | the uri of the request. [transfer none]
Returns : | a GstRTSPResult.

### gst_rtsp_message_init_request ()

    GstRTSPResult       gst_rtsp_message_init_request       (GstRTSPMessage *msg,
                                                             GstRTSPMethod method,
                                                             const gchar *uri);

Initialize `msg` as a request message with `method` and `uri`. To clear `msg` again, use `gst_rtsp_message_unset()`.

`msg` : | a GstRTSPMessage
`method` : | the request method to use
`uri` : | the uri of the request. [transfer none]
Returns : | a GstRTSPResult.

### gst_rtsp_message_parse_request ()

    GstRTSPResult       gst_rtsp_message_parse_request      (GstRTSPMessage *msg,
                                                             GstRTSPMethod *method,
                                                             const gchar **uri,
                                                             GstRTSPVersion *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.

`msg` : | a GstRTSPMessage
`method` : | location to hold the method. [out][allow-none]
`uri` : | location to hold the uri. [out][allow-none]
`version` : | location to hold the version. [out][allow-none]
Returns : | a GstRTSPResult.

### gst_rtsp_message_new_response ()

    GstRTSPResult       gst_rtsp_message_new_response       (GstRTSPMessage **msg,
                                                             GstRTSPStatusCode code,
                                                             const gchar *reason,
                                                             const GstRTSPMessage *request);

Create a new response GstRTSPMessage with `code` and `reason` and store the result message in `msg`. Free with `gst_rtsp_message_free()`.

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.

`msg` : | a location for the new GstRTSPMessage. [out][transfer full]
`code` : | the status code
`reason` : | the status reason or `NULL`. [transfer none][allow-none]
`request` : | the request that triggered the response or `NULL`. [transfer none][allow-none]
Returns : | a GstRTSPResult.

### gst_rtsp_message_init_response ()

    GstRTSPResult       gst_rtsp_message_init_response      (GstRTSPMessage *msg,
                                                             GstRTSPStatusCode code,
                                                             const gchar *reason,
                                                             const GstRTSPMessage *request);

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.

`msg` : | a GstRTSPMessage
`code` : | the status code
`reason` : | the status reason or `NULL`. [transfer none][allow-none]
`request` : | the request that triggered the response or `NULL`. [transfer none][allow-none]
Returns : | a GstRTSPResult.

### gst_rtsp_message_parse_response ()

    GstRTSPResult       gst_rtsp_message_parse_response     (GstRTSPMessage *msg,
                                                             GstRTSPStatusCode *code,
                                                             const gchar **reason,
                                                             GstRTSPVersion *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.

`msg` : | a GstRTSPMessage
`code` : | location to hold the status code. [out][allow-none]
`reason` : | location to hold the status reason. [out][allow-none]
`version` : | location to hold the version. [out][allow-none]
Returns : | a GstRTSPResult.

### gst_rtsp_message_new_data ()

    GstRTSPResult       gst_rtsp_message_new_data           (GstRTSPMessage **msg,
                                                             guint8 channel);

Create a new data GstRTSPMessage with `channel` and store the result message in `msg`. Free with `gst_rtsp_message_free()`.

`msg` : | a location for the new GstRTSPMessage. [out][transfer full]
`channel` : | the channel
Returns : | a GstRTSPResult.

### gst_rtsp_message_init_data ()

    GstRTSPResult       gst_rtsp_message_init_data          (GstRTSPMessage *msg,
                                                             guint8 channel);

Initialize a new data GstRTSPMessage for `channel`.

`msg` : | a GstRTSPMessage
`channel` : | a channel
Returns : | a GstRTSPResult.

### gst_rtsp_message_parse_data ()

    GstRTSPResult       gst_rtsp_message_parse_data         (GstRTSPMessage *msg,
                                                             guint8 *channel);

Parse the data message `msg` and store the channel in `channel`.

`msg` : | a GstRTSPMessage
`channel` : | location to hold the channel. [out]
Returns : | a GstRTSPResult.

### gst_rtsp_message_add_header ()

    GstRTSPResult       gst_rtsp_message_add_header         (GstRTSPMessage *msg,
                                                             GstRTSPHeaderField field,
                                                             const gchar *value);

Add a header with key `field` and `value` to `msg`. This function takes a copy of `value`.

`msg` : | a GstRTSPMessage
`field` : | a GstRTSPHeaderField
`value` : | the value of the header. [transfer none]
Returns : | a GstRTSPResult.

### gst_rtsp_message_take_header ()

    GstRTSPResult       gst_rtsp_message_take_header        (GstRTSPMessage *msg,
                                                             GstRTSPHeaderField field,
                                                             gchar *value);

Add a header with key `field` and `value` to `msg`. This function takes ownership of `value`.

`msg` : | a GstRTSPMessage
`field` : | a GstRTSPHeaderField
`value` : | the value of the header
Returns : | a GstRTSPResult.

### gst_rtsp_message_remove_header ()

    GstRTSPResult       gst_rtsp_message_remove_header      (GstRTSPMessage *msg,
                                                             GstRTSPHeaderField field,
                                                             gint indx);

Remove the `indx` header with key `field` from `msg`. If `indx` equals -1, all headers will be removed.

`msg` : | a GstRTSPMessage
`field` : | a GstRTSPHeaderField
`indx` : | the index of the header
Returns : | a GstRTSPResult.

### gst_rtsp_message_get_header ()

    GstRTSPResult       gst_rtsp_message_get_header         (const GstRTSPMessage *msg,
                                                             GstRTSPHeaderField field,
                                                             gchar **value,
                                                             gint indx);

Get the `indx` header value with key `field` from `msg`. The result in `value` stays valid as long as it remains present in `msg`.

`msg` : | a GstRTSPMessage
`field` : | a GstRTSPHeaderField
`value` : | pointer to hold the result. [out][transfer none]
`indx` : | the index of the header
Returns : | GST_RTSP_OK when `field` was found, GST_RTSP_ENOTIMPL if the key was not found.

### gst_rtsp_message_append_headers ()

    GstRTSPResult       gst_rtsp_message_append_headers     (const GstRTSPMessage *msg,
                                                             GString *str);

Append the currently configured headers in `msg` to the GString `str` suitable for transmission.

`msg` : | a GstRTSPMessage
`str` : | a string. [transfer none]
Returns : | GST_RTSP_OK.

### gst_rtsp_message_set_body ()

    GstRTSPResult       gst_rtsp_message_set_body           (GstRTSPMessage *msg,
                                                             const guint8 *data,
                                                             guint size);

Set the body of `msg` to a copy of `data`.

`msg` : | a GstRTSPMessage
`data` : | the data. [array length=size][transfer none]
`size` : | the size of `data`
Returns : | GST_RTSP_OK.

### gst_rtsp_message_take_body ()

    GstRTSPResult       gst_rtsp_message_take_body          (GstRTSPMessage *msg,
                                                             guint8 *data,
                                                             guint size);

Set the body of `msg` to `data` and `size`. This method takes ownership of `data`.

`msg` : | a GstRTSPMessage
`data` : | the data. [array length=size][transfer full]
`size` : | the size of `data`
Returns : | GST_RTSP_OK.

### gst_rtsp_message_get_body ()

    GstRTSPResult       gst_rtsp_message_get_body           (const GstRTSPMessage *msg,
                                                             guint8 **data,
                                                             guint *size);

Get the body of `msg`. `data` remains valid for as long as `msg` is valid and unchanged.

`msg` : | a GstRTSPMessage
`data` : | location for the data. [out][transfer none][array length=size]
`size` : | location for the size of `data`. [out]
Returns : | GST_RTSP_OK.

### gst_rtsp_message_steal_body ()

    GstRTSPResult       gst_rtsp_message_steal_body         (GstRTSPMessage *msg,
                                                             guint8 **data,
                                                             guint *size);

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.

`msg` : | a GstRTSPMessage
`data` : | location for the data. [out][transfer full][array length=size]
`size` : | location for the size of `data`. [out]
Returns : | GST_RTSP_OK.

### gst_rtsp_message_dump ()

    GstRTSPResult       gst_rtsp_message_dump               (GstRTSPMessage *msg);

Dump the contents of `msg` to stdout.

`msg` : | a GstRTSPMessage
Returns : | GST_RTSP_OK.

## See Also

gstrtspconnection