From 0b3644a21be28b5747acede5982b9d653dea26d9 Mon Sep 17 00:00:00 2001 From: Wim Taymans Date: Thu, 11 Jul 2013 16:57:14 +0200 Subject: [PATCH] docs: improve docs --- docs/README | 10 ++++- docs/libs/gst-rtsp-server-docs.sgml | 6 ++- docs/libs/gst-rtsp-server-sections.txt | 55 ++++++++++++++---------- gst/rtsp-server/rtsp-address-pool.c | 7 +++ gst/rtsp-server/rtsp-auth.c | 7 +++ gst/rtsp-server/rtsp-client.c | 29 ++++++++++++- gst/rtsp-server/rtsp-client.h | 16 +++---- gst/rtsp-server/rtsp-media-factory-uri.c | 13 ++++++ gst/rtsp-server/rtsp-media-factory.c | 19 ++++++++ gst/rtsp-server/rtsp-media-factory.h | 14 +++--- gst/rtsp-server/rtsp-media.c | 7 +++ gst/rtsp-server/rtsp-mount-points.c | 19 +++++++- gst/rtsp-server/rtsp-params.c | 8 ++++ gst/rtsp-server/rtsp-permissions.c | 8 ++++ gst/rtsp-server/rtsp-sdp.c | 8 ++++ gst/rtsp-server/rtsp-server.c | 44 +++++++++++++++++-- gst/rtsp-server/rtsp-server.h | 19 ++++---- gst/rtsp-server/rtsp-session-media.c | 8 ++++ gst/rtsp-server/rtsp-session-pool.c | 23 ++++++++++ gst/rtsp-server/rtsp-session.c | 27 ++++++++++++ gst/rtsp-server/rtsp-stream-transport.c | 7 +++ gst/rtsp-server/rtsp-stream.c | 7 +++ gst/rtsp-server/rtsp-thread-pool.c | 7 +++ gst/rtsp-server/rtsp-token.c | 7 +++ 24 files changed, 320 insertions(+), 55 deletions(-) diff --git a/docs/README b/docs/README index 943382e29f..f2e878bd39 100644 --- a/docs/README +++ b/docs/README @@ -93,8 +93,8 @@ can build simple server applications with it. g_main_loop_run (loop); } - The server manages two other objects: GstRTSPSessionPool and - GstRTSPMountPoints. + The server manages four other objects: GstRTSPSessionPool, + GstRTSPMountPoints, GstRTSPAuth and GstRTSPThreadPool. The GstRTSPSessionPool is an object that keeps track of all the active sessions in the server. A session will usually be kept for each client that performed a @@ -109,6 +109,12 @@ can build simple server applications with it. request URL to a specific stream and its configuration. We explain in the next topic how to configure this object. + GstRTSPAuth is an object that authenticates users and authorizes actions + performed by users. + + GstRTSPThreadPool manages the threads used for client connections and media + pipelines. + * Making url mount points diff --git a/docs/libs/gst-rtsp-server-docs.sgml b/docs/libs/gst-rtsp-server-docs.sgml index 716d8b216f..4035cc8d69 100644 --- a/docs/libs/gst-rtsp-server-docs.sgml +++ b/docs/libs/gst-rtsp-server-docs.sgml @@ -19,11 +19,15 @@ + + - + + + diff --git a/docs/libs/gst-rtsp-server-sections.txt b/docs/libs/gst-rtsp-server-sections.txt index edfe53ecb7..3e6d6be7e2 100644 --- a/docs/libs/gst-rtsp-server-sections.txt +++ b/docs/libs/gst-rtsp-server-sections.txt @@ -1,6 +1,8 @@
rtsp-address-pool GstRTSPAddressPool + + GST_RTSP_ADDRESS_POOL_ANY_IPV4 GST_RTSP_ADDRESS_POOL_ANY_IPV6 GstRTSPAddress @@ -8,6 +10,7 @@ GstRTSPAddressFlags gst_rtsp_address_copy gst_rtsp_address_free + GstRTSPAddressPool GstRTSPAddressPoolClass gst_rtsp_address_pool_new @@ -45,10 +48,12 @@ gst_rtsp_auth_remove_basic gst_rtsp_auth_setup gst_rtsp_auth_check + GST_RTSP_AUTH_CHECK_URL GST_RTSP_AUTH_CHECK_MEDIA_FACTORY_ACCESS GST_RTSP_AUTH_CHECK_MEDIA_FACTORY_CONSTRUCT + GST_RTSP_MEDIA_FACTORY_ROLE GST_RTSP_MEDIA_FACTORY_PERM_ACCESS GST_RTSP_MEDIA_FACTORY_PERM_CONSTRUCT @@ -68,9 +73,11 @@ gst_rtsp_auth_get_type
rtsp-client GstRTSPClient + GstRTSPClientState gst_rtsp_client_state_get_current + GstRTSPClient GstRTSPClientClass @@ -82,24 +89,25 @@ gst_rtsp_client_set_session_pool gst_rtsp_client_get_mount_points gst_rtsp_client_set_mount_points -gst_rtsp_client_get_use_client_settings -gst_rtsp_client_set_use_client_settings - gst_rtsp_client_get_auth gst_rtsp_client_set_auth gst_rtsp_client_get_thread_pool gst_rtsp_client_set_thread_pool +gst_rtsp_client_get_use_client_settings +gst_rtsp_client_set_use_client_settings + gst_rtsp_client_get_connection gst_rtsp_client_set_connection +gst_rtsp_client_attach + GstRTSPClientSendFunc gst_rtsp_client_set_send_func gst_rtsp_client_handle_message gst_rtsp_client_send_request -gst_rtsp_client_attach GstRTSPClientSessionFilterFunc gst_rtsp_client_session_filter @@ -190,29 +198,30 @@ GstRTSPMediaFactoryClass gst_rtsp_media_factory_new -gst_rtsp_media_factory_construct -gst_rtsp_media_factory_create_element - -gst_rtsp_media_factory_get_address_pool -gst_rtsp_media_factory_set_address_pool - -gst_rtsp_media_factory_get_buffer_size -gst_rtsp_media_factory_set_buffer_size - gst_rtsp_media_factory_get_launch gst_rtsp_media_factory_set_launch gst_rtsp_media_factory_get_permissions gst_rtsp_media_factory_set_permissions -gst_rtsp_media_factory_get_protocols -gst_rtsp_media_factory_set_protocols +gst_rtsp_media_factory_set_shared +gst_rtsp_media_factory_is_shared gst_rtsp_media_factory_is_eos_shutdown gst_rtsp_media_factory_set_eos_shutdown -gst_rtsp_media_factory_set_shared -gst_rtsp_media_factory_is_shared +gst_rtsp_media_factory_get_protocols +gst_rtsp_media_factory_set_protocols + +gst_rtsp_media_factory_get_address_pool +gst_rtsp_media_factory_set_address_pool + +gst_rtsp_media_factory_get_buffer_size +gst_rtsp_media_factory_set_buffer_size + +gst_rtsp_media_factory_construct +gst_rtsp_media_factory_create_element + GST_RTSP_MEDIA_FACTORY_CAST GST_RTSP_MEDIA_FACTORY_CLASS_CAST @@ -316,11 +325,14 @@ gst_rtsp_server_set_address gst_rtsp_server_get_service gst_rtsp_server_set_service -gst_rtsp_server_get_bound_port - gst_rtsp_server_get_backlog gst_rtsp_server_set_backlog +gst_rtsp_server_get_tls_certificate +gst_rtsp_server_set_tls_certificate + +gst_rtsp_server_get_bound_port + gst_rtsp_server_get_mount_points gst_rtsp_server_set_mount_points @@ -333,9 +345,6 @@ gst_rtsp_server_set_thread_pool gst_rtsp_server_get_auth gst_rtsp_server_set_auth -gst_rtsp_server_get_tls_certificate -gst_rtsp_server_set_tls_certificate - gst_rtsp_server_get_use_client_settings gst_rtsp_server_set_use_client_settings @@ -562,6 +571,7 @@ gst_rtsp_stream_transport_get_type
rtsp-thread-pool GstRTSPThreadPool + GstRTSPThreadType GstRTSPThread @@ -571,6 +581,7 @@ gst_rtsp_thread_unref gst_rtsp_thread_reuse gst_rtsp_thread_stop + GstRTSPThreadPool GstRTSPThreadPoolClass gst_rtsp_thread_pool_new diff --git a/gst/rtsp-server/rtsp-address-pool.c b/gst/rtsp-server/rtsp-address-pool.c index c5c0727e86..297f85cba5 100644 --- a/gst/rtsp-server/rtsp-address-pool.c +++ b/gst/rtsp-server/rtsp-address-pool.c @@ -16,6 +16,13 @@ * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, * Boston, MA 02110-1301, USA. */ +/** + * SECTION:rtsp-address-pool + * @short_description: A pool of network addresses + * @see_also: #GstRTSPStream, #GstRTSPStreamTransport + * + * Last reviewed on 2013-07-11 (1.0.0) + */ #include #include diff --git a/gst/rtsp-server/rtsp-auth.c b/gst/rtsp-server/rtsp-auth.c index 06f5aeba7d..dc0b2e04a7 100644 --- a/gst/rtsp-server/rtsp-auth.c +++ b/gst/rtsp-server/rtsp-auth.c @@ -16,6 +16,13 @@ * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, * Boston, MA 02110-1301, USA. */ +/** + * SECTION:rtsp-auth + * @short_description: Authentication and authorization + * @see_also: #GstRTSPPermission, #GstRTSPtoken + * + * Last reviewed on 2013-07-11 (1.0.0) + */ #include diff --git a/gst/rtsp-server/rtsp-client.c b/gst/rtsp-server/rtsp-client.c index d5feb6ffe0..6df8059e51 100644 --- a/gst/rtsp-server/rtsp-client.c +++ b/gst/rtsp-server/rtsp-client.c @@ -16,6 +16,28 @@ * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, * Boston, MA 02110-1301, USA. */ +/** + * SECTION:rtsp-client + * @short_description: A client connection state + * @see_also: #GstRTSPServer, #GstRTSPThreadPool + * + * The client object handles the connection with a client for as long as a TCP + * connection is open. + * + * A #GstRTSPClient is created by #GstRTSPServer when a new connection is + * accepted and it inherits the #GstRTSPMountPoints, #GstRTSPSessionPool, + * #GstRTSPAuth and #GstRTSPThreadPool from the server. + * + * The client connection should be configured with the #GstRTSPConnection using + * gst_rtsp_client_set_connection() before it can be attached to a #GMainContext + * using gst_rtsp_client_attach(). From then on the client will handle requests + * on the connection. + * + * Use gst_rtsp_client_session_filter() to iterate or modify all the + * #GstRTSPSession objects managed by the client object. + * + * Last reviewed on 2013-07-11 (1.0.0) + */ #include #include @@ -2391,6 +2413,9 @@ gst_rtsp_client_get_connection (GstRTSPClient * client) * Set @func as the callback that will be called when a new message needs to be * sent to the client. @user_data is passed to @func and @notify is called when * @user_data is no longer in use. + * + * By default, the client will send the messages on the #GstRTSPConnection that + * was configured with gst_rtsp_client_attach() was called. */ void gst_rtsp_client_set_send_func (GstRTSPClient * client, @@ -2453,7 +2478,8 @@ gst_rtsp_client_handle_message (GstRTSPClient * client, * @session: a #GstRTSPSession to send the request to or %NULL * @request: The request #GstRTSPMessage to send * - * Send a request message to the client. + * Send a request message to the remote end. @request must be a + * #GST_RTSP_MESSAGE_REQUEST. */ GstRTSPResult gst_rtsp_client_send_request (GstRTSPClient * client, GstRTSPSession * session, @@ -2733,6 +2759,7 @@ gst_rtsp_client_attach (GstRTSPClient * client, GMainContext * context) g_return_val_if_fail (GST_IS_RTSP_CLIENT (client), 0); priv = client->priv; + g_return_val_if_fail (priv->connection != NULL, 0); g_return_val_if_fail (priv->watch == NULL, 0); /* create watch for the connection and attach */ diff --git a/gst/rtsp-server/rtsp-client.h b/gst/rtsp-server/rtsp-client.h index cd5de87ea1..82f5eec91e 100644 --- a/gst/rtsp-server/rtsp-client.h +++ b/gst/rtsp-server/rtsp-client.h @@ -160,32 +160,32 @@ void gst_rtsp_client_set_mount_points (GstRTSPClient *client, GstRTSPMountPoints *mounts); GstRTSPMountPoints * gst_rtsp_client_get_mount_points (GstRTSPClient *client); -void gst_rtsp_client_set_use_client_settings (GstRTSPClient * client, - gboolean use_client_settings); -gboolean gst_rtsp_client_get_use_client_settings (GstRTSPClient * client); - void gst_rtsp_client_set_auth (GstRTSPClient *client, GstRTSPAuth *auth); GstRTSPAuth * gst_rtsp_client_get_auth (GstRTSPClient *client); void gst_rtsp_client_set_thread_pool (GstRTSPClient *client, GstRTSPThreadPool *pool); GstRTSPThreadPool * gst_rtsp_client_get_thread_pool (GstRTSPClient *client); +void gst_rtsp_client_set_use_client_settings (GstRTSPClient * client, + gboolean use_client_settings); +gboolean gst_rtsp_client_get_use_client_settings (GstRTSPClient * client); + gboolean gst_rtsp_client_set_connection (GstRTSPClient *client, GstRTSPConnection *conn); GstRTSPConnection * gst_rtsp_client_get_connection (GstRTSPClient *client); +guint gst_rtsp_client_attach (GstRTSPClient *client, + GMainContext *context); + void gst_rtsp_client_set_send_func (GstRTSPClient *client, GstRTSPClientSendFunc func, gpointer user_data, GDestroyNotify notify); + GstRTSPResult gst_rtsp_client_handle_message (GstRTSPClient *client, GstRTSPMessage *message); - GstRTSPResult gst_rtsp_client_send_request (GstRTSPClient * client, GstRTSPSession *session, GstRTSPMessage *request); -guint gst_rtsp_client_attach (GstRTSPClient *client, - GMainContext *context); - /** * GstRTSPClientSessionFilterFunc: * @client: a #GstRTSPClient object diff --git a/gst/rtsp-server/rtsp-media-factory-uri.c b/gst/rtsp-server/rtsp-media-factory-uri.c index e2e80d93ef..46300a9f62 100644 --- a/gst/rtsp-server/rtsp-media-factory-uri.c +++ b/gst/rtsp-server/rtsp-media-factory-uri.c @@ -16,6 +16,19 @@ * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, * Boston, MA 02110-1301, USA. */ +/** + * SECTION:rtsp-media-factory-uri + * @short_description: A factory for URI sources + * @see_also: #GstRTSPMediaFactory, #GstRTSPMedia + * + * This specialized #GstRTSPMediaFactory constructs media pipelines from a URI, + * given with gst_rtsp_media_factory_uri_set_uri(). + * + * It will automatically demux and payload the different streams found in the + * media at URL. + * + * Last reviewed on 2013-07-11 (1.0.0) + */ #include diff --git a/gst/rtsp-server/rtsp-media-factory.c b/gst/rtsp-server/rtsp-media-factory.c index 2864f40ae3..391ea83e58 100644 --- a/gst/rtsp-server/rtsp-media-factory.c +++ b/gst/rtsp-server/rtsp-media-factory.c @@ -16,6 +16,25 @@ * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, * Boston, MA 02110-1301, USA. */ +/** + * SECTION:rtsp-media-factory + * @short_description: A factory for media pipelines + * @see_also: #GstRTSPMountPoints, #GstRTSPMedia + * + * The #GstRTSPMediaFactory is responsible for creating or recycling + * #GstRTSPMedia objects based on the passed URL. + * + * The default implementation of the object can create #GstRTSPMedia objects + * containing a pipeline created from a launch description set with + * gst_rtsp_media_factory_set_launch(). + * + * Media from a factory can be shared by setting the shared flag with + * gst_rtsp_media_factory_set_shared(). When a factory is shared, + * gst_rtsp_media_factory_construct() will return the same #GstRTSPMedia when + * the url matches. + * + * Last reviewed on 2013-07-11 (1.0.0) + */ #include "rtsp-media-factory.h" diff --git a/gst/rtsp-server/rtsp-media-factory.h b/gst/rtsp-server/rtsp-media-factory.h index 035cbe2cb0..2815d95f1e 100644 --- a/gst/rtsp-server/rtsp-media-factory.h +++ b/gst/rtsp-server/rtsp-media-factory.h @@ -69,10 +69,10 @@ struct _GstRTSPMediaFactory { * #GstRTSPMedia for @url. The default implementation of this * function calls create_element to retrieve an element and then looks for * pay%d to create the streams. - * @configure: configure the media created with @construct. The default - * implementation will configure the 'shared' property of the media. * @create_pipeline: create a new pipeline or re-use an existing one and * add the #GstRTSPMedia's element created by @construct to the pipeline. + * @configure: configure the media created with @construct. The default + * implementation will configure the 'shared' property of the media. * @media_constructed: signal emited when a media was constructed * @media_configure: signal emited when a media should be configured * @@ -85,8 +85,8 @@ struct _GstRTSPMediaFactoryClass { GstElement * (*create_element) (GstRTSPMediaFactory *factory, const GstRTSPUrl *url); GstRTSPMedia * (*construct) (GstRTSPMediaFactory *factory, const GstRTSPUrl *url); - void (*configure) (GstRTSPMediaFactory *factory, GstRTSPMedia *media); GstElement * (*create_pipeline) (GstRTSPMediaFactory *factory, GstRTSPMedia *media); + void (*configure) (GstRTSPMediaFactory *factory, GstRTSPMedia *media); /* signals */ void (*media_constructed) (GstRTSPMediaFactory *factory, GstRTSPMedia *media); @@ -99,14 +99,14 @@ GType gst_rtsp_media_factory_get_type (void); GstRTSPMediaFactory * gst_rtsp_media_factory_new (void); /* configuring the factory */ -void gst_rtsp_media_factory_set_permissions (GstRTSPMediaFactory *factory, - GstRTSPPermissions *permissions); -GstRTSPPermissions * gst_rtsp_media_factory_get_permissions (GstRTSPMediaFactory *factory); - void gst_rtsp_media_factory_set_launch (GstRTSPMediaFactory *factory, const gchar *launch); gchar * gst_rtsp_media_factory_get_launch (GstRTSPMediaFactory *factory); +void gst_rtsp_media_factory_set_permissions (GstRTSPMediaFactory *factory, + GstRTSPPermissions *permissions); +GstRTSPPermissions * gst_rtsp_media_factory_get_permissions (GstRTSPMediaFactory *factory); + void gst_rtsp_media_factory_set_shared (GstRTSPMediaFactory *factory, gboolean shared); gboolean gst_rtsp_media_factory_is_shared (GstRTSPMediaFactory *factory); diff --git a/gst/rtsp-server/rtsp-media.c b/gst/rtsp-server/rtsp-media.c index 46706fa6bf..78f5f853c4 100644 --- a/gst/rtsp-server/rtsp-media.c +++ b/gst/rtsp-server/rtsp-media.c @@ -16,6 +16,13 @@ * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, * Boston, MA 02110-1301, USA. */ +/** + * SECTION:rtsp-media + * @short_description: The media pipeline + * @see_also: #GstRTSPMediaFactory, #GstRTSPStream + * + * Last reviewed on 2013-07-11 (1.0.0) + */ #include #include diff --git a/gst/rtsp-server/rtsp-mount-points.c b/gst/rtsp-server/rtsp-mount-points.c index 9df3c757dc..86c7a4369a 100644 --- a/gst/rtsp-server/rtsp-mount-points.c +++ b/gst/rtsp-server/rtsp-mount-points.c @@ -16,7 +16,24 @@ * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, * Boston, MA 02110-1301, USA. */ - +/** + * SECTION:rtsp-mount-points + * @short_description: Map a path to media + * @see_also: #GstRTSPMediaFactory, #GstRTSPClient + * + * A #GstRTSPMountPoints object maintains a relation between paths + * and #GstRTSPMediaFactory objects. This object is usually given to + * #GstRTSPClient and used to find the media attached to a path. + * + * With gst_rtsp_mount_points_add_factory () and + * gst_rtsp_mount_points_remove_factory(), factories can be added and + * removed. + * + * With gst_rtsp_mount_points_match() you can find the #GstRTSPMediaFactory + * object that completely matches the given path. + * + * Last reviewed on 2013-07-11 (1.0.0) + */ #include #include "rtsp-mount-points.h" diff --git a/gst/rtsp-server/rtsp-params.c b/gst/rtsp-server/rtsp-params.c index be45e0fc66..d1f9b698c1 100644 --- a/gst/rtsp-server/rtsp-params.c +++ b/gst/rtsp-server/rtsp-params.c @@ -16,6 +16,14 @@ * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, * Boston, MA 02110-1301, USA. */ +/** + * SECTION:rtsp-params + * @short_description: Param get and set implementation + * @see_also: #GstRTSPClient + * + * Last reviewed on 2013-07-11 (1.0.0) + */ + #include #include "rtsp-params.h" diff --git a/gst/rtsp-server/rtsp-permissions.c b/gst/rtsp-server/rtsp-permissions.c index f4098676a9..eae9383be9 100644 --- a/gst/rtsp-server/rtsp-permissions.c +++ b/gst/rtsp-server/rtsp-permissions.c @@ -16,6 +16,14 @@ * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, * Boston, MA 02110-1301, USA. */ +/** + * SECTION:rtsp-permissions + * @short_description: Roles and associated permissions + * @see_also: #GstRTSPToken, #GstRTSPAuth + * + * Last reviewed on 2013-07-11 (1.0.0) + */ + #include diff --git a/gst/rtsp-server/rtsp-sdp.c b/gst/rtsp-server/rtsp-sdp.c index 5dfec79d97..be94d19b55 100644 --- a/gst/rtsp-server/rtsp-sdp.c +++ b/gst/rtsp-server/rtsp-sdp.c @@ -16,6 +16,14 @@ * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, * Boston, MA 02110-1301, USA. */ +/** + * SECTION:rtsp-sdp + * @short_description: Make SDP messages + * @see_also: #GstRTSPMedia + * + * Last reviewed on 2013-07-11 (1.0.0) + */ + #include #include "rtsp-sdp.h" diff --git a/gst/rtsp-server/rtsp-server.c b/gst/rtsp-server/rtsp-server.c index 8f63d3430e..f9766b61b9 100644 --- a/gst/rtsp-server/rtsp-server.c +++ b/gst/rtsp-server/rtsp-server.c @@ -16,7 +16,42 @@ * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, * Boston, MA 02110-1301, USA. */ - +/** + * SECTION:rtsp-server + * @short_description: The main server object + * @see_also: #GstRTSPClient, #GstRTSPThreadPool + * + * 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 with gst_rtsp_server_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) + */ #include #include @@ -99,7 +134,6 @@ GST_DEBUG_CATEGORY_STATIC (rtsp_server_debug); #define GST_CAT_DEFAULT rtsp_server_debug typedef struct _ClientContext ClientContext; -typedef struct _Loop Loop; static guint gst_rtsp_server_signals[SIGNAL_LAST] = { 0 }; @@ -165,7 +199,7 @@ gst_rtsp_server_class_init (GstRTSPServerClass * klass) * pending connections for the server may grow. If a connection request arrives * when the queue is full, the client may receive an error with an indication of * ECONNREFUSED or, if the underlying protocol supports retransmission, the - * request may be ignored so that a later reattempt at connection succeeds. + * request may be ignored so that a later reattempt at connection succeeds. */ g_object_class_install_property (gobject_class, PROP_BACKLOG, g_param_spec_int ("backlog", "Backlog", @@ -376,6 +410,10 @@ out: * @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. */ void diff --git a/gst/rtsp-server/rtsp-server.h b/gst/rtsp-server/rtsp-server.h index 311a01d18c..7140bff2c4 100644 --- a/gst/rtsp-server/rtsp-server.h +++ b/gst/rtsp-server/rtsp-server.h @@ -56,11 +56,12 @@ struct _GstRTSPServer { /** * GstRTSPServerClass: - * * @create_client: Create, configure a new GstRTSPClient - * object that handles the new connection on @socket. + * 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. * @setup_connection: Setup the new client connection. The default - * implementation will configure the TLS certificate. + * implementation will configure the TLS certificate when specified. * @client_connected: emited when a new client connected. * * The RTSP server class structure @@ -68,8 +69,6 @@ struct _GstRTSPServer { struct _GstRTSPServerClass { GObjectClass parent_class; - GThreadPool *pool; - GstRTSPClient * (*create_client) (GstRTSPServer *server); gboolean (*setup_connection) (GstRTSPServer *server, GstRTSPClient *client, GstRTSPConnection *conn); @@ -87,11 +86,14 @@ gchar * gst_rtsp_server_get_address (GstRTSPServer *serve void gst_rtsp_server_set_service (GstRTSPServer *server, const gchar *service); gchar * gst_rtsp_server_get_service (GstRTSPServer *server); -int gst_rtsp_server_get_bound_port (GstRTSPServer *server); - void gst_rtsp_server_set_backlog (GstRTSPServer *server, gint backlog); gint gst_rtsp_server_get_backlog (GstRTSPServer *server); +void gst_rtsp_server_set_tls_certificate (GstRTSPServer *server, GTlsCertificate *cert); +GTlsCertificate * gst_rtsp_server_get_tls_certificate (GstRTSPServer *server); + +int gst_rtsp_server_get_bound_port (GstRTSPServer *server); + void gst_rtsp_server_set_session_pool (GstRTSPServer *server, GstRTSPSessionPool *pool); GstRTSPSessionPool * gst_rtsp_server_get_session_pool (GstRTSPServer *server); @@ -108,9 +110,6 @@ void gst_rtsp_server_set_use_client_settings (GstRTSPServer *se gboolean use_client_settings); gboolean gst_rtsp_server_get_use_client_settings (GstRTSPServer *server); -void gst_rtsp_server_set_tls_certificate (GstRTSPServer *server, GTlsCertificate *cert); -GTlsCertificate * gst_rtsp_server_get_tls_certificate (GstRTSPServer *server); - gboolean gst_rtsp_server_transfer_connection (GstRTSPServer * server, GSocket *socket, const gchar * ip, gint port, const gchar *initial_buffer); diff --git a/gst/rtsp-server/rtsp-session-media.c b/gst/rtsp-server/rtsp-session-media.c index 3f3fd15ef7..5740a0440d 100644 --- a/gst/rtsp-server/rtsp-session-media.c +++ b/gst/rtsp-server/rtsp-session-media.c @@ -16,6 +16,14 @@ * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, * Boston, MA 02110-1301, USA. */ +/** + * SECTION:rtsp-session-media + * @short_description: Media managed in a session + * @see_also: #GstRTSPMedia, #GstRTSPSession + * + * Last reviewed on 2013-07-11 (1.0.0) + */ + #include #include "rtsp-session.h" diff --git a/gst/rtsp-server/rtsp-session-pool.c b/gst/rtsp-server/rtsp-session-pool.c index 393ce6568a..d18c11c14f 100644 --- a/gst/rtsp-server/rtsp-session-pool.c +++ b/gst/rtsp-server/rtsp-session-pool.c @@ -16,6 +16,29 @@ * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, * Boston, MA 02110-1301, USA. */ +/** + * SECTION:rtsp-session-pool + * @short_description: An object for managing sessions + * @see_also: #GstRTSPSession + * + * 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) + */ #include "rtsp-session-pool.h" diff --git a/gst/rtsp-server/rtsp-session.c b/gst/rtsp-server/rtsp-session.c index fe93a5f260..20540ab82b 100644 --- a/gst/rtsp-server/rtsp-session.c +++ b/gst/rtsp-server/rtsp-session.c @@ -16,6 +16,33 @@ * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, * Boston, MA 02110-1301, USA. */ +/** + * SECTION:rtsp-session + * @short_description: An object to manage media + * @see_also: #GstRTSPSessionPool, #GstRTSPSessionMedia, #GstRTSPMedia + * + * 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) + */ + #include #include "rtsp-session.h" diff --git a/gst/rtsp-server/rtsp-stream-transport.c b/gst/rtsp-server/rtsp-stream-transport.c index 0a03ad21c3..40452c27c7 100644 --- a/gst/rtsp-server/rtsp-stream-transport.c +++ b/gst/rtsp-server/rtsp-stream-transport.c @@ -16,6 +16,13 @@ * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, * Boston, MA 02110-1301, USA. */ +/** + * SECTION:rtsp-stream-transport + * @short_description: A media stream transport configuration + * @see_also: #GstRTSPStream + * + * Last reviewed on 2013-07-11 (1.0.0) + */ #include #include diff --git a/gst/rtsp-server/rtsp-stream.c b/gst/rtsp-server/rtsp-stream.c index fd8038e737..63222c4159 100644 --- a/gst/rtsp-server/rtsp-stream.c +++ b/gst/rtsp-server/rtsp-stream.c @@ -16,6 +16,13 @@ * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, * Boston, MA 02110-1301, USA. */ +/** + * SECTION:rtsp-stream + * @short_description: A media stream + * @see_also: #GstRTSPMedia + * + * Last reviewed on 2013-07-11 (1.0.0) + */ #include #include diff --git a/gst/rtsp-server/rtsp-thread-pool.c b/gst/rtsp-server/rtsp-thread-pool.c index 88bd792749..236da0de24 100644 --- a/gst/rtsp-server/rtsp-thread-pool.c +++ b/gst/rtsp-server/rtsp-thread-pool.c @@ -16,6 +16,13 @@ * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, * Boston, MA 02110-1301, USA. */ +/** + * SECTION:rtsp-thread-pool + * @short_description: A pool of threads + * @see_also: #GstRTSPMedia, #GstRTSPClient + * + * Last reviewed on 2013-07-11 (1.0.0) + */ #include diff --git a/gst/rtsp-server/rtsp-token.c b/gst/rtsp-server/rtsp-token.c index 2a4d29bb51..f82e58db3c 100644 --- a/gst/rtsp-server/rtsp-token.c +++ b/gst/rtsp-server/rtsp-token.c @@ -16,6 +16,13 @@ * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, * Boston, MA 02110-1301, USA. */ +/** + * SECTION:rtsp-token + * @short_description: Roles and permissions for a client + * @see_also: #GstRTSPClient, #GstRTSPPermission, #GstRTSPAuth + * + * Last reviewed on 2013-07-11 (1.0.0) + */ #include -- 2.34.1