From: Wim Taymans Date: Tue, 16 Jul 2013 10:32:51 +0000 (+0200) Subject: docs: improve docs X-Git-Tag: 1.19.3~495^2~1015 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=041b1b79a15d53af42fa6e6537f445c644e15a85;p=platform%2Fupstream%2Fgstreamer.git docs: improve docs --- diff --git a/docs/libs/gst-rtsp-server-sections.txt b/docs/libs/gst-rtsp-server-sections.txt index ac36099..978019a 100644 --- a/docs/libs/gst-rtsp-server-sections.txt +++ b/docs/libs/gst-rtsp-server-sections.txt @@ -55,13 +55,13 @@ GST_RTSP_AUTH_CHECK_MEDIA_FACTORY_ACCESS GST_RTSP_AUTH_CHECK_MEDIA_FACTORY_CONSTRUCT GST_RTSP_AUTH_CHECK_TRANSPORT_CLIENT_SETTINGS - -GST_RTSP_MEDIA_FACTORY_ROLE + +GST_RTSP_TOKEN_MEDIA_FACTORY_ROLE +GST_RTSP_TOKEN_TRANSPORT_CLIENT_SETTINGS -GST_RTSP_MEDIA_FACTORY_PERM_ACCESS -GST_RTSP_MEDIA_FACTORY_PERM_CONSTRUCT -GST_RTSP_TRANSPORT_PERM_CLIENT_SETTINGS +GST_RTSP_PERM_MEDIA_FACTORY_ACCESS +GST_RTSP_PERM_MEDIA_FACTORY_CONSTRUCT GST_RTSP_AUTH_CAST GST_RTSP_AUTH_CLASS_CAST @@ -131,14 +131,11 @@ gst_rtsp_client_get_type
rtsp-media GstRTSPMedia -GstRTSPMediaStatus - GstRTSPMedia GstRTSPMediaClass gst_rtsp_media_new gst_rtsp_media_get_element gst_rtsp_media_take_pipeline -gst_rtsp_media_get_status gst_rtsp_media_set_permissions gst_rtsp_media_get_permissions @@ -161,26 +158,31 @@ gst_rtsp_media_get_address_pool gst_rtsp_media_set_buffer_size gst_rtsp_media_get_buffer_size -gst_rtsp_media_use_time_provider -gst_rtsp_media_is_time_provider -gst_rtsp_media_get_time_provider - + gst_rtsp_media_prepare gst_rtsp_media_unprepare +GstRTSPMediaStatus +gst_rtsp_media_get_status + gst_rtsp_media_collect_streams gst_rtsp_media_create_stream - -gst_rtsp_media_get_clock -gst_rtsp_media_get_base_time gst_rtsp_media_n_streams gst_rtsp_media_get_stream gst_rtsp_media_find_stream + gst_rtsp_media_seek gst_rtsp_media_get_range_string gst_rtsp_media_set_state + + +gst_rtsp_media_get_clock +gst_rtsp_media_get_base_time +gst_rtsp_media_use_time_provider +gst_rtsp_media_is_time_provider +gst_rtsp_media_get_time_provider GST_RTSP_MEDIA_CAST GST_RTSP_MEDIA_CLASS_CAST @@ -545,6 +547,7 @@ gst_rtsp_stream_transport_set_callbacks GstRTSPKeepAliveFunc gst_rtsp_stream_transport_set_keepalive +gst_rtsp_stream_transport_keep_alive gst_rtsp_stream_transport_set_active @@ -554,7 +557,6 @@ gst_rtsp_stream_transport_is_timed_out gst_rtsp_stream_transport_send_rtcp gst_rtsp_stream_transport_send_rtp -gst_rtsp_stream_transport_keep_alive GST_RTSP_STREAM_TRANSPORT_CAST GST_RTSP_STREAM_TRANSPORT_CLASS_CAST diff --git a/gst/rtsp-server/rtsp-auth.c b/gst/rtsp-server/rtsp-auth.c index 8b4866f..da575ee 100644 --- a/gst/rtsp-server/rtsp-auth.c +++ b/gst/rtsp-server/rtsp-auth.c @@ -21,7 +21,29 @@ * @short_description: Authentication and authorization * @see_also: #GstRTSPPermission, #GstRTSPtoken * - * Last reviewed on 2013-07-11 (1.0.0) + * The #GstRTSPAuth object is responsible for checking if the current user is + * allowed to perform requested actions. The default implementation has some + * reasonable checks but subclasses can implement custom security policies. + * + * A new auth object is made with gst_rtsp_auth_new(). It is usually configured + * on the #GstRTSPServer object. + * + * The RTSP server will call gst_rtsp_auth_check() with a string describing the + * check to perform. The possible checks are prefixed with + * #GST_RTSP_AUTH_CHECK_*. Depending on the check, the default implementation + * will use the current #GstRTSPToken, #GstRTSPClientState and + * #GstRTSPPermissions on the object to check if an operation is allowed. + * + * The default #GstRTSPAuth object has support for basic authentication. With + * gst_rtsp_auth_add_basic() you can add a basic authentication string together + * with the #GstRTSPToken that will become active when successfully + * authenticated. + * + * When a TLS certificate has been set with gst_rtsp_auth_set_tls_certificate(), + * the default auth object will require the client to connect with a TLS + * connection. + * + * Last reviewed on 2013-07-16 (1.0.0) */ #include @@ -395,18 +417,18 @@ check_factory (GstRTSPAuth * auth, GstRTSPClientState * state, return FALSE; if (!(role = gst_rtsp_token_get_string (state->token, - GST_RTSP_MEDIA_FACTORY_ROLE))) + GST_RTSP_TOKEN_MEDIA_FACTORY_ROLE))) goto no_media_role; if (!(perms = gst_rtsp_media_factory_get_permissions (state->factory))) goto no_permissions; if (g_str_equal (check, "auth.check.media.factory.access")) { if (!gst_rtsp_permissions_is_allowed (perms, role, - GST_RTSP_MEDIA_FACTORY_PERM_ACCESS)) + GST_RTSP_PERM_MEDIA_FACTORY_ACCESS)) goto no_access; } else if (g_str_equal (check, "auth.check.media.factory.construct")) { if (!gst_rtsp_permissions_is_allowed (perms, role, - GST_RTSP_MEDIA_FACTORY_PERM_CONSTRUCT)) + GST_RTSP_PERM_MEDIA_FACTORY_CONSTRUCT)) goto no_construct; } return TRUE; @@ -446,7 +468,7 @@ check_client_settings (GstRTSPAuth * auth, GstRTSPClientState * state, return FALSE; return gst_rtsp_token_is_allowed (state->token, - GST_RTSP_TRANSPORT_PERM_CLIENT_SETTINGS); + GST_RTSP_TOKEN_TRANSPORT_CLIENT_SETTINGS); } static gboolean diff --git a/gst/rtsp-server/rtsp-auth.h b/gst/rtsp-server/rtsp-auth.h index b6b10ad..54c268f 100644 --- a/gst/rtsp-server/rtsp-auth.h +++ b/gst/rtsp-server/rtsp-auth.h @@ -113,7 +113,7 @@ gchar * gst_rtsp_auth_make_basic (const gchar * user, const g * GST_RTSP_AUTH_CHECK_MEDIA_FACTORY_CONSTRUCT: * * Check if media can be constructed from a media factory - * The response is sent on error. + * A response should be sent on error. */ #define GST_RTSP_AUTH_CHECK_MEDIA_FACTORY_CONSTRUCT "auth.check.media.factory.construct" /** @@ -128,35 +128,38 @@ gchar * gst_rtsp_auth_make_basic (const gchar * user, const g /* tokens */ /** - * GST_RTSP_MEDIA_FACTORY_ROLE: + * GST_RTSP_TOKEN_MEDIA_FACTORY_ROLE: * * G_TYPE_STRING, the role to use when dealing with media factories + * + * The default #GstRTSPAuth object uses this string in the token to find the + * role of the media factory. It will then retrieve the #GstRTSPPermissions of + * the media factory and retrieve the role with the same name. + */ +#define GST_RTSP_TOKEN_MEDIA_FACTORY_ROLE "media.factory.role" +/** + * GST_RTSP_TOKEN_TRANSPORT_CLIENT_SETTINGS: + * + * G_TYPE_BOOLEAN, %TRUE if the client can specify TTL, destination and + * port pair in multicast. */ -#define GST_RTSP_MEDIA_FACTORY_ROLE "media.factory.role" +#define GST_RTSP_TOKEN_TRANSPORT_CLIENT_SETTINGS "transport.client-settings" /* permissions */ /** - * GST_RTSP_MEDIA_FACTORY_PERM_ACCESS: + * GST_RTSP_PERM_MEDIA_FACTORY_ACCESS: * * G_TYPE_BOOLEAN, %TRUE if the media can be accessed, %FALSE will * return a 404 Not Found error when trying to access the media. */ -#define GST_RTSP_MEDIA_FACTORY_PERM_ACCESS "media.factory.access" +#define GST_RTSP_PERM_MEDIA_FACTORY_ACCESS "media.factory.access" /** - * GST_RTSP_MEDIA_FACTORY_PERM_CONSTRUCT: + * GST_RTSP_PERM_MEDIA_FACTORY_CONSTRUCT: * * G_TYPE_BOOLEAN, %TRUE if the media can be constructed, %FALSE will * return a 404 Not Found error when trying to access the media. */ -#define GST_RTSP_MEDIA_FACTORY_PERM_CONSTRUCT "media.factory.construct" -/** - * GST_RTSP_TRANSPORT_PERM_CLIENT_SETTINGS: - * - * G_TYPE_BOOLEAN, %TRUE if the client can specify TTL, destination and - * port pair in multicast. - */ -#define GST_RTSP_TRANSPORT_PERM_CLIENT_SETTINGS "transport.client-settings" - +#define GST_RTSP_PERM_MEDIA_FACTORY_CONSTRUCT "media.factory.construct" G_END_DECLS diff --git a/gst/rtsp-server/rtsp-media.c b/gst/rtsp-server/rtsp-media.c index 78f5f85..26f734f 100644 --- a/gst/rtsp-server/rtsp-media.c +++ b/gst/rtsp-server/rtsp-media.c @@ -19,7 +19,44 @@ /** * SECTION:rtsp-media * @short_description: The media pipeline - * @see_also: #GstRTSPMediaFactory, #GstRTSPStream + * @see_also: #GstRTSPMediaFactory, #GstRTSPStream, #GstRTSPSession, + * #GstRTSPSessionMedia + * + * a #GstRTSPMedia contains the complete GStreamer pipeline to manage the + * streaming to the clients. The actual data transfer is done by the + * #GstRTSPStream objects that are created and exposed by the #GstRTSPMedia. + * + * The #GstRTSPMedia is usually created from a #GstRTSPMediaFactory when the + * client does a DESCRIBE or SETUP of a resource. + * + * A media is created with gst_rtsp_media_new() that takes the element that will + * provide the streaming elements. For each of the streams, a new #GstRTSPStream + * object needs to be made with the gst_rtsp_media_create_stream() which takes + * the payloader element and the source pad that produces the RTP stream. + * + * The pipeline of the media is set to PAUSED with gst_rtsp_media_prepare(). The + * prepare method will add rtpbin and sinks and sources to send and receive RTP + * and RTCP packets from the clients. Each stream srcpad is connected to an + * input into the internal rtpbin. + * + * It is also possible to dynamically create #GstRTSPStream objects during the + * prepare phase. With gst_rtsp_media_get_status() you can check the status of + * the prepare phase. + * + * After the media is prepared, it is ready for streaming. It will usually be + * managed in a session with gst_rtsp_session_manage_media(). See + * #GstRTSPSession and #GstRTSPSessionMedia. + * + * The state of the media can be controlled with gst_rtsp_media_set_state (). + * Seeking can be done with gst_rtsp_media_seek(). + * + * With gst_rtsp_media_unprepare() the pipeline is stopped and shut down. When + * gst_rtsp_media_set_eos_shutdown() an EOS will be sent to the pipeline to + * cleanly shut down. + * + * With gst_rtsp_media_set_shared(), the media can be shared between multiple + * clients. With gst_rtsp_media_set_reusable() you can control if the pipeline + * can be prepared again after an unprepare. * * Last reviewed on 2013-07-11 (1.0.0) */ diff --git a/gst/rtsp-server/rtsp-session-media.c b/gst/rtsp-server/rtsp-session-media.c index 5740a04..1b8e7e2 100644 --- a/gst/rtsp-server/rtsp-session-media.c +++ b/gst/rtsp-server/rtsp-session-media.c @@ -21,7 +21,16 @@ * @short_description: Media managed in a session * @see_also: #GstRTSPMedia, #GstRTSPSession * - * Last reviewed on 2013-07-11 (1.0.0) + * The #GstRTSPSessionMedia object manages a #GstRTSPMedia with a given path. + * + * With gst_rtsp_session_media_get_transport() and + * gst_rtsp_session_media_set_transport() the transports of a #GstRTSPStream of + * the managed #GstRTSPMedia can be retrieved and configured. + * + * Use gst_rtsp_session_media_set_state() to control the media state and + * transports. + * + * Last reviewed on 2013-07-16 (1.0.0) */ #include diff --git a/gst/rtsp-server/rtsp-stream-transport.c b/gst/rtsp-server/rtsp-stream-transport.c index 40452c2..c71c8ea 100644 --- a/gst/rtsp-server/rtsp-stream-transport.c +++ b/gst/rtsp-server/rtsp-stream-transport.c @@ -19,9 +19,23 @@ /** * SECTION:rtsp-stream-transport * @short_description: A media stream transport configuration - * @see_also: #GstRTSPStream + * @see_also: #GstRTSPStream, #GstRTSPSessionMedia * - * Last reviewed on 2013-07-11 (1.0.0) + * The #GstRTSPStreamTransport configures the transport used by a + * #GstRTSPStream. It is usually manages by a #GstRTSPSessionMedia object. + * + * With gst_rtsp_stream_transport_set_callbacks(), callbacks can be configured + * to handle the RTP and RTCP packets from the stream, for example when they + * need to be sent over TCP. + * + * With gst_rtsp_stream_transport_set_active() the transports are added and + * removed from the stream. + * + * A #GstRTSPStream will call gst_rtsp_stream_transport_keep_alive() when RTCP + * is received from the client. It will also call + * gst_rtsp_stream_transport_set_timed_out() when a receiver has timed out. + * + * Last reviewed on 2013-07-16 (1.0.0) */ #include diff --git a/gst/rtsp-server/rtsp-stream-transport.h b/gst/rtsp-server/rtsp-stream-transport.h index 61257f5..b73bf6e 100644 --- a/gst/rtsp-server/rtsp-stream-transport.h +++ b/gst/rtsp-server/rtsp-stream-transport.h @@ -100,6 +100,7 @@ void gst_rtsp_stream_transport_set_keepalive (GstRTSPStreamT GstRTSPKeepAliveFunc keep_alive, gpointer user_data, GDestroyNotify notify); +void gst_rtsp_stream_transport_keep_alive (GstRTSPStreamTransport *trans); gboolean gst_rtsp_stream_transport_set_active (GstRTSPStreamTransport *trans, gboolean active); @@ -115,8 +116,6 @@ gboolean gst_rtsp_stream_transport_send_rtp (GstRTSPStreamT gboolean gst_rtsp_stream_transport_send_rtcp (GstRTSPStreamTransport *trans, GstBuffer *buffer); -void gst_rtsp_stream_transport_keep_alive (GstRTSPStreamTransport *trans); - G_END_DECLS #endif /* __GST_RTSP_STREAM_TRANSPORT_H__ */ diff --git a/gst/rtsp-server/rtsp-stream.c b/gst/rtsp-server/rtsp-stream.c index 63222c4..ba8913b 100644 --- a/gst/rtsp-server/rtsp-stream.c +++ b/gst/rtsp-server/rtsp-stream.c @@ -21,7 +21,27 @@ * @short_description: A media stream * @see_also: #GstRTSPMedia * - * Last reviewed on 2013-07-11 (1.0.0) + * The #GstRTSPStream object manages the data transport for one stream. It + * is created from a payloader element and a source pad that produce the RTP + * packets for the stream. + * + * With gst_rtsp_stream_join_bin() the streaming elements are added to the bin + * and rtpbin. gst_rtsp_stream_leave_bin() removes the elements again. + * + * The #GstRTSPStream will use the configured addresspool, as set with + * gst_rtsp_stream_set_address_pool(), to allocate multicast addresses for the + * stream. With gst_rtsp_stream_get_multicast_address() you can get the + * configured address. + * + * With gst_rtsp_stream_get_server_port () you can get the port that the server + * will use to receive RTCP. This is the part that the clients will use to send + * RTCP to. + * + * With gst_rtsp_stream_add_transport() destinations can be added where the + * stream should be sent to. Use gst_rtsp_stream_remove_transport() to remove + * the destination again. + * + * Last reviewed on 2013-07-16 (1.0.0) */ #include diff --git a/tests/check/gst/client.c b/tests/check/gst/client.c index d3a1808..8a442bc 100644 --- a/tests/check/gst/client.c +++ b/tests/check/gst/client.c @@ -536,8 +536,9 @@ GST_START_TEST (test_client_multicast_invalid_transport_specific) state.client = client; state.auth = gst_rtsp_auth_new (); state.token = - gst_rtsp_token_new (GST_RTSP_TRANSPORT_PERM_CLIENT_SETTINGS, - G_TYPE_BOOLEAN, TRUE, "media.factory.role", G_TYPE_STRING, "user", NULL); + gst_rtsp_token_new (GST_RTSP_TOKEN_TRANSPORT_CLIENT_SETTINGS, + G_TYPE_BOOLEAN, TRUE, GST_RTSP_TOKEN_MEDIA_FACTORY_ROLE, G_TYPE_STRING, + "user", NULL); gst_rtsp_client_state_push_current (&state); /* simple SETUP with a valid URI and multicast, but an invalid ip */ @@ -623,8 +624,9 @@ GST_START_TEST (test_client_multicast_transport_specific) state.client = client; state.auth = gst_rtsp_auth_new (); state.token = - gst_rtsp_token_new (GST_RTSP_TRANSPORT_PERM_CLIENT_SETTINGS, - G_TYPE_BOOLEAN, TRUE, "media.factory.role", G_TYPE_STRING, "user", NULL); + gst_rtsp_token_new (GST_RTSP_TOKEN_TRANSPORT_CLIENT_SETTINGS, + G_TYPE_BOOLEAN, TRUE, GST_RTSP_TOKEN_MEDIA_FACTORY_ROLE, G_TYPE_STRING, + "user", NULL); gst_rtsp_client_state_push_current (&state); expected_transport = "RTP/AVP;multicast;destination=233.252.0.1;"