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, you would do something like this:

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 "0.0.0.0" and any available port.

There is no real use of the ​Transport instance, except to create account-less account (with lib.create_account_for_transport(), as will be explained in later chapter), and perhaps to display list of transport infos 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:

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 like this:

lib.destroy()
lib = None