Add a README and more example code

Add a README file that contains a small introduction on how to use the server
along with the example code explained in the readme.

docs/README

@@ -0,0 +1,175 @@
+README 
+------
+
+(Last updated on Fri 30 jan 2009, version 0.10.1.1)
+
+This HOWTO describes the basic usage of the GStreamer RTSP libraries and how you
+can build simple server applications with it.
+
+* General
+
+ The server relies heavily on the RTSP infrastructure of GStreamer. This includes
+ all of the media acquisition, decoding, encoding, payloading and UDP/TCP
+ streaming. We use the gstrtpbin element for all the session management. Most of
+ the RTSP message parsing and construction in the server is done using the RTSP
+ library that comes with gst-plugins-base. 
+
+ The result is that the server is rather small (a few 1000 lines of code) and easy
+ to understand and extend. In its current state of development, things change
+ fast, API and ABI are unstable. We encourage people to use it for their various
+ use cases and participate by suggesting changes/features.
+
+ Most of the server is built as a library containing a bunch of GObject objects
+ that provide reasonable default functionality but has a fair amount of hooks
+ to override the default behaviour.
+
+ The server currently integrates with the glib mainloop nicely. It is also a
+ heavy user of multiple threads. It's currently not meant to be used in
+ high-load scenarios and you should probably not put it on a public IP address.
+
+* Initialisation
+
+ You need to initialize GStreamer before using any of the RTSP server functions.
+
+   #include <gst/gst.h>
+
+   int
+   main (int argc, char *argv[])
+   {
+     gst_init (&argc, &argv);
+
+     ...
+   }
+ 
+ The server itself currently does not have any specific initialisation function
+ but that might change in the future.
+
+
+* Creating the server
+
+ The first thing you want to do is create a new GstRTSPServer object. This object
+ will handle all the new client connections to your server once it is added to a
+ GMainLoop. You can create a new server object like this:
+
+   #include <gst/rtsp-server/rtsp-server.h>
+
+   GstRTSPServer *server;
+
+   server = gst_rtsp_server_new ();
+
+ The server will by default listen on port 8554 for new connections. This can be
+ changed by calling gst_rtsp_server_set_port() or with the 'port' GObject
+ property. This makes it possible to run multiple server instances listening on
+ multiple ports on one machine.
+
+ We can make the server start listening on its default port by attaching it to a
+ mainloop. The following example shows how this is done and will start a server
+ on the default 8554 port. For any request we make, we will get a NOT_FOUND
+ error code because we need to configure more things before the server becomes
+ useful.
+
+   #include <gst/gst.h>
+   #include <gst/rtsp-server/rtsp-server.h>
+
+   int
+   main (int argc, char *argv[])
+   {
+     GstRTSPServer *server;
+     GMainLoop *loop;
+
+     gst_init (&argc, &argv);
+
+     server = gst_rtsp_server_new ();
+
+     /* make a mainloop for the default context */
+     loop = g_main_loop_new (NULL, FALSE);
+
+     /* attach the server to the default maincontext */
+     gst_rtsp_server_attach (server, NULL);
+
+     /* start serving */
+     g_main_loop_run (loop);
+   }
+
+ The server manages two other objects: GstRTSPSessionPool and
+ GstRTSPMediaMapping. 
+
+ 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
+ SETUP request for a certain media stream. It contains the configuration that
+ 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
+ request URL to a specific stream and its configuration. We explain in the next
+ topic how to configure this object.
+
+* Making url mappings
+
+ Next we need to define what media is attached to a particular URL. What we want
+ to achieve is that when the user asks our server for a specific URL, say /test,
+ that we create (or reuse) a GStreamer pipeline that produces one or more RTP
+ streams. 
+ 
+ The object that can create such pipeline is called a GstRTSPMediaFactory object. 
+ The default implementation of GstRTSPMediaFactory allows you to easily create
+ GStreamer pipelines using the gst-launch syntax. It possible to create a
+ GstRTSPMediaFactory subclass that uses different methods for constructing
+ pipelines.
+
+ The default GstRTSPMediaFactory can be configured with a gst-launch line that
+ produces a toplevel bin (use '(' and ')' around the pipeline description to
+ force a toplevel GstBin instead of the default GstPipeline toplevel element).
+ The pipeline description should contain elements named payN, one for each
+ stream (ex. pay0, pay1, ...). Also, for increased compatibility each stream
+ should have a different payload type which can be configured on the payloader.
+
+ The following code snippet illustrates how to create a media factory that
+ creates an RTP feed of an H264 encoded test video signal.
+
+   GstRTSPMediaFactory *factory;
+
+   factory = gst_rtsp_media_factory_new ();
+
+   gst_rtsp_media_factory_set_launch (factory, 
+                "( videotestsrc ! x264enc ! rtph264pay pt=96 name=pay0 )");
+
+ Now that we have the media factory, we can attach it to a specific url. To do
+ this we get the default GstRTSPMediaMapping from our server and add the url to
+ factory mapping to it like this:
+
+   GstRTSPMediaMapping *mapping;
+
+   ...create server..create factory..
+
+   /* get the default mapping from the server */
+   mapping = gst_rtsp_server_get_media_mapping (server);
+
+   /* attach the video test signal to the "/test" URL */
+   gst_rtsp_media_mapping_add_factory (mapping, "/test", factory);
+   g_object_unref (mapping);
+
+ When starting the server now and directing an RTP client to the URL (like with 
+ vlc, mplayer or gstreamer):
+
+   rtsp://localhost:8554/test 
+
+ a test signal will be streamed to the client. The full example code can be
+ found in the examples/test-readme.c file.
+
+
+
+
+
+
+
+
+
+
+
+
+
+

examples/Makefile.am

@@ -1,4 +1,4 @@
-noinst_PROGRAMS = test-video test-ogg test-mp4
+noinst_PROGRAMS = test-video test-ogg test-mp4 test-readme
 
 INCLUDES = -I$(top_srcdir) -I$(srcdir)
 

examples/test-readme.c

@@ -0,0 +1,64 @@
+/* GStreamer
+ * Copyright (C) 2008 Wim Taymans <wim.taymans at gmail.com>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Library General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ * Boston, MA 02111-1307, USA.
+ */
+
+#include <gst/gst.h>
+
+#include <gst/rtsp-server/rtsp-server.h>
+
+int
+main (int argc, char *argv[])
+{
+  GMainLoop *loop;
+  GstRTSPServer *server;
+  GstRTSPMediaMapping *mapping;
+  GstRTSPMediaFactory *factory;
+
+  gst_init (&argc, &argv);
+
+  loop = g_main_loop_new (NULL, FALSE);
+
+  /* create a server instance */
+  server = gst_rtsp_server_new ();
+
+  /* get the mapping for this server, every server has a default mapper object
+   * that be used to map uri mount points to media factories */
+  mapping = gst_rtsp_server_get_media_mapping (server);
+
+  /* make a media factory for a test stream. The default media factory can use
+   * gst-launch syntax to create pipelines. 
+   * any launch line works as long as it contains elements named pay%d. Each
+   * element with pay%d names will be a stream */
+  factory = gst_rtsp_media_factory_new ();
+  gst_rtsp_media_factory_set_launch (factory, 
+    "( videotestsrc ! x264enc ! rtph264pay name=pay0 pt=96 )");
+
+  /* attach the test factory to the /test url */
+  gst_rtsp_media_mapping_add_factory (mapping, "/test", factory);
+
+  /* don't need the ref to the mapper anymore */
+  g_object_unref (mapping);
+
+  /* attach the server to the default maincontext */
+  gst_rtsp_server_attach (server, NULL);
+
+  /* start serving */
+  g_main_loop_run (loop);
+
+  return 0;
+}