Author: derek Date: Tue Nov 14 19:25:36 2006 New Revision: 202 Modified: sofaswitch/trunk/callflow/docs/current/eachicon.dxy Log: Update to describe more of the items on the screen, and in alphabetical order. Modified: sofaswitch/trunk/callflow/docs/current/eachicon.dxy ============================================================================== --- sofaswitch/trunk/callflow/docs/current/eachicon.dxy (original) +++ sofaswitch/trunk/callflow/docs/current/eachicon.dxy Tue Nov 14 19:25:36 2006 @@ -17,6 +17,7 @@ \li \ref subsecReadFromFile \li \ref subsecRequestNode \li \ref subsecStartFlow +\li \ref subsecTimer \li \ref subsecWriteToFile All of the control structures in this application have optional parameters. @@ -28,67 +29,40 @@ can specify a string, which is indicated by placing double quotes at either end. Which makes (for example) "voip" a valid string Python code. -\subsection subsecStartFlow Initiate graph processing -Start of graph processing is indicated by the toolbar icon and drawing area -image of + + + +\subsection subsecConditional Conditional execution +The toolbar icon and a rendering of a drawing area shape for the "Conditional" +item is shown below. <CENTER><TABLE frame=void border=0><TR><TD> -\image html Controlsstart.png +\image html ControlsIf.png </TD><TD>            </TD><TD> -\image html startflow.png +\image html conditional.png </TD></TR> </TABLE></CENTER> +On clicking the right mouse button on this shape, a window comes up. The tool +tip is as described before. The condition, which is evaluated is a Python +expression. Should this expression not be valid, a message will be printed to +the display when the compiled code is executed. + +On evaluation of the compiled code, execution switches to the bottom (True +result) or right output (False result). -When this graph is processed, this item indicates that a new identity on the -server will be created, for each item on this graph to communicate with. Thus, -on instantiation, this graph will be identified as identity \c c290 (say). Any -messages sent via the server will be labelled as being sent by \c c290. -It is mandatory that there is only one of these items on each graph. Placing -more than Start of graph processing item on the drawing area is ambiguous - -where would call processing start ? -\subsection subsecJoinObjects Join items on the drawing area -The toolbar icon and a possible rendering of a drawing area shape is shown below. -<CENTER><TABLE frame=void border=0><TR><TD> -\image html JoinObjects.png -</TD><TD> -           -</TD><TD> -\image html joinlines.png -</TD></TR> -</TABLE></CENTER> -Items on the drawing screen may be joined directly - one to another, or joined -with this structure, which is multiline segment object. -Select the toolbar icon, move to the drawing area, and left click to mark the -points on the shape and complete with the right mouse button. -Once completed, you may move the shape by selecting it with the left button -or shift left to select multiple objects. -When there is a valid connection at both ends of this object, a filled black -circle is drawn at each end. -It is entirely valid to have the output of several items connected to one -item. Thus, of the the following two shapes, the left is valid, -<CENTER><TABLE frame=void border=0><TR><TD> -\image html validjoinexample.png -</TD><TD> -           -</TD><TD> -\image html faultyjoinexample.png -</TD></TR> -</TABLE></CENTER> -and the right shape is wrong. The key problem with the right shape is that it -is ambiguous, since it is not clear where the flow of execution -should go. In this example, it would "work", in that there is no -difference if either path is followed. + + \subsection subsecEndCall End a call End a call to some external entity is indicated by the toolbar icon and drawing area image of @@ -114,41 +88,89 @@ hangup the call, and then make a new call on the same worker node. -\subsection subsecRequestNode Request Node -The toolbar icon and a rendering of a drawing area shape for the "Request Node" + +\subsection subsecEndEverything End Everything +The toolbar icon and a rendering of a drawing area shape for the "End Everything" item is shown below. <CENTER><TABLE frame=void border=0><TR><TD> -\image html RequestNode.png +\image html bitmaps/death.png </TD><TD>            </TD><TD> -\image html requestnode.png +\image html current/Death.png </TD></TR> </TABLE></CENTER> -Request Node is a key component of the SofaSwitch suite of applications. With -this item, the controller asks the designated application to supply one worker -node for use by this call graph. Alternatively, this is the mechanism by which -this call graph gets remote entities who can handle media data. +This icon initiates immediate closure of this Python instance. The connection +to the remote server is severed immediately. All pending TCP messages that we +were to have sent out are dropped. All pending timer events are +ignored. Further, processing will not ever return to any part of this graph. -Once created, the requested worker has a lifetime of 2 seconds. This lifetime is -set by the designated application. If the requested worker is not acknowledged -after 2 seconds, it is destroyed by the designated application. -On receiving advise the node has been created, and its identity, this call -graph can advise the node to "transfer media to itself". Once this command is -made, the requested node is safe from death by timeout. -The Right Mouse Button on this request node shape brings up a menu box. You -may adjust the Tool Tip accordingly - I prefer to change this to indicate -who/what I am requesting a node from. The timer period here is a float, which -indicates how many seconds we will wait for a reply. The timer which runs is -labelled by the above string, which is used in the comparison of an eventer -box \ref subsecEventer. The additional information field is used to provide -details that some SofaSwitch applications want. For example, the conference -utility needs information on which room the node should be in. + + + + + + + + + + + + + +\subsection subsecEndProcessing End Graph Processing +The toolbar icon and a rendering of a drawing area shape for the "End Graph Processing" +item is shown below. +<CENTER><TABLE frame=void border=0><TR><TD> +\image html bitmaps/ControlsEndHere.png +</TD><TD> +           +</TD><TD> +\image html current/endflow.png +</TD></TR> +</TABLE></CENTER> + +This icon is provided as a means for temporarily holding up graph processing, +while we wait for external events. If processing does fall into here, external +events will move graph processing to an Event Collection item as required. +Note that if graph processing was such that some events were never registered +for, then execution will be permanently stuck in the "End Graph Processing" +item. + +When execution is in the "End Graph Processing" item, waiting for an event to +happen, there is no CPU penalty. + +Consider the following graph. +\image html faultyendprocessing.png "Permanent stuckly in End Graph Processing" + +Execution starts at the top, moves to the Event Collection item where it +registers for some event, and then moves to the "End Graph Processing" +item. Since there is no means of generating events which can be sent to this +call graph, execution will never move to the "Event Collection" +item. Consequently, this graph will sit idle, until it is terminated by user +intervention. + + + + + + + + + + + + + + + + + \subsection subsecEventer Event Collection The toolbar icon and a rendering of a drawing area shape for the "Event Collection" item is shown below. @@ -186,76 +208,63 @@ button. To illustrate, after a DTMF event, the Python variable will hold the particular DTMF value that was detected. -\subsection subsecEndEverything End Everything -The toolbar icon and a rendering of a drawing area shape for the "End Everything" -item is shown below. + + + + + + + + +\subsection subsecJoinObjects Join items +The toolbar icon and a possible rendering of a drawing area shape is shown below. <CENTER><TABLE frame=void border=0><TR><TD> -\image html bitmaps/death.png +\image html JoinObjects.png </TD><TD>            </TD><TD> -\image html current/Death.png +\image html joinlines.png </TD></TR> </TABLE></CENTER> -This icon initiates immediate closure of this Python instance. The connection -to the remote server is severed immediately. All pending TCP messages that we -were to have sent out are dropped. All pending timer events are -ignored. Further, processing will not ever return to any part of this graph. +Items on the drawing screen may be joined directly - one to another, or joined +with this structure, which is multiline segment object. +Select the toolbar icon, move to the drawing area, and left click to mark the +points on the shape and complete with the right mouse button. +Once completed, you may move the shape by selecting it with the left button +or shift left to select multiple objects. -\subsection subsecEndProcessing End Graph Processing -The toolbar icon and a rendering of a drawing area shape for the "End Graph Processing" -item is shown below. +When there is a valid connection at both ends of this object, a filled black +circle is drawn at each end. + +It is entirely valid to have the output of several items connected to one +item. Thus, of the the following two shapes, the left is valid, + <CENTER><TABLE frame=void border=0><TR><TD> -\image html bitmaps/ControlsEndHere.png +\image html validjoinexample.png </TD><TD>            </TD><TD> -\image html current/endflow.png +\image html faultyjoinexample.png </TD></TR> </TABLE></CENTER> -This icon is provided as a means for temporarily holding up graph processing, -while we wait for external events. If processing does fall into here, external -events will move graph processing to an Event Collection item as required. -Note that if graph processing was such that some events were never registered -for, then execution will be permanently stuck in the "End Graph Processing" -item. +and the right shape is wrong. The key problem with the right shape is that it +is ambiguous, since it is not clear where the flow of execution +should go. In this example, it would "work", in that there is no +difference if either path is followed. -When execution is in the "End Graph Processing" item, waiting for an event to -happen, there is no CPU penalty. -Consider the following graph. -\image html faultyendprocessing.png "Permanent stuckly in End Graph Processing" -Execution starts at the top, moves to the Event Collection item where it -registers for some event, and then moves to the "End Graph Processing" -item. Since there is no means of generating events which can be sent to this -call graph, execution will never move to the "Event Collection" -item. Consequently, this graph will sit idle, until it is terminated by user -intervention. -\subsection subsecConditional Conditional execution -The toolbar icon and a rendering of a drawing area shape for the "Conditional" -item is shown below. -<CENTER><TABLE frame=void border=0><TR><TD> -\image html ControlsIf.png -</TD><TD> -           -</TD><TD> -\image html conditional.png -</TD></TR> -</TABLE></CENTER> -On clicking the right mouse button on this shape, a window comes up. The tool -tip is as described before. The condition, which is evaluated is a Python -expression. Should this expression not be valid, a message will be printed to -the display when the compiled code is executed. - -On evaluation of the compiled code, execution switches to the bottom (True -result) or right output (False result). + + + + + \subsection subsecMakeCall Make a call Make a call to some external entity is indicated by the toolbar icon and drawing area image of @@ -284,6 +293,18 @@ getting the voip node to make a call to "h323:127.0.0.1". + + + + + + + + + + + + \subsection subsecReadFromFile Read from file Read from file is an answering machine specific function, and is indicated by the toolbar icon and drawing area image of @@ -316,6 +337,103 @@ answering machine worker node. + + + + + + + + + + + + + + + + + + + +\subsection subsecRequestNode Request Node + +The toolbar icon and a rendering of a drawing area shape for the "Request Node" +item is shown below. +<CENTER><TABLE frame=void border=0><TR><TD> +\image html RequestNode.png +</TD><TD> +           +</TD><TD> +\image html requestnode.png +</TD></TR> +</TABLE></CENTER> + +Request Node is a key component of the SofaSwitch suite of applications. With +this item, the controller asks the designated application to supply one worker +node for use by this call graph. Alternatively, this is the mechanism by which +this call graph gets remote entities who can handle media data. + +Once created, the requested worker has a lifetime of 2 seconds. This lifetime is +set by the designated application. If the requested worker is not acknowledged +after 2 seconds, it is destroyed by the designated application. + +On receiving advise the node has been created, and its identity, this call +graph can advise the node to "transfer media to itself". Once this command is +made, the requested node is safe from death by timeout. + +The Right Mouse Button on this request node shape brings up a menu box. You +may adjust the Tool Tip accordingly - I prefer to change this to indicate +who/what I am requesting a node from. The timer period here is a float, which +indicates how many seconds we will wait for a reply. The timer which runs is +labelled by the above string, which is used in the comparison of an eventer +box \ref subsecEventer. The additional information field is used to provide +details that some SofaSwitch applications want. For example, the conference +utility needs information on which room the node should be in. + + + + + + + + + + + + + + + + + + + +\subsection subsecStartFlow Initiate graph processing +Start of graph processing is indicated by the toolbar icon and drawing area +image of +<CENTER><TABLE frame=void border=0><TR><TD> +\image html Controlsstart.png +</TD><TD> +           +</TD><TD> +\image html startflow.png +</TD></TR> +</TABLE></CENTER> + + +When this graph is processed, this item indicates that a new identity on the +server will be created, for each item on this graph to communicate with. Thus, +on instantiation, this graph will be identified as identity \c c290 (say). Any +messages sent via the server will be labelled as being sent by \c c290. + +It is mandatory that there is only one of these items on each graph. Placing +more than Start of graph processing item on the drawing area is ambiguous - +where would call processing start ? + + + + \subsection subsecTimer Timer A timer is indicated by the toolbar icon and drawing area image of <CENTER><TABLE frame=void border=0><TR><TD> @@ -327,6 +445,7 @@ </TD></TR> </TABLE></CENTER> + On clicking the right mouse button on this shape, a window comes up. The tool tip is as described before. @@ -334,7 +453,35 @@ number here with an exponent, or a python variable. Thus, one would specify a delay of 1200 milliseconds as 1.2. -The label one applies to the timer is specified on the +The label one applies to the timer is specified in the last field of the +displayed window. This label is applied to timers generated by this particular +graph, and should only be unique to this graph. Timer events which are +generated when processing a different graph are never passed to this graph. + +We have supplied an example timerlabel of self.myId + "thistimer". The Python +variable self.myId is the string id the server applied to this particular +graph. The text "thistimer" is a string we generated to differentiate two +timers on the same graph. + + + + + + + + + + + + + + + + + + + + \subsection subsecWriteToFile Write to file