[svn-to-darcs @ 3]

Initial import.

20070308172817-9b33b-67cd56c0fd9ed7be56f874da659e87cbac239c81.gz

3 files changed, 162 insertions, 0 deletions

diff --git a/docs/.git-darcs-dir b/docs/.git-darcs-dir
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/docs/.git-darcs-dir
diff --git a/docs/Makefile.am b/docs/Makefile.am
new file mode 100644
index 0000000..2d3ef61
--- /dev/null
+++ b/docs/Makefile.am
@@ -0,0 +1,79 @@
+## Process this file with automake to produce Makefile.in
+
+# We require automake 1.6 at least.
+AUTOMAKE_OPTIONS = 1.6
+
+# This is a blank Makefile.am for using gtk-doc.
+# Copy this to your project's API docs directory and modify the variables to
+# suit your project. See the GTK+ Makefiles in gtk+/docs/reference for examples
+# of using the various options.
+
+# The name of the module, e.g. 'glib'.
+DOC_MODULE=telepathy-sofiasip
+
+# The top-level SGML file. You can change this if you want to.
+DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
+
+# The directory containing the source code. Relative to $(srcdir).
+# gtk-doc will search all .c & .h files beneath here for inline comments
+# documenting the functions and macros.
+# e.g. DOC_SOURCE_DIR=../../../gtk
+DOC_SOURCE_DIR=../server
+
+# Extra options to pass to gtkdoc-scangobj. Not normally needed.
+SCANGOBJ_OPTIONS=
+
+# Extra options to supply to gtkdoc-scan.
+# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED" 
+SCAN_OPTIONS=
+
+# Extra options to supply to gtkdoc-mkdb.
+# e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml
+MKDB_OPTIONS=--sgml-mode --output-format=xml
+
+# Extra options to supply to gtkdoc-mktmpl
+# e.g. MKTMPL_OPTIONS=--only-section-tmpl
+MKTMPL_OPTIONS=
+
+# Extra options to supply to gtkdoc-fixref. Not normally needed.
+# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html
+FIXXREF_OPTIONS=
+
+# Used for dependencies. The docs will be rebuilt if any of these change.
+# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h
+# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c
+HFILE_GLOB=
+CFILE_GLOB=
+
+# Header files to ignore when scanning.
+# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
+IGNORE_HFILES=
+
+# Images to copy into HTML directory.
+# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
+HTML_IMAGES=
+
+# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
+# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
+content_files=
+
+# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# These files must be listed here *and* in content_files
+# e.g. expand_content_files=running.sgml
+expand_content_files=
+
+# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
+# Only needed if you are using gtkdoc-scangobj to dynamically query widget
+# signals and properties.
+# e.g. INCLUDES=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
+# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
+INCLUDES=
+GTKDOC_LIBS=
+
+# This includes the standard gtk-doc make rules, copied by gtkdocize.
+# temporarily disabled (2006/04)
+#include $(top_srcdir)/gtk-doc.make
+
+# Other files to distribute
+# e.g. EXTRA_DIST += version.xml.in
+EXTRA_DIST =
diff --git a/docs/design.txt b/docs/design.txt
new file mode 100644
index 0000000..9eebb14
--- /dev/null
+++ b/docs/design.txt
@@ -0,0 +1,83 @@
+title: Design notes for Telepathy-SIP
+version: 20061215-6
+
+General
+-------
+
+Telepathy-sofiasip is a SIP connection manager for the Telepathy framework. 
+The code is based on the Jabber/XMPP connection manager 
+implementation (telepathy-gabble).
+
+Testing
+-------
+
+For testing basic functionality, use the 'tests/tp_caller' app that
+comes with the package.
+
+Use of Sofia-SIP
+----------------
+
+Telepathy-sofiasip originally used the Sofia-SIP "NuaGlib" API, but
+was ported to directly use the "NUA" API to get more direct access
+to the low-level interfaces provided by Sofia-SIP.
+
+There are two different architectural approaches how Sofia-SIP 
+could be used:
+
+ 1) One NUA instance, with one set of operating system level
+    sockets for SIP signaling, is created by the connection
+    manager object.
+ 2) A separate NUA instance is created for each connection
+    to the network.
+
+The current implementation follows (2), but switching to (1) should
+be considered once the multiple identities support in sofia-sip
+matures.
+
+Outbound calls
+--------------
+
+- client requests a channel with type of "StreamedMedia" with remote URI XXX
+  using the RequestChannel method (if:org.freedesktop.Telepathy.Connection)
+    - SIPMediaChannel (sipchan) and SIPMediaSession (sipsess) objects are created
+    - 'sipsess' emits NewSessionHandler
+    - SIPConnection emits NewChannel
+- application requests media streams with "RequestStreams"
+    - SIPMediaStream (sipstream) objects are created
+    - emit sipsess.NewStreamHandler() signal for each stream
+    - emit sipsess.StreamAdded() signal for each stream
+- client creates a StreamEngine (e) and passes the new channel object (c)
+  to it with e.HandleChannel(c)
+    - stream engine connects to the SIPMediaChannel and issues c.GetSessionHandlers()
+    - StreamEngine will connect to signals emitted by the channel object
+    - StreamEngine will call SipMediaSession.Ready() to complete the setup
+- StreamEngine launches local candidate/codec discovery
+- once the local candidate/codecs are found
+     - note: unlike in Jingle, the candidates are sent in one go, 
+       not one candidate at a time
+     - thus in the SIP implementation, we have to have a separate logic
+       to decide when to send our offer/answer
+     - the offer/answer logic depends on the status of all the streams,
+       and only once valid SDP description is available for all of them,
+       an offer/answer can be sent (see sip_media_session.c:priv_offer_answer_step())
+
+Incoming calls
+--------------
+
+- the SIP stack delivers the 'nua_i_invite' signal which is handled in 
+  sip-connection-sofia.c:priv_i_invite()
+- SIPConnection will create the media channel objects and start setting 
+  up them for a session as done for outbound calls (see above) 
+
+Mapping sessions and streams to SIP
+-----------------------------------
+
+- basis for handling sessions and streams is defined in RFC3264,
+  with examples given in RFC4317
+- telepathy-sofiasip has to keep track of all stream added to 
+  a session (removed streams have to be kept around in the signaling,
+  marked as not-used with zero as the port number)
+- the SIPMediaSession object maintains an array of SIPMediaStream
+  objects
+    - note that disabled, or streams with unknown media type,
+      are stored as NULL pointers to the array