GstRTSPSessionPool: GStreamer RTSP Server Reference Manual

## GstRTSPSessionPool GstRTSPSessionPool — An object for managing sessions |

## Functions

GstRTSPSessionPool * | gst_rtsp_session_pool_new ()
guint | gst_rtsp_session_pool_get_max_sessions ()
void | gst_rtsp_session_pool_set_max_sessions ()
guint | gst_rtsp_session_pool_get_n_sessions ()
GstRTSPSession * | gst_rtsp_session_pool_create ()
GstRTSPSession * | gst_rtsp_session_pool_find ()
gboolean | gst_rtsp_session_pool_remove ()
guint | gst_rtsp_session_pool_cleanup ()
gboolean | (*GstRTSPSessionPoolFunc) ()
GSource * | gst_rtsp_session_pool_create_watch ()
GstRTSPFilterResult | (*GstRTSPSessionPoolFilterFunc) ()
GList * | gst_rtsp_session_pool_filter ()

## Properties

guint | max-sessions | Read / Write

## Signals

void | session-removed | Run Last

## Types and Values

struct | GstRTSPSessionPool
struct | GstRTSPSessionPoolClass

## Object Hierarchy

        GObject
        ╰── GstRTSPSessionPool

## Description

The GstRTSPSessionPool object manages a list of GstRTSPSession objects.

The maximum number of sessions can be configured with `gst_rtsp_session_pool_set_max_sessions()`. The current number of sessions can be retrieved with `gst_rtsp_session_pool_get_n_sessions()`.

Use `gst_rtsp_session_pool_create()` to create a new GstRTSPSession object. The session object can be found again with its id and `gst_rtsp_session_pool_find()`.

All sessions can be iterated with `gst_rtsp_session_pool_filter()`.

Run `gst_rtsp_session_pool_cleanup()` periodically to remove timed out sessions or use `gst_rtsp_session_pool_create_watch()` to be notified when session cleanup should be performed.

Last reviewed on 2013-07-11 (1.0.0)

## Functions

### gst_rtsp_session_pool_new ()

    GstRTSPSessionPool *
    gst_rtsp_session_pool_new (void);

Create a new GstRTSPSessionPool instance.

#### Returns

A new GstRTSPSessionPool. `g_object_unref()` after usage.

[transfer full]

### gst_rtsp_session_pool_get_max_sessions ()

    guint
    gst_rtsp_session_pool_get_max_sessions
                                   (GstRTSPSessionPool *pool);

Get the maximum allowed number of sessions in `pool` . 0 means an unlimited amount of sessions.

#### Parameters

pool | a GstRTSPSessionPool |

#### Returns

the maximum allowed number of sessions.

### gst_rtsp_session_pool_set_max_sessions ()

    void
    gst_rtsp_session_pool_set_max_sessions
                                   (GstRTSPSessionPool *pool,
                                    guint max);

Configure the maximum allowed number of sessions in `pool` to `max` . A value of 0 means an unlimited amount of sessions.

#### Parameters

pool | a GstRTSPSessionPool |
max | the maximum number of sessions |

### gst_rtsp_session_pool_get_n_sessions ()

    guint
    gst_rtsp_session_pool_get_n_sessions (GstRTSPSessionPool *pool);

Get the amount of active sessions in `pool` .

#### Parameters

pool | a GstRTSPSessionPool |

#### Returns

the amount of active sessions in `pool` .

### gst_rtsp_session_pool_create ()

    GstRTSPSession *
    gst_rtsp_session_pool_create (GstRTSPSessionPool *pool);

Create a new GstRTSPSession object in `pool` .

#### Parameters

pool | a GstRTSPSessionPool |

#### Returns

a new GstRTSPSession.

[transfer full]

### gst_rtsp_session_pool_find ()

    GstRTSPSession *
    gst_rtsp_session_pool_find (GstRTSPSessionPool *pool,
                                const gchar *sessionid);

Find the session with `sessionid` in `pool` . The access time of the session will be updated with `gst_rtsp_session_touch()`.

#### Parameters

pool | the pool to search |
sessionid | the session id |

#### Returns

the GstRTSPSession with `sessionid` or `NULL` when the session did not exist. `g_object_unref()` after usage.

[transfer full][nullable]

### gst_rtsp_session_pool_remove ()

    gboolean
    gst_rtsp_session_pool_remove (GstRTSPSessionPool *pool,
                                  GstRTSPSession *sess);

Remove `sess` from `pool` , releasing the ref that the pool has on `sess` .

#### Parameters

pool | a GstRTSPSessionPool |
sess | a GstRTSPSession. | [transfer none]

#### Returns

`TRUE` if the session was found and removed.

### gst_rtsp_session_pool_cleanup ()

    guint
    gst_rtsp_session_pool_cleanup (GstRTSPSessionPool *pool);

Inspect all the sessions in `pool` and remove the sessions that are inactive for more than their timeout.

#### Parameters

pool | a GstRTSPSessionPool |

#### Returns

the amount of sessions that got removed.

### GstRTSPSessionPoolFunc ()

    gboolean
    (*GstRTSPSessionPoolFunc) (GstRTSPSessionPool *pool,
                               gpointer user_data);

The function that will be called from the GSource watch on the session pool.

The function will be called when the pool must be cleaned up because one or more sessions timed out.

#### Parameters

pool | a GstRTSPSessionPool object |
user_data | user data that has been given when registering the handler |

#### Returns

`FALSE` if the source should be removed.

### gst_rtsp_session_pool_create_watch ()

    GSource *
    gst_rtsp_session_pool_create_watch (GstRTSPSessionPool *pool);

Create a GSource that will be dispatched when the session should be cleaned up.

#### Parameters

pool | a GstRTSPSessionPool |

#### Returns

a GSource.

[transfer full]

### GstRTSPSessionPoolFilterFunc ()

    GstRTSPFilterResult
    (*GstRTSPSessionPoolFilterFunc) (GstRTSPSessionPool *pool,
                                     GstRTSPSession *session,
                                     gpointer user_data);

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

When this function returns GST_RTSP_FILTER_REMOVE, `session` will be removed from `pool` .

A return value of GST_RTSP_FILTER_KEEP will leave `session` untouched in `pool` .

A value of GST_RTSP_FILTER_REF will add `session` to the result GList of `gst_rtsp_session_pool_filter()`.

#### Parameters

pool | a GstRTSPSessionPool object |
session | a GstRTSPSession in `pool` |
user_data | user data that has been given to `gst_rtsp_session_pool_filter()` |

#### Returns

a GstRTSPFilterResult.

### gst_rtsp_session_pool_filter ()

    GList *
    gst_rtsp_session_pool_filter (GstRTSPSessionPool *pool,
                                  GstRTSPSessionPoolFilterFunc func,
                                  gpointer user_data);

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

If `func` returns GST_RTSP_FILTER_REMOVE, the session will be set to the expired state with `gst_rtsp_session_set_expired()` and removed from `pool` .

If `func` returns GST_RTSP_FILTER_KEEP, the session will remain in `pool` .

If `func` returns GST_RTSP_FILTER_REF, the session will remain in `pool` 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 sessions.

#### Parameters

pool | a GstRTSPSessionPool |
func | a callback. | [scope call][allow-none]
user_data | user data passed to `func` . | [closure]

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

    struct GstRTSPSessionPool;

An object that keeps track of the active sessions. This object is usually attached to a GstRTSPServer object to manage the sessions in that server.

### struct GstRTSPSessionPoolClass

    struct GstRTSPSessionPoolClass {
      GObjectClass  parent_class;

      gchar *          (*create_session_id)   (GstRTSPSessionPool *pool);
      GstRTSPSession * (*create_session)      (GstRTSPSessionPool *pool, const gchar *id);

      /* signals */
      void             (*session_removed)     (GstRTSPSessionPool *pool,
                                               GstRTSPSession *session);
    };

#### Members

GObjectClass `parent_class`; |  |
`create_session_id` () | create a new random session id. Subclasses can create custom session ids and should not check if the session exists. |
`create_session` () | make a new session object. |
`session_removed` () | a session was removed from the pool |

## Property Details

### The `“max-sessions”` property

      “max-sessions”             guint

the maximum amount of sessions (0 = unlimited).

Flags: Read / Write

Default value: 0

## Signal Details

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

    void
    user_function (GstRTSPSessionPool *gstrtspsessionpool,
                   GstRTSPSession     *arg1,
                   gpointer            user_data)

Flags: Run Last

## See Also

GstRTSPSession