GstRTSPServer

## GstRTSPServer GstRTSPServer — The main server object |

## Synopsis

    struct              GstRTSPServer;
    struct              GstRTSPServerClass;
    GstRTSPServer *     gst_rtsp_server_new                 (void);
    gchar *             gst_rtsp_server_get_address         (GstRTSPServer *server);
    void                gst_rtsp_server_set_address         (GstRTSPServer *server,
                                                             const gchar *address);
    gchar *             gst_rtsp_server_get_service         (GstRTSPServer *server);
    void                gst_rtsp_server_set_service         (GstRTSPServer *server,
                                                             const gchar *service);
    gint                gst_rtsp_server_get_backlog         (GstRTSPServer *server);
    void                gst_rtsp_server_set_backlog         (GstRTSPServer *server,
                                                             gint backlog);
    int                 gst_rtsp_server_get_bound_port      (GstRTSPServer *server);
    GstRTSPMountPoints * gst_rtsp_server_get_mount_points   (GstRTSPServer *server);
    void                gst_rtsp_server_set_mount_points    (GstRTSPServer *server,
                                                             GstRTSPMountPoints *mounts);
    GstRTSPSessionPool * gst_rtsp_server_get_session_pool   (GstRTSPServer *server);
    void                gst_rtsp_server_set_session_pool    (GstRTSPServer *server,
                                                             GstRTSPSessionPool *pool);
    GstRTSPThreadPool * gst_rtsp_server_get_thread_pool     (GstRTSPServer *server);
    void                gst_rtsp_server_set_thread_pool     (GstRTSPServer *server,
                                                             GstRTSPThreadPool *pool);
    GstRTSPAuth *       gst_rtsp_server_get_auth            (GstRTSPServer *server);
    void                gst_rtsp_server_set_auth            (GstRTSPServer *server,
                                                             GstRTSPAuth *auth);
    gboolean            gst_rtsp_server_transfer_connection (GstRTSPServer *server,
                                                             GSocket *socket,
                                                             const gchar *ip,
                                                             gint port,
                                                             const gchar *initial_buffer);
    gboolean            gst_rtsp_server_io_func             (GSocket *socket,
                                                             GIOCondition condition,
                                                             GstRTSPServer *server);
    GSocket *           gst_rtsp_server_create_socket       (GstRTSPServer *server,
                                                             GCancellable *cancellable,
                                                             GError **error);
    GSource *           gst_rtsp_server_create_source       (GstRTSPServer *server,
                                                             GCancellable *cancellable,
                                                             GError **error);
    guint               gst_rtsp_server_attach              (GstRTSPServer *server,
                                                             GMainContext *context);
    GstRTSPFilterResult (*GstRTSPServerClientFilterFunc)    (GstRTSPServer *server,
                                                             GstRTSPClient *client,
                                                             gpointer user_data);
    GList *             gst_rtsp_server_client_filter       (GstRTSPServer *server,
                                                             GstRTSPServerClientFilterFunc func,
                                                             gpointer user_data);

## Object Hierarchy

      GObject
       +----GstRTSPServer

## Properties

      "address"                  gchar*                : Read / Write
      "backlog"                  gint                  : Read / Write
      "bound-port"               gint                  : Read
      "mount-points"             GstRTSPMountPoints*   : Read / Write
      "service"                  gchar*                : Read / Write
      "session-pool"             GstRTSPSessionPool*   : Read / Write

## Signals

      "client-connected"                               : Run Last

## Description

The server object is the object listening for connections on a port and creating GstRTSPClient objects to handle those connections.

The server will listen on the address set with `gst_rtsp_server_set_address()` and the port or service configured with `gst_rtsp_server_set_service()`. Use `gst_rtsp_server_set_backlog()` to configure the amount of pending requests that the server will keep. By default the server listens on the current network (0.0.0.0) and port 8554.

The server will require an SSL connection when a TLS certificate has been set in the auth object with `gst_rtsp_auth_set_tls_certificate()`.

To start the server, use `gst_rtsp_server_attach()` to attach it to a GMainContext. For more control, `gst_rtsp_server_create_source()` and `gst_rtsp_server_create_socket()` can be used to get a GSource and GSocket respectively.

`gst_rtsp_server_transfer_connection()` can be used to transfer an existing socket to the RTSP server, for example from an HTTP server.

Once the server socket is attached to a mainloop, it will start accepting connections. When a new connection is received, a new GstRTSPClient object is created to handle the connection. The new client will be configured with the server GstRTSPAuth, GstRTSPMountPoints, GstRTSPSessionPool and GstRTSPThreadPool.

The server uses the configured GstRTSPThreadPool object to handle the remainder of the communication with this client.

Last reviewed on 2013-07-11 (1.0.0)

## Details

### struct GstRTSPServer

    struct GstRTSPServer;

This object listens on a port, creates and manages the clients connected to it.

### struct GstRTSPServerClass

    struct GstRTSPServerClass {
      GObjectClass  parent_class;

      GstRTSPClient * (*create_client)      (GstRTSPServer *server);

      /* signals */
      void            (*client_connected)   (GstRTSPServer *server, GstRTSPClient *client);
    };

The RTSP server class structure

GObjectClass `parent_class`; |
`create_client` () | Create, configure a new GstRTSPClient object that handles the new connection on `socket`. The default implementation will create a GstRTSPClient and will configure the mount-points, auth, session-pool and thread-pool on the client.
`client_connected` () | emited when a new client connected.

### gst_rtsp_server_new ()

    GstRTSPServer *     gst_rtsp_server_new                 (void);

Create a new GstRTSPServer instance.

### gst_rtsp_server_get_address ()

    gchar *             gst_rtsp_server_get_address         (GstRTSPServer *server);

Get the address on which the server will accept connections.

`server` : | a GstRTSPServer
Returns : | the server address. `g_free()` after usage.

### gst_rtsp_server_set_address ()

    void                gst_rtsp_server_set_address         (GstRTSPServer *server,
                                                             const gchar *address);

Configure `server` to accept connections on the given address.

This function must be called before the server is bound.

`server` : | a GstRTSPServer
`address` : | the address

### gst_rtsp_server_get_service ()

    gchar *             gst_rtsp_server_get_service         (GstRTSPServer *server);

Get the service on which the server will accept connections.

`server` : | a GstRTSPServer
Returns : | the service. use `g_free()` after usage.

### gst_rtsp_server_set_service ()

    void                gst_rtsp_server_set_service         (GstRTSPServer *server,
                                                             const gchar *service);

Configure `server` to accept connections on the given service. `service` should be a string containing the service name (see services(5)) or a string containing a port number between 1 and 65535.

When `service` is set to "0", the server will listen on a random free port. The actual used port can be retrieved with `gst_rtsp_server_get_bound_port()`.

This function must be called before the server is bound.

`server` : | a GstRTSPServer
`service` : | the service

### gst_rtsp_server_get_backlog ()

    gint                gst_rtsp_server_get_backlog         (GstRTSPServer *server);

The maximum amount of queued requests for the server.

`server` : | a GstRTSPServer
Returns : | the server backlog.

### gst_rtsp_server_set_backlog ()

    void                gst_rtsp_server_set_backlog         (GstRTSPServer *server,
                                                             gint backlog);

configure the maximum amount of requests that may be queued for the server.

This function must be called before the server is bound.

`server` : | a GstRTSPServer
`backlog` : | the backlog

### gst_rtsp_server_get_bound_port ()

    int                 gst_rtsp_server_get_bound_port      (GstRTSPServer *server);

Get the port number where the server was bound to.

`server` : | a GstRTSPServer
Returns : | the port number

### gst_rtsp_server_get_mount_points ()

    GstRTSPMountPoints * gst_rtsp_server_get_mount_points   (GstRTSPServer *server);

Get the GstRTSPMountPoints used as the mount points of `server`.

`server` : | a GstRTSPServer
Returns : | the GstRTSPMountPoints of `server`. `g_object_unref()` after usage. [transfer full]

### gst_rtsp_server_set_mount_points ()

    void                gst_rtsp_server_set_mount_points    (GstRTSPServer *server,
                                                             GstRTSPMountPoints *mounts);

configure `mounts` to be used as the mount points of `server`.

`server` : | a GstRTSPServer
`mounts` : | a GstRTSPMountPoints

### gst_rtsp_server_get_session_pool ()

    GstRTSPSessionPool * gst_rtsp_server_get_session_pool   (GstRTSPServer *server);

Get the GstRTSPSessionPool used as the session pool of `server`.

`server` : | a GstRTSPServer
Returns : | the GstRTSPSessionPool used for sessions. `g_object_unref()` after usage. [transfer full]

### gst_rtsp_server_set_session_pool ()

    void                gst_rtsp_server_set_session_pool    (GstRTSPServer *server,
                                                             GstRTSPSessionPool *pool);

configure `pool` to be used as the session pool of `server`.

`server` : | a GstRTSPServer
`pool` : | a GstRTSPSessionPool

### gst_rtsp_server_get_thread_pool ()

    GstRTSPThreadPool * gst_rtsp_server_get_thread_pool     (GstRTSPServer *server);

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

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

### gst_rtsp_server_set_thread_pool ()

    void                gst_rtsp_server_set_thread_pool     (GstRTSPServer *server,
                                                             GstRTSPThreadPool *pool);

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

`server` : | a GstRTSPServer
`pool` : | a GstRTSPThreadPool

### gst_rtsp_server_get_auth ()

    GstRTSPAuth *       gst_rtsp_server_get_auth            (GstRTSPServer *server);

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

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

### gst_rtsp_server_set_auth ()

    void                gst_rtsp_server_set_auth            (GstRTSPServer *server,
                                                             GstRTSPAuth *auth);

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

`server` : | a GstRTSPServer
`auth` : | a GstRTSPAuth

### gst_rtsp_server_transfer_connection ()

    gboolean            gst_rtsp_server_transfer_connection (GstRTSPServer *server,
                                                             GSocket *socket,
                                                             const gchar *ip,
                                                             gint port,
                                                             const gchar *initial_buffer);

Take an existing network socket and use it for an RTSP connection. This is used when transferring a socket from an HTTP server which should be used as an RTSP over HTTP tunnel. The `initial_buffer` contains any remaining data that the HTTP server read from the socket while parsing the HTTP header.

`server` : | a GstRTSPServer
`socket` : | a network socket. [transfer full]
`ip` : | the IP address of the remote client
`port` : | the port used by the other end
`initial_buffer` : | any initial data that was already read from the socket
Returns : | TRUE if all was ok, FALSE if an error occured.

### gst_rtsp_server_io_func ()

    gboolean            gst_rtsp_server_io_func             (GSocket *socket,
                                                             GIOCondition condition,
                                                             GstRTSPServer *server);

A default GSocketSourceFunc that creates a new GstRTSPClient to accept and handle a new connection on `socket` or `server`.

`socket` : | a GSocket
`condition` : | the condition on `source`
`server` : | a GstRTSPServer
Returns : | TRUE if the source could be connected, FALSE if an error occured.

### gst_rtsp_server_create_socket ()

    GSocket *           gst_rtsp_server_create_socket       (GstRTSPServer *server,
                                                             GCancellable *cancellable,
                                                             GError **error);

Create a GSocket for `server`. The socket will listen on the configured service.

`server` : | a GstRTSPServer
`cancellable` : | a GCancellable
`error` : | a GError
Returns : | the GSocket for `server` or `NULL` when an error occured. [transfer full]

### gst_rtsp_server_create_source ()

    GSource *           gst_rtsp_server_create_source       (GstRTSPServer *server,
                                                             GCancellable *cancellable,
                                                             GError **error);

Create a GSource for `server`. The new source will have a default GSocketSourceFunc of `gst_rtsp_server_io_func()`.

`cancellable` if not `NULL` can be used to cancel the source, which will cause the source to trigger, reporting the current condition (which is likely 0 unless cancellation happened at the same time as a condition change). You can check for this in the callback using `g_cancellable_is_cancelled()`.

`server` : | a GstRTSPServer
`cancellable` : | a GCancellable or `NULL`.
`error` : | a GError
Returns : | the GSource for `server` or `NULL` when an error occured. Free with `g_source_unref()`

### gst_rtsp_server_attach ()

    guint               gst_rtsp_server_attach              (GstRTSPServer *server,
                                                             GMainContext *context);

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

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

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

### GstRTSPServerClientFilterFunc ()

    GstRTSPFilterResult (*GstRTSPServerClientFilterFunc)    (GstRTSPServer *server,
                                                             GstRTSPClient *client,
                                                             gpointer user_data);

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

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

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

A value of GST_RTSP_FILTER_REF will add `client` to the result GList of `gst_rtsp_server_client_filter()`.

`server` : | a GstRTSPServer object
`client` : | a GstRTSPClient in `server`
`user_data` : | user data that has been given to `gst_rtsp_server_client_filter()`
Returns : | a GstRTSPFilterResult.

### gst_rtsp_server_client_filter ()

    GList *             gst_rtsp_server_client_filter       (GstRTSPServer *server,
                                                             GstRTSPServerClientFilterFunc func,
                                                             gpointer user_data);

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

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

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

If `func` returns GST_RTSP_FILTER_REF, the client will remain in `server` 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 client.

`server` : | a GstRTSPServer
`func` : | a callback. [scope call][allow-none]
`user_data` : | user data passed to `func`
Returns : | a GList with all clients 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 GstRTSPClient][transfer full]

## Property Details

### The `"address"` property

      "address"                  gchar*                : Read / Write

The address the server uses to listen on.

Default value: "0.0.0.0"

### The `"backlog"` property

      "backlog"                  gint                  : Read / Write

The maximum length to which the queue of pending connections may grow.

Allowed values: >= 0

Default value: 5

### The `"bound-port"` property

      "bound-port"               gint                  : Read

The port number the server is listening on.

Allowed values: [-1,65535]

Default value: -1

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

      "mount-points"             GstRTSPMountPoints*   : Read / Write

The mount points to use for client session.

### The `"service"` property

      "service"                  gchar*                : Read / Write

The service or port number the server uses to listen on.

Default value: "8554"

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

      "session-pool"             GstRTSPSessionPool*   : Read / Write

The session pool to use for client session.

## Signal Details

### The `"client-connected"` signal

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

## See Also

GstRTSPClient, GstRTSPThreadPool