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

`conn` : | a GstRTSPConnection
`conn2` : | a GstRTSPConnection
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 cseq,
                                             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);
    } 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()`.

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);

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 returned as the cseq argument in the message_sent callback.

`watch` : | a GstRTSPWatch
`message` : | a GstRTSPMessage
Returns : | the sequence number of the message or -1 if the cseq could not be determined.

Since 0.10.23

## See Also

gstrtspurl