Startup and Shutdown

The Lib Class

The ​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:

import pjsua

lib = Lib()

Once the library is instantiated, you can retrieve the Lib instance using ​Lib.instance() static method.

Initialize the Library

Initialize the library by calling its ​init() method:

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 ​init() method takes three optional arguments to specify various core settings:

• ​UAConfig, to specify core SIP user agent settings
• ​MediaConfig, to specify various media settings, including ICE and TURN.
• ​LogConfig, to customize logging settings.

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

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 ​Transport objects before it can send or receive SIP messages:

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 ​Transport instance and it takes an optional ​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 ​Transport instance, except to create userless account (with ​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 ​lib.start() method:

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 ​lib.destroy():

lib.destroy()
lib = None