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

## Types and Values

| GstRTSPConnection
| GstRTSPWatch
| GstRTSPWatchFuncs

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

Last reviewed on 2007-07-24 (0.10.14)

## Functions

### gst_rtsp_connection_create ()

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

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

A copy of `url` will be made.

#### Parameters

url | a GstRTSPUrl |
conn | storage for a GstRTSPConnection. | [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.

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

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

## Types and Values

### GstRTSPConnection

    typedef struct _GstRTSPConnection GstRTSPConnection;

Opaque RTSP connection object.

### GstRTSPWatch

    typedef struct _GstRTSPWatch GstRTSPWatch;

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

### GstRTSPWatchFuncs

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

Callback functions from a GstRTSPWatch.

#### Members

`message_received` () | callback when a message was received |
`message_sent` () | callback when a message was sent |
`closed` () | callback when the connection is closed |
`error` () | callback when an error occured |
`tunnel_start` () | a client started a tunneled connection. The tunnelid of the connection must be saved. |
`tunnel_complete` () | a client finished a tunneled connection. In this callback you usually pair the tunnelid of this connection with the saved one using `gst_rtsp_connection_do_tunnel()`. |
`error_full` () | callback when an error occured with more information than the `error` callback. |
`tunnel_lost` () | callback when the post connection of a tunnel is closed. |

## See Also

gstrtspurl