Module Documentation: ivr Application

Readme file

**********************
* IVR plug-in README *
**********************


Description:
------------

The 'ivr' plug-in enables SEMS to execute Python scripts 
implementing some application. If you need more information
concerning the developement of your own applications, have a
look at the HOWTO under following link:
http://www.iptel.org/howto/sems_application_development_tutorial

Configuration file ivr.conf:
----------------------------

script_path: path to the script repository. All the scripts 
             included in this path will be pre-loaded at startup.

Note: Pre-loaded IVR scripts are registered and thus reachable
      just like every other SEMS application plug-in.

Warning: For security reasons, only pre-loaded scripts can 
         be executed.


How to select which Python script will be executed:
---------------------------------------------------


there are quite a few possibilities to call a certain script:

* based on username:

  - in ser.cfg:
    t_write_unix("/tmp/sems_sock","ivr")

  - in this case, the script is determined by the username 
    found in the request URI.

  - Ex: R-URI 123@sems.iptel.org starts <script_path>/123.py


* based on the plugin name parameter:

  - in ser.cfg:
    t_write_unix("/tmp/sems_sock","whatEverScriptYouWantToUse")

  - this will start <script_path>/whatEverScriptYouWantToUse.py, 
    no matter which URI has been dialed.


* based on the "P-App-Name" header:

  - in ser.cfg:
    t_write_unix("/tmp/sems_sock","sems")

  - the SIP message should contain following header:
    P-App-Name: whatEverScriptYouWantToUse

  - this form will start the application/script mentioned in the header value.


Troubleshooting:
----------------

- How to i know which scripts have been pre-loaded:

  Look at the log file when running with full debug infos.
  You will see at the beginning some similar entries:

(25110) DEBUG: Ivr-Python: Python-Ivr logging started
(25110) DEBUG: onLoad (Ivr.cpp:348): ** IVR compile time configuration:
(25110) DEBUG: onLoad (Ivr.cpp:349): **     built with PYTHON support.
(25110) DEBUG: onLoad (Ivr.cpp:352): **     Text-To-Speech enabled
(25110) DEBUG: onLoad (Ivr.cpp:357): ** IVR run time configuration:
(25110) DEBUG: onLoad (Ivr.cpp:358): **     script path:         '../apps/test_ivr'
(25110) DEBUG: onLoad (Ivr.cpp:374): directory '../apps/test_ivr' opened
(25110) INFO: onLoad (Ivr.cpp:401): Application script registered: test_ivr.

  This means that the script 'test_ivr.py' has been loaded successfully.


- My script won't load:

  Look at the debug information present at start time, some libraries 
  may be missing in which case you should set the proper PYTHONPATH
  before starting SEMS.


IVR API quickref:
-----------------


 globals: getHeader(String headers, String name)
             get header with name from headers

          getSessionParam(String headers, String name)
            get session parameter with name from headers
            (parameter from P-Iptel-Param)

          log(String str)
              log using sems' log facility

          createThread(Callable thread)
              create a thread. Only to be used on module 
              initialization code!

class IvrDialogBase:

    # Event handlers
    def onStart(self): # SIP dialog start
        pass

    def onBye(self): # SIP dialog is BYEd
        pass
    
    def onSessionStart(self): # audio session start
        pass

    def onEmptyQueue(self): # audio queue is empty
        pass
    
    def onDtmf(self,key,duration): # received DTMF
        pass


    # Session control
    def stopSession(self): # stop everything
        pass

    def bye(self): # BYEs (or CANCELs) the SIP dialog
        pass


    # Media control
    def enqueue(self,audio_play,audio_rec): # add something to the playlist
        pass

    def flush(self): # flushes playlist
        pass

    # Call datas / control

    # get only property wrapping AmSipDialog AmSession::dlg.
    # only its properties should be exposed.
    dialog

    # B2BUA

    # if true, traffic will be relayed
    # transaprently to the other side
    # if this is 'True' at the beginning 
    # of the session, the Caller's INVITE
    # will be relayed to the callee, without
    # having to use connectCallee()
    B2BMode = False

    # call given party as (new) callee
    # local_party and local_uri are optional:
    #  if not present, the From of caller leg will be used 
    #  for the From of the callee leg.
    # Another options is connectCallee(None), then the callee 
    # of the initial caller request is connected
    # 
    # remote_party and local_party will be used as To/From headers.
    # remote_uri and local_uri is only provided for the application.
    #
    # Examples: 
    #  self.connectCallee(None)
    #   # connect To of caller leg with From of caller leg
    #  
    #  self.connectCallee('<sip:conference@serverip>', 'sip:conference@serverip')
    #   # connect conference@serverip with From of caller leg
    #  
    #  self.connectCallee('<sip:otheruser@domain>', 'sip:otheruser@domain',\
    #                     'FunkyApp <sip:funkyapp@domain>', 'sip:funkyapp@domain')
    #   # connect otheruser@domain from funkyapp.
    def connectCallee(self,remote_party,remote_uri,local_party,local_uri):
        pass

    # terminate the callee's call
    def terminateOtherLeg(self):
        pass

    # terminate our call
    def terminateLeg(self):
        pass

    # start a new audio session with the caller
    # sends a re-INVITE if needed.
    def connectAudio(self):
        pass

    # end the audio session
    # sends a re-INVITE if needed to reconnect to the current callee
    def disconnectAudio(self):
    	pass

    # B2BUA Event handlers
    # some other handlers...

Links

Back to Application Modules Documentation, to Example Applications.
Generated on Fri May 16 12:02:06 2008 for SEMS by  doxygen 1.5.1
Home |  Recent changes |  Search |  Glossary |  Sitemap |  Login