gstrtspconnection

gstrtspconnection — manage RTSP connections

Functions

GstRTSPResult gst_rtsp_connection_create ()
GstRTSPResult gst_rtsp_connection_create_from_socket ()
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 ()
void gst_rtsp_connection_set_http_mode ()
GstRTSPResult gst_rtsp_connection_set_proxy ()
GSocket * gst_rtsp_connection_get_read_socket ()
GSocket * gst_rtsp_connection_get_write_socket ()
GTlsConnection * gst_rtsp_connection_get_tls ()
gboolean gst_rtsp_connection_set_tls_validation_flags ()
GTlsCertificateFlags gst_rtsp_connection_get_tls_validation_flags ()
GstRTSPWatch * gst_rtsp_watch_new ()
void gst_rtsp_watch_unref ()
guint gst_rtsp_watch_attach ()
void gst_rtsp_watch_reset ()
GstRTSPResult gst_rtsp_watch_send_message ()
GstRTSPResult gst_rtsp_watch_write_data ()
void gst_rtsp_watch_get_send_backlog ()
void gst_rtsp_watch_set_send_backlog ()
GstRTSPResult gst_rtsp_watch_wait_backlog ()

Types and Values

Object Hierarchy


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.

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.

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

Parameters

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.

Parameters

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

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.


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

 

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

 

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.


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

 

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.


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.


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

 

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.


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.


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.


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

 

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.


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.

Parameters

conn

a GstRTSPConnection

 

Returns

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

[transfer none]


gst_rtsp_connection_get_tls ()

GTlsConnection *
gst_rtsp_connection_get_tls (GstRTSPConnection *conn,
                             GError **error);

Get the TLS connection of conn .

For client side this will return the GTlsClientConnection when connected over TLS.

For server side connections, this function will create a GTlsServerConnection when called the first time and will return that same connection on subsequent calls. The server is then responsible for configuring the TLS connection.

Parameters

conn

a GstRTSPConnection

 

error

GError for error reporting, or NULL to ignore.

 

Returns

the TLS connection for conn .

[transfer none]

Since 1.2


gst_rtsp_connection_set_tls_validation_flags ()

gboolean
gst_rtsp_connection_set_tls_validation_flags
                               (GstRTSPConnection *conn,
                                GTlsCertificateFlags flags);

Sets the TLS validation flags to be used to verify the peer certificate when a TLS connection is established.

Parameters

conn

a GstRTSPConnection

 

flags

the validation flags.

 

Returns

TRUE if the validation flags are set correctly, or FALSE if conn is NULL or is not a TLS connection.

Since 1.2.1


gst_rtsp_connection_get_tls_validation_flags ()

GTlsCertificateFlags
gst_rtsp_connection_get_tls_validation_flags
                               (GstRTSPConnection *conn);

Gets the TLS validation flags used to verify the peer certificate when a TLS connection is established.

Parameters

conn

a GstRTSPConnection

 

Returns

the validationg flags.

Since 1.2.1


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.


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

 

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.


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

 

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.

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

If the amount of queued data exceeds the limits set with gst_rtsp_watch_set_send_backlog(), this function will return GST_RTSP_ENOMEM.

Parameters

watch

a GstRTSPWatch

 

data

the data to queue.

[array length=size][transfer full]

size

the size of data

 

id

location for a message ID or NULL.

[out][allow-none]

Returns

GST_RTSP_OK on success. GST_RTSP_ENOMEM when the backlog limits are reached. GST_RTSP_EINTR when watch was flushing.


gst_rtsp_watch_get_send_backlog ()

void
gst_rtsp_watch_get_send_backlog (GstRTSPWatch *watch,
                                 gsize *bytes,
                                 guint *messages);

Get the maximum amount of bytes and messages that will be queued in watch . See gst_rtsp_watch_set_send_backlog().

Parameters

watch

a GstRTSPWatch

 

bytes

maximum bytes.

[out][allow-none]

messages

maximum messages.

[out][allow-none]

Since 1.2


gst_rtsp_watch_set_send_backlog ()

void
gst_rtsp_watch_set_send_backlog (GstRTSPWatch *watch,
                                 gsize bytes,
                                 guint messages);

Set the maximum amount of bytes and messages that will be queued in watch . When the maximum amounts are exceeded, gst_rtsp_watch_write_data() and gst_rtsp_watch_send_message() will return GST_RTSP_ENOMEM.

A value of 0 for bytes or messages means no limits.

Parameters

watch

a GstRTSPWatch

 

bytes

maximum bytes

 

messages

maximum messages

 

Since 1.2


gst_rtsp_watch_wait_backlog ()

GstRTSPResult
gst_rtsp_watch_wait_backlog (GstRTSPWatch *watch,
                             GTimeVal *timeout);

Wait until there is place in the backlog queue, timeout is reached or watch is set to flushing.

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.

The typically use of this function is when gst_rtsp_watch_write_data returns GST_RTSP_ENOMEM. The caller then calls this function to wait for free space in the backlog queue and try again.

Parameters

watch

a GstRTSPWatch

 

timeout

a GTimeVal timeout

 

Returns

GST_RTSP_OK when if there is room in queue. GST_RTSP_ETIMEOUT when timeout was reached. GST_RTSP_EINTR when watch is flushing GST_RTSP_EINVAL when called with invalid parameters.

Since 1.4

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);
  GstRTSPResult     (*tunnel_http_response) (GstRTSPWatch *watch,
                                             GstRTSPMessage *request,
                                             GstRTSPMessage *response,
                                             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.

 

tunnel_lost ()

callback when the post connection of a tunnel is closed.

 

tunnel_http_response ()

callback when an HTTP response to the GET request is about to be sent for a tunneled connection. The response can be modified in the callback. Since 1.4.

 

See Also

gstrtspurl