Changes between Initial Version and Version 1 of Python_SIP/Calls

Jul 23, 2008 8:33:02 PM (14 years ago)



  • Python_SIP/Calls

    v1 v1  
     1= Calls = 
     5Calls are represented by [ Call] class. 
     7== Making Outgoing Calls == 
     9Making outgoing call is simple, just invoke [ make_call()] method of the [ Account] object. Assuming you have the account object as ''acc'' variable and destination URI string in ''dst_uri'': 
     11 {{{ 
     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 }}} 
     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 [ call] instance, and events to the call will be reported to the callback. 
     23More on the callback will be explained a bit later. 
     26== Receiving Incoming Calls == 
     28Incoming calls are reported as [ on_incoming_call()] of the [ AccountCallback] class. You must derive a class from the !AccountCallback to handle incoming calls: 
     30 {{{ 
     32class MyAccountCallback(pjsua.AccountCallback): 
     33    def __init__(self, account=None): 
     34        pjsua.AccountCallback.__init__(self, account) 
     36    def on_incoming_call(self, call): 
     37        my_cb = MyCallCallback() 
     38        call.set_callback(my_cb) 
     39 }}} 
     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. 
     44== Call Operations == 
     46Please see [ Call class] documentation. 
     48== Handling Call Events == 
     50All call properties such as state, media state, remote peer information, etc. are stored as [ CallInfo] class, which can be retrieved from the call object with using [ info()] method of the call. 
     52== Handling Call Events == 
     54Events to the call will be reported to [ 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. 
     56=== Call Disconnection === 
     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. 
     60The call disconnection is reported in [ on_state()] method of [ CallCallback] and it can be detected as follows: 
     62 {{{ 
     65class MyCallCallback(pjsua.CallCallback): 
     66    ... 
     67    def on_state(self): 
     68        if == pjsua.CallState.DISCONNECTED: 
     69            print 'This call has been disconnected' 
     70 }}} 
     73== Working with Call's Media == 
     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 [ on_media_state()] callback, and the media state itself is stored as the ''media_state'' member of [ CallInfo] class. 
     77The ''media state'' value can be one of the [ MediaState] constant. 
     79Below is a sample code to connect the call to the sound device when the call's media state is active: 
     81 {{{ 
     84class MyCallCallback(pjsua.CallCallback): 
     85    ... 
     86    # Notification when call's media state has changed. 
     87    def on_media_state(self): 
     88        if == pj.MediaState.ACTIVE: 
     89            # Connect the call to sound device 
     90            call_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 }}} 
     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.