Author: derek Date: Tue Jun 19 00:23:31 2007 New Revision: 328 Added: sofaswitch/trunk/overview/app1.sgml sofaswitch/trunk/overview/chap1.sgml sofaswitch/trunk/overview/chap2.sgml Log: Add these files, which are part of the move to docbook for documents. Added: sofaswitch/trunk/overview/app1.sgml ============================================================================== --- (empty file) +++ sofaswitch/trunk/overview/app1.sgml Tue Jun 19 00:23:31 2007 @@ -0,0 +1,77 @@ +<appendix> +<title>Building these docs</title> +<para> +The documentation for &callflow; was generated from multiple +<literal>.sgml</literal> and <literal>.xml</literal> files. The utility +<screen> +xsltproc +</screen> +was used to process the supplied files to generate <literal>html</literal> +files and several auxillary help files. The generated files were compressed +into one <literal>.zip</literal> file. When the &callflow; utility runs, the +generated zip file is read in. A <literal>wxWidgets</literal> class is used to +display the html documentation. +</para> + +<para> +The file <literal>makedoc.xsl</literal> contains the stylesheet commands that +are used when converting the docbook file <literal>callflow.xml</literal> into +html. It is likely that the third line in this file (which specifies the +location of the docbook stylesheet to generate html) will need to be changed +for your particular system. +</para> + +<para> +Under windows, you are still going to use docbook to transform the +<literal>.xml</literal> file into html documentation. You will need to follow +similar steps to those described in a +<ulink url="http://www.codeproject.com/winhelp/docbook_howto.asp">windows +guide</ulink>, but you will end up with native windows looking documentation. +</para> + +<para> +The unix command +<screen> +xsltproc makedoc.xsl callflow.xml +</screen> +will generate output something like +<screen> +Writing ch01.html for chapter +Writing ch02s02.html for sect1 +Writing ch02s03.html for sect1 +Writing ch02s04.html for sect1 +Writing ch02s05.html for sect1 +Writing ch02.html for chapter +Writing ch03s02.html for sect1 +Writing ch03s03.html for sect1 +Writing ch03s04.html for sect1 +Writing ch03s05.html for sect1 +Writing ch03s06.html for sect1 +Writing ch03s07.html for sect1 +Writing ch03s08.html for sect1 +Writing ch03s09.html for sect1 +Writing ch03s10.html for sect1 +Writing ch03s11.html for sect1 +Writing ch03s12.html for sect1 +Writing ch03s13.html for sect1 +Writing ch03s14.html for sect1 +Writing ch03s15.html for sect1 +Writing ch03s16.html for sect1 +Writing ch03.html for chapter +Writing apa.html for appendix +Writing index.html for book +Writing callflow.hhp +Writing callflow.hhc +</screen> +Once the actual html is generated, the zip file must be created. This zip file +contains the files generated by the <literal>xsltproc</literal> command and the +image files referenced by the .sgml files. On +Unix, the command is +<screen> + find . -name \*.html -or -name \*.hh\* -or -name \*.png | xargs zip doc.zip +</screen> +The generated <literal>doc.zip</literal> file must be in the same directory as +where the &callflow; executable is run from. +</para> + +</appendix> Added: sofaswitch/trunk/overview/chap1.sgml ============================================================================== --- (empty file) +++ sofaswitch/trunk/overview/chap1.sgml Tue Jun 19 00:23:31 2007 @@ -0,0 +1,50 @@ +<chapter> +<title>Synopsis of &sofaswitch;</title> +<titleabbrev>Synopsis</titleabbrev> + +<para> +&sofaswitch; is the result of a detailed analsysis of freely available +audio switches. The available switches are (essentially) monolithic monsters +that are unmaintainable, and hard to configure. Further, we saw numerous add on +packages (consisting of hundreds/thousands lines of code) to provide new +functionality. Vast chunks of code were duplicated from one component to +another, with resulting loss of reliability and configurability. +</para> + +<para> +An audio switch is, essentially, a means of connecting multiple different +streams of audio together in a controlled manner. Consequently, &sofaswitch; +was written to do just that. Different components to handle different incoming +audio sources (audio file, voip, TDM, conference), a common "glue" protocol, +and a control system. +</para> + +<para> + &sofaswitch; is a suite of programs. Together, these programs provide the +functionality of a PBX. Operation of these programs is controlled by one +program, which can be written in any language. +</para> + + +<para> +The programs in the &sofaswitch; suite communicate with each viah TCP and UDP +packets. Consequently, there is no requirement for the programs to have the +same license. Further, operation of the &sofaswitch; system is +modularised. Consequently, failure in one prrogram will not stop another +program +</para> + +<para> +The current testing regime has shown the software to be 32 and 64 bit clean. It +compiles and runs fine on Suse 10, Redhat 9, and Fedora Core 1. We expect it +to compile and run correctly on windows. +</para> + +<para> +The user of the &sofaswitch; system has the minimum of limitations on how +different components are joined together. Thus, a call generator, answering +machine with IVR, conference system with IVR can be created with ease. +</para> + +</chapter> + Added: sofaswitch/trunk/overview/chap2.sgml ============================================================================== --- (empty file) +++ sofaswitch/trunk/overview/chap2.sgml Tue Jun 19 00:23:31 2007 @@ -0,0 +1,749 @@ +<chapter> +<title>Format & content of the TCP control message</title> +<titleabbrev>Control message protocol</titleabbrev> + +<para> +In this chapter we explain the format of the TCP messages, which are used to +control the operation of the different &sofaswitch; components. Also described +is the relationship between different components, which is required for the +communications protocol to make any "sense". Some justification is given for +the choices made. However, there will be some topics that no amount of +justification/discussion will be convincing enough. +</para> + + +<para> +As stated before, &sofaswitch; consists of many different running applications, +where each different application may run on a different machine and will have a +different purpose. Consequently, there is a need for a standardised method of +communication between the applications which will work transparently across +OS's, hardware types, and network types. +</para> + +<sect1><title>Micro Management</title> +<para> +A key element in understanding why we chose where communication flows is that +we are opposed to "micro manaagement". By "micro management", we refer to the +practice where one part of the software has an excessive interest in the +minute details of another component in the software. For more details, see +<ulink url="http://en.wikipedia.org/wiki/Micromanagement">wikipedia-micro management</ulink> +</para> + +<para> +To illustrate, the Controlling entity directs two nodes to send audio between +them. There are two distinct methods for implementing this: +<itemizedlist> +<listitem><para> + for the Controller to work out what ports are available in the two nodes, + and then advise both nodes to which port to send the audio data + </para></listitem> + <listitem><para> + two nodes are told they are talking to each other by the Controller. + Then, the two nodes discuss amongst themselves + how they communicate (which could be via tcp, bridging, pipes, etc) + </para></listitem> +</itemizedlist> +</para> + +<para> +The first approach is micro management - the Controller does not need to know +about ports. Worse, it constrains the two nodes to only talk via network +ports. The second approach is harder - the nodes are all given some +"intelligence" and have to be able to respond to a wider range of messages. +The second approach does give flexibility though. If the two nodes are (for +example) on the same telephony card on a PC, they can send audio between them +via direct bridging. +</para> +</sect1> + +<sect1><title> Entities provided by &sofaswitch;</title> +<para> +There are several distinct entities used by &sofaswitch;. It is important to +understand the difference between them, and how the entities interact. +</para> + +<para> +<informaltable frame="all"> +<tgroup cols="2"> +<tbody> +<row><entry><para>Worker</para></entry> +<entry><para> handles commands associated with one particular audio circuit. + In a voip application, which is capable of handling 30 (say) concurrent calls, + there will be (at most) 30 active Workers. +</para></entry></row> +<row><entry><para>Server</para></entry> +<entry><para>responsible for establishing (as required) new + Workers. It can be used to terminate the &sofaswitch; + application. Messages which are appropriate for a particular + Worker are never ever sent via the Supervisor +</para></entry></row> +<row><entry><para>Server </para></entry> +<entry><para> +is responsible for passing control messages between + different &sofaswitch; entities. There is only one instance of + a Server in the &sofaswitch; network, so all control messages + pass through the Server. Thus, the Server knows about every + active &sofaswitch; entity. +</para></entry></row> +<row><entry><para>Controller</para></entry> +<entry><para> +is responsible for generating control mesasges to + get things to happen. It is this entity who initiates + responses from the &sofaswitch; system as real world events + happen. There may be multiple active Controllers - this is a + matter of implementation for the user. +</para></entry></row> +</tbody></tgroup></informaltable> +</para> + +<para> +Even the controller can be split up into a Worker/Supervisor distinction. The +Worker in the controller sends commands appropriate to managing one current +call. The Supervisor creates Workers to handle new calls, as required. How the +Controller is configured/written is entirely up to the user. We have provided +Python examples, and a graphical editor to generate those Python examples, but +the user may choose to implement a completely different system. +</para> + +<para> +Workers and Supervisors exist together inside one running application to +handle voice calls. The Worker is the only entity who "touches" raw audio +data. Everything else worries about control. The Supervisor is in direct +contact with 1 (or more) Workers. Thus, the supervisor is responsible for +Worker creation/initiation/deletion. There are several SofaSwitch +applications (am, mcu, voip), each of which contain one Supervisor and +multiple workers. By sending audio between the different workers, we can +create the functionality of a voice switch. +</para> + +<para> +We have a "star" shaped network, as all control messages go via the +server. However, this is not strictly true as raw audio will pass directly +between any two workers. Alternatively, audio is never ever passed through the +server. This design decision was made so that any extra burst of processing +required on the server will not slow down/interrupt audio traffic. Further, +removing audio traffic from the server reduces the load on the server +considerably. +</para> +</sect1> + +<sect1><title>The contents of all messages</title> +<para> +Control communication is always via text messages in TCP packets. The last +byte in every message is a zero byte. By using a zero byte, we can determine +if the remote stack has concatenated consecutive TCP messages. +</para> + +<para> +Prior to any communication, a node must connect to the server and +identify itself. Once identified, anyone connected to that server can +talk to the node. A node (suppose it is "switch") will first do a TCP +Connect to this server. This server will then spawn of a TCPConnection +class to listen for all further communications from switch. Node +switch then sends a zero terminated string of +</para> + +<para> <literal>switch 0</literal>      + (string, with a trailing zero byte)</para> + +<para> +to this server. This string identifies the remote node to this server. On +receipt of this string, the server can make a unique label for the +TCPConnection class, and add it to the internal list. Once the TCPConnection +class has been added to the internal list, full bidirectional comms is now +possible with node "switch". +</para> + +<para> +The server assumes all remote nodes will correctly choose a valid unique ID. +My preference is that the supervisor connects with a label such as +"controller", "voip", or "am". Workers spawned by that supervisor have a +number appended to the supervisor's label. Thus, the voip supervisor connects +as "voip". All workers spawned by the voip supervisor will be called "voip1", +"voip2", etc. This naming scheme makes debugging somewhat easier, as you can +identify, from the label, the origin/destination of a message. +</para> + +<para> +In some cases, the connecting node has no idea what unique ID to specify. It +will (in this case) use the string "?"0 and let the server assign a unique ID. +The connecting node can then use the command "whoami" to enquire of the server +to find out what unique ID was assigned. This indentification process is ideal +for Controllers. You can invoke multiple instances of the same script to do +some task, and know that all control instances have unique ids. +</para> + +<para> +A control message, which is sent via the server has the format +</para> + +<para><literal> + remoteNode : message 0</literal>      + (string, with a trailing zero byte)</para> + +<para> +The server changes the message, and sends it to the remote node as +</para> +<para><literal> +sourceNode : message 0</literal>      + (string, with a trailing zero byte +</para> + +<para> +Thus, this server has changed the message. This is acceptable, as it +means that the receiving node is able to determine who sent the +message. The receiving node cannot determine the source of the message +by socket analysis. This happens as the network stack of the receiving +node will always say that the source of each packet is this message +server. +</para> + +<para> +To illustrate, suppose A sends the message <literal>status</literal> to B. +A sends to the sever +</para> + +<para><literal>B:status 0</literal>      + (string, with a trailing zero byte)</para> + +<para> +the server receives this packet and then sends to B +</para> + +<para><literal>A:status 0</literal>      + (string, with a trailing zero byte)</para> + +<para> +When B receives this message, B knows the source of the message and can respond +accordingly. Further, should the server concatanate two TCP messages together, +B can accurately split the two messages. The source of each message in a +concatanated block can be easily determined. +</para> +</sect1> + +<sect1> +<title>Worker/Supervisor commands</title> + +<para> +The following commands are provided in this protocol. They are +designed to be sent from a Worker/Supervisor to a +Worker/Supervisor. Most will be sent by Workers, but there is no check +if the source is allowed to send this message. Indeed, it is possible +for any node connected to the server to control any other node +connected to the server. +</para> + + +<para> +<informaltable frame="all"> +<tgroup cols="2"> +<tbody> +<row><entry><para><literal>hangup</literal></para></entry> +<entry><para>The Worker which receives this terminates the current call +</para></entry></row> + +<row><entry><para><literal>callnode</literal></para></entry> +<entry><para> +Causes a Worker/Supervisor to start a voip call to voip destination. This command is + not relevant for an answering machine type node. +</para></entry></row> + +<row><entry><para><literal>status </literal></para></entry> +<entry><para> + A query on the Worker/Supervisor's status. If an argument is supplied, then + status is required of that entity. For example, you could specify the status of a + particular conference room</para></entry></row> + +<row><entry><para><literal> duration</literal></para></entry> +<entry><para> +A query for the worker to reply with the duration of the current call, or the + supervisor to reply with how long it has been up </para></entry></row> + +<row><entry><para><literal> identify </literal></para></entry> +<entry><para> + The node will reply with an english sentence describing how long it has been up +</para></entry></row> + +<row><entry><para><literal>debug</literal></para></entry> +<entry><para> + casue the receiving node to turn on (or not) debugging features. Typically, +this will make the recipient generate text, which goes to the console. +</para></entry></row> + +<row><entry><para><literal> answer</literal></para></entry> +<entry><para> + the worker node will answer the incoming voip call or not. There will be the + word <literal>true</literal> or <literal>false</literal> after the word + <literal>answer</literal>, to say if we answer the call. +</para></entry></row> +<row><entry><para><literal>transferudp</literal></para></entry> +<entry><para> +Used in the exchange to advise remote nodes of where the local udp receive port is +</para></entry></row> +<row><entry><para><literal>queryaddress</literal></para></entry> +<entry><para> + no longer used, as it has been superseded by the transferudp command +</para></entry></row> + +<row><entry><para><literal>adviseaddress</literal></para></entry> +<entry><para> + no longer used, as it has been superseded by the transferudp command +</para></entry></row> + +<row><entry><para><literal>quitnow</literal></para></entry> +<entry><para> +Is only processable by a Supervisor node Worker nodes will ignore this +command. The &sofaswitch; application that processes this +command will exit, and cease execution. +</para></entry></row> + +<row><entry><para><literal>help </literal></para></entry> +<entry><para> + cause the recipient node to reply with the list of understood commands. This +is particularly helpful when you are controlling &sofaswitch; applications +manually by commands typed in at the console. +</para></entry></row> + +<row><entry><para><literal>querydestaddress</literal></para></entry> +<entry><para> + no longer used, as it has been superseded by the transferudp command +</para></entry></row> + +<row><entry><para><literal>senddtmf </literal></para></entry> +<entry><para> +advise the recipient worker to send the folling dtmf stream to the remote voip node. + Typically, a voip worker would receive this message, and send dtmf to the + other end of the call. +</para></entry></row> + +<row><entry><para><literal>receiveddtmf</literal></para></entry> +<entry><para> +A worker node has detected a DTMF sequence, and is passing the detected + sequence back to the controller. Typically, a voip worker would be able to + detect DTMF, and is passing this on to the controller. The sound node, and + telephone line handlers can also detect DTMF events (which are alternatively + key pad presses) +</para></entry></row> + +<row><entry><para><literal>reporttome </literal></para></entry> +<entry><para> +A supervisor (or worker) this message. A controller will send this message. The + recipient of this message will then send all queries (e.g. answer call) to the source + of this mesasge In this way, the +controller will register to receive notification of events from the recipient +of this message. +</para></entry></row> + +<row><entry><para><literal>setreceivedmsgfile</literal></para></entry> +<entry><para> +An answering machine Worker will receive this message, and write incoming + audio to the specified file +</para></entry></row> + + +<row><entry><para><literal>setannouncementfile</literal></para></entry> +<entry><para> +An answering machine Worker will receive this message, and read audio from + the specified file, and send this audio to the address specified in the + previous transfer udp message. +</para></entry></row> +</tbody> +</tgroup> +</informaltable> +</para> +</sect1> + + +<sect1> +<title>Server commands</title> +<para> +Some commands are actioned by the server, and not passed on to the +destination node. These commands do not have a destination node +specified. They are therefore of the format: +</para> + +<para> + <literal>command 0</literal>      + (string, with a trailing zero byte)</para> + +<para> +which contains no colon character, and is terminated by a zero +byte. +</para> + +<para> +<informaltable frame="all"> +<tgroup cols="2"> +<tbody> +<row><entry><para><literal>quitnow </literal></para></entry> +<entry><para> + Cause the server to end. On ending, every application + connected to the server will end also. +</para></entry></row> + +<row><entry><para><literal>list </literal></para></entry> +<entry><para> + Cause the server to respond with a list of all the currently + connected nodes. The command "list" is similar to the notion + of presence as used in XMPP, except that here, presence is + driven by the client. +</para></entry></row> + +<row><entry><para><literal>whoami</literal></para></entry> +<entry><para> + A request to the server to advise us who we are. This command + is useful when we are some controller who has connected to + the server and set the server to generate a unique Id for + us. It is also a debugging tool from the command prompt case + - we can enquire of the server to report our ID. +</para></entry></row> +<row><entry><para><literal>adviseontermination remNode</literal></para></entry> +<entry><para> + This commands the server to (on this node terminating) send a + message to <literal>remNode</literal>. The message will + advise <literal>remNode</literal> that this this node has died. Thus, the + controller will get a message if the box running the answer + machine (for example) is unplugged. + Alternatively, if the application that generated this message crashes, +<literal>remNode</literal> will receive a termination message (sent from the server). +</para></entry></row> +</tbody> +</tgroup> +</informaltable> +</para> + +</sect1> + + +<sect1> +<title>Description & example of the <literal>transferdp</literal> command</title> + +<para> +We stated above that audio is carried on UDP packets between &sofaswitch; +worker nodes. Further, it was noted that the Controller is not required to know +about the method by which the audio is transferred. We describe here how the +exchange of audio between two worker nodes is managed. This example is based +around the audio being carried in UDP packets. +</para> + +<para> +Below is a sequence of three messages, as sent by worker nodes, to setup the +transfer of audio beteen the worker nodes of <literal>voip41</literal> (voice +over ip worker) and <literal>am3</literal> (answering machine worker). Note +that <literal>controller10</literal> is a worker node in the controller, and is +responsible for handling one call. + +<informaltable frame="all"> +<tgroup cols="4"> +<tbody> +<row> +<entry><literal> controller10 </literal></entry> +<entry> sends </entry> +<entry><literal> voip41: transferudp am3 +</literal></entry></row> + +<row><entry><literal> voip41 </literal></entry> +<entry> sends </entry> +<entry><literal> am3:192.168.1.109:6204 +</literal></entry></row> + +<row><entry><literal> am3 </literal></entry> +<entry> sends </entry> +<entry><literal> voip41:192.168.1.54: 45021 done +</literal></entry></row> +</tbody></tgroup></informaltable> +</para> + +<para> +The <literal>controller10</literal> tells <literal>voip41</literal> that it has +to send audio to the <literal>am3</literal> node. Once the controller has sent +this message, the controller has no further news on if anything has +happened. <literal>voip41</literal> receives the transferudp message and +advises <literal>am3</literal> of an ip/port address. This second message in +the transfer advises <literal>am3</literal> of where to send audio data +to. <literal>am3</literal>, on receipt of message 2, can start sending audio to +the address specified in message 2. <literal>am3</literal> then advises +<literal>voip41</literal> of the address that <literal>voip41</literal> should +send audio to. When <literal>voip41</literal> receives message 3, +<literal>voip41</literal> can start sending audio to port 45021 of ip adresss +<literal>192.168.1.54</literal>. On receipt of message 3, +<literal>voip41</literal> will send no more messages, as message 3 contains the +word <literal>done</literal>. +</para> + +<para> +Note that in this example, <literal>voip41</literal> decided that audio had to +be sent via UDP. If <literal>voip41</literal> shared some other interprocess +communication system with <literal>am3</literal>, then the format of the second +and third message could have been entirely different. +</para> + +</sect1> + +<sect1><title> Example of a Supervisor requesting a new id</title> +<para> +The controller supervisor has decided it needs a new worker in a +sofaswitch application. Since the controller supervisor is not +interested in micro management, the controller supervisor will create +a worker node. Consequently, the controller forks/thread create +(whatever) and creates a new Worker node (<literal>controller10</literal>). Now, +<literal>controller10</literal> sends the message +<literal>voip requestnewid</literal> +to the <literal>voip</literal> &sofaswitch; application supervisor. +The voip supervisor creates a new worker +(<literal>voip20</literal>). The voip supervisor sends a message to <literal>controller10</literal> stating +that a newid has been created, and it is <literal>voip20</literal>. The messages, as received by the server are: +</para> + +<para> +<informaltable frame="all"> +<tgroup cols="3"> +<tbody> +<row><entry> <literal>controller10</literal> </entry> +<entry>sends</entry> +<entry><literal>voip:requestnewid</literal></entry></row> + +<row><entry> <literal>voip</literal> </entry> +<entry>sends</entry> +<entry><literal>controller10:requestnewid voip20</literal></entry></row> +</tbody> +</tgroup> +</informaltable> +</para> + +<para> +Then, <literal>controller10</literal> will send messages to <literal>voip20</literal> asking it to +transferudp, or make a call, or whatever. +</para> +</sect1> + + + +<sect1><title> Example of calling a remote voip address</title> +<para> +The controller supervisor should not issue the <literal>callnode</literal> +command. Given that we do not believe in micro management, we will let the +controller supervisor to create a controller-worker thread/process to issue the +<literal>callnode</literal> command. The controller worker will be called +<literal>controller10</literal>. The messages that are sent are: +</para> + +<para> +<informaltable frame="all"> +<tgroup cols="3"> +<tbody> +<row><entry> <literal>controller10</literal> </entry> +<entry>sends</entry> +<entry><literal>voip:requestnewid</literal></entry></row> + +<row><entry> <literal>voip</literal> </entry> +<entry>sends</entry> +<entry><literal>controller10:requestnewid voip20</literal></entry></row> + +<row><entry> <literal>controller10</literal> </entry> +<entry>sends</entry> +<entry><literal>voip20:callnode h323:h323.voxgratia.org</literal></entry></row> + +<row><entry> <literal>voip20</literal> </entry> +<entry>sends</entry> +<entry><literal>controller10:callestablished voip20</literal></entry></row> + +</tbody> +</tgroup> +</informaltable> +</para> + +<para> +The <literal>callestablished</literal> message is sent when the call is up and running. +In this example, <literal>controller10</literal> knew who was making the call. However, +it need not be so. The controller does not have to request a new id to initiate a voip call to a remote node. +Instead, the controller can ask the voip supervisor to create a new call. +</para> + +<para> +In this case the voip supervisor will create a voip worker, and get the voip worker +to make the voip call. The voip worker will then advise (from this example) +<literal>controller10</literal> that the call is established, and the id of the +voip worker. Here, the controller worker is required to wait for the call +established message to find out who is managing the call. +</para> + +<para> +Thus, the voip supervisor can be used to create a Worker (which then implements +the <literal>callnode</literal> command) In this case, a suitable message flow would be: +</para> + +<para> +<informaltable frame="all"> +<tgroup cols="3"> +<tbody> +<row><entry> <literal>controller10</literal> </entry> +<entry>sends</entry> +<entry><literal>voip:callnode h323:h323.voxgratia.org</literal></entry></row> +<row><entry> <literal>voip20</literal> </entry> +<entry>sends</entry> +<entry><literal>controller10:callestablished voip20</literal></entry></row> +</tbody> +</tgroup> +</informaltable> +</para> + + +<para> +Once the controller know who the worker nodes are, it can start the +<literal>transferudp</literal> sequence. However if the voip worker and am +worker complete the <literal>transferudp</literal> sequence before the call is +established (from the voip perspective), and the controller then tells the am +worker the announcement file, the very first part of the announcement file will +not be heard by the remote voip node. +</para> + +<para> +Consequently, the am announcement file should be set after the call is +established. The am received message file can be set at any time. Although, +setting the am announcement file too late will mean that the first part of the +incoming voice call will be missed. +</para> +</sect1> + +<sect1> +<title>Complete example, Make outgoing call</title> +<para> +In this section, we put "everthing together", and describe the commands issued +when a voip call to a remote node is made. To add to the realisim, we capture +the messages as seen by the server. The server can report all incoming and +outgoing messages. Perusal of this log will help the reader to understand what +has happened. +</para> + +<para> +In this example, a voip node is being asked to call a remote entity. Audio data +from the voip worker will be transfered to the &sofaswitch; entity "sound". The +"sound" entity is mainly for testing, and connects a sound card to the +&sofaswitch; environment. The voip node is running on the box at I.P address +<literal>192.168.1.109</literal>. The sound node is running on the box at +I.P. address <literal>192.168.1.108</literal>. +</para> + +<para> +The log of messages from the &sofaswitch; server is provided below. Notice that +this log (generated by the server) contains a column that indicates if the +source of the message, or destination of the message. Thus, most memssages are +repeated, because the log below shows incoming and outgoing messages to the +server. +<programlisting> + +19/ 6/2007 9:52:25.980656 Recv New node of sound +19/ 6/2007 9:52:49.562018 Recv New node of ? +19/ 6/2007 9:52:49.562316 Recv from c83 whoami +19/ 6/2007 9:52:49.562376 Send to c83 c83 +19/ 6/2007 9:52:49.570221 Recv from c83 voip:reporttome +19/ 6/2007 9:52:49.570343 Send to voip c83:reporttome +19/ 6/2007 9:52:49.570371 Recv from c83 voip:REQUESTNEWID +19/ 6/2007 9:52:49.570424 Send to voip c83:REQUESTNEWID +19/ 6/2007 9:52:49.570446 Recv from c83 sound:REQUESTNEWID +19/ 6/2007 9:52:49.571467 Send to sound c83:REQUESTNEWID +19/ 6/2007 9:52:49.572196 Recv from sound AdviseOnTermination c83 +19/ 6/2007 9:52:49.572238 Recv from sound c83:REQUESTNEWID sound +19/ 6/2007 9:52:49.572288 Send to c83 sound:REQUESTNEWID sound +19/ 6/2007 9:52:49.885411 Recv from voip AdviseOnTermination c83 +19/ 6/2007 9:52:49.965734 Recv from voip22 AdviseOnTermination c83 +19/ 6/2007 9:52:49.966074 Recv from voip c83:REQUESTNEWID voip22 +19/ 6/2007 9:52:49.966137 Send to c83 voip:REQUESTNEWID voip22 +19/ 6/2007 9:52:49.967668 Recv from c83 voip22:CALLNODE iax2:guest@conference.freeswitch.org/42 +19/ 6/2007 9:52:49.967791 Send to voip22 c83:CALLNODE iax2:guest@conference.freeswitch.org/42 +19/ 6/2007 9:52:49.967820 Recv from c83 voip22:TRANSFERUDP sound +19/ 6/2007 9:52:49.967862 Send to voip22 c83:TRANSFERUDP sound +19/ 6/2007 9:52:49.976023 Recv from voip22 AdviseOnTermination c83 +19/ 6/2007 9:52:50. 91997 Recv New node of voip32 +19/ 6/2007 9:52:55.641031 Recv from voip22 sound:TRANSFERUDP sound 192.168.1.109:60010 +19/ 6/2007 9:52:55.641122 Send to sound voip22:TRANSFERUDP sound 192.168.1.109:60010 +19/ 6/2007 9:52:55.642802 Recv from sound voip22:TRANSFERUDP sound 192.168.1.108:63000 done +19/ 6/2007 9:52:55.642878 Send to voip22 sound:TRANSFERUDP sound 192.168.1.108:63000 done +19/ 6/2007 9:52:56. 74599 Recv from voip22 c83:CallEstablished voip22 +19/ 6/2007 9:52:56. 74687 Send to c83 voip22:CallEstablished voip22 +19/ 6/2007 10:43:33.733437 Send to c83 sound:Terminating +19/ 6/2007 10:43:33.735661 Recv from c83 sound:TRANSFERUDP sound +19/ 6/2007 10:43:33.735691 Recv from c83 voip22:HANGUP +19/ 6/2007 10:43:33.735739 Send to voip22 c83:HANGUP +</programlisting> +</para> + +<para> +The key events in the above log can be summarized by the list below +<itemizedlist><listitem><para> +The sound node is started, and connects to the server. The server reports that +a new node has started, where the new node has identified itself as +<literal>sound</literal>. +</para></listitem> +<listitem><para> +A controller script is started, which has no fixed/preset identity. It +therefore connects to the server with no id (and uses <literal>?</literal>). In +the third and fourth line, we see how the controller script requests the server +to tell the script what its identity is. +</para></listitem> + +<listitem><para> +The controller requests a worker node from the <literal>voip</literal> node and +from the <literal>sound</literal> node. +</para></listitem> + +<listitem><para> +The controller receives a message that <literal>sound</literal> is available +for use. +</para></listitem> + +<listitem><para> +The nodes <literal>sound</literal>, <literal>voip</literal>, and +<literal>voip22</literal> advise the server that on termination, node +<literal>c83</literal> should receive a message that they died. +</para></listitem> + +<listitem><para> +<literal>voip</literal> sends a message to <literal>c83</literal> stating that +it has created a new worker node (<literal>voip22</literal>) for use. +</para></listitem> + +<listitem><para> +<literal>voip22</literal> is asked to make a voip call to +<literal>iax2:guest@conference.freeswitch.org/42</literal>. In this case, the +call will use the IAX2 voip protocol. +</para></listitem> + +<listitem><para> +Immediately after the call is created, the <literal>transferudp</literal> +process is initiated. The controller (<literal>c83</literal>) causes the audio +input&output of <literal>voip22</literal> and <literal>sound</literal> to be connected. +</para></listitem> + +<listitem><para> +In the middle of the <literal>transferudp</literal> message exchange, there is +a comment about a new node, <literal>voip32</literal>. This new node is created +by the <literal>voip</literal> supervisor ahead of time. In this setup, the +<literal>voip</literal> supervisor has a total of 10 nodes prebuilt, already +connected to the server which are ready for use. Thus, the moment the +<literal>voip</literal> supervisor receives a request for a new worker, it can +reply with an available worker. +</para></listitem> + +<listitem><para> +The voip worker <literal>voip22</literal> sends a message at <literal> +9:52:56. 74687</literal> to say that the call is established. +</para></listitem> + +<listitem><para> +The worker <literal>sound</literal> is terminated by +<literal>Ctrl-C</literal>. The server detects this and sends a message to the +controller at <literal>10:43:33.733437</literal> +</para></listitem> + +<listitem><para> +The call is disestablished. The controller closes down +<literal>voip22</literal> and directs <literal>sound</literal> to redirect +audio to itself. Since the <literal>sound</literal> node is already dead, this +<literal>transferudp</literal> command is dropped. +</para></listitem> +</itemizedlist> +</para> +</sect1> +</chapter> \ No newline at end of file