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