GstRTSPClient: GStreamer RTSP Server Reference Manual

## GstRTSPClient GstRTSPClient — A client connection state |

## Functions

GstRTSPClient * | gst_rtsp_client_new ()
void | gst_rtsp_client_close ()
GstRTSPSessionPool * | gst_rtsp_client_get_session_pool ()
void | gst_rtsp_client_set_session_pool ()
GstRTSPMountPoints * | gst_rtsp_client_get_mount_points ()
void | gst_rtsp_client_set_mount_points ()
GstRTSPAuth * | gst_rtsp_client_get_auth ()
void | gst_rtsp_client_set_auth ()
GstRTSPThreadPool * | gst_rtsp_client_get_thread_pool ()
void | gst_rtsp_client_set_thread_pool ()
GstRTSPConnection * | gst_rtsp_client_get_connection ()
gboolean | gst_rtsp_client_set_connection ()
guint | gst_rtsp_client_attach ()
gboolean | (*GstRTSPClientSendFunc) ()
void | gst_rtsp_client_set_send_func ()
GstRTSPResult | gst_rtsp_client_handle_message ()
GstRTSPResult | gst_rtsp_client_send_message ()
GstRTSPFilterResult | (*GstRTSPClientSessionFilterFunc) ()
GList * | gst_rtsp_client_session_filter ()

## Properties

gboolean | drop-backlog | Read / Write
GstRTSPMountPoints * | mount-points | Read / Write
GstRTSPSessionPool * | session-pool | Read / Write

## Signals

void | announce-request | Run Last
gchar* | check-requirements | Run Last
void | closed | Run Last
void | describe-request | Run Last
void | get-parameter-request | Run Last
void | handle-response | Run Last
void | new-session | Run Last
void | options-request | Run Last
void | pause-request | Run Last
void | play-request | Run Last
void | record-request | Run Last
void | send-message | Run Last
void | set-parameter-request | Run Last
void | setup-request | Run Last
void | teardown-request | Run Last

## Types and Values

struct | GstRTSPClient
struct | GstRTSPClientClass

## Object Hierarchy

        GObject
        ╰── GstRTSPClient

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

## Functions

### gst_rtsp_client_new ()

    GstRTSPClient *
    gst_rtsp_client_new (void);

Create a new GstRTSPClient instance.

#### Returns

a new GstRTSPClient.

[transfer full]

### gst_rtsp_client_close ()

    void
    gst_rtsp_client_close (GstRTSPClient *client);

Close the connection of `client` and remove all media it was managing.

#### Parameters

client | a GstRTSPClient |

Since: 1.4

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

#### Parameters

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.

#### Parameters

client | a GstRTSPClient |
pool | a GstRTSPSessionPool. | [transfer none]

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

#### Parameters

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.

#### Parameters

client | a GstRTSPClient |
mounts | a GstRTSPMountPoints. | [transfer none]

### gst_rtsp_client_get_auth ()

    GstRTSPAuth *
    gst_rtsp_client_get_auth (GstRTSPClient *client);

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

#### Parameters

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

#### Parameters

client | a GstRTSPClient |
auth | a GstRTSPAuth. | [transfer none]

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

#### Parameters

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

#### Parameters

client | a GstRTSPClient |
pool | a GstRTSPThreadPool. | [transfer none]

### gst_rtsp_client_get_connection ()

    GstRTSPConnection *
    gst_rtsp_client_get_connection (GstRTSPClient *client);

Get the GstRTSPConnection of `client` .

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

client | a GstRTSPClient |
func | a GstRTSPClientSendFunc. | [scope notified]
user_data | user data passed to `func` . | [closure]
notify | called when `user_data` is no longer in use. | [allow-none]

### gst_rtsp_client_handle_message ()

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

Let the client handle `message` .

#### Parameters

client | a GstRTSPClient |
message | an GstRTSPMessage. | [transfer none]

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

#### Parameters

client | a GstRTSPClient |
session | a GstRTSPSession to send the message to or `NULL`. | [allow-none][transfer none]
message | The GstRTSPMessage to send. | [transfer none]

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

#### Parameters

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.

#### Parameters

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]

## Types and Values

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

      void     (*tunnel_http_response)    (GstRTSPClient * client, GstRTSPMessage * request,
                                           GstRTSPMessage * response);
      void     (*send_message)            (GstRTSPClient * client, GstRTSPContext *ctx,
                                           GstRTSPMessage * response);

      gboolean (*handle_sdp)              (GstRTSPClient *client, GstRTSPContext *ctx, GstRTSPMedia *media, GstSDPMessage *sdp);

      void     (*announce_request)        (GstRTSPClient *client, GstRTSPContext *ctx);
      void     (*record_request)          (GstRTSPClient *client, GstRTSPContext *ctx);
      gchar*   (*check_requirements)      (GstRTSPClient *client, GstRTSPContext *ctx, gchar ** arr);
    };

The client class structure.

#### Members

`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` () |  |
`tunnel_http_response` () | called when a response to the GET request is about to be sent for a tunneled connection. The response can be modified. Since 1.4 |
`send_message` () |  |
`handle_sdp` () |  |
`announce_request` () |  |
`record_request` () |  |
`check_requirements` () |  |

## Property Details

### The `“drop-backlog”` property

      “drop-backlog”             gboolean

Drop data when the backlog queue is full.

Flags: Read / Write

Default value: TRUE

### The `“mount-points”` property

      “mount-points”             GstRTSPMountPoints *

The mount points to use for client session.

Flags: Read / Write

### The `“session-pool”` property

      “session-pool”             GstRTSPSessionPool *

The session pool to use for client session.

Flags: Read / Write

## Signal Details

### The `“announce-request”` signal

    void
    user_function (GstRTSPClient  *gstrtspclient,
                   GstRTSPContext *arg1,
                   gpointer        user_data)

Flags: Run Last

### The `“check-requirements”` signal

    gchar*
    user_function (GstRTSPClient  *client,
                   GstRTSPContext *ctx,
                   GStrv           arr,
                   gpointer        user_data)

#### Parameters

client | a GstRTSPClient |
ctx | a GstRTSPContext |
arr | a NULL-terminated array of strings |
user_data | user data set when the signal handler was connected. |

#### Returns

a newly allocated string with comma-separated list of unsupported options. An empty string must be returned if all options are supported.

Flags: Run Last

Since: 1.6

### The `“closed”` signal

    void
    user_function (GstRTSPClient *gstrtspclient,
                   gpointer       user_data)

Flags: Run Last

### The `“describe-request”` signal

    void
    user_function (GstRTSPClient  *gstrtspclient,
                   GstRTSPContext *arg1,
                   gpointer        user_data)

Flags: Run Last

### The `“get-parameter-request”` signal

    void
    user_function (GstRTSPClient  *gstrtspclient,
                   GstRTSPContext *arg1,
                   gpointer        user_data)

Flags: Run Last

### The `“handle-response”` signal

    void
    user_function (GstRTSPClient  *gstrtspclient,
                   GstRTSPContext *arg1,
                   gpointer        user_data)

Flags: Run Last

### The `“new-session”` signal

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

Flags: Run Last

### The `“options-request”` signal

    void
    user_function (GstRTSPClient  *gstrtspclient,
                   GstRTSPContext *arg1,
                   gpointer        user_data)

Flags: Run Last

### The `“pause-request”` signal

    void
    user_function (GstRTSPClient  *gstrtspclient,
                   GstRTSPContext *arg1,
                   gpointer        user_data)

Flags: Run Last

### The `“play-request”` signal

    void
    user_function (GstRTSPClient  *gstrtspclient,
                   GstRTSPContext *arg1,
                   gpointer        user_data)

Flags: Run Last

### The `“record-request”` signal

    void
    user_function (GstRTSPClient  *gstrtspclient,
                   GstRTSPContext *arg1,
                   gpointer        user_data)

Flags: Run Last

### The `“send-message”` signal

    void
    user_function (GstRTSPClient  *client,
                   GstRTSPContext *session,
                   gpointer        message,
                   gpointer        user_data)

#### Parameters

client | The RTSP client |
session | The session. | [type GstRtspServer.RTSPSession]
message | The message. | [type GstRtsp.RTSPMessage]
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“set-parameter-request”` signal

    void
    user_function (GstRTSPClient  *gstrtspclient,
                   GstRTSPContext *arg1,
                   gpointer        user_data)

Flags: Run Last

### The `“setup-request”` signal

    void
    user_function (GstRTSPClient  *gstrtspclient,
                   GstRTSPContext *arg1,
                   gpointer        user_data)

Flags: Run Last

### The `“teardown-request”` signal

    void
    user_function (GstRTSPClient  *gstrtspclient,
                   GstRTSPContext *arg1,
                   gpointer        user_data)

Flags: Run Last

## See Also

GstRTSPServer, GstRTSPThreadPool