[asterisk-commits] phsultan: branch phsultan/jabberreceive r158544 - /team/phsultan/jabberreceiv...

[SVN commits to the Asterisk project]

Author: phsultan
Date: Fri Nov 21 16:40:04 2008
New Revision: 158544

URL: http://svn.digium.com/view/asterisk?view=rev&rev=158544
Log:
Add more usage examples

Modified:
    team/phsultan/jabberreceive/doc/jabber.txt

Modified: team/phsultan/jabberreceive/doc/jabber.txt
URL: http://svn.digium.com/view/asterisk/team/phsultan/jabberreceive/doc/jabber.txt?view=diff&rev=158544&r1=158543&r2=158544
==============================================================================
--- team/phsultan/jabberreceive/doc/jabber.txt (original)
+++ team/phsultan/jabberreceive/doc/jabber.txt Fri Nov 21 16:40:04 2008
@@ -5,10 +5,9 @@
 is immensly extendable.  This allows us to easily integrate Asterisk with 
 XMPP. The Asterisk XMPP Interface is provided by res_jabber.so.
 
-res_jabber allows for Asterisk to connect to any jabber server via the 
-standard client protocol or also as a simple client. 
-
-res_jabber is also used to provide the connection interface for chan_jingle.
+res_jabber allows for Asterisk to connect to any XMPP (Jabber) server and
+is also used to provide the connection interface for chan_jingle and
+chan_gtalk.
 
 A function (JABBER_STATUS) and two applications (JabberSend and
 JabberReceive) are exposed to the dialplan.
@@ -20,7 +19,7 @@
 **** JABBER_STATUS ****
 
 Note : as of version 1.6, the corresponding application JabberStatus is still
-available.
+available, but marked as deprecated in favor of this function.
 
 JABBER_STATUS stores the status of a buddy in a dialplan variable for
 further use. Here is an AEL example of how to use it :
@@ -38,12 +37,11 @@
 
 **** JabberSend ****
 
-JabberSend sends an XMPP message to a buddy. Ex. (call notification) :
+JabberSend sends an XMPP message to a buddy. Example :
 
 context default {
 	_XXXX => {
 	      JabberSend(asterisk-xmpp,buddy at gmail.com,${CALLERID(name)} is calling ${EXTEN});
-	      
 	      Dial(SIP/${EXTEN}, 30);
 	      Hangup();
 	}
@@ -51,27 +49,48 @@
 
 **** JabberReceive ****
 
-JabberReceive waits for an XMPP message from an XMPP buddy and passes
-it to dialplan variable. It makes a Jingle to
-SIP/H323/MGCP/PSTN/... gateway out of Asterisk. In this example, a
-user initiates a Gtalk voice call to Asterisk through his/her
-GoogleTalk client. Asterisk establishes the call and starts a
-chat conversation with the user to ask for a number to dial :
+JabberReceive waits (up to X seconds) for a message from buddy and stores
+it to a dialplan variable. Used along with JabberSend (or SendText, 
+provided it's implemented in the corresponding channel type),
+JabberReceive helps Asterisk interact with users while calls flow
+through the dialplan.
 
-context gtalk-in {
-	s => {
-	  NoOp(Caller id : ${CALLERID(all)});
-	  Answer();
-	  JabberSend(asterisk-xmpp,${CALLERID(name),Please enter the number you wish to call);
-	  JabberReceive(${CALLERID(name)},NEWEXTEN);
-	  JabberSend(asterisk-xmpp,$(CALLERID(name),(Calling ${NEWEXTEN} ...);
-	  Dial(SIP/${NEWEXTEN);
-	  Hangup(); 
+JabberReceive/JabberSend are not tied to the XMPP media modules
+chan_gtalk and chan_jingle, and can be used anywhere in the dialplan.
+In the following example, calls targeted to extension 1234 (be it 
+accessed from SIP, DAHDI or whatever channel type) are controlled by
+user bob at jabber.org. Asterisk notifies him that a call is coming, and
+asks him to take an action. This dialog takes place over an XMPP chat.
+
+context from-ext {
+	1234 => {
+		Answer();
+		JabberSend(asterisk-xmpp,bob at jabber.org,Call from $CALLERID(num), choose an option to process the call);
+		JabberSend(asterisk-xmpp,bob at jabber.org,1 : forward to cellphone);
+		JabberSend(asterisk-xmpp,bob at jabber.org,2 : forward to work phone);
+		JabberSend(asterisk-xmpp,bob at jabber.org,Default action : forward to your voicemail);
+		JabberReceive(bob at jabber.org,OPTION,20);
+		switch (${OPTION}) {
+			case 1:
+	  			JabberSend(asterisk-xmpp,$(CALLERID(name),(Calling cellphone...);
+				Dial(SIP/987654321);
+				break;
+			case 2:
+				JabberSend(asterisk-xmpp,$(CALLERID(name),(Calling workphone...);
+				Dial(SIP/${EXTEN});
+				break;
+			default:
+				Voicemail(${EXTEN}|u)
+		}
 	}
 }
 
-A shorter version for this snippet, that takes advantage of the
-SendText application (available for chan_gtalk) :
+When calling from a GoogleTalk or Jingle client, the CALLERID(name) 
+is set to the XMPP id of the caller (i.e. his JID). In the 
+following example, Asterisk chats back with the caller identified by the 
+caller id. We also take advantage of the SendText implementation in 
+chan_gtalk (available in chan_jingle, and chan_sip as well), to 
+allow the caller to establish SIP calls from his GoogleTalk client :
 
 context gtalk-in {
 	s => {