docs: improve docs

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
 
-<SUBSECTION AuthRoles>
+<SUBSECTION AuthTokens>
-GST_RTSP_MEDIA_FACTORY_ROLE
+GST_RTSP_TOKEN_MEDIA_FACTORY_ROLE
+GST_RTSP_TOKEN_TRANSPORT_CLIENT_SETTINGS
 
 <SUBSECTION AuthPermissions>
-GST_RTSP_MEDIA_FACTORY_PERM_ACCESS
+GST_RTSP_PERM_MEDIA_FACTORY_ACCESS
-GST_RTSP_MEDIA_FACTORY_PERM_CONSTRUCT
+GST_RTSP_PERM_MEDIA_FACTORY_CONSTRUCT
-GST_RTSP_TRANSPORT_PERM_CLIENT_SETTINGS
 <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
+<SUBSECTION MediaPrepare>
-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
 
+<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

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

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
- */
-#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
+ * The default #GstRTSPAuth object uses this string in the token to find the
- * return a 404 Not Found error when trying to access the media.
+ * 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:
+ * GST_RTSP_TOKEN_TRANSPORT_CLIENT_SETTINGS:
- *
- * 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_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
 

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

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

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

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

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

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,
+      gst_rtsp_token_new (GST_RTSP_TOKEN_TRANSPORT_CLIENT_SETTINGS,
-      G_TYPE_BOOLEAN, TRUE, "media.factory.role", G_TYPE_STRING, "user", NULL);
+      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,
+      gst_rtsp_token_new (GST_RTSP_TOKEN_TRANSPORT_CLIENT_SETTINGS,
-      G_TYPE_BOOLEAN, TRUE, "media.factory.role", G_TYPE_STRING, "user", NULL);
+      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;"