Changes between Initial Version and Version 1 of Python_SIP/Calls


Ignore:
Timestamp:
Jul 23, 2008 8:33:02 PM (11 years ago)
Author:
bennylp
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Python_SIP/Calls

    v1 v1  
     1= Calls = 
     2 
     3[[TracNav(Python_SIP/TOC)]] 
     4 
     5Calls are represented by [http://www.pjsip.org/python/pjsua.htm#Call Call] class. 
     6 
     7== Making Outgoing Calls == 
     8 
     9Making outgoing call is simple, just invoke [http://www.pjsip.org/python/pjsua.htm#Account-make_call make_call()] method of the [http://www.pjsip.org/python/pjsua.htm#Account Account] object. Assuming you have the account object as ''acc'' variable and destination URI string in ''dst_uri'': 
     10 
     11 {{{ 
     12#!python 
     13 
     14try: 
     15    my_cb = MyCallCallback() 
     16    call = acc.make_call(dst_uri, cb=my_cb) 
     17except pjsua.Error, err: 
     18    print 'Error making outgoing call:', err 
     19 }}} 
     20 
     21The snippet above initiates outgoing call to ''dst_uri'', install the callback to the call, and saves the call instance in ''call'' object. Subsequent operations to the call can use the method in the [http://www.pjsip.org/python/pjsua.htm#Call call] instance, and events to the call will be reported to the callback. 
     22 
     23More on the callback will be explained a bit later. 
     24 
     25 
     26== Receiving Incoming Calls == 
     27 
     28Incoming calls are reported as [http://www.pjsip.org/python/pjsua.htm#AccountCallback-on_incoming_call on_incoming_call()] of the [http://www.pjsip.org/python/pjsua.htm#AccountCallback AccountCallback] class. You must derive a class from the !AccountCallback to handle incoming calls: 
     29 
     30 {{{ 
     31#!python 
     32class MyAccountCallback(pjsua.AccountCallback): 
     33    def __init__(self, account=None): 
     34        pjsua.AccountCallback.__init__(self, account) 
     35 
     36    def on_incoming_call(self, call): 
     37        my_cb = MyCallCallback() 
     38        call.set_callback(my_cb) 
     39 }}} 
     40 
     41For incoming calls, the call instance is given in the callback parameter as shown above. We just need to install our callback to receive call events to the call. 
     42 
     43 
     44== Call Operations == 
     45 
     46Please see [http://www.pjsip.org/python/pjsua.htm#Call Call class] documentation. 
     47 
     48== Handling Call Events == 
     49 
     50All call properties such as state, media state, remote peer information, etc. are stored as [http://www.pjsip.org/python/pjsua.htm#CallInfo CallInfo] class, which can be retrieved from the call object with using [http://www.pjsip.org/python/pjsua.htm#Call-info info()] method of the call. 
     51 
     52== Handling Call Events == 
     53 
     54Events to the call will be reported to [http://www.pjsip.org/python/pjsua.htm#CallCallback CallCallback] instance that is installed to the call object. To handle these events, you must derive a class from !CallCallback class and install the instance to the call object. 
     55 
     56=== Call Disconnection === 
     57 
     58Call disconnection event is a special event since once the callback that reports this event returns, the call is no longer valid and any operations invoked to the call object will raise error exception. 
     59 
     60The call disconnection is reported in [http://www.pjsip.org/python/pjsua.htm#CallCallback-on_state on_state()] method of [http://www.pjsip.org/python/pjsua.htm#CallCallback CallCallback] and it can be detected as follows: 
     61 
     62 {{{ 
     63#!python 
     64 
     65class MyCallCallback(pjsua.CallCallback): 
     66    ... 
     67    def on_state(self): 
     68        if self.call.info().state == pjsua.CallState.DISCONNECTED: 
     69            print 'This call has been disconnected' 
     70 }}} 
     71 
     72 
     73== Working with Call's Media == 
     74 
     75You can only operate with the call's media (e.g. connecting the call to the sound device in the conference bridge) when the call's media is ready (or active). The changes to the call's media state is reported in [http://www.pjsip.org/python/pjsua.htm#CallCallback-on_media_state on_media_state()] callback, and the media state itself is stored as the ''media_state'' member of [http://www.pjsip.org/python/pjsua.htm#CallInfo CallInfo] class. 
     76 
     77The ''media state'' value can be one of the [http://www.pjsip.org/python/pjsua.htm#MediaState MediaState] constant. 
     78 
     79Below is a sample code to connect the call to the sound device when the call's media state is active: 
     80 
     81 {{{ 
     82#!python 
     83 
     84class MyCallCallback(pjsua.CallCallback): 
     85    ... 
     86    # Notification when call's media state has changed. 
     87    def on_media_state(self): 
     88        if self.call.info().media_state == pj.MediaState.ACTIVE: 
     89            # Connect the call to sound device 
     90            call_slot = self.call.info().conf_slot 
     91            pj.Lib.instance().conf_connect(call_slot, 0) 
     92            pj.Lib.instance().conf_connect(0, call_slot) 
     93            print "Media is now active" 
     94        else: 
     95            print "Media is inactive" 
     96 }}} 
     97 
     98When the ''media_state'' has moved from active to non-active (for example when call is put on hold), there is no need to disconnect the call's connection in the bridge since the call's media will be removed automatically when it's no longer valid, and this will automatically remote all connections in the conference bridge to/from the call. 
     99 
     100