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
  "timeout-always-visible"   gboolean              : 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

Returns :

a new GstRTSPSession. [transfer full]

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. [transfer none]

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

Warning

gst_rtsp_session_next_timeout is deprecated and should not be used in newly-written code. Use gst_rtsp_session_next_timeout_usec() instead.

Get the amount of milliseconds till the session will expire.

session :

a GstRTSPSession

now :

the current system time. [transfer none]

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

Warning

gst_rtsp_session_is_expired is deprecated and should not be used in newly-written code. Use gst_rtsp_session_is_expired_usec() instead.

Check if session timeout out.

session :

a GstRTSPSession

now :

the current system time. [transfer none]

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. [transfer none]

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. [closure]

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


The "timeout-always-visible" property

  "timeout-always-visible"   gboolean              : Read / Write

timeout always visible in header.

Default value: FALSE

See Also

GstRTSPSessionPool, GstRTSPSessionMedia, GstRTSPMedia