GstRTSPSession: GStreamer RTSP Server Reference Manual

## GstRTSPSession GstRTSPSession — An object to manage media |

## Functions

GstRTSPSession * | gst_rtsp_session_new ()
const gchar * | gst_rtsp_session_get_sessionid ()
gchar * | gst_rtsp_session_get_header ()
void | gst_rtsp_session_set_timeout ()
guint | gst_rtsp_session_get_timeout ()
void | gst_rtsp_session_touch ()
void | gst_rtsp_session_prevent_expire ()
void | gst_rtsp_session_allow_expire ()
gint | gst_rtsp_session_next_timeout ()
gboolean | gst_rtsp_session_is_expired ()
GstRTSPSessionMedia * | gst_rtsp_session_manage_media ()
gboolean | gst_rtsp_session_release_media ()
GstRTSPSessionMedia * | gst_rtsp_session_get_media ()
GstRTSPFilterResult | (*GstRTSPSessionFilterFunc) ()
GList * | gst_rtsp_session_filter ()

## Properties

gchar * | sessionid | Read / Write / Construct Only
guint | timeout | Read / Write
gboolean | timeout-always-visible | Read / Write

## Types and Values

struct | GstRTSPSession
struct | GstRTSPSessionClass
enum | GstRTSPFilterResult

## Object Hierarchy

        GObject
        ╰── GstRTSPSession

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

## Functions

### gst_rtsp_session_new ()

    GstRTSPSession *
    gst_rtsp_session_new (const gchar *sessionid);

Create a new GstRTSPSession instance with `sessionid` .

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

session | a GstRTSPSession |

### gst_rtsp_session_prevent_expire ()

    void
    gst_rtsp_session_prevent_expire (GstRTSPSession *session);

Prevent `session` from expiring.

#### Parameters

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

#### Parameters

session | a GstRTSPSession |

### gst_rtsp_session_next_timeout ()

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

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

#### Parameters

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

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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]

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

#### Parameters

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.

#### Parameters

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]

## Types and Values

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

### enum GstRTSPFilterResult

Possible return values for `gst_rtsp_session_pool_filter()`.

#### Members

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 |

## Property Details

### The `“sessionid”` property

      “sessionid”                gchar *

the session id.

Flags: Read / Write / Construct Only

Default value: NULL

### The `“timeout”` property

      “timeout”                  guint

the timeout of the session (0 = never).

Flags: Read / Write

Default value: 60

### The `“timeout-always-visible”` property

      “timeout-always-visible”   gboolean

timeout always visible in header.

Flags: Read / Write

Default value: FALSE

## See Also

GstRTSPSessionPool, GstRTSPSessionMedia, GstRTSPMedia