documentation and some bfix

git-svn-id: http://svn.berlios.de/svnroot/repos/sems/trunk@1368 8eb893ce-cfd4-0310-b710-fb5ebe64c474

apps/dsm/mods/mod_py/PyDSMSession.cpp

@@ -111,7 +111,7 @@ extern "C" {
     int loop = 0;
     int front = 0;
 
-    if(!PyArg_ParseTuple(args,"s|ii",&name, &loop))
+    if(!PyArg_ParseTuple(args,"s|ii", &name, &loop, &front))
       return NULL;
 
     GET_SESS_PTR;
@@ -281,8 +281,8 @@ extern "C" {
     {"playPrompt",       (PyCFunction)playPrompt, METH_VARARGS,"play a prompt"},
     {"playFile",         (PyCFunction)playFile,   METH_VARARGS,"play a file"},
     {"recordFile",       (PyCFunction)recordFile, METH_VARARGS,"start recording to a file"},
-    {"getRecordLength",  (PyCFunction)getRecordLength, METH_VARARGS,"get the length of the current recording"},
-    {"getRecordDataSize",(PyCFunction)getRecordDataSize, METH_VARARGS,"get the data size of the current recording"},
+    {"getRecordLength",  (PyCFunction)getRecordLength, METH_NOARGS,"get the length of the current recording"},
+    {"getRecordDataSize",(PyCFunction)getRecordDataSize, METH_NOARGS,"get the data size of the current recording"},
     {"stopRecord",      (PyCFunction)stopRecord, METH_NOARGS,"stop the running recording"},
     {"closePlaylist",   (PyCFunction)closePlaylist, METH_VARARGS,"close the playlist"},
     {"setPromptSet",    (PyCFunction)setPromptSet, METH_VARARGS,"set prompt set"},
@@ -292,7 +292,7 @@ extern "C" {
     {"mute",            (PyCFunction)mute, METH_NOARGS,"mute RTP)"},
     {"unmute",          (PyCFunction)unmute, METH_NOARGS,"unmute RTP"},
     {"B2BconnectCallee", (PyCFunction)B2BconnectCallee, METH_VARARGS,"connect callee of B2B leg"},
-    {"B2BterminateOtherLeg", (PyCFunction)B2BterminateOtherLeg, METH_VARARGS,"terminate other leg of B2B call"},
+    {"B2BterminateOtherLeg", (PyCFunction)B2BterminateOtherLeg, METH_NOARGS,"terminate other leg of B2B call"},
 
     {NULL}  /* Sentinel */
   };

apps/dsm/mods/mod_py/Readme.mod_py.txt

@@ -0,0 +1,168 @@
+mod_py - DSM actions and conditions in Python
+=============================================
+
+mod_py adds one action and one condition to DSM: py(...)
+
+py() action may execute arbitrary python code; py() condition 
+python code needs to evaluate to an expression which returns
+True or False (or and int value).
+
+The 'type' and 'params' are accessible to determine the current
+event's type and parameters.
+
+py() actions and conditions can access session's variables using
+session.var(name) and session.setvar(name, value).
+
+They may even directly use some media functionality implemented 
+in DSM sessions - see session module's help below. But, 
+conceptionally, mod_py is above DSM, so while it would be 
+possible it is not recommended to extend it with functions that
+manipulate the AmSession directly.
+
+Indentation is a little ugly with multi-line py() actions. 
+But this is Python's fault (in 21st century, who creates a 
+programming language with fixed indentation?).
+
+locals
+======
+type    - event type (dsm.Timer, dsm.Key, ...)
+params  - dictionary with event parameters 
+           (e.g. params['id'] for event==dsm.Timer)
+dsm     - module to access dsm functions (see below)
+session - module to access session functions (see below)
+
+example
+=======
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+import(mod_py);
+
+initial state begin 
+ enter {
+  py(dsm.INFO("hello dsm-world"))
+  py(
+session.setvar('some_variable','some val')
+print session.var('some_variable')
+print "dsm.Timer = ", dsm.Timer
+)
+  setTimer(1, 5);
+  log(2, $some_variable)
+  repost();
+};
+
+transition "timer" begin - py(type == dsm.Timer and params['id'] == '1')  / 
+         py(session.playFile('wav/default_en.wav')); -> wait;
+
+transition "key 1" begin - py(type == dsm.Key and params['key'] == '1')  / 
+         py(session.playFile('wav/default_en.wav')); -> wait;
+
+state wait;
+transition "bye recvd" (begin, wait) - hangup / stop -> end;
+state end;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+modules
+=======
+------------------------
+help on module session:
+
+NAME
+    session
+
+FILE
+    (built-in)
+
+FUNCTIONS
+    B2BconnectCallee(string remote_party, string remote_uri [, bool relayed_invite])
+        connect callee of B2B leg
+
+    B2BterminateOtherLeg()
+        terminate other leg of B2B call
+
+    addSeparator(string name[, bool front])
+        add a named separator to playlist
+
+    closePlaylist(bool notify)
+        close the playlist
+
+    connectMedia()
+        connect media (RTP processing)
+
+    disconnectMedia()
+        disconnect media (RTP processing)
+
+    getRecordDataSize()
+        get the data size of the current recording
+
+    getRecordLength()
+        get the length of the current recording
+
+    mute()
+        mute RTP)
+
+    playFile(string name [, bool loop[, bool front]])
+        play a file
+
+    playPrompt(string name [, bool loop])
+        play a prompt
+
+    recordFile(string name)
+        start recording to a file
+
+    setError(int errno)
+        set error (errno)
+
+    setPromptSet(string name)
+        set prompt set
+
+    setvar(string name, string value)
+        set a session's variable
+
+    stopRecord()
+        stop the running recording
+
+    unmute()
+        unmute RTP
+
+    var(string name)
+        get a session's variable
+------------------------------------
+Help on module dsm:
+
+NAME
+    dsm
+
+FILE
+    (built-in)
+
+FUNCTIONS
+    DBG(string msg)
+        Log a message using SEMS' logging system, level debug
+
+    ERROR(string msg)
+        Log a message using SEMS' logging system, level error
+
+    INFO(string msg)
+        Log a message using SEMS' logging system, level info
+
+    WARN(string msg)
+        Log a message using SEMS' logging system, level warning
+
+    log(int level, string msg)
+        Log a message using SEMS' logging system
+
+DATA
+    Any = 0
+    B2BOtherBye = 13
+    B2BOtherReply = 12
+    DSMEvent = 10
+    Hangup = 6
+    Hold = 7
+    Invite = 1
+    Key = 3
+    NoAudio = 5
+    PlaylistSeparator = 11
+    SessionStart = 2
+    Timer = 4
+    UnHold = 8
+    XmlrpcResponse = 9
+