gstrtspconnection

gstrtspconnection — manage RTSP connections

Synopsis

#include <gst/rtsp/gstrtspconnection.h>

                    GstRTSPConnection;
GstRTSPResult       gst_rtsp_connection_create          (const GstRTSPUrl *url,
                                                         GstRTSPConnection **conn);
GstRTSPResult       gst_rtsp_connection_create_from_socket
                                                        (GSocket *socket,
                                                         const gchar *ip,
                                                         guint16 port,
                                                         const gchar *initial_buffer,
                                                         GstRTSPConnection **conn);
GstRTSPResult       gst_rtsp_connection_accept          (GSocket *socket,
                                                         GstRTSPConnection **conn,
                                                         GCancellable *cancellable);
GstRTSPResult       gst_rtsp_connection_connect         (GstRTSPConnection *conn,
                                                         GTimeVal *timeout);
GstRTSPResult       gst_rtsp_connection_close           (GstRTSPConnection *conn);
GstRTSPResult       gst_rtsp_connection_free            (GstRTSPConnection *conn);
GstRTSPResult       gst_rtsp_connection_read            (GstRTSPConnection *conn,
                                                         guint8 *data,
                                                         guint size,
                                                         GTimeVal *timeout);
GstRTSPResult       gst_rtsp_connection_write           (GstRTSPConnection *conn,
                                                         const guint8 *data,
                                                         guint size,
                                                         GTimeVal *timeout);
GstRTSPResult       gst_rtsp_connection_poll            (GstRTSPConnection *conn,
                                                         GstRTSPEvent events,
                                                         GstRTSPEvent *revents,
                                                         GTimeVal *timeout);
GstRTSPResult       gst_rtsp_connection_send            (GstRTSPConnection *conn,
                                                         GstRTSPMessage *message,
                                                         GTimeVal *timeout);
GstRTSPResult       gst_rtsp_connection_receive         (GstRTSPConnection *conn,
                                                         GstRTSPMessage *message,
                                                         GTimeVal *timeout);
GstRTSPResult       gst_rtsp_connection_next_timeout    (GstRTSPConnection *conn,
                                                         GTimeVal *timeout);
GstRTSPResult       gst_rtsp_connection_reset_timeout   (GstRTSPConnection *conn);
GstRTSPResult       gst_rtsp_connection_flush           (GstRTSPConnection *conn,
                                                         gboolean flush);
GstRTSPResult       gst_rtsp_connection_set_auth        (GstRTSPConnection *conn,
                                                         GstRTSPAuthMethod method,
                                                         const gchar *user,
                                                         const gchar *pass);
void                gst_rtsp_connection_set_auth_param  (GstRTSPConnection *conn,
                                                         const gchar *param,
                                                         const gchar *value);
void                gst_rtsp_connection_clear_auth_params
                                                        (GstRTSPConnection *conn);
GstRTSPResult       gst_rtsp_connection_set_qos_dscp    (GstRTSPConnection *conn,
                                                         guint qos_dscp);
void                gst_rtsp_connection_set_ip          (GstRTSPConnection *conn,
                                                         const gchar *ip);
const gchar *       gst_rtsp_connection_get_ip          (const GstRTSPConnection *conn);
GstRTSPUrl *        gst_rtsp_connection_get_url         (const GstRTSPConnection *conn);
void                gst_rtsp_connection_set_tunneled    (GstRTSPConnection *conn,
                                                         gboolean tunneled);
gboolean            gst_rtsp_connection_is_tunneled     (const GstRTSPConnection *conn);
const gchar *       gst_rtsp_connection_get_tunnelid    (const GstRTSPConnection *conn);
GstRTSPResult       gst_rtsp_connection_do_tunnel       (GstRTSPConnection *conn,
                                                         GstRTSPConnection *conn2);
void                gst_rtsp_connection_set_http_mode   (GstRTSPConnection *conn,
                                                         gboolean enable);
GstRTSPResult       gst_rtsp_connection_set_proxy       (GstRTSPConnection *conn,
                                                         const gchar *host,
                                                         guint port);
GSocket *           gst_rtsp_connection_get_read_socket (const GstRTSPConnection *conn);
GSocket *           gst_rtsp_connection_get_write_socket
                                                        (const GstRTSPConnection *conn);
                    GstRTSPWatch;
                    GstRTSPWatchFuncs;
GstRTSPWatch *      gst_rtsp_watch_new                  (GstRTSPConnection *conn,
                                                         GstRTSPWatchFuncs *funcs,
                                                         gpointer user_data,
                                                         GDestroyNotify notify);
void                gst_rtsp_watch_unref                (GstRTSPWatch *watch);
guint               gst_rtsp_watch_attach               (GstRTSPWatch *watch,
                                                         GMainContext *context);
void                gst_rtsp_watch_reset                (GstRTSPWatch *watch);
GstRTSPResult       gst_rtsp_watch_send_message         (GstRTSPWatch *watch,
                                                         GstRTSPMessage *message,
                                                         guint *id);
GstRTSPResult       gst_rtsp_watch_write_data           (GstRTSPWatch *watch,
                                                         const guint8 *data,
                                                         guint size,
                                                         guint *id);

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)

Details

GstRTSPConnection

typedef struct _GstRTSPConnection GstRTSPConnection;

Opaque RTSP connection object.


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.

url :

a GstRTSPUrl

conn :

storage for a GstRTSPConnection. [out][transfer full]

Returns :

GST_RTSP_OK when conn contains a valid connection.

gst_rtsp_connection_create_from_socket ()

GstRTSPResult       gst_rtsp_connection_create_from_socket
                                                        (GSocket *socket,
                                                         const gchar *ip,
                                                         guint16 port,
                                                         const gchar *initial_buffer,
                                                         GstRTSPConnection **conn);

Create a new GstRTSPConnection for handling communication on the existing socket socket. The initial_buffer contains zero terminated data already read from socket which should be used before starting to read new data.

socket :

a GSocket

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. [out][transfer full]

Returns :

GST_RTSP_OK when conn contains a valid connection.

gst_rtsp_connection_accept ()

GstRTSPResult       gst_rtsp_connection_accept          (GSocket *socket,
                                                         GstRTSPConnection **conn,
                                                         GCancellable *cancellable);

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

socket :

a socket

conn :

storage for a GstRTSPConnection. [out][transfer full]

cancellable :

a GCancellable to cancel the operation

Returns :

GST_RTSP_OK when conn contains a valid connection.

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

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.

conn :

a GstRTSPConnection

Returns :

GST_RTSP_OK on success.

gst_rtsp_connection_free ()

GstRTSPResult       gst_rtsp_connection_free            (GstRTSPConnection *conn);

Close and free conn.

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

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

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

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.

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

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

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.

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.

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.

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.

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.

conn :

a GstRTSPConnection

param :

authentication directive

value :

value

gst_rtsp_connection_clear_auth_params ()

void                gst_rtsp_connection_clear_auth_params
                                                        (GstRTSPConnection *conn);

Clear the list of authentication directives stored in conn.

conn :

a GstRTSPConnection

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.

conn :

a GstRTSPConnection

qos_dscp :

DSCP value

Returns :

GST_RTSP_OK on success.

gst_rtsp_connection_set_ip ()

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

Set the IP address of the server.

conn :

a GstRTSPConnection

ip :

an ip address

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.

conn :

a GstRTSPConnection

Returns :

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

gst_rtsp_connection_get_url ()

GstRTSPUrl *        gst_rtsp_connection_get_url         (const GstRTSPConnection *conn);

Retrieve the URL of the other end of conn.

conn :

a GstRTSPConnection

Returns :

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

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.

conn :

a GstRTSPConnection

tunneled :

the new state

gst_rtsp_connection_is_tunneled ()

gboolean            gst_rtsp_connection_is_tunneled     (const GstRTSPConnection *conn);

Get the tunneling state of the connection.

conn :

a GstRTSPConnection

Returns :

if conn is using HTTP tunneling.

gst_rtsp_connection_get_tunnelid ()

const gchar *       gst_rtsp_connection_get_tunnelid    (const GstRTSPConnection *conn);

Get the tunnel session id the connection.

conn :

a GstRTSPConnection

Returns :

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

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.

conn :

a GstRTSPConnection

conn2 :

a GstRTSPConnection or NULL

Returns :

return GST_RTSP_OK on success.

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.

conn :

a GstRTSPConnection

enable :

TRUE to enable manual HTTP mode

gst_rtsp_connection_set_proxy ()

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

Set the proxy host and port.

conn :

a GstRTSPConnection

host :

the proxy host

port :

the proxy port

Returns :

GST_RTSP_OK.

gst_rtsp_connection_get_read_socket ()

GSocket *           gst_rtsp_connection_get_read_socket (const GstRTSPConnection *conn);

gst_rtsp_connection_get_write_socket ()

GSocket *           gst_rtsp_connection_get_write_socket
                                                        (const GstRTSPConnection *conn);

Get the file descriptor for writing.

conn :

a GstRTSPConnection

Returns :

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

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.

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.

tunnel_lost ()

callback when the post connection of a tunnel is closed.

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.

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.

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.

watch :

a GstRTSPWatch

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.

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.

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.

watch :

a GstRTSPWatch

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.

watch :

a GstRTSPWatch

message :

a GstRTSPMessage

id :

location for a message ID or NULL. [out][allow-none]

Returns :

GST_RTSP_OK on success.

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.

watch :

a GstRTSPWatch

data :

the data to queue

size :

the size of data

id :

location for a message ID or NULL. [out][allow-none]

Returns :

GST_RTSP_OK on success.

See Also

gstrtspurl