gstrtspmessage: GStreamer Base Plugins 1.0 Library Reference Manual

## gstrtspmessage gstrtspmessage — RTSP messages |

## Functions

GstRTSPResult | gst_rtsp_message_new ()
GstRTSPResult | gst_rtsp_message_init ()
GstRTSPResult | gst_rtsp_message_unset ()
GstRTSPResult | gst_rtsp_message_free ()
GstRTSPMsgType | gst_rtsp_message_get_type ()
GstRTSPResult | gst_rtsp_message_new_request ()
GstRTSPResult | gst_rtsp_message_init_request ()
GstRTSPResult | gst_rtsp_message_parse_request ()
GstRTSPResult | gst_rtsp_message_new_response ()
GstRTSPResult | gst_rtsp_message_init_response ()
GstRTSPResult | gst_rtsp_message_parse_response ()
GstRTSPResult | gst_rtsp_message_new_data ()
GstRTSPResult | gst_rtsp_message_init_data ()
GstRTSPResult | gst_rtsp_message_parse_data ()
GstRTSPResult | gst_rtsp_message_add_header ()
GstRTSPResult | gst_rtsp_message_take_header ()
GstRTSPResult | gst_rtsp_message_remove_header ()
GstRTSPResult | gst_rtsp_message_get_header ()
GstRTSPResult | gst_rtsp_message_add_header_by_name ()
GstRTSPResult | gst_rtsp_message_take_header_by_name ()
GstRTSPResult | gst_rtsp_message_remove_header_by_name ()
GstRTSPResult | gst_rtsp_message_get_header_by_name ()
GstRTSPResult | gst_rtsp_message_append_headers ()
GstRTSPResult | gst_rtsp_message_set_body ()
GstRTSPResult | gst_rtsp_message_take_body ()
GstRTSPResult | gst_rtsp_message_get_body ()
GstRTSPResult | gst_rtsp_message_steal_body ()
GstRTSPResult | gst_rtsp_message_dump ()

## Types and Values

enum | GstRTSPMsgType
struct | GstRTSPMessage

## Includes

    #include <gst/rtsp/gstrtspmessage.h>

## Description

Provides methods for creating and parsing request, response and data messages.

## Functions

### gst_rtsp_message_new ()

    GstRTSPResult
    gst_rtsp_message_new (GstRTSPMessage **msg);

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

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

msg | a GstRTSPMessage |

#### Returns

GST_RTSP_OK.

### gst_rtsp_message_free ()

    GstRTSPResult
    gst_rtsp_message_free (GstRTSPMessage *msg);

Free the memory used by `msg` .

#### Parameters

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` .

#### Parameters

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()`.

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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` .

#### Parameters

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` .

#### Parameters

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` .

#### Parameters

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` .

#### Parameters

msg | a GstRTSPMessage |
field | a GstRTSPHeaderField |
value | the value of the header. | [transfer full]

#### 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.

#### Parameters

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` .

#### Parameters

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_add_header_by_name ()

    GstRTSPResult
    gst_rtsp_message_add_header_by_name (GstRTSPMessage *msg,
                                         const gchar *header,
                                         const gchar *value);

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

#### Parameters

msg | a GstRTSPMessage |
header | header string. | [transfer none]
value | the value of the header. | [transfer none]

#### Returns

a GstRTSPResult.

Since: 1.6

### gst_rtsp_message_take_header_by_name ()

    GstRTSPResult
    gst_rtsp_message_take_header_by_name (GstRTSPMessage *msg,
                                          const gchar *header,
                                          gchar *value);

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

#### Parameters

msg | a GstRTSPMessage |
header | a header string. | [transfer none]
value | the value of the header. | [transfer full]

#### Returns

a GstRTSPResult.

Since: 1.6

### gst_rtsp_message_remove_header_by_name ()

    GstRTSPResult
    gst_rtsp_message_remove_header_by_name
                                   (GstRTSPMessage *msg,
                                    const gchar *header,
                                    gint index);

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

#### Parameters

msg | a GstRTSPMessage |
header | the header string |
index | the index of the header |

#### Returns

a GstRTSPResult

Since: 1.6

### gst_rtsp_message_get_header_by_name ()

    GstRTSPResult
    gst_rtsp_message_get_header_by_name (GstRTSPMessage *msg,
                                         const gchar *header,
                                         gchar **value,
                                         gint index);

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

#### Parameters

msg | a GstRTSPMessage |
header | a GstRTSPHeaderField |
value | pointer to hold the result. | [out][transfer none]
index | the index of the header |

#### Returns

GST_RTSP_OK when `field` was found, GST_RTSP_ENOTIMPL if the key was not found.

Since: 1.6

### 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.

#### Parameters

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` .

#### Parameters

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` .

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

msg | a GstRTSPMessage |

#### Returns

GST_RTSP_OK.

## Types and Values

### enum GstRTSPMsgType

The type of a message.

#### Members

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.

#### Members

GstRTSPMsgType `type`; | the message type |

## See Also

gstrtspconnection