emacs-jabber jabber.texi,1.124,1.125

[Magnus H. <leg...@us...>]

Update of /cvsroot/emacs-jabber/emacs-jabber
In directory sc8-pr-cvs17.sourceforge.net:/tmp/cvs-serv3690

Modified Files:
	jabber.texi 
Log Message:
Revision: ma...@fr...--2005/emacs-jabber--cvs-head--0--patch-572
Creator:  Magnus Henoch <ma...@fr...>

Manual: add a section about the connection object


Index: jabber.texi
===================================================================
RCS file: /cvsroot/emacs-jabber/emacs-jabber/jabber.texi,v
retrieving revision 1.124
retrieving revision 1.125
diff -u -d -r1.124 -r1.125
--- jabber.texi	26 Aug 2008 01:49:59 -0000	1.124
+++ jabber.texi	11 Sep 2008 08:23:06 -0000	1.125
@@ -2122,6 +2122,7 @@
 look.  Knowledge of Jabber protocols is assumed.
 
 @menu
+* Connection object::           
 * XML representation::          
 * Roster structure::            
 * Listening for new requests::  
@@ -2131,7 +2132,41 @@
 * Stanza chains::               
 @end menu
 
-@node XML representation, Roster structure, Hacking and extending, Hacking and extending
+@node Connection object, XML representation, Hacking and extending, Hacking and extending
+@section Connection object
+@cindex connection object
+@cindex account object
+@cindex FSM
+
+Each Jabber connection is represented by a ``connection object''.  This
+object has the form of a finite state machine, and is realized by the
+library @code{fsm}.@footnote{So far, this library is only distributed
+with jabber.el.  The author hopes that it could be useful for other
+projects, too.}
+
+The various states of this object are defined in @file{jabber-core.el}.
+They describe the way of the connection through the establishing of a
+network connection and authentication, and finally comes to the
+@code{:session-established} state where ordinary traffic takes place.
+
+These details are normally opaque to an extension author.  As will be
+noted, many functions expect to receive a connection object, and
+functions at extension points generally receive such an object in order
+to pass it on.  The following functions simply query the internal state
+of the connection:
+
+@defun jabber-connection-jid connection
+The @code{jabber-connection-jid} function returns the full JID of
+@var{connection}, i.e. a string of the form
+@code{"username@@server/resource"}.
+@end defun
+
+@defun jabber-connection-bare-jid connection
+The @code{jabber-connection-bare-jid} function returns the bare JID of
+@var{connection}, i.e. a string of the form @code{"username@@server"}.
+@end defun
+
+@node XML representation, Roster structure, Connection object, Hacking and extending
 @section XML representation
 
 @cindex XML representation