gstrtspconnection

gstrtspconnection — manage RTSP connections

Functions

GstRTSPResult gst_rtsp_connection_create ()
GstRTSPResult gst_rtsp_connection_create_from_fd ()
GstRTSPResult gst_rtsp_connection_accept ()
GstRTSPResult gst_rtsp_connection_connect ()
GstRTSPResult gst_rtsp_connection_close ()
GstRTSPResult gst_rtsp_connection_free ()
GstRTSPResult gst_rtsp_connection_read ()
GstRTSPResult gst_rtsp_connection_write ()
GstRTSPResult gst_rtsp_connection_poll ()
GstRTSPResult gst_rtsp_connection_send ()
GstRTSPResult gst_rtsp_connection_receive ()
GstRTSPResult gst_rtsp_connection_next_timeout ()
GstRTSPResult gst_rtsp_connection_reset_timeout ()
GstRTSPResult gst_rtsp_connection_flush ()
GstRTSPResult gst_rtsp_connection_set_auth ()
void gst_rtsp_connection_set_auth_param ()
void gst_rtsp_connection_clear_auth_params ()
GstRTSPResult gst_rtsp_connection_set_qos_dscp ()
void gst_rtsp_connection_set_ip ()
const gchar * gst_rtsp_connection_get_ip ()
GstRTSPUrl * gst_rtsp_connection_get_url ()
void gst_rtsp_connection_set_tunneled ()
gboolean gst_rtsp_connection_is_tunneled ()
const gchar * gst_rtsp_connection_get_tunnelid ()
GstRTSPResult gst_rtsp_connection_do_tunnel ()
gint gst_rtsp_connection_get_readfd ()
gint gst_rtsp_connection_get_writefd ()
void gst_rtsp_connection_set_http_mode ()
GstRTSPResult gst_rtsp_connection_set_proxy ()
GstRTSPWatch * gst_rtsp_watch_new ()
void gst_rtsp_watch_unref ()
guint gst_rtsp_watch_attach ()
void gst_rtsp_watch_reset ()
guint gst_rtsp_watch_queue_message ()
guint gst_rtsp_watch_queue_data ()
GstRTSPResult gst_rtsp_watch_send_message ()
GstRTSPResult gst_rtsp_watch_write_data ()

Types and Values

Includes

#include <gst/rtsp/gstrtspconnection.h>

Description

This object manages the RTSP connection to the server. It provides function to receive and send bytes and messages.

Last reviewed on 2007-07-24 (0.10.14)

Functions

gst_rtsp_connection_create ()

GstRTSPResult
gst_rtsp_connection_create (const GstRTSPUrl *url,
                            GstRTSPConnection **conn);

Create a newly allocated GstRTSPConnection from url and store it in conn . The connection will not yet attempt to connect to url , use gst_rtsp_connection_connect().

A copy of url will be made.

Parameters

url

a GstRTSPUrl

 

conn

storage for a GstRTSPConnection

 

Returns

GST_RTSP_OK when conn contains a valid connection.


gst_rtsp_connection_create_from_fd ()

GstRTSPResult
gst_rtsp_connection_create_from_fd (gint fd,
                                    const gchar *ip,
                                    guint16 port,
                                    const gchar *initial_buffer,
                                    GstRTSPConnection **conn);

Create a new GstRTSPConnection for handling communication on the existing file descriptor fd . The initial_buffer contains any data already read from fd which should be used before starting to read new data.

Parameters

fd

a file descriptor

 

ip

the IP address of the other end

 

port

the port used by the other end

 

initial_buffer

data already read from fd

 

conn

storage for a GstRTSPConnection

 

Returns

GST_RTSP_OK when conn contains a valid connection.

Since 0.10.25


gst_rtsp_connection_accept ()

GstRTSPResult
gst_rtsp_connection_accept (gint sock,
                            GstRTSPConnection **conn);

Accept a new connection on sock and create a new GstRTSPConnection for handling communication on new socket.

Parameters

sock

a socket

 

conn

storage for a GstRTSPConnection

 

Returns

GST_RTSP_OK when conn contains a valid connection.

Since 0.10.23


gst_rtsp_connection_connect ()

GstRTSPResult
gst_rtsp_connection_connect (GstRTSPConnection *conn,
                             GTimeVal *timeout);

Attempt to connect to the url of conn made with gst_rtsp_connection_create(). If timeout is NULL this function can block forever. If timeout contains a valid timeout, this function will return GST_RTSP_ETIMEOUT after the timeout expired.

This function can be cancelled with gst_rtsp_connection_flush().

Parameters

conn

a GstRTSPConnection

 

timeout

a GTimeVal timeout

 

Returns

GST_RTSP_OK when a connection could be made.


gst_rtsp_connection_close ()

GstRTSPResult
gst_rtsp_connection_close (GstRTSPConnection *conn);

Close the connected conn . After this call, the connection is in the same state as when it was first created.

Parameters

conn

a GstRTSPConnection

 

Returns

GST_RTSP_OK on success.


gst_rtsp_connection_free ()

GstRTSPResult
gst_rtsp_connection_free (GstRTSPConnection *conn);

Close and free conn .

Parameters

conn

a GstRTSPConnection

 

Returns

GST_RTSP_OK on success.


gst_rtsp_connection_read ()

GstRTSPResult
gst_rtsp_connection_read (GstRTSPConnection *conn,
                          guint8 *data,
                          guint size,
                          GTimeVal *timeout);

Attempt to read size bytes into data from the connected conn , blocking up to the specified timeout . timeout can be NULL, in which case this function might block forever.

This function can be cancelled with gst_rtsp_connection_flush().

Parameters

conn

a GstRTSPConnection

 

data

the data to read

 

size

the size of data

 

timeout

a timeout value or NULL

 

Returns

GST_RTSP_OK on success.


gst_rtsp_connection_write ()

GstRTSPResult
gst_rtsp_connection_write (GstRTSPConnection *conn,
                           const guint8 *data,
                           guint size,
                           GTimeVal *timeout);

Attempt to write size bytes of data to the connected conn , blocking up to the specified timeout . timeout can be NULL, in which case this function might block forever.

This function can be cancelled with gst_rtsp_connection_flush().

Parameters

conn

a GstRTSPConnection

 

data

the data to write

 

size

the size of data

 

timeout

a timeout value or NULL

 

Returns

GST_RTSP_OK on success.


gst_rtsp_connection_poll ()

GstRTSPResult
gst_rtsp_connection_poll (GstRTSPConnection *conn,
                          GstRTSPEvent events,
                          GstRTSPEvent *revents,
                          GTimeVal *timeout);

Wait up to the specified timeout for the connection to become available for at least one of the operations specified in events . When the function returns with GST_RTSP_OK, revents will contain a bitmask of available operations on conn .

timeout can be NULL, in which case this function might block forever.

This function can be cancelled with gst_rtsp_connection_flush().

Parameters

conn

a GstRTSPConnection

 

events

a bitmask of GstRTSPEvent flags to check

 

revents

location for result flags

 

timeout

a timeout

 

Returns

GST_RTSP_OK on success.

Since 0.10.15


gst_rtsp_connection_send ()

GstRTSPResult
gst_rtsp_connection_send (GstRTSPConnection *conn,
                          GstRTSPMessage *message,
                          GTimeVal *timeout);

Attempt to send message to the connected conn , blocking up to the specified timeout . timeout can be NULL, in which case this function might block forever.

This function can be cancelled with gst_rtsp_connection_flush().

Parameters

conn

a GstRTSPConnection

 

message

the message to send

 

timeout

a timeout value or NULL

 

Returns

GST_RTSP_OK on success.


gst_rtsp_connection_receive ()

GstRTSPResult
gst_rtsp_connection_receive (GstRTSPConnection *conn,
                             GstRTSPMessage *message,
                             GTimeVal *timeout);

Attempt to read into message from the connected conn , blocking up to the specified timeout . timeout can be NULL, in which case this function might block forever.

This function can be cancelled with gst_rtsp_connection_flush().

Parameters

conn

a GstRTSPConnection

 

message

the message to read

 

timeout

a timeout value or NULL

 

Returns

GST_RTSP_OK on success.


gst_rtsp_connection_next_timeout ()

GstRTSPResult
gst_rtsp_connection_next_timeout (GstRTSPConnection *conn,
                                  GTimeVal *timeout);

Calculate the next timeout for conn , storing the result in timeout .

Parameters

conn

a GstRTSPConnection

 

timeout

a timeout

 

Returns

GST_RTSP_OK.


gst_rtsp_connection_reset_timeout ()

GstRTSPResult
gst_rtsp_connection_reset_timeout (GstRTSPConnection *conn);

Reset the timeout of conn .

Parameters

conn

a GstRTSPConnection

 

Returns

GST_RTSP_OK.


gst_rtsp_connection_flush ()

GstRTSPResult
gst_rtsp_connection_flush (GstRTSPConnection *conn,
                           gboolean flush);

Start or stop the flushing action on conn . When flushing, all current and future actions on conn will return GST_RTSP_EINTR until the connection is set to non-flushing mode again.

Parameters

conn

a GstRTSPConnection

 

flush

start or stop the flush

 

Returns

GST_RTSP_OK.


gst_rtsp_connection_set_auth ()

GstRTSPResult
gst_rtsp_connection_set_auth (GstRTSPConnection *conn,
                              GstRTSPAuthMethod method,
                              const gchar *user,
                              const gchar *pass);

Configure conn for authentication mode method with user and pass as the user and password respectively.

Parameters

conn

a GstRTSPConnection

 

method

authentication method

 

user

the user

 

pass

the password

 

Returns

GST_RTSP_OK.


gst_rtsp_connection_set_auth_param ()

void
gst_rtsp_connection_set_auth_param (GstRTSPConnection *conn,
                                    const gchar *param,
                                    const gchar *value);

Setup conn with authentication directives. This is not necesary for methods GST_RTSP_AUTH_NONE and GST_RTSP_AUTH_BASIC. For GST_RTSP_AUTH_DIGEST, directives should be taken from the digest challenge in the WWW-Authenticate response header and can include realm, domain, nonce, opaque, stale, algorithm, qop as per RFC2617.

Parameters

conn

a GstRTSPConnection

 

param

authentication directive

 

value

value

 

Since 0.10.20


gst_rtsp_connection_clear_auth_params ()

void
gst_rtsp_connection_clear_auth_params (GstRTSPConnection *conn);

Clear the list of authentication directives stored in conn .

Parameters

conn

a GstRTSPConnection

 

Since 0.10.20


gst_rtsp_connection_set_qos_dscp ()

GstRTSPResult
gst_rtsp_connection_set_qos_dscp (GstRTSPConnection *conn,
                                  guint qos_dscp);

Configure conn to use the specified DSCP value.

Parameters

conn

a GstRTSPConnection

 

qos_dscp

DSCP value

 

Returns

GST_RTSP_OK on success.

Since 0.10.20


gst_rtsp_connection_set_ip ()

void
gst_rtsp_connection_set_ip (GstRTSPConnection *conn,
                            const gchar *ip);

Set the IP address of the server.

Parameters

conn

a GstRTSPConnection

 

ip

an ip address

 

Since 0.10.23


gst_rtsp_connection_get_ip ()

const gchar *
gst_rtsp_connection_get_ip (const GstRTSPConnection *conn);

Retrieve the IP address of the other end of conn .

Parameters

conn

a GstRTSPConnection

 

Returns

The IP address as a string. this value remains valid until the connection is closed.

Since 0.10.20


gst_rtsp_connection_get_url ()

GstRTSPUrl *
gst_rtsp_connection_get_url (const GstRTSPConnection *conn);

Retrieve the URL of the other end of conn .

Parameters

conn

a GstRTSPConnection

 

Returns

The URL. This value remains valid until the connection is freed.

Since 0.10.23


gst_rtsp_connection_set_tunneled ()

void
gst_rtsp_connection_set_tunneled (GstRTSPConnection *conn,
                                  gboolean tunneled);

Set the HTTP tunneling state of the connection. This must be configured before the conn is connected.

Parameters

conn

a GstRTSPConnection

 

tunneled

the new state

 

Since 0.10.23


gst_rtsp_connection_is_tunneled ()

gboolean
gst_rtsp_connection_is_tunneled (const GstRTSPConnection *conn);

Get the tunneling state of the connection.

Parameters

conn

a GstRTSPConnection

 

Returns

if conn is using HTTP tunneling.

Since 0.10.23


gst_rtsp_connection_get_tunnelid ()

const gchar *
gst_rtsp_connection_get_tunnelid (const GstRTSPConnection *conn);

Get the tunnel session id the connection.

Parameters

conn

a GstRTSPConnection

 

Returns

returns a non-empty string if conn is being tunneled over HTTP.

Since 0.10.23


gst_rtsp_connection_do_tunnel ()

GstRTSPResult
gst_rtsp_connection_do_tunnel (GstRTSPConnection *conn,
                               GstRTSPConnection *conn2);

If conn received the first tunnel connection and conn2 received the second tunnel connection, link the two connections together so that conn manages the tunneled connection.

After this call, conn2 cannot be used anymore and must be freed with gst_rtsp_connection_free().

If conn2 is NULL then only the base64 decoding context will be setup for conn .

Parameters

conn

a GstRTSPConnection

 

conn2

a GstRTSPConnection or NULL

 

Returns

return GST_RTSP_OK on success.

Since 0.10.23


gst_rtsp_connection_get_readfd ()

gint
gst_rtsp_connection_get_readfd (const GstRTSPConnection *conn);

Get the file descriptor for reading.

Parameters

conn

a GstRTSPConnection

 

Returns

the file descriptor used for reading or -1 on error. The file descriptor remains valid until the connection is closed.

Since 0.10.23


gst_rtsp_connection_get_writefd ()

gint
gst_rtsp_connection_get_writefd (const GstRTSPConnection *conn);

Get the file descriptor for writing.

Parameters

conn

a GstRTSPConnection

 

Returns

the file descriptor used for writing or -1 on error. The file descriptor remains valid until the connection is closed.

Since 0.10.23


gst_rtsp_connection_set_http_mode ()

void
gst_rtsp_connection_set_http_mode (GstRTSPConnection *conn,
                                   gboolean enable);

By setting the HTTP mode to TRUE the message parsing will support HTTP messages in addition to the RTSP messages. It will also disable the automatic handling of setting up an HTTP tunnel.

Parameters

conn

a GstRTSPConnection

 

enable

TRUE to enable manual HTTP mode

 

Since 0.10.25


gst_rtsp_connection_set_proxy ()

GstRTSPResult
gst_rtsp_connection_set_proxy (GstRTSPConnection *conn,
                               const gchar *host,
                               guint port);

Set the proxy host and port.

Parameters

conn

a GstRTSPConnection

 

host

the proxy host

 

port

the proxy port

 

Returns

GST_RTSP_OK.

Since 0.10.23


gst_rtsp_watch_new ()

GstRTSPWatch *
gst_rtsp_watch_new (GstRTSPConnection *conn,
                    GstRTSPWatchFuncs *funcs,
                    gpointer user_data,
                    GDestroyNotify notify);

Create a watch object for conn . The functions provided in funcs will be called with user_data when activity happened on the watch.

The new watch is usually created so that it can be attached to a maincontext with gst_rtsp_watch_attach().

conn must exist for the entire lifetime of the watch.

Parameters

conn

a GstRTSPConnection

 

funcs

watch functions

 

user_data

user data to pass to funcs

 

notify

notify when user_data is not referenced anymore

 

Returns

a GstRTSPWatch that can be used for asynchronous RTSP communication. Free with gst_rtsp_watch_unref() after usage.

Since 0.10.23


gst_rtsp_watch_unref ()

void
gst_rtsp_watch_unref (GstRTSPWatch *watch);

Decreases the reference count of watch by one. If the resulting reference count is zero the watch and associated memory will be destroyed.

Parameters

watch

a GstRTSPWatch

 

Since 0.10.23


gst_rtsp_watch_attach ()

guint
gst_rtsp_watch_attach (GstRTSPWatch *watch,
                       GMainContext *context);

Adds a GstRTSPWatch to a context so that it will be executed within that context.

Parameters

watch

a GstRTSPWatch

 

context

a GMainContext (if NULL, the default context will be used)

 

Returns

the ID (greater than 0) for the watch within the GMainContext.

Since 0.10.23


gst_rtsp_watch_reset ()

void
gst_rtsp_watch_reset (GstRTSPWatch *watch);

Reset watch , this is usually called after gst_rtsp_connection_do_tunnel() when the file descriptors of the connection might have changed.

Parameters

watch

a GstRTSPWatch

 

Since 0.10.23


gst_rtsp_watch_queue_message ()

guint
gst_rtsp_watch_queue_message (GstRTSPWatch *watch,
                              GstRTSPMessage *message);

gst_rtsp_watch_queue_message is deprecated and should not be used in newly-written code.

Use gst_rtsp_watch_send_message()

Queue a message for transmission in watch . The contents of this message will be serialized and transmitted when the connection of the watch becomes writable.

The return value of this function will be used as the id argument in the message_sent callback.

Parameters

watch

a GstRTSPWatch

 

message

a GstRTSPMessage

 

Returns

an id.

Since 0.10.23


gst_rtsp_watch_queue_data ()

guint
gst_rtsp_watch_queue_data (GstRTSPWatch *watch,
                           const guint8 *data,
                           guint size);

gst_rtsp_watch_queue_data is deprecated and should not be used in newly-written code.

Use gst_rtsp_watch_write_data()

Queue data for transmission in watch . It will be transmitted when the connection of the watch becomes writable.

This function will take ownership of data and g_free() it after use.

The return value of this function will be used as the id argument in the message_sent callback.

Parameters

watch

a GstRTSPWatch

 

data

the data to queue

 

size

the size of data

 

Returns

an id.

Since 0.10.24


gst_rtsp_watch_send_message ()

GstRTSPResult
gst_rtsp_watch_send_message (GstRTSPWatch *watch,
                             GstRTSPMessage *message,
                             guint *id);

Send a message using the connection of the watch . If it cannot be sent immediately, it will be queued for transmission in watch . The contents of message will then be serialized and transmitted when the connection of the watch becomes writable. In case the message is queued, the ID returned in id will be non-zero and used as the ID argument in the message_sent callback.

Parameters

watch

a GstRTSPWatch

 

message

a GstRTSPMessage

 

id

location for a message ID or NULL

 

Returns

GST_RTSP_OK on success.

Since 0.10.25


gst_rtsp_watch_write_data ()

GstRTSPResult
gst_rtsp_watch_write_data (GstRTSPWatch *watch,
                           const guint8 *data,
                           guint size,
                           guint *id);

Write data using the connection of the watch . If it cannot be sent immediately, it will be queued for transmission in watch . The contents of message will then be serialized and transmitted when the connection of the watch becomes writable. In case the message is queued, the ID returned in id will be non-zero and used as the ID argument in the message_sent callback.

This function will take ownership of data and g_free() it after use.

Parameters

watch

a GstRTSPWatch

 

data

the data to queue

 

size

the size of data

 

id

location for a message ID or NULL

 

Returns

GST_RTSP_OK on success.

Since 0.10.25

Types and Values

GstRTSPConnection

typedef struct _GstRTSPConnection GstRTSPConnection;

Opaque RTSP connection object.


GstRTSPWatch

typedef struct _GstRTSPWatch GstRTSPWatch;

Opaque RTSP watch object that can be used for asynchronous RTSP operations.


GstRTSPWatchFuncs

typedef struct {
  GstRTSPResult     (*message_received) (GstRTSPWatch *watch, GstRTSPMessage *message,
                                         gpointer user_data);
  GstRTSPResult     (*message_sent)     (GstRTSPWatch *watch, guint id,
                                         gpointer user_data);
  GstRTSPResult     (*closed)           (GstRTSPWatch *watch, gpointer user_data);
  GstRTSPResult     (*error)            (GstRTSPWatch *watch, GstRTSPResult result,
                                         gpointer user_data);
  GstRTSPStatusCode (*tunnel_start)     (GstRTSPWatch *watch, gpointer user_data);
  GstRTSPResult     (*tunnel_complete)  (GstRTSPWatch *watch, gpointer user_data);
  GstRTSPResult     (*error_full)       (GstRTSPWatch *watch, GstRTSPResult result,
                                         GstRTSPMessage *message, guint id,
                                         gpointer user_data);
  GstRTSPResult     (*tunnel_lost)      (GstRTSPWatch *watch, gpointer user_data);
} GstRTSPWatchFuncs;

Callback functions from a GstRTSPWatch.

Members

message_received ()

callback when a message was received

 

message_sent ()

callback when a message was sent

 

closed ()

callback when the connection is closed

 

error ()

callback when an error occured

 

tunnel_start ()

a client started a tunneled connection. The tunnelid of the connection must be saved.

 

tunnel_complete ()

a client finished a tunneled connection. In this callback you usually pair the tunnelid of this connection with the saved one using gst_rtsp_connection_do_tunnel().

 

error_full ()

callback when an error occured with more information than the error callback. Since 0.10.25

 

tunnel_lost ()

callback when the post connection of a tunnel is closed. Since 0.10.29

 

Since 0.10.23

See Also

gstrtspurl