diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/.git-darcs-dir | 0 | ||||
| -rw-r--r-- | docs/Makefile.am | 79 | ||||
| -rw-r--r-- | docs/design.txt | 83 |
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 |