GstRTSPSession

## GstRTSPSession GstRTSPSession — An object to manage media |

## Synopsis

    struct              GstRTSPSession;
    struct              GstRTSPSessionClass;
    GstRTSPSession *    gst_rtsp_session_new                (const gchar *sessionid);
    const gchar *       gst_rtsp_session_get_sessionid      (GstRTSPSession *session);
    gchar *             gst_rtsp_session_get_header         (GstRTSPSession *session);
    void                gst_rtsp_session_set_timeout        (GstRTSPSession *session,
                                                             guint timeout);
    guint               gst_rtsp_session_get_timeout        (GstRTSPSession *session);
    void                gst_rtsp_session_touch              (GstRTSPSession *session);
    void                gst_rtsp_session_prevent_expire     (GstRTSPSession *session);
    void                gst_rtsp_session_allow_expire       (GstRTSPSession *session);
    gint                gst_rtsp_session_next_timeout       (GstRTSPSession *session,
                                                             GTimeVal *now);
    gboolean            gst_rtsp_session_is_expired         (GstRTSPSession *session,
                                                             GTimeVal *now);
    GstRTSPSessionMedia * gst_rtsp_session_manage_media     (GstRTSPSession *sess,
                                                             const gchar *path,
                                                             GstRTSPMedia *media);
    gboolean            gst_rtsp_session_release_media      (GstRTSPSession *sess,
                                                             GstRTSPSessionMedia *media);
    GstRTSPSessionMedia * gst_rtsp_session_get_media        (GstRTSPSession *sess,
                                                             const gchar *path,
                                                             gint *matched);
    enum                GstRTSPFilterResult;
    GstRTSPFilterResult (*GstRTSPSessionFilterFunc)         (GstRTSPSession *sess,
                                                             GstRTSPSessionMedia *media,
                                                             gpointer user_data);
    GList *             gst_rtsp_session_filter             (GstRTSPSession *sess,
                                                             GstRTSPSessionFilterFunc func,
                                                             gpointer user_data);

## Object Hierarchy

      GObject
       +----GstRTSPSession

## Properties

      "sessionid"                gchar*                : Read / Write / Construct Only
      "timeout"                  guint                 : Read / Write

## Description

The GstRTSPSession is identified by an id, unique in the GstRTSPSessionPool that created the session and manages media and its configuration.

A GstRTSPSession has a timeout that can be retrieved with `gst_rtsp_session_get_timeout()`. You can check if the sessions is expired with `gst_rtsp_session_is_expired()`. `gst_rtsp_session_touch()` will reset the expiration counter of the session.

When a client configures a media with SETUP, a session will be created to keep track of the configuration of that media. With `gst_rtsp_session_manage_media()`, the media is added to the managed media in the session. With `gst_rtsp_session_release_media()` the media can be released again from the session. Managed media is identified in the sessions with a url. Use `gst_rtsp_session_get_media()` to get the media that matches (part of) the given url.

The media in a session can be iterated with `gst_rtsp_session_filter()`.

Last reviewed on 2013-07-11 (1.0.0)

## Details

### struct GstRTSPSession

    struct GstRTSPSession;

Session information kept by the server for a specific client. One client session, identified with a session id, can handle multiple medias identified with the url of a media.

### struct GstRTSPSessionClass

    struct GstRTSPSessionClass {
      GObjectClass  parent_class;
    };

### gst_rtsp_session_new ()

    GstRTSPSession *    gst_rtsp_session_new                (const gchar *sessionid);

Create a new GstRTSPSession instance with `sessionid`.

`sessionid` : | a session id

### gst_rtsp_session_get_sessionid ()

    const gchar *       gst_rtsp_session_get_sessionid      (GstRTSPSession *session);

Get the sessionid of `session`.

`session` : | a GstRTSPSession
Returns : | the sessionid of `session`. The value remains valid as long as `session` is alive.

### gst_rtsp_session_get_header ()

    gchar *             gst_rtsp_session_get_header         (GstRTSPSession *session);

Get the string that can be placed in the Session header field.

`session` : | a GstRTSPSession
Returns : | the Session header of `session`. `g_free()` after usage. [transfer full]

### gst_rtsp_session_set_timeout ()

    void                gst_rtsp_session_set_timeout        (GstRTSPSession *session,
                                                             guint timeout);

Configure `session` for a timeout of `timeout` seconds. The session will be cleaned up when there is no activity for `timeout` seconds.

`session` : | a GstRTSPSession
`timeout` : | the new timeout

### gst_rtsp_session_get_timeout ()

    guint               gst_rtsp_session_get_timeout        (GstRTSPSession *session);

Get the timeout value of `session`.

`session` : | a GstRTSPSession
Returns : | the timeout of `session` in seconds.

### gst_rtsp_session_touch ()

    void                gst_rtsp_session_touch              (GstRTSPSession *session);

Update the last_access time of the session to the current time.

`session` : | a GstRTSPSession

### gst_rtsp_session_prevent_expire ()

    void                gst_rtsp_session_prevent_expire     (GstRTSPSession *session);

Prevent `session` from expiring.

`session` : | a GstRTSPSession

### gst_rtsp_session_allow_expire ()

    void                gst_rtsp_session_allow_expire       (GstRTSPSession *session);

Allow `session` to expire. This method must be called an equal amount of time as `gst_rtsp_session_prevent_expire()`.

`session` : | a GstRTSPSession

### gst_rtsp_session_next_timeout ()

    gint                gst_rtsp_session_next_timeout       (GstRTSPSession *session,
                                                             GTimeVal *now);

Get the amount of milliseconds till the session will expire.

`session` : | a GstRTSPSession
`now` : | the current system time
Returns : | the amount of milliseconds since the session will time out.

### gst_rtsp_session_is_expired ()

    gboolean            gst_rtsp_session_is_expired         (GstRTSPSession *session,
                                                             GTimeVal *now);

Check if `session` timeout out.

`session` : | a GstRTSPSession
`now` : | the current system time
Returns : | `TRUE` if `session` timed out

### gst_rtsp_session_manage_media ()

    GstRTSPSessionMedia * gst_rtsp_session_manage_media     (GstRTSPSession *sess,
                                                             const gchar *path,
                                                             GstRTSPMedia *media);

Manage the media object `obj` in `sess`. `path` will be used to retrieve this media from the session with `gst_rtsp_session_get_media()`.

Ownership is taken from `media`.

`sess` : | a GstRTSPSession
`path` : | the path for the media
`media` : | a GstRTSPMedia. [transfer full]
Returns : | a new `GstRTSPSessionMedia` object. [transfer none]

### gst_rtsp_session_release_media ()

    gboolean            gst_rtsp_session_release_media      (GstRTSPSession *sess,
                                                             GstRTSPSessionMedia *media);

Release the managed `media` in `sess`, freeing the memory allocated by it.

`sess` : | a GstRTSPSession
`media` : | a GstRTSPMedia
Returns : | `TRUE` if there are more media session left in `sess`.

### gst_rtsp_session_get_media ()

    GstRTSPSessionMedia * gst_rtsp_session_get_media        (GstRTSPSession *sess,
                                                             const gchar *path,
                                                             gint *matched);

Get the session media for `path`. `matched` will contain the number of matched characters of `path`.

`sess` : | a GstRTSPSession
`path` : | the path for the media
`matched` : | the amount of matched characters. [out]
Returns : | the configuration for `path` in `sess`. [transfer none]

### enum GstRTSPFilterResult

    typedef enum {
      GST_RTSP_FILTER_REMOVE,
      GST_RTSP_FILTER_KEEP,
      GST_RTSP_FILTER_REF,
    } GstRTSPFilterResult;

Possible return values for `gst_rtsp_session_pool_filter()`.

`GST_RTSP_FILTER_REMOVE` | Remove session
`GST_RTSP_FILTER_KEEP` | Keep session in the pool
`GST_RTSP_FILTER_REF` | Ref session in the result list

### GstRTSPSessionFilterFunc ()

    GstRTSPFilterResult (*GstRTSPSessionFilterFunc)         (GstRTSPSession *sess,
                                                             GstRTSPSessionMedia *media,
                                                             gpointer user_data);

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

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

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

A value of GST_RTSP_FILTER_REF will add `media` to the result GList of `gst_rtsp_session_filter()`.

`sess` : | a GstRTSPSession object
`media` : | a GstRTSPSessionMedia in `sess`
`user_data` : | user data that has been given to `gst_rtsp_session_filter()`
Returns : | a GstRTSPFilterResult.

### gst_rtsp_session_filter ()

    GList *             gst_rtsp_session_filter             (GstRTSPSession *sess,
                                                             GstRTSPSessionFilterFunc func,
                                                             gpointer user_data);

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

If `func` returns GST_RTSP_FILTER_REMOVE, the media will be removed from `sess`.

If `func` returns GST_RTSP_FILTER_KEEP, the media will remain in `sess`.

If `func` returns GST_RTSP_FILTER_REF, the media will remain in `sess` 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 all media.

`sess` : | a GstRTSPSession
`func` : | a callback. [scope call][allow-none]
`user_data` : | user data passed to `func`
Returns : | a GList with all media 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 GstRTSPSessionMedia][transfer full]

## Property Details

### The `"sessionid"` property

      "sessionid"                gchar*                : Read / Write / Construct Only

the session id.

Default value: NULL

### The `"timeout"` property

      "timeout"                  guint                 : Read / Write

the timeout of the session (0 = never).

Default value: 60

## See Also

GstRTSPSessionPool, GstRTSPSessionMedia, GstRTSPMedia