## 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_accept          (gint sock,
                                                             GstRTSPConnection **conn);
    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);
                        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);
    guint               gst_rtsp_watch_queue_message        (GstRTSPWatch *watch,
                                                             GstRTSPMessage *message);

## 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
Returns : | GST_RTSP_OK when `conn` contains a valid connection.

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

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

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

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

`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

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

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

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

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

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

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

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

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

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

`conn` : | a GstRTSPConnection
`conn2` : | a GstRTSPConnection or `NULL`
Returns : | return GST_RTSP_OK on success.

Since 0.10.23

### 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);
    } 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. Since 0.10.25

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.

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

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

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

`watch` : | a GstRTSPWatch

Since 0.10.23

### gst_rtsp_watch_queue_message ()

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

### Warning

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

`watch` : | a GstRTSPWatch
`message` : | a GstRTSPMessage
Returns : | an id.

Since 0.10.23

## See Also

gstrtspurl