mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2025-02-04 05:22:30 +00:00
Code Issues 1 Projects Releases Wiki Activity

docs: improve docs

Browse source
This commit is contained in:
Wim Taymans 2013-07-16 12:32:51 +02:00
parent d3d7df5a1e
commit 041b1b79a1
9 changed files with 160 additions and 52 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

34
docs/libs/gst-rtsp-server-sections.txt
View file

@ -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
<SUBSECTION AuthRoles>
GST_RTSP_MEDIA_FACTORY_ROLE
<SUBSECTION AuthTokens>
GST_RTSP_TOKEN_MEDIA_FACTORY_ROLE
GST_RTSP_TOKEN_TRANSPORT_CLIENT_SETTINGS
<SUBSECTION AuthPermissions>
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
<SUBSECTION Standard>
GST_RTSP_AUTH_CAST
GST_RTSP_AUTH_CLASS_CAST
@ -131,14 +131,11 @@ gst_rtsp_client_get_type
<SECTION>
<FILE>rtsp-media</FILE>
<TITLE>GstRTSPMedia</TITLE>
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
<SUBSECTION MediaPrepare>
gst_rtsp_media_prepare
gst_rtsp_media_unprepare
GstRTSPMediaStatus
gst_rtsp_media_get_status
<SUBSECTION MediaStreams>
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
<SUBSECTION MediaState>
gst_rtsp_media_seek
gst_rtsp_media_get_range_string
gst_rtsp_media_set_state
<SUBSECTION MediaClocks>
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
<SUBSECTION Standard>
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
<SUBSECTION Standard>
GST_RTSP_STREAM_TRANSPORT_CAST
GST_RTSP_STREAM_TRANSPORT_CLASS_CAST

32
gst/rtsp-server/rtsp-auth.c
View file

@ -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 <string.h>
@ -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

43
gst/rtsp-server/rtsp-auth.h
View file

@ -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
*/
#define GST_RTSP_MEDIA_FACTORY_ROLE "media.factory.role"
/* permissions */
/**
* GST_RTSP_MEDIA_FACTORY_PERM_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.
* 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_MEDIA_FACTORY_PERM_ACCESS "media.factory.access"
#define GST_RTSP_TOKEN_MEDIA_FACTORY_ROLE "media.factory.role"
/**
* GST_RTSP_MEDIA_FACTORY_PERM_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:
* 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_TRANSPORT_PERM_CLIENT_SETTINGS "transport.client-settings"
#define GST_RTSP_TOKEN_TRANSPORT_CLIENT_SETTINGS "transport.client-settings"
/* permissions */
/**
* 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_PERM_MEDIA_FACTORY_ACCESS "media.factory.access"
/**
* 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_PERM_MEDIA_FACTORY_CONSTRUCT "media.factory.construct"
G_END_DECLS

39
gst/rtsp-server/rtsp-media.c
View file

@ -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)
*/

11
gst/rtsp-server/rtsp-session-media.c
View file

@ -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 <string.h>

18
gst/rtsp-server/rtsp-stream-transport.c
View file

@ -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 <string.h>

3
gst/rtsp-server/rtsp-stream-transport.h
View file

@ -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__ */

22
gst/rtsp-server/rtsp-stream.c
View file

@ -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 <stdlib.h>

10
tests/check/gst/client.c
View file

@ -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;"