GstRTSPClient

## GstRTSPClient GstRTSPClient — A client connection state |

## Synopsis

    struct              GstRTSPClient;
    struct              GstRTSPClientClass;
    GstRTSPClient *     gst_rtsp_client_new                 (void);
    GstRTSPSessionPool * gst_rtsp_client_get_session_pool   (GstRTSPClient *client);
    void                gst_rtsp_client_set_session_pool    (GstRTSPClient *client,
                                                             GstRTSPSessionPool *pool);
    GstRTSPMountPoints * gst_rtsp_client_get_mount_points   (GstRTSPClient *client);
    void                gst_rtsp_client_set_mount_points    (GstRTSPClient *client,
                                                             GstRTSPMountPoints *mounts);
    GstRTSPAuth *       gst_rtsp_client_get_auth            (GstRTSPClient *client);
    void                gst_rtsp_client_set_auth            (GstRTSPClient *client,
                                                             GstRTSPAuth *auth);
    GstRTSPThreadPool * gst_rtsp_client_get_thread_pool     (GstRTSPClient *client);
    void                gst_rtsp_client_set_thread_pool     (GstRTSPClient *client,
                                                             GstRTSPThreadPool *pool);
    GstRTSPConnection * gst_rtsp_client_get_connection      (GstRTSPClient *client);
    gboolean            gst_rtsp_client_set_connection      (GstRTSPClient *client,
                                                             GstRTSPConnection *conn);
    guint               gst_rtsp_client_attach              (GstRTSPClient *client,
                                                             GMainContext *context);
    gboolean            (*GstRTSPClientSendFunc)            (GstRTSPClient *client,
                                                             GstRTSPMessage *message,
                                                             gboolean close,
                                                             gpointer user_data);
    void                gst_rtsp_client_set_send_func       (GstRTSPClient *client,
                                                             GstRTSPClientSendFunc func,
                                                             gpointer user_data,
                                                             GDestroyNotify notify);
    GstRTSPResult       gst_rtsp_client_handle_message      (GstRTSPClient *client,
                                                             GstRTSPMessage *message);
    GstRTSPResult       gst_rtsp_client_send_message        (GstRTSPClient *client,
                                                             GstRTSPSession *session,
                                                             GstRTSPMessage *message);
    GstRTSPFilterResult (*GstRTSPClientSessionFilterFunc)   (GstRTSPClient *client,
                                                             GstRTSPSession *sess,
                                                             gpointer user_data);
    GList *             gst_rtsp_client_session_filter      (GstRTSPClient *client,
                                                             GstRTSPClientSessionFilterFunc func,
                                                             gpointer user_data);

## Object Hierarchy

      GObject
       +----GstRTSPClient

## Properties

      "mount-points"             GstRTSPMountPoints*   : Read / Write
      "session-pool"             GstRTSPSessionPool*   : Read / Write

## Signals

      "closed"                                         : Run Last
      "describe-request"                               : Run Last
      "get-parameter-request"                          : Run Last
      "handle-response"                                : Run Last
      "new-session"                                    : Run Last
      "options-request"                                : Run Last
      "pause-request"                                  : Run Last
      "play-request"                                   : Run Last
      "set-parameter-request"                          : Run Last
      "setup-request"                                  : Run Last
      "teardown-request"                               : Run Last

## Description

The client object handles the connection with a client for as long as a TCP connection is open.

A GstRTSPClient is created by GstRTSPServer when a new connection is accepted and it inherits the GstRTSPMountPoints, GstRTSPSessionPool, GstRTSPAuth and GstRTSPThreadPool from the server.

The client connection should be configured with the GstRTSPConnection using `gst_rtsp_client_set_connection()` before it can be attached to a GMainContext using `gst_rtsp_client_attach()`. From then on the client will handle requests on the connection.

Use `gst_rtsp_client_session_filter()` to iterate or modify all the GstRTSPSession objects managed by the client object.

Last reviewed on 2013-07-11 (1.0.0)

## Details

### struct GstRTSPClient

    struct GstRTSPClient;

The client object represents the connection and its state with a client.

### struct GstRTSPClientClass

    struct GstRTSPClientClass {
      GObjectClass  parent_class;

      GstSDPMessage * (*create_sdp) (GstRTSPClient *client, GstRTSPMedia *media);
      gboolean        (*configure_client_media)     (GstRTSPClient * client,
                                                     GstRTSPMedia * media, GstRTSPStream * stream,
                                                     GstRTSPContext * ctx);
      gboolean        (*configure_client_transport) (GstRTSPClient * client,
                                                     GstRTSPContext * ctx,
                                                     GstRTSPTransport * ct);
      GstRTSPResult   (*params_set) (GstRTSPClient *client, GstRTSPContext *ctx);
      GstRTSPResult   (*params_get) (GstRTSPClient *client, GstRTSPContext *ctx);
      gchar *         (*make_path_from_uri) (GstRTSPClient *client, const GstRTSPUrl *uri);

      /* signals */
      void     (*closed)                  (GstRTSPClient *client);
      void     (*new_session)             (GstRTSPClient *client, GstRTSPSession *session);
      void     (*options_request)         (GstRTSPClient *client, GstRTSPContext *ctx);
      void     (*describe_request)        (GstRTSPClient *client, GstRTSPContext *ctx);
      void     (*setup_request)           (GstRTSPClient *client, GstRTSPContext *ctx);
      void     (*play_request)            (GstRTSPClient *client, GstRTSPContext *ctx);
      void     (*pause_request)           (GstRTSPClient *client, GstRTSPContext *ctx);
      void     (*teardown_request)        (GstRTSPClient *client, GstRTSPContext *ctx);
      void     (*set_parameter_request)   (GstRTSPClient *client, GstRTSPContext *ctx);
      void     (*get_parameter_request)   (GstRTSPClient *client, GstRTSPContext *ctx);
      void     (*handle_response)         (GstRTSPClient *client, GstRTSPContext *ctx);
    };

The client class structure.

GObjectClass `parent_class`; |
`create_sdp` () | called when the SDP needs to be created for media.
`configure_client_media` () | called when the stream in media needs to be configured. The default implementation will configure the blocksize on the payloader when spcified in the request headers.
`configure_client_transport` () | called when the client transport needs to be configured.
`params_set` () | set parameters. This function should also initialize the RTSP response(ctx->response) via a call to `gst_rtsp_message_init_response()`
`params_get` () | get parameters. This function should also initialize the RTSP response(ctx->response) via a call to `gst_rtsp_message_init_response()`
`make_path_from_uri` () |
`closed` () |
`new_session` () |
`options_request` () |
`describe_request` () |
`setup_request` () |
`play_request` () |
`pause_request` () |
`teardown_request` () |
`set_parameter_request` () |
`get_parameter_request` () |
`handle_response` () |

### gst_rtsp_client_new ()

    GstRTSPClient *     gst_rtsp_client_new                 (void);

Create a new GstRTSPClient instance.

Returns : | a new GstRTSPClient

### gst_rtsp_client_get_session_pool ()

    GstRTSPSessionPool * gst_rtsp_client_get_session_pool   (GstRTSPClient *client);

Get the GstRTSPSessionPool object that `client` uses to manage its sessions.

`client` : | a GstRTSPClient
Returns : | a GstRTSPSessionPool, unref after usage. [transfer full]

### gst_rtsp_client_set_session_pool ()

    void                gst_rtsp_client_set_session_pool    (GstRTSPClient *client,
                                                             GstRTSPSessionPool *pool);

Set `pool` as the sessionpool for `client` which it will use to find or allocate sessions. the sessionpool is usually inherited from the server that created the client but can be overridden later.

`client` : | a GstRTSPClient
`pool` : | a GstRTSPSessionPool

### gst_rtsp_client_get_mount_points ()

    GstRTSPMountPoints * gst_rtsp_client_get_mount_points   (GstRTSPClient *client);

Get the GstRTSPMountPoints object that `client` uses to manage its sessions.

`client` : | a GstRTSPClient
Returns : | a GstRTSPMountPoints, unref after usage. [transfer full]

### gst_rtsp_client_set_mount_points ()

    void                gst_rtsp_client_set_mount_points    (GstRTSPClient *client,
                                                             GstRTSPMountPoints *mounts);

Set `mounts` as the mount points for `client` which it will use to map urls to media streams. These mount points are usually inherited from the server that created the client but can be overriden later.

`client` : | a GstRTSPClient
`mounts` : | a GstRTSPMountPoints

### gst_rtsp_client_get_auth ()

    GstRTSPAuth *       gst_rtsp_client_get_auth            (GstRTSPClient *client);

Get the GstRTSPAuth used as the authentication manager of `client`.

`client` : | a GstRTSPClient
Returns : | the GstRTSPAuth of `client`. `g_object_unref()` after usage. [transfer full]

### gst_rtsp_client_set_auth ()

    void                gst_rtsp_client_set_auth            (GstRTSPClient *client,
                                                             GstRTSPAuth *auth);

configure `auth` to be used as the authentication manager of `client`.

`client` : | a GstRTSPClient
`auth` : | a GstRTSPAuth

### gst_rtsp_client_get_thread_pool ()

    GstRTSPThreadPool * gst_rtsp_client_get_thread_pool     (GstRTSPClient *client);

Get the GstRTSPThreadPool used as the thread pool of `client`.

`client` : | a GstRTSPClient
Returns : | the GstRTSPThreadPool of `client`. `g_object_unref()` after usage. [transfer full]

### gst_rtsp_client_set_thread_pool ()

    void                gst_rtsp_client_set_thread_pool     (GstRTSPClient *client,
                                                             GstRTSPThreadPool *pool);

configure `pool` to be used as the thread pool of `client`.

`client` : | a GstRTSPClient
`pool` : | a GstRTSPThreadPool

### gst_rtsp_client_get_connection ()

    GstRTSPConnection * gst_rtsp_client_get_connection      (GstRTSPClient *client);

Get the GstRTSPConnection of `client`.

`client` : | a GstRTSPClient
Returns : | the GstRTSPConnection of `client`. The connection object returned remains valid until the client is freed. [transfer none]

### gst_rtsp_client_set_connection ()

    gboolean            gst_rtsp_client_set_connection      (GstRTSPClient *client,
                                                             GstRTSPConnection *conn);

Set the GstRTSPConnection of `client`. This function takes ownership of `conn`.

`client` : | a GstRTSPClient
`conn` : | a GstRTSPConnection. [transfer full]
Returns : | `TRUE` on success.

### gst_rtsp_client_attach ()

    guint               gst_rtsp_client_attach              (GstRTSPClient *client,
                                                             GMainContext *context);

Attaches `client` to `context`. When the mainloop for `context` is run, the client will be dispatched. When `context` is `NULL`, the default context will be used).

This function should be called when the client properties and urls are fully configured and the client is ready to start.

`client` : | a GstRTSPClient
`context` : | a GMainContext. [allow-none]
Returns : | the ID (greater than 0) for the source within the GMainContext.

### GstRTSPClientSendFunc ()

    gboolean            (*GstRTSPClientSendFunc)            (GstRTSPClient *client,
                                                             GstRTSPMessage *message,
                                                             gboolean close,
                                                             gpointer user_data);

This callback is called when `client` wants to send `message`. When `close` is `TRUE`, the connection should be closed when the message has been sent.

`client` : | a GstRTSPClient
`message` : | a GstRTSPMessage
`close` : | close the connection
`user_data` : | user data when registering the callback
Returns : | `TRUE` on success.

### gst_rtsp_client_set_send_func ()

    void                gst_rtsp_client_set_send_func       (GstRTSPClient *client,
                                                             GstRTSPClientSendFunc func,
                                                             gpointer user_data,
                                                             GDestroyNotify notify);

Set `func` as the callback that will be called when a new message needs to be sent to the client. `user_data` is passed to `func` and `notify` is called when `user_data` is no longer in use.

By default, the client will send the messages on the GstRTSPConnection that was configured with `gst_rtsp_client_attach()` was called.

`client` : | a GstRTSPClient
`func` : | a GstRTSPClientSendFunc
`user_data` : | user data passed to `func`
`notify` : | called when `user_data` is no longer in use

### gst_rtsp_client_handle_message ()

    GstRTSPResult       gst_rtsp_client_handle_message      (GstRTSPClient *client,
                                                             GstRTSPMessage *message);

Let the client handle `message`.

`client` : | a GstRTSPClient
`message` : | an GstRTSPMessage
Returns : | a GstRTSPResult.

### gst_rtsp_client_send_message ()

    GstRTSPResult       gst_rtsp_client_send_message        (GstRTSPClient *client,
                                                             GstRTSPSession *session,
                                                             GstRTSPMessage *message);

Send a message message to the remote end. `message` must be a GST_RTSP_MESSAGE_REQUEST or a GST_RTSP_MESSAGE_RESPONSE.

`client` : | a GstRTSPClient
`session` : | a GstRTSPSession to send the message to or `NULL`
`message` : | The GstRTSPMessage to send

### GstRTSPClientSessionFilterFunc ()

    GstRTSPFilterResult (*GstRTSPClientSessionFilterFunc)   (GstRTSPClient *client,
                                                             GstRTSPSession *sess,
                                                             gpointer user_data);

This function will be called by the `gst_rtsp_client_session_filter()`. An implementation should return a value of GstRTSPFilterResult.

When this function returns GST_RTSP_FILTER_REMOVE, `sess` will be removed from `client`.

A return value of GST_RTSP_FILTER_KEEP will leave `sess` untouched in `client`.

A value of GST_RTSP_FILTER_REF will add `sess` to the result GList of `gst_rtsp_client_session_filter()`.

`client` : | a GstRTSPClient object
`sess` : | a GstRTSPSession in `client`
`user_data` : | user data that has been given to `gst_rtsp_client_session_filter()`
Returns : | a GstRTSPFilterResult.

### gst_rtsp_client_session_filter ()

    GList *             gst_rtsp_client_session_filter      (GstRTSPClient *client,
                                                             GstRTSPClientSessionFilterFunc func,
                                                             gpointer user_data);

Call `func` for each session managed by `client`. The result value of `func` determines what happens to the session. `func` will be called with `client` locked so no further actions on `client` can be performed from `func`.

If `func` returns GST_RTSP_FILTER_REMOVE, the session will be removed from `client`.

If `func` returns GST_RTSP_FILTER_KEEP, the session will remain in `client`.

If `func` returns GST_RTSP_FILTER_REF, the session will remain in `client` but will also be added with an additional ref to the result GList of this function..

When `func` is `NULL`, GST_RTSP_FILTER_REF will be assumed for each session.

`client` : | a GstRTSPClient
`func` : | a callback. [scope call][allow-none]
`user_data` : | user data passed to `func`
Returns : | a GList with all sessions for which `func` returned GST_RTSP_FILTER_REF. After usage, each element in the GList should be unreffed before the list is freed. [element-type GstRTSPSession][transfer full]

## Property Details

### The `"mount-points"` property

      "mount-points"             GstRTSPMountPoints*   : Read / Write

The mount points to use for client session.

### The `"session-pool"` property

      "session-pool"             GstRTSPSessionPool*   : Read / Write

The session pool to use for client session.

## Signal Details

### The `"closed"` signal

    void                user_function                      (GstRTSPClient *gstrtspclient,
                                                            gpointer       user_data)          : Run Last

### The `"describe-request"` signal

    void                user_function                      (GstRTSPClient *gstrtspclient,
                                                            gpointer       arg1,
                                                            gpointer       user_data)          : Run Last

### The `"get-parameter-request"` signal

    void                user_function                      (GstRTSPClient *gstrtspclient,
                                                            gpointer       arg1,
                                                            gpointer       user_data)          : Run Last

### The `"handle-response"` signal

    void                user_function                      (GstRTSPClient *gstrtspclient,
                                                            gpointer       arg1,
                                                            gpointer       user_data)          : Run Last

### The `"new-session"` signal

    void                user_function                      (GstRTSPClient  *gstrtspclient,
                                                            GstRTSPSession *arg1,
                                                            gpointer        user_data)          : Run Last

### The `"options-request"` signal

    void                user_function                      (GstRTSPClient *gstrtspclient,
                                                            gpointer       arg1,
                                                            gpointer       user_data)          : Run Last

### The `"pause-request"` signal

    void                user_function                      (GstRTSPClient *gstrtspclient,
                                                            gpointer       arg1,
                                                            gpointer       user_data)          : Run Last

### The `"play-request"` signal

    void                user_function                      (GstRTSPClient *gstrtspclient,
                                                            gpointer       arg1,
                                                            gpointer       user_data)          : Run Last

### The `"set-parameter-request"` signal

    void                user_function                      (GstRTSPClient *gstrtspclient,
                                                            gpointer       arg1,
                                                            gpointer       user_data)          : Run Last

### The `"setup-request"` signal

    void                user_function                      (GstRTSPClient *gstrtspclient,
                                                            gpointer       arg1,
                                                            gpointer       user_data)          : Run Last

### The `"teardown-request"` signal

    void                user_function                      (GstRTSPClient *gstrtspclient,
                                                            gpointer       arg1,
                                                            gpointer       user_data)          : Run Last

## See Also

GstRTSPServer, GstRTSPThreadPool