= Startup and Shutdown =

[[TracNav(Python_SIP/TOC)]]

== The Lib Class ==

The [http://www.pjsip.org/python/pjsua.htm#Lib Lib class] is a singleton class, and application MUST create one and at most one of this class instance before it can do anything else. This class is the core class of pjsua module, and it provides the following functions:
 * pjsua initialization and shutting down
 * customization of core pjsua settings, such as core SIP settings, media settings, and logging settings
 * media manipulations

This chapter will describe some of the functions above. The media API will be explained in later chapters.

== Initialization ==

=== Instantiate the Library ===

Before anything else, you must instantiate the Lib class:

 {{{
#!python
import pjsua

lib = Lib()
 }}}

Once the library is instantiated, you can retrieve the Lib instance using [http://www.pjsip.org/python/pjsua.htm#Lib-instance Lib.instance()] static method.


=== Initialize the Library ===

Initialize the library by calling its [http://www.pjsip.org/python/pjsua.htm#Lib-init init()] method:

 {{{
#!python
try:
    lib.init()
except pjsua.Error, err:
    print 'Initialization error:', err
 }}}

The snippet above initializes the library with the default settings. The {{{init()}}} method will raise exception if error occurs, so we need to trap the exception using try/except clause as above.

The [http://www.pjsip.org/python/pjsua.htm#Lib-init init()] method takes three optional arguments to specify various core settings:
 - [http://www.pjsip.org/python/pjsua.htm#UAConfig UAConfig], to specify core SIP user agent settings
 - [http://www.pjsip.org/python/pjsua.htm#MediaConfig MediaConfig], to specify various media settings, including ICE and TURN.
 - [http://www.pjsip.org/python/pjsua.htm#LogConfig LogConfig], to customize logging settings.

To customize the settings, create instance of the above configuration class(es) and specify them to {{{init()}}}, for example:

 {{{
#!python
try:
    my_ua_cfg = pjsua.UAConfig()
    my_ua_cfg.stun_host = "stun.pjsip.org"
    my_media_cfg = pjsua.MediaConfig()
    my_media_cfg.enable_ice = True

    lib.init(ua_cfg=my_ua_cfg, media_cfg=my_media_cfg)

except pjsua.Error, err:
    print 'Initialization error:', err
 }}}


=== Create One or More Transports ===

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
 }}}

The {{{create_transport()}}} method returns the newly created [http://www.pjsip.org/python/pjsua.htm#Transport Transport] instance and it takes an optional [http://www.pjsip.org/python/pjsua.htm#TransportConfig TransportConfig] object to customize the transport settings like bound address and listening port number. Without this, by default the transport will be bound to INADDR_ANY and any available port.

There is no real use of the [http://www.pjsip.org/python/pjsua.htm#Transport Transport] instance, except to create ''userless'' account (with [http://www.pjsip.org/python/pjsua.htm#Lib-create_account_for_transport lib.create_account_for_transport()], as will be explained in later chapter), and perhaps to display the list of transports to user if the application wants it.


=== Starting the Library ===

Now we're ready to start the library. We need to start the library to finalize the initialization phase, e.g. to complete the initial STUN address resolution, initialize/start the sound device, etc. To start the library, call [http://www.pjsip.org/python/pjsua.htm#Lib-start lib.start()] method:

 {{{
#!python
try:
    lib.start()
except pj.Error, e:
    print "Error starting pjsua:", e
 }}}


== Shutting Down the Library ==

Once the application exits, the library needs to be shutdown so that resources can be released back to the operating system. This is done by calling [http://www.pjsip.org/python/pjsua.htm#Lib-destroy lib.destroy()]:

 {{{
#!python
lib.destroy()
lib = None
 }}}