docs: update docs and comments

3 files changed, 119 insertions, 38 deletions

diff --git a/docs/README b/docs/README
index 76d4ab9..50ad82f 100644
--- a/docs/README
+++ b/docs/README
@@ -100,13 +100,13 @@ can build simple server applications with it.
  the client negotiated with the server to receive the particular stream, ie. the
  transport used and port pairs for UDP along with the state of the streaming.
  The default implementation of the session pool is usually sufficient but
  alternative implementation can be used by the server.
 
  The GstRTSPMediaMapping object is more interesting and needs more configuration
- before the server object is useful. This object manages to mapping from a
+ before the server object is useful. This object manages the mapping from a
  request URL to a specific stream and its configuration. We explain in the next
  topic how to configure this object.
 
 
 * Making url mappings
 
@@ -199,74 +199,156 @@ can build simple server applications with it.
 
  The prepare method will also create 2 UDP ports for each stream that can be
  used for sending and receiving RTP/RTCP from clients. These port numbers will
  have to be negotiated with the client in the SETUP requests.
 
  When preparing a GstRTSPMedia, a multifdsink is also constructed for streaming
- the stream over TCP^when requested.
+ the stream over TCP when requested.
 
 
 * the GstRTSPClient object
 
  When a server detects a new client connection on its port, it will call its
  accept_client vmethod. The default implementation of this function will create
  a new GstRTCPClient object, will configure the session pool and media mapper
  objects in it and will then call the accept function of the client.
 
- The default GstRTSPClient will accept the connection and will start a new
- GThread to handle the connection. In RTSP it is usual to keep the connection
- open between multiple RTSP requests. The client thread will simply block for a
- new GstRTSPMessage, will dispatch it and will send a response.
- 
- We will briefly describe how it deals with some common requests.
+ The default GstRTSPClient will accept the connection and will attach a watch to
+ the server mainloop. In RTSP it is usual to keep the connection
+ open between multiple RTSP requests. The client watch will be dispatched by the
+ server mainloop when a new GstRTSPMessage is received, which will then be
+ handled and a response will be sent.
+
+ The GstRTSPClient object remains alive for as long as a client has a TCP
+ connection open with the server. Since is possible for a client to open and close
+ the TCP connection between requests, we cannot store the state related
+ to the configured RTSP session in the GstRTSPClient object. This server state
+ is instead stored in the GstRTSPSession object.
 
- - DESCRIBE:
 
-    locates the GstRTSPMedia for the url, prepares it and asks the sdp helper
-    function to construct an SDP from the caps of the prepared media pipeline.
-    It will also cache the url+media object so that it can be reused later.
+* GstRTSPSession
+
+ This object contains state about a specific RTSP session identified with a
+ session id. This state contains the configured streams and their associated
+ transports.
  
- - SETUP
+ When a GstRTSPClient performs a SETUP request, the server will allocate a new
+ GstRTSPSession with a unique session id from the GstRTSPSessionPool. The pool
+ maintains a list of all existing sessions and makes sure that no session id is
+ used multiple times. The session id is sent to the client so that the client
+ can refer to its previously configured state by sending the session id in
+ further requests.
+
+ A client will then use the session id to configure one or more streams,
+ identified by their url. This information is kept in a GstRTSPSessionMedia
+ structure that is refered to from the GstRTSPSession. 
+
+
+* GstRTSPSessionMedia and GstRTSPSessionStream
+
+ A GstRTSPSessionMedia is identified by a URL and is referenced by a
+ GstRTSPSession. It is created as soon as a client performs a SETUP operation on
+ a particular URL. It will contain a link to the GstRTSPMedia object associated
+ with the URL along with the state of the media and the configured transports
+ for each of the streams in the media.
+
+ Each SETUP request performed by the client will configure a
+ GstRTSPSessionStream object linked to by the GstRTSPSessionMedia structure.
+ It will contain the transport information needed to send this stream to the
+ client. The GstRTSPSessionStream also contains a link to the GstRTSPMediaStream
+ object that generates the actual data to be streamed to the client.
 
-    A new GstRTSPSession object will be created from the GstRTSPSessionPool
-    object configured in the GstRTSPClient. This session will contain the
-    configuration of the client regarding the media it is streaming and the
-    ports/transport it negotiated with the server.
+ Note how GstRTSPMedia and GstRTSPMediaStream (the providers of the data to
+ stream) are decoupled from GstRTSPSessionMedia and GstRTSPSessionStream (the
+ configuration of how to send this stream to a client) in order to be able to
+ send the data of one GstRTSPMedia to multiple clients.
 
-    The sessionid is set in the response header. The client will add the
-    sessionid to any further SETUP/PLAY/PAUSE/TEARDOWN request so that we can
-    always find the session again.
 
-    The session configuration for a sessionid will have a link to the prepared
-    GstRTSPMedia object of the stream. The port and transport of the client is
-    stored in the session configuration.
+* media control
 
- - PLAY
+ After a client has configured the transports for a GstRTSPMedia and its
+ GstRTSPMediaStreams, the client can play/pause/stop the stream.
 
-    The session configuration is retrieved with the sessionid and the client
-    ports are configured in the UDP sinks, then the streaming to the client 
-    is started. 
+ The GstRTSPMedia object was prepared in the DESCRIBE call (or during SETUP when
+ the client skipped the DESCRIBE request). As seen earlier, this configures a
+ couple of multiudpsink and udpsrc elements to respectively send and receive the
+ media to clients.
 
- - PAUSE
+ When a client performs a PLAY request, its configured destination UDP ports are
+ added to the GstRTSPMediaStream target destinations, at which point data will
+ be sent to the client. The corresponding GstRTSPMedia object will be set to the
+ PLAYING state if it was not allready in order to send the data to the
+ destination.
 
-    The session configuration is retrieved with the sessionid and the client
-    ports are removed from the UDP sinks, the streaming to the client 
-    pauses. 
+ The server needs to prepare an RTP-Info header field in the PLAY response,
+ which consists of the sequence number and the RTP timestamp of the next RTP
+ packet. In order to achive this, the server queries the payloaders for this
+ information when it prerolled the pipeline.
 
- - TEARDOWN
+ When a client performs a PAUSE request, the destination UDP ports are removed
+ from the GstRTSPMediaStream object and the GstRTSPMedia object is set to PAUSED
+ if no other destinations are configured anymore.
 
-    The session configuration is released along with its link to the
-    GstRTSPMedia object. When no more clients are refering to the GstRTSPMedia
-    object, it can be released as well.
 
+* seeking
+
+ A seek is performed when a client sends a Range header in the PLAY request.
+ This only works when not dealing with shared (live) streams.
+
+ The server performs a GStreamer flushing seek on the media, waits for the
+ pipeline to preroll again and then responds to the client after collecting the
+ new RTP sequence number and timestamp from the payloaders.
+
+
+* session management
+
+ The server has to react to clients that suddenly disappear because of network
+ problems or otherwise. It needs to make sure that it can reasonable free the
+ resources that are used by the various objects in use for streaming when the
+ client appears to be gone.
+
+ Each of the GstRTSPSession objects managed by a GstRTSPSessionPool has
+ therefore a last_access field that contains the timestamp of when activity from
+ a client was last recorded.
+ 
+ Various ways exist to detect activity from a client:
 
+  - RTSP keepalive requests. When a client is receiving RTP data, the RTSP TCP
+    connection is largely unused. It is the client responsability to
+    periodically send keep-alive requests over the TCP channel.
 
+    Whenever a keep-alive request is received by the server (any request that
+    contains a session id, usually an OPTION or GET_PARAMETER request) the
+    last_access of the session is updated.
 
+  - Since it is not required for a client to keep the RTSP TCP connection open
+    while streaming, gst-rtsp-server also detects activity from clients by
+    looking at the RTCP messages it receives.
 
+    When an RTCP message is received from a client, the server looks in its list
+    of active ports if this message originates from a known host/port pair that
+    is currently active in a GstRTSPSession. If this is the case, the session is
+    kept alive.
 
+    Since the server does not know anything about the port number that will be
+    used by the client to send RTCP, this method does not always work. Later
+    RTSP RFCs will include support for negotiating this port number with the
+    server. Most clients however use the same port number for sending and
+    receiving RTCP exactly for this reason.
 
+ If there was no activity in a particular session for a long time (by default 60
+ seconds), the sessionpool will destroy the session along with all related
+ objects and media as if a TEARDOWN happened from the client.
 
 
+* TEARDOWN
 
+ A TEARDOWN request will first location the GstRTSPSessionMedia of the URL. It
+ will then remove all transports from the streams, making sure that streaming
+ stops to the client. It will then remove the GstRTSPSessionMedia and
+ GstRTSPSessionStream structures. Finally the GstRTSPSession is released back
+ into the pool.
 
+ When there are no more references to the GstRTSPMedia, the media pipeline is
+ shut down and destroyed.
 
 
diff --git a/gst/rtsp-server/rtsp-client.c b/gst/rtsp-server/rtsp-client.c
index c8f75dc..ee76abc 100644
--- a/gst/rtsp-server/rtsp-client.c
+++ b/gst/rtsp-server/rtsp-client.c
@@ -1472,13 +1472,13 @@ static GstRTSPWatchFuncs watch_funcs = {
 
 /**
  * gst_rtsp_client_attach:
  * @client: a #GstRTSPClient
  * @channel: a #GIOChannel
  *
- * Accept a new connection for @client on the socket in @source. 
+ * Accept a new connection for @client on the socket in @channel. 
  *
  * This function should be called when the client properties and urls are fully
  * configured and the client is ready to start.
  *
  * Returns: %TRUE if the client could be accepted.
  */
diff --git a/gst/rtsp-server/rtsp-server.c b/gst/rtsp-server/rtsp-server.c
index 3d690f8..489224f 100644
--- a/gst/rtsp-server/rtsp-server.c
+++ b/gst/rtsp-server/rtsp-server.c
@@ -461,14 +461,13 @@ default_accept_client (GstRTSPServer *server, GIOChannel *channel)
 
   /* a new client connected, create a session to handle the client. */
   client = gst_rtsp_client_new ();
 
   /* set the session pool that this client should use */
   gst_rtsp_client_set_session_pool (client, server->session_pool);
-
-  /* set the session pool that this client should use */
+  /* set the media mapping that this client should use */
   gst_rtsp_client_set_media_mapping (client, server->media_mapping);
 
   /* accept connections for that client, this function returns after accepting
    * the connection and will run the remainder of the communication with the
    * client asyncronously. */
   if (!gst_rtsp_client_accept (client, channel))