Changes between Version 4 and Version 5 of Python_SIP_Tutorial

Timestamp:

Jul 15, 2008 11:29:07 AM (16 years ago)

Author:

bennylp

Comment:

--

Python_SIP_Tutorial

@@ -1 +1 @@
 
 = Getting Started =
-
-The Python language binding for PJSUA-API is available in PJSIP release 0.5.10 or later.
+----
+
+This tutorial replaces the older [wiki:Py_PJSUA py_pjsua] tutorial.
 
 == What is it? ==
 
-'''[/repos/browser/pjproject/trunk/pjsip-apps/src/py_pjsua py_pjsua]''' is a Python module implemented in C language to provide '''[http://www.pjsip.org/pjsip/docs/html/group__PJSUA__LIB.htm PJSUA-API]''' for [http://www.python.org Python] applications. Using '''[/repos/browser/pjproject/trunk/pjsip-apps/src/py_pjsua py_pjsua]''' enables Python application to exploit the features of PJSIP, for example:
- * multiple SIP accounts
- * SIP for presence (SIMPLE) and instant messaging
- * multiple/unlimited calls
- * call hold and transfer (attended or unattended)
- * DTMF support
- * conferencing with multiple/unlimited sources
- * wideband and ultra-wideband audio support
- * WAV files playback, playlist, and recording
- * adaptive jitter buffer, silence detection, packet lost concealment, etc.
- * tone generation
- * multiple sound devices (planned)
- * ICE support (planned)
- * and so on.
-
-== Status ==
-
-The '''py_pjsua''' module has just been released on 0.5.10 version and therefore it's expected to contain few bugs, so it's still in alpha/beta stage.
-
-Also since the Python abstraction is created manually (rather than using automated Python abstraction generation tools), it is expected that there will be time lag between introduction of new API in PJSUA-API (the C API) and the implementation in the Python module.
-
-
-== Building py_pjsua Module ==
+This is the new Python wrapper for [http://www.pjsip.org/pjsip/docs/html/group__PJSUA__LIB.htm PJSUA API] which is available in PJSIP version 0.9.5 and later. It is much easier to use, much more Python-ish, and it deprecates the old [wiki:Py_PJSUA py_pjsua] Python module.
+
+The Python wrapper is implemented in two modules:
+
+ '''_pjsua''' module ::
+  This is the low-level C Python module which provides Python binding to [http://www.pjsip.org/pjsip/docs/html/group__PJSUA__LIB.htm PJSUA API]. This module is the successor of  [wiki:Py_PJSUA py_pjsua] module which now has been deprecated.
+
+ '''pjsua''' module ::
+  This is the higher level abstraction for [http://www.pjsip.org/pjsip/docs/html/group__PJSUA__LIB.htm PJSUA API]. It is object oriented and implemented purely on Python, on top of {{{_pjsua}}} module.
+
+Applications should use the '''pjsua''' module rather than '''_pjsua''' module, since it is easier to use and it is the module which API compatibility will be maintained between releases.
+
+You can find all the source codes in [source:pjproject/trunk/pjsip-apps/src/python pjproject/pjsip-apps/src/python] directory.
+
+
+== Building The Modules ==
 
 Using Microsoft Visual Studio projects:
  * Open '''pjsip-apps.dsw''' from {{{pjsip-apps\build}}} directory.
- * Select '''py_pjsua''' project.
+ * Select '''python_pjsua''' project as the active project.
  * Build the project
- * The Python module will be placed in {{{pjsip-apps\lib}}} directory.
+ * The {{{_pjsua.pyd}}} Python module will be placed in {{{pjsip-apps\lib}}} directory.
+ * Copy {{{_pjsua.pyd}}} and {{{pjsua.py}}} from {{{pjsip-apps\src\python}}} directory to Python's site_packages directory (see Python manual for this), or alternatively add the directories where these files reside to your {{{PYTHONPATH}}} environment variable.
 
 Using Python build script:
- * Go to {{{pjsip-apps/src/py_pjsua}}} directory.
+ * Go to {{{pjsip-apps/src/python}}} directory.
  * Run '''{{{'python ./setup.py build'}}}'''
  * The Python module will be placed in {{{build}}} directory inside current directory.
- * Alternatively run '''{{{'python ./setup.py install'}}}''' to install the '''py_pjsua''' module to Python's site_packages directory.
-
+ * Alternatively run '''{{{'python ./setup.py install'}}}''' to install both '''_pjsua''' and '''pjsua''' modules to Python's site_packages directory.
+
+[[BR]]
 
 = Developing Python SIP Application =
+----
 
 == Introduction ==
 
-The Python API is pretty much the same like PJSUA-API - each Python function corresponds to one function in PJSUA-API, therefore one can use [http://www.pjsip.org/pjsip/docs/html/group__PJSUA__LIB.htm PJSUA-API Documentation] or [wiki:PJSIP_Tutorial PJSUA Tutorial] to learn about the Python API.
-
-To highlight the similarities between PJSUA-API and the py_pjsua API, below are some sample names:
-
-{{{
-         PJSUA-API:                       py_pjsua API:
-
-  #include <pjsua-lib/pjsua.h>  ==>   import py_pjsua
-
-  pjsua_create()                ==>   py_pjsua.create()
-  pjsua_init()                  ==>   py_pjsua.init()
-  
-  pjsua_call_make_call()        ==>   py_pjsua.call_make_call()
-}}}
-
-
-
-
-== Sample Application ==
-
-Please see [/repos/browser/pjproject/trunk/pjsip-apps/src/py_pjsua/pjsua_app.py pjsua_app.py] for a sample/simple Python application.
-
-
-== Documentation ==
-
-The documentation for the Python module is integrated with '''[http://www.pjsip.org/pjsip/docs/html/group__PJSUA__LIB.htm PJSUA-API Documentation]'''. Please follow the step by step on how to use the API there, as well as specific instructions to use each PJSUA feature.
-
+The pjsua module only contains few classes so it should be straightforward to use.
+
+=== Error Handling ===
+
+By convention, we use exceptions as means to report error. Operations which yields error will raise [http://www.pjsip.org/python/pjsua.htm#Error pjsua.Error] exception.
+
+
+=== Lib Class ===
+
+The [http://www.pjsip.org/python/pjsua.htm#Lib Lib] class provides the base API's to communicate with PJSUA-API and to create objects (such as [http://www.pjsip.org/python/pjsua.htm#Account Account] and [http://www.pjsip.org/python/pjsua.htm#Transport Transport]).
+
+==== Initializing the Library ====
+
+Instantiate the library:
+
+ {{{
+#!python
+
+import pjsua as pj
+
+lib = pj.Lib()
+
+ }}}
+
+then initialize and start the library. 
+
+ {{{
+#!python
+
+try:
+    lib.init()
+    lib.start()
+
+except pj.Error, e:
+    print "Error initializing library:", e
+ }}}
+
+Both the {{{init()}}} and {{{start()}}} methods above may be given additional parameters. Please see [http://www.pjsip.org/python/pjsua.htm#Lib Lib] class reference manual for more information.
+
+
+=== Transport ===
+
+Application needs to create one or more [http://www.pjsip.org/python/pjsua.htm#Transport Transport] objects before it can send or receive SIP messages:
+
+ {{{
+#!python
+
+try:
+    udp = lib.create_transport(pj.TransportType.UDP)
+
+except pj.Error, e:
+    print "Error creating transport:", e
+ }}}
+
+
+=== Accounts ===
+
+Application must create at least one [http://www.pjsip.org/python/pjsua.htm#Account Account] before it can send and receive SIP messages. An account specifies the '''From:''' URI, so it's needed before you can send SIP messages.
+
+There are two types of accounts in pjsua:
+ * real account: this is an account that can register to a SIP server
+ * transport account: this corresponds to one [http://www.pjsip.org/python/pjsua.htm#Transport Transport]. So for example if we have created UDP transport which listens to {{{192.168.0.1:5080}}}, the transport account will have URI: "{{{sip:192.168.0.1:5080}}}" (rather than, say, "{{{sip:user@domain}}}").
+
+There can be more than one accounts in an application.
+
+==== Creating Accounts ====
+
+To create transport account:
+
+ {{{
+#!python
+
+try:
+    acc = lib.create_account_for_transport(udp)
+
+except pj.Error, e:
+    print "Error creating UDP local account:", e
+ }}}
+
+To create a real account account, first you must configure an [http://www.pjsip.org/python/pjsua.htm#AccountConfig AccountConfig], then create the account:
+
+ {{{
+#!python
+
+try:
+    acc_cfg = pj.AccountConfig()
+    acc_cfg.id = "sip:user@pjsip.org"
+    acc_cfg.reg_uri = "sip:pjsip.org"
+    acc_cfg.proxy = ["<sip:pjsip.org;lr>"]
+    acc_cfg.auth_cred = [pj.AuthCred("*", "user", "password")]
+
+    acc = lib.create_account(acc_cfg, True)
+
+except pj.Error, e:
+    print "Error creating account:", e
+ }}}
+
+Alternatively, for typical account config like above, we can do like this:
+
+ {{{
+#!python
+
+try:
+    acc = lib.create_account(pj.AccountConfig("pjsip.org", "username", "password"), True)
+
+except pj.Error, e:
+    print "Error creating account:", e
+ }}}
+
+
+==== Getting Events from Account ====
+
+[http://www.pjsip.org/python/pjsua.htm#Account Account] object emits events such as incoming call and registration state. 
+
+To capture events from [http://www.pjsip.org/python/pjsua.htm#Account Account], first you need to derive your account callback class from [http://www.pjsip.org/python/pjsua.htm#AccountCallback AccountCallback] class and implement the relevant callback methods:
+
+ {{{
+#!python
+
+class MyAccountCallback(pj.AccountCallback):
+    def __init__(self, account):
+        pj.AccountCallback.__init__(self, account)
+
+    def on_reg_state(self):
+        print "Account", self.account.info().uri,
+        print "registration status is", self.account.info().reg_reason
+
+    def on_incoming_call(self, call):
+        print "Incoming call from", call.info().remote_uri
+        call.answer(200)
+ }}}
+
+(Note: we've touched the [http://www.pjsip.org/python/pjsua.htm#Call Call] object a little bit above, that will be explained later).
+
+Then install the callback to [http://www.pjsip.org/python/pjsua.htm#Account Account] object:
+
+ {{{
+#!python
+
+   acc_cb = MyAccountCallback(acc)
+   acc.set_callback(acc_cb)
+ }}}
+
+
+==== Account Sample Application ====
+
+For a complete account sample application (including registration), please see source:pjproject/trunk/pjsip-apps/src/python/samples/registration.py
+
+
+=== Calls ===
+
+==== Creating Calls ====
+
+Incoming call events are reported via [http://www.pjsip.org/python/pjsua.htm#AccountCallback AccountCallback]'s {{{on_incoming_call()}}} callback as shown above.
+
+To make outgoing call:
+
+ {{{
+#!python
+
+   call = acc.make_call("sip:buddy@pjsip.org")
+ }}}
+
+Note that as with all PJSIP operations, the {{{make_call()}}} function is asynchronous; it will not block until the call is connected, but rather it will return immediately as soon as the initial INVITE request is sent. Application is then informed about the call completion via [http://www.pjsip.org/python/pjsua.htm#CallCallback CallCallback] object (see below).
+
+==== Getting Events from Call ====
+
+To retrieve events from a call, derive a class from [http://www.pjsip.org/python/pjsua.htm#CallCallback CallCallback] class and implement the methods that you want to be notified about. Normally at the very least you'd want to implement {{{on_state()}}} and {{{on_media_state()}}} methods:
+
+ {{{
+#!python
+
+class MyCallCallback(pj.CallCallback):
+    def __init__(self, call):
+        pj.CallCallback.__init__(self, call)
+
+    def on_state(self):
+        print "Call with", self.call.info().remote_uri,
+        print "is", self.call.info().state_text
+
+    def on_media_state(self):
+        if self.call.info().media_state == pj.MediaState.ACTIVE:
+            # Connect the call to sound device
+            call_slot = self.call.info().conf_slot
+            pj.Lib.instance().conf_connect(call_slot, 0)
+            pj.Lib.instance().conf_connect(0, call_slot)
+            print "Media is now active"
+        else:
+            print "Media is inactive"
+
+ }}}
+
+Then install your callback to the call object:
+
+ {{{
+#!python
+
+  call_cb = MyCallCallback(call)
+  call.set_callback(call_cb)
+ }}}
+
+
+==== Call Sample Application ====
+
+For a complete call sample application, please see source:pjproject/trunk/pjsip-apps/src/python/samples/call.py
+