Changes between Version 4 and Version 5 of Python_SIP/Basic_Concept


Ignore:
Timestamp:
Jul 24, 2008 2:33:41 PM (16 years ago)
Author:
bennylp
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • Python_SIP/Basic_Concept

    v4 v5  
    99==== Asynchronous Operations ==== 
    1010 
    11 If you have developed applications with PJSIP you'll know about this already, but this concept probably needs to be explained a little bit here to new PJSIP users. 
     11If you have developed applications with PJSIP, you'll know about this already. In PJSIP, all operations that involve sending and receiving SIP messages are asynchronous, meaning that the function that invokes the operation will complete immediately, and you will be given the completion status as callbacks.  
    1212 
    13 In PJSIP, all operations that involve sending and receiving SIP messages are asynchronous, meaning that the function that invokes the operation will complete immediately, and you will be given the completion status as callbacks. Take a look for example the {{{make_call()}}} method of the [http://www.pjsip.org/python/pjsua.htm#Account Account] class. This function is used to initiate outgoing call to a destination. When this function returns successfully, it does not mean that the call has been established, but rather that the call has been '''initiated''' successfully. You will be given the report of the call completion (such as ''Ringing'' or ''Connected''/''Confirmed''' events) in the {{{on_state()}}} callback of [http://www.pjsip.org/python/pjsua.htm#CallCallback CallCallback] class. 
     13Take a look for example the [http://www.pjsip.org/python/pjsua.htm#Account-make_call make_call()] method of the [http://www.pjsip.org/python/pjsua.htm#Account Account] class. This function is used to initiate outgoing call to a destination. When this function returns successfully, it does not mean that the call has been established, but rather it means that the call has been '''initiated''' successfully. You will be given the report of the call progress and/or completion in the [http://www.pjsip.org/python/pjsua.htm#CallCallback-on_state on_state()] method of [http://www.pjsip.org/python/pjsua.htm#CallCallback CallCallback] class. 
    1414 
    1515 
    16 ==== Where to Start ==== 
     16==== The Main Classes ==== 
    1717 
    18 The [http://www.pjsip.org/python/pjsua.htm PJSUA Python Module Reference Manual] shows quite few classes there, and it doesn't show clearly where to start. But actually the concept is quite simple, with the main classes described below.  
     18The [http://www.pjsip.org/python/pjsua.htm PJSUA Python Module Reference Manual] shows quite many classes there, and it is probably not very easy to spot which are the important classes. But actually the concept is quite simple. Here are the main classes of the library.  
    1919 
    2020 '''[http://www.pjsip.org/python/pjsua.htm#Lib Lib] class:''' :: 
    … …  
    3636==== Basic Usage Pattern ==== 
    3737 
    38 With the methods of the main classes above, you will be able to invoke various operations quite easily. But how can we get events/notifications from these classes? 
     38With the methods of the main classes above, you will be able to invoke various operations to the object quite easily. But how can we get events/notifications from these classes? 
    3939 
    4040It's with the callback classes. 
    4141 
    42 Callback classes also provide the mean to ''connect'' pjsua objects with your application's objects. The idea is like this. All the pjsua main classes above (''Lib'', ''Account'', ''Call'', and ''Buddy'') are final classes, meaning they are not intended to be subclasses or derived. Each of these classes (except ''Lib'') have their corresponding callback class ([http://www.pjsip.org/python/pjsua.htm#AccountCallback AccountCallback], [http://www.pjsip.org/python/pjsua.htm#CallCallback CallCallback], and [http://www.pjsip.org/python/pjsua.htm#BuddyCallback BuddyCallback]), and events emitted by these classes will be sent to the callback class. These callback classes are subclass-able, and in fact you must derive a class from these callback class in order to customize the processing of the events. 
     42Each of the main classes above (except Lib) will report their events to the callback instance that is installed to them. So to get and handle these events, just derive a class from the corresponding callback class ([http://www.pjsip.org/python/pjsua.htm#AccountCallback AccountCallback], [http://www.pjsip.org/python/pjsua.htm#CallCallback CallCallback], or [http://www.pjsip.org/python/pjsua.htm#BuddyCallback BuddyCallback]), implement the relevant method (depending on which event you want to handle), and install the callback instance to the object. 
    4343 
    44 It's probably much easier to explain with an example. 
    45  
    46 First derive a class from the appropriate callback class, say [http://www.pjsip.org/python/pjsua.htm#CallCallback CallCallback] class: 
    47  
    48   {{{ 
    49 #!python 
    50  
    51 class MyCallCallback(pjsua.CallCallback): 
    52     # You can put glue attributes here. 
    53     # e.g. we'll put an imaginary text control here 
    54     text_ctrl = None 
    55  
    56     def __init__(self, call=None): 
    57         pjsua.CallCallback.__init__(self, call) 
    58  
    59     def on_state(self): 
    60         text_ctrl.set_text("Call state is " + self.call.info().state_text) 
    61   }}} 
    62  
    63 As you can see above, the primary objective of deriving a class from the callback class is to customize the processing of an event. And in your callback class, you can put your own object attributes there to connect the call object with your application objects. 
    64  
    65 Then you ''install'' your callback to the Call object like this: 
    66  
    67   {{{ 
    68 #!python 
    69  
    70 def make_call(dst_uri): 
    71     my_cb = MyCallCallback(none) 
    72     try: 
    73         call = acc.make_call(dst_uri, cb=my_cb) 
    74     except pjsua.Error, err: 
    75         print 'Error making call', err 
    76         return None 
    77     return call 
    78   }}} 
    79  
    80 or using {{{set_callback()}}} method like this: 
    81  
    82   {{{ 
    83 #!python 
    84  
    85 def make_call(dst_uri): 
    86     my_cb = MyCallCallback(none) 
    87     try: 
    88         call = acc.make_call(dst_uri) 
    89         call.set_callback(my_cb) 
    90     except pjsua.Error, err: 
    91         print 'Error making call', err 
    92         return None 
    93     return call 
    94   }}} 
    95  
    96 This later method is not preferred since it is possible to loose events with this method, e.g. due to the use of multi-threading, events may be emitted by the call object while the callback is not installed. It is possible to avoid loosing events this way by using library lock though, as will be explained later. 
    97  
    98 I hope the snippet above will give you a bit of info on the basic pattern used by the library. More will be explained in later sections. 
    99  
     44More will be explained in later chapters. 
    10045 
    10146==== Error Handling ====