pjsua

Multimedia communication client library based on SIP protocol.
 
This implements a fully featured multimedia communication client 
library based on PJSIP stack (http://www.pjsip.org)
 
 
1. FEATURES
 
  - Session Initiation Protocol (SIP) features:
     - Basic registration and call
     - Multiple accounts
     - Call hold, attended and unattended call transfer
     - Presence
     - Instant messaging
     - Multiple SIP accounts
  - Media features:
     - Audio
     - Conferencing
     - Narrowband and wideband
     - Codecs: PCMA, PCMU, GSM, iLBC, Speex, G.722, L16
     - RTP/RTCP
     - Secure RTP (SRTP)
     - WAV playback, recording, and playlist
  - NAT traversal features
     - Symmetric RTP
     - STUN
     - TURN
     - ICE
 
 
2. USING
 
See http://www.pjsip.org/trac/wiki/Python_SIP_Tutorial for a more thorough
tutorial. 

 
Classes
       
Account
AccountCallback
AccountConfig
AccountInfo
AuthCred
Buddy
BuddyCallback
BuddyInfo
Call
CallCallback
CallInfo
CallRole
CallState
CodecInfo
CodecParameter
Error
Lib
LogConfig
MediaConfig
MediaDir
MediaState
PresenceActivity
SIPUri
SoundDeviceInfo
SubscriptionState
TURNConnType
Transport
TransportConfig
TransportFlag
TransportInfo
TransportType
UAConfig

 
class Account
    This describes SIP account class.
 
PJSUA accounts provide identity (or identities) of the user who is 
currently using the application. In SIP terms, the identity is used 
as the From header in outgoing requests.
 
Account may or may not have client registration associated with it. 
An account is also associated with route set and some authentication 
credentials, which are used when sending SIP request messages using 
the account. An account also has presence's online status, which 
will be reported to remote peer when they subscribe to the account's 
presence, or which is published to a presence server if presence 
publication is enabled for the account.
 
Account is created with Lib.create_account(). At least one account 
MUST be created. If no user association is required, application can 
create a userless account by calling Lib.create_account_for_transport().
A userless account identifies local endpoint instead of a particular 
user, and it correspond with a particular transport instance.
 
Also one account must be set as the default account, which is used as 
the account to use when PJSUA fails to match a request with any other
accounts.
 
  Methods defined here:
__del__(self)
__init__(self, lib, id, cb=None)
Construct this class. This is normally called by Lib class and
not by application.
 
Keyword arguments:
lib -- the Lib instance.
id  -- the pjsua account ID.
cb  -- AccountCallback instance to receive events from this Account.
       If callback is not specified here, it must be set later
       using set_callback().
__str__(self)
add_buddy(self, uri, cb=None)
Add new buddy.
 
Keyword argument:
uri     -- SIP URI of the buddy
cb      -- BuddyCallback instance to be installed to the newly
           created Buddy object. If this callback is not specified
           (i.e. None is given), it must be installed later using
           buddy.set_callback().
 
Return:
    Buddy object
delete(self)
Delete this account.
info(self)
Retrieve AccountInfo for this account.
is_default(self)
Check if this account is the default account.
is_valid(self)
Check if this account is still valid.
make_call(self, dst_uri, cb=None, hdr_list=None)
Make outgoing call to the specified URI.
 
Keyword arguments:
dst_uri  -- Destination SIP URI.
cb       -- CallCallback instance to be installed to the newly
            created Call object. If this CallCallback is not
            specified (i.e. None is given), it must be installed
            later using call.set_callback().
hdr_list -- Optional list of headers to be sent with outgoing
            INVITE
 
Return:
    Call instance.
pres_notify(self, pres_obj, state, reason='', hdr_list=None)
Send NOTIFY to inform account presence status or to terminate
server side presence subscription.
 
Keyword arguments:
pres_obj    -- The subscription object from on_incoming_subscribe()
               callback
state       -- Subscription state, from SubscriptionState
reason      -- Optional reason phrase.
hdr_list    -- Optional header list.
set_basic_status(self, is_online)
Set basic presence status of this account.
 
Keyword argument:
is_online   -- boolean to indicate basic presence availability.
set_callback(self, cb)
Register callback to receive notifications from this object.
 
Keyword argument:
cb  -- AccountCallback instance.
set_default(self)
Set this account as default account to send outgoing requests
and as the account to receive incoming requests when more exact
matching criteria fails.
set_presence_status(self, is_online, activity=0, pres_text='', rpid_id='')
Set presence status of this account. 
 
Keyword arguments:
is_online   -- boolean to indicate basic presence availability
activity    -- value from PresenceActivity
pres_text   -- optional string to convey additional information about
               the activity (such as "On the phone")
rpid_id     -- optional string to be placed as RPID ID.
set_registration(self, renew)
Manually renew registration or unregister from the server.
 
Keyword argument:
renew   -- boolean to indicate whether registration is renewed.
           Setting this value for False will trigger unregistration.
set_transport(self, transport)
Set this account to only use the specified transport to send
outgoing requests.
 
Keyword argument:
transport   -- Transport object.

 
class AccountCallback
    Class to receive notifications on account's events.
 
Derive a class from this class and register it to the Account object
using Account.set_callback() to start receiving events from the Account
object.
 
Member documentation:
 
account     -- the Account object.
 
  Methods defined here:
__del__(self)
__init__(self, account=None)
on_incoming_call(self, call)
Notification about incoming call.
 
Unless this callback is implemented, the default behavior is to
reject the call with default status code.
 
Keyword arguments:
call    -- the new incoming call
on_incoming_subscribe(self, buddy, from_uri, contact_uri, pres_obj)
Notification when incoming SUBSCRIBE request is received. 
 
Application may use this callback to authorize the incoming 
subscribe request (e.g. ask user permission if the request 
should be granted)
 
Keyword arguments:
buddy       -- The buddy object, if buddy is found. Otherwise
               the value is None.
from_uri    -- The URI string of the sender.
pres_obj    -- Opaque presence subscription object, which is
               needed by Account.pres_notify()
 
Return:
    Tuple (code, reason), where:
     code:      The status code. If code is >= 300, the
                request is rejected. If code is 200, the
                request is accepted and NOTIFY will be sent
                automatically. If code is 202, application
                must accept or reject the request later with
                Account.press_notify().
     reason:    Optional reason phrase, or None to use the
                default reasoh phrase for the status code.
on_pager(self, from_uri, contact, mime_type, body)
Notification that incoming instant message is received on
this account.
 
Keyword arguments:
from_uri   -- sender's URI
contact    -- sender's Contact URI
mime_type  -- MIME type of the instant message body
body       -- the instant message body
on_pager_status(self, to_uri, body, im_id, code, reason)
Notification about the delivery status of previously sent
instant message.
 
Keyword arguments:
to_uri  -- the destination URI of the message
body    -- the message body
im_id   -- message ID
code    -- SIP status code
reason  -- SIP reason phrase
on_reg_state(self)
Notification that the registration status has changed.
on_typing(self, from_uri, contact, is_typing)
Notification that remote is typing or stop typing.
 
Keyword arguments:
buddy     -- Buddy object for the sender, if found. Otherwise
             this will be None
from_uri  -- sender's URI of the indication
contact   -- sender's contact URI
is_typing -- boolean to indicate whether remote is currently
             typing an instant message.

Data and other attributes defined here:
account = None

 
class AccountConfig
    This describes account configuration to create an account.
 
Member documentation:
 
priority                -- account priority for matching incoming
                           messages.
id                      -- SIP URI of this account. This setting is
                           mandatory.
force_contact           -- force to use this URI as Contact URI. Setting
                           this value is generally not recommended.
reg_uri                 -- specify the registrar URI. Mandatory if
                           registration is required.
reg_timeout             -- specify the SIP registration refresh interval
                           in seconds.
require_100rel          -- specify if reliable provisional response is
                           to be enforced (with Require header).
publish_enabled         -- specify if PUBLISH should be used. When
                           enabled, the PUBLISH will be sent to the
                           registrar.
pidf_tuple_id           -- optionally specify the tuple ID in outgoing
                           PIDF document.
proxy                   -- list of proxy URI.
auth_cred               -- list of AuthCred containing credentials to
                           authenticate against the registrars and
                           the proxies.
auth_initial_send       -- specify if empty Authorization header should be
                           sent. May be needed for IMS.
auth_initial_algorithm  -- when auth_initial_send is enabled, optionally
                           specify the authentication algorithm to use.
                           Valid values are "md5", "akav1-md5", or
                           "akav2-md5". 
transport_id            -- optionally specify the transport ID to be used
                           by this account. Shouldn't be needed unless
                           for specific requirements (e.g. in multi-homed
                           scenario).
allow_contact_rewrite   -- specify whether the account should learn its
                           Contact address from REGISTER response and 
                           update the registration accordingly. Default is
                           True.
ka_interval             -- specify the interval to send NAT keep-alive 
                           packet.
ka_data                 -- specify the NAT keep-alive packet contents.
use_srtp                -- specify the SRTP usage policy. Valid values
                           are: 0=disable, 1=optional, 2=mandatory.
                           Default is 0.
srtp_secure_signaling   -- specify the signaling security level required
                           by SRTP. Valid values are: 0=no secure 
                           transport is required, 1=hop-by-hop secure
                           transport such as TLS is required, 2=end-to-
                           end secure transport is required (i.e. "sips").
 
  Methods defined here:
__init__(self, domain='', username='', password='', display='', registrar='', proxy='')
Construct account config. If domain argument is specified, 
a typical configuration will be built.
 
Keyword arguments:
domain    -- domain name of the server.
username  -- user name.
password  -- plain-text password.
display   -- optional display name for the user name.
registrar -- the registrar URI. If domain name is specified
             and this argument is empty, the registrar URI
             will be constructed from the domain name.
proxy     -- the proxy URI. If domain name is specified
             and this argument is empty, the proxy URI
             will be constructed from the domain name.
build_config(self, domain, username, password, display='', registrar='', proxy='')
Construct account config. If domain argument is specified, 
a typical configuration will be built.
 
Keyword arguments:
domain    -- domain name of the server.
username  -- user name.
password  -- plain-text password.
display   -- optional display name for the user name.
registrar -- the registrar URI. If domain name is specified
             and this argument is empty, the registrar URI
             will be constructed from the domain name.
proxy     -- the proxy URI. If domain name is specified
             and this argument is empty, the proxy URI
             will be constructed from the domain name.

Data and other attributes defined here:
allow_contact_rewrite = True
auth_cred = []
auth_initial_algorithm = ''
auth_initial_send = False
force_contact = ''
id = ''
ka_data = '\r\n'
ka_interval = 15
pidf_tuple_id = ''
priority = 0
proxy = []
publish_enabled = False
reg_timeout = 0
reg_uri = ''
require_100rel = False
srtp_secure_signaling = 1
transport_id = -1
use_srtp = 0

 
class AccountInfo
    This describes Account info. Application retrives account info
with Account.info().
 
Member documentation:
 
is_default      -- True if this is the default account.
uri             -- the account URI.
reg_active      -- True if registration is active for this account.
reg_expires     -- contains the current registration expiration value,
                   in seconds.
reg_status      -- the registration status. If the value is less than
                   700, it specifies SIP status code. Value greater than
                   this specifies the error code.
reg_reason      -- contains the registration status text (e.g. the
                   error message).
online_status   -- the account's presence online status, True if it's 
                   publishing itself as online.
online_text     -- the account's presence status text.
 
  Methods defined here:
__init__(self, ai)

Data and other attributes defined here:
is_default = False
online_status = False
online_text = ''
reg_active = False
reg_expires = -1
reg_reason = ''
reg_status = 0
uri = ''

 
class AuthCred
    Authentication credential for SIP or TURN account.
 
Member documentation:
 
scheme      -- authentication scheme (default is "Digest")
realm       -- realm
username    -- username
passwd_type -- password encoding (zero for plain-text)
passwd      -- the password
 
  Methods defined here:
__init__(self, realm, username, passwd, scheme='Digest', passwd_type=0)

Data and other attributes defined here:
passwd = ''
passwd_type = 0
realm = '*'
scheme = 'Digest'
username = ''

 
class Buddy
    Buddy represents person or remote agent.
 
This class provides functions to subscribe to buddy's presence and
to send or receive instant messages from the buddy.
 
  Methods defined here:
__del__(self)
__init__(self, lib, id, account, cb)
__str__(self)
delete(self)
Remove this buddy from the buddy list.
info(self)
Get buddy info as BuddyInfo.
send_pager(self, text, im_id=0, content_type='text/plain', hdr_list=None)
Send instant message to remote buddy.
 
Keyword arguments:
text         -- Instant message to be sent
im_id        -- Optional instant message ID to identify this
                instant message when delivery status callback
                is called.
content_type -- MIME type identifying the instant message
hdr_list     -- Optional list of headers to be sent with the
                request.
send_typing_ind(self, is_typing=True, hdr_list=None)
Send typing indication to remote buddy.
 
Keyword argument:
is_typing -- boolean to indicate wheter user is typing.
hdr_list  -- Optional list of headers to be sent with the
             request.
set_callback(self, cb)
Install callback to receive notifications from this object.
 
Keyword argument:
cb  -- BuddyCallback instance.
subscribe(self)
Subscribe to buddy's presence status notification.
unsubscribe(self)
Unsubscribe from buddy's presence status notification.

 
class BuddyCallback
    This class can be used to receive notifications about Buddy's
presence status change. Application needs to derive a class from
this class, and register the instance with Buddy.set_callback().
 
Member documentation:
 
buddy   -- the Buddy object.
 
  Methods defined here:
__init__(self, buddy=None)
on_pager(self, mime_type, body)
Notification that incoming instant message is received from
this buddy.
 
Keyword arguments:
mime_type  -- MIME type of the instant message body
body       -- the instant message body
on_pager_status(self, body, im_id, code, reason)
Notification about the delivery status of previously sent
instant message.
 
Keyword arguments:
body    -- the message body
im_id   -- message ID
code    -- SIP status code
reason  -- SIP reason phrase
on_state(self)
Notification that buddy's presence state has changed. Application
may then retrieve the new status with Buddy.info() function.
on_typing(self, is_typing)
Notification that remote is typing or stop typing.
 
Keyword arguments:
is_typing -- boolean to indicate whether remote is currently
             typing an instant message.

Data and other attributes defined here:
buddy = None

 
class BuddyInfo
    This class contains information about Buddy. Application may 
retrieve this information by calling Buddy.info().
 
Member documentation:
 
uri             -- the Buddy URI.
contact         -- the Buddy Contact URI, if available.
online_status   -- the presence online status.
online_text     -- the presence online status text.
activity        -- the PresenceActivity
subscribed      -- specify whether buddy's presence status is currently
                   being subscribed.
sub_state       -- SubscriptionState
sub_term_reason -- The termination reason string of the last presence
                   subscription to this buddy, if any.
 
  Methods defined here:
__init__(self, pjsua_bi=None)

Data and other attributes defined here:
activity = 0
contact = ''
online_status = 0
online_text = ''
sub_state = 0
sub_term_reason = ''
subscribed = False
uri = ''

 
class Call
    This class represents SIP call.
 
Application initiates outgoing call with Account.make_call(), and
incoming calls are reported in AccountCallback.on_incoming_call().
 
  Methods defined here:
__del__(self)
__init__(self, lib, call_id, cb=None)
__str__(self)
answer(self, code=200, reason='', hdr_list=None)
Send provisional or final response to incoming call.
 
Keyword arguments:
code     -- SIP status code.
reason   -- Reason phrase. Put empty to send default reason
            phrase for the status code.
hdr_list -- Optional list of headers to be sent with the
            INVITE response.
attach_to_id(self, call_id)
dial_dtmf(self, digits)
Send DTMF digits with RTP event package.
 
Keyword arguments:
digits  -- DTMF digit string.
dump_status(self, with_media=True, indent='', max_len=1024)
Dump the call status.
hangup(self, code=603, reason='', hdr_list=None)
Terminate the call.
 
Keyword arguments:
code     -- SIP status code.
reason   -- Reason phrase. Put empty to send default reason
            phrase for the status code.
hdr_list -- Optional list of headers to be sent with the
            message.
hold(self, hdr_list=None)
Put the call on hold.
 
Keyword arguments:
hdr_list -- Optional list of headers to be sent with the
            message.
info(self)
Get the CallInfo.
is_valid(self)
Check if this call is still valid.
reinvite(self, hdr_list=None)
Send re-INVITE and optionally offer new codecs to use.
 
Keyword arguments:
hdr_list   -- Optional list of headers to be sent with the
              message.
send_request(self, method, hdr_list=None, content_type=None, body=None)
Send arbitrary request to remote call. 
 
This is useful for example to send INFO request. Note that this 
function should not be used to send request that will change the 
call state such as CANCEL or BYE.
 
Keyword arguments:
method       -- SIP method name.
hdr_list     -- Optional header list to be sent with the request.
content_type -- Content type to describe the body, if the body
                is present
body         -- Optional SIP message body.
set_callback(self, cb)
Set callback object to retrieve event notifications from this call.
 
Keyword arguments:
cb  -- CallCallback instance.
transfer(self, dest_uri, hdr_list=None)
Transfer the call to new destination.
 
Keyword arguments:
dest_uri -- Specify the SIP URI to transfer the call to.
hdr_list -- Optional list of headers to be sent with the
            message.
transfer_to_call(self, call, hdr_list=None, options=0)
Attended call transfer.
 
Keyword arguments:
call     -- The Call object to transfer call to.
hdr_list -- Optional list of headers to be sent with the
            message.
options  -- Must be zero for now.
unhold(self, hdr_list=None)
Release the call from hold.
 
Keyword arguments:
hdr_list -- Optional list of headers to be sent with the
            message.
update(self, hdr_list=None, options=0)
Send UPDATE and optionally offer new codecs to use.
 
Keyword arguments:
hdr_list   -- Optional list of headers to be sent with the
              message.
options    -- Must be zero for now.

 
class CallCallback
    Class to receive event notification from Call objects. 
 
Use Call.set_callback() method to install instance of this callback 
class to receive event notifications from the call object.
 
Member documentation:
 
call    -- the Call object.
 
  Methods defined here:
__del__(self)
__init__(self, call=None)
on_dtmf_digit(self, digits)
Notification on incoming DTMF digits.
 
Keyword argument:
digits  -- string containing the received digits.
on_media_state(self)
Notification that the call's media state has changed.
on_pager(self, mime_type, body)
Notification that incoming instant message is received on
this call.
 
Keyword arguments:
mime_type  -- MIME type of the instant message body.
body       -- the instant message body.
on_pager_status(self, body, im_id, code, reason)
Notification about the delivery status of previously sent
instant message.
 
Keyword arguments:
body    -- message body
im_id   -- message ID
code    -- SIP status code
reason  -- SIP reason phrase
on_replace_request(self, code, reason)
Notification when incoming INVITE with Replaces header is received. 
 
Application may reject the request by returning value greather than
or equal to 500. The default behavior is to accept the request.
 
Keyword arguments:
code    -- default status code to return
reason  -- default reason phrase to return
 
Return:
The callback should return (code, reason) tuple.
on_replaced(self, new_call)
Notification that this call will be replaced with new_call. 
After this callback is called, this call will be disconnected.
 
Keyword arguments:
new_call    -- the new call that will replace this call.
on_state(self)
Notification that the call's state has changed.
on_transfer_request(self, dst, code)
Notification that call is being transfered by remote party. 
 
Application can decide to accept/reject transfer request by returning
code greater than or equal to 500. The default behavior is to accept 
the transfer by returning 202.
 
Keyword arguments:
dst     -- string containing the destination URI
code    -- the suggested status code to return to accept the request.
 
Return:
the callback should return 202 to accept the request, or 300-699 to
reject the request.
on_transfer_status(self, code, reason, final, cont)
Notification about the status of previous call transfer request. 
 
Keyword arguments:
code    -- SIP status code to indicate completion status.
text    -- SIP status reason phrase.
final   -- if True then this is a final status and no further
           notifications will be sent for this call transfer
           status.
cont    -- suggested return value.
 
Return:
If the callback returns false then no further notification will
be sent for the transfer request for this call.
on_typing(self, is_typing)
Notification that remote is typing or stop typing.
 
Keyword arguments:
is_typing -- boolean to indicate whether remote is currently
             typing an instant message.

Data and other attributes defined here:
call = None

 
class CallInfo
    This structure contains various information about Call.
 
Application may retrieve this information with Call.info().
 
Member documentation:
 
role            -- CallRole
account         -- Account object.
uri             -- SIP URI of local account.
contact         -- local Contact URI.
remote_uri      -- remote SIP URI.
remote_contact  -- remote Contact URI
sip_call_id     -- call's Call-ID identification
state           -- CallState
state_text      -- state text.
last_code       -- last SIP status code
last_reason     -- text phrase for last_code
media_state     -- MediaState
media_dir       -- MediaDir
conf_slot       -- conference slot number for this call.
call_time       -- call's connected duration in seconds.
total_time      -- total call duration in seconds.
 
  Methods defined here:
__init__(self, lib=None, ci=None)

Data and other attributes defined here:
account = None
call_time = 0
conf_slot = -1
contact = ''
last_code = 0
last_reason = ''
media_dir = 0
media_state = 0
remote_contact = ''
remote_uri = ''
role = 0
sip_call_id = ''
state = 0
state_text = ''
total_time = 0
uri = ''

 
class CallRole
    Call role constants.
 
Member documentation:
 
CALLER  -- role is caller
CALLEE  -- role is callee
 
  Data and other attributes defined here:
CALLEE = 1
CALLER = 0

 
class CallState
    Call state constants.
 
Member documentation:
 
NULL            -- call is not initialized.
CALLING         -- initial INVITE is sent.
INCOMING        -- initial INVITE is received.
EARLY           -- provisional response has been sent or received.
CONNECTING      -- 200/OK response has been sent or received.
CONFIRMED       -- ACK has been sent or received.
DISCONNECTED    -- call is disconnected.
 
  Data and other attributes defined here:
CALLING = 1
CONFIRMED = 5
CONNECTING = 4
DISCONNECTED = 6
EARLY = 3
INCOMING = 2
NULL = 0

 
class CodecInfo
    This describes codec info.
 
Member documentation:
name            -- codec name
priority        -- codec priority (0-255)
clock_rate      -- clock rate
channel_count   -- number of channels
avg_bps         -- average bandwidth in bits per second
frm_ptime       -- base frame length in milliseconds
ptime           -- RTP frame length in milliseconds.
pt              -- payload type.
vad_enabled     -- specify if Voice Activity Detection is currently
                   enabled.
plc_enabled     -- specify if Packet Lost Concealment is currently
                   enabled.
 
  Methods defined here:
__init__(self, codec_info, codec_param)

Data and other attributes defined here:
avg_bps = 0
channel_count = 0
clock_rate = 0
frm_ptime = 0
name = ''
plc_enabled = False
priority = 0
pt = 0
ptime = 0
vad_enabled = False

 
class CodecParameter
    This specifies various parameters that can be configured for codec.
 
Member documentation:
 
ptime       -- specify the outgoing RTP packet length in milliseconds.
vad_enabled -- specify if VAD should be enabled.
plc_enabled -- specify if PLC should be enabled.
 
  Methods defined here:
__init__(self, codec_param)

Data and other attributes defined here:
plc_enabled = False
ptime = 0
vad_enabled = False

 
class Error
    Error exception class.
 
Member documentation:
 
op_name  -- name of the operation that generated this error.
obj      -- the object that generated this error.
err_code -- the error code.
 
  Methods defined here:
__init__(self, op_name, obj, err_code, err_msg='')
__str__(self)
err_msg(self)
Retrieve the description of the error.

Data and other attributes defined here:
err_code = -1
obj = None
op_name = ''

 
class Lib
    Library instance.
 
  Methods defined here:
__del__(self)
__init__(self)
__str__(self)
auto_lock(self)
conf_connect(self, src_slot, dst_slot)
Establish unidirectional media flow from souce to sink. 
 
One source may transmit to multiple destinations/sink. And if 
multiple sources are transmitting to the same sink, the media 
will be mixed together. Source and sink may refer to the same ID, 
effectively looping the media.
 
If bidirectional media flow is desired, application needs to call
this function twice, with the second one having the arguments 
reversed.
 
Keyword arguments:
src_slot    -- integer to identify the conference slot number of
               the source/transmitter.
dst_slot    -- integer to identify the conference slot number of    
               the destination/receiver.
conf_disconnect(self, src_slot, dst_slot)
Disconnect media flow from the source to destination port.
 
Keyword arguments:
src_slot    -- integer to identify the conference slot number of
               the source/transmitter.
dst_slot    -- integer to identify the conference slot number of    
               the destination/receiver.
conf_get_max_ports(self)
Get the conference bridge capacity.
 
Return:
    conference bridge capacity.
conf_get_signal_level(self, slot)
Get last signal level transmitted to or received from the 
specified port. The signal levels are float values from 0.0 to 1.0,
with 0.0 indicates no signal, and 1.0 indicates the loudest signal
level.
 
Keyword arguments:
slot        -- integer to identify the conference slot number.
 
Return value:
    (tx_level, rx_level) tuple.
conf_set_rx_level(self, slot, level)
Adjust the signal level to be received from the specified port
(to the bridge) by making it louder or quieter.
 
Keyword arguments:
slot        -- integer to identify the conference slot number.
level       -- Signal level adjustment. Value 1.0 means no level
               adjustment, while value 0 means to mute the port.
conf_set_tx_level(self, slot, level)
Adjust the signal level to be transmitted from the bridge to 
the specified port by making it louder or quieter.
 
Keyword arguments:
slot        -- integer to identify the conference slot number.
level       -- Signal level adjustment. Value 1.0 means no level
               adjustment, while value 0 means to mute the port.
create_account(self, acc_config, set_default=True, cb=None)
Create a new local pjsua account using the specified configuration.
 
Keyword arguments:
acc_config  -- AccountConfig
set_default -- boolean to specify whether to use this as the
               default account.
cb          -- AccountCallback instance.
 
Return:
    Account instance
create_account_for_transport(self, transport, set_default=True, cb=None)
Create a new local pjsua transport for the specified transport.
 
Keyword arguments:
transport   -- the Transport instance.
set_default -- boolean to specify whether to use this as the
               default account.
cb          -- AccountCallback instance.
 
Return:
    Account instance
create_player(self, filename, loop=False)
Create WAV file player.
 
Keyword arguments
filename    -- WAV file name
loop        -- boolean to specify whether playback should
               automatically restart upon EOF
Return:
    WAV player ID
create_playlist(self, filelist, label='playlist', loop=True)
Create WAV playlist.
 
Keyword arguments:
filelist    -- List of WAV file names.
label       -- Optional name to be assigned to the playlist
               object (useful for logging)
loop        -- boolean to specify whether playback should
               automatically restart upon EOF
 
Return:
    playlist_id
create_recorder(self, filename)
Create WAV file recorder.
 
Keyword arguments
filename    -- WAV file name
 
Return:
    WAV recorder ID
create_transport(self, type, cfg=None)
Create SIP transport instance of the specified type. 
 
Keyword arguments:
type    -- transport type from TransportType constant.
cfg     -- TransportConfig instance
 
Return:
    Transport object
destroy(self)
Destroy the library, and pjsua.
enum_codecs(self)
Return list of codecs supported by pjsua.
 
Return:
    list of CodecInfo
enum_snd_dev(self)
Enumerate sound devices in the system.
 
Return:
    list of SoundDeviceInfo. The index of the element specifies
    the device ID for the device.
get_codec_parameter(self, name)
Get codec parameter for the specified codec.
 
Keyword arguments:
name    -- codec name.
get_snd_dev(self)
Get the device IDs of current sound devices used by pjsua.
 
Return:
    (capture_dev_id, playback_dev_id) tuple
handle_events(self, timeout=50)
Poll the events from underlying pjsua library.
 
Application must poll the stack periodically if worker thread
is disable when starting the library.
 
Keyword argument:
timeout -- in milliseconds.
hangup_all(self)
Hangup all calls.
init(self, ua_cfg=None, log_cfg=None, media_cfg=None)
Initialize pjsua with the specified configurations.
 
Keyword arguments:
ua_cfg      -- optional UAConfig instance
log_cfg     -- optional LogConfig instance
media_cfg   -- optional MediaConfig instance
player_destroy(self, player_id)
Destroy the WAV player.
 
Keyword arguments:
player_id   -- the WAV player ID.
player_get_slot(self, player_id)
Get the conference port ID for the specified player.
 
Keyword arguments:
player_id  -- the WAV player ID
 
Return:
    Conference slot number for the player
player_set_pos(self, player_id, pos)
Set WAV playback position.
 
Keyword arguments:
player_id   -- WAV player ID
pos         -- playback position, in samples
playlist_destroy(self, playlist_id)
Destroy the WAV playlist.
 
Keyword arguments:
playlist_id   -- the WAV playlist ID.
playlist_get_slot(self, playlist_id)
Get the conference port ID for the specified playlist.
 
Keyword arguments:
playlist_id  -- the WAV playlist ID
 
Return:
    Conference slot number for the playlist
recorder_destroy(self, rec_id)
Destroy the WAV recorder.
 
Keyword arguments:
rec_id   -- the WAV recorder ID.
recorder_get_slot(self, rec_id)
Get the conference port ID for the specified recorder.
 
Keyword arguments:
rec_id  -- the WAV recorder ID
 
Return:
    Conference slot number for the recorder
set_codec_parameter(self, name, param)
Modify codec parameter for the specified codec.
 
Keyword arguments:
name    -- codec name
param   -- codec parameter.
set_codec_priority(self, name, priority)
Change the codec priority.
 
Keyword arguments:
name     -- Codec name
priority -- Codec priority, which range is 0-255.
set_null_snd_dev(self)
Disable the sound devices. This is useful if the system
does not have sound device installed.
set_snd_dev(self, capture_dev, playback_dev)
Change the current sound devices.
 
Keyword arguments:
capture_dev  -- the device ID of capture device to be used
playback_dev -- the device ID of playback device to be used.
start(self, with_thread=True)
Start the library. 
 
Keyword argument:
with_thread -- specify whether the module should create worker
               thread.
verify_sip_url(self, sip_url)
Verify that the specified string is a valid URI. 
 
Keyword argument:
sip_url -- the URL string.
 
Return:
    0 is the the URI is valid, otherwise the appropriate error 
    code is returned.

Static methods defined here:
instance()
Return singleton instance of Lib.
strerror(err)

 
class LogConfig
    Logging configuration to be specified in Lib.init().
 
Member documentation:
 
msg_logging   -- specify if SIP messages should be logged. Set to
                 True.
level         -- specify the input verbosity level.
console_level -- specify the output verbosity level.
decor         -- specify log decoration.
filename      -- specify the log filename.
callback      -- specify callback to be called to write the logging
                 messages. Sample function:
 
                 def log_cb(level, str, len):
                    print str,
 
  Methods defined here:
__init__(self, level=-1, filename='', callback=None, console_level=-1)

Data and other attributes defined here:
callback = None
console_level = 5
decor = 0
filename = ''
level = 5
msg_logging = True

 
class MediaConfig
    Media configuration to be specified in Lib.init().
 
Member documentation:
 
clock_rate          -- specify the core clock rate of the audio,
                       most notably the conference bridge.
snd_clock_rate      -- optionally specify different clock rate for
                       the sound device.
snd_auto_close_time -- specify the duration in seconds when the
                       sound device should be closed after inactivity
                       period.
channel_count       -- specify the number of channels to open the sound
                       device and the conference bridge.
audio_frame_ptime   -- specify the length of audio frames in millisecond.
max_media_ports     -- specify maximum number of audio ports to be
                       supported by the conference bridge.
quality             -- specify the audio quality setting (1-10)
ptime               -- specify the audio packet length of transmitted
                       RTP packet.
no_vad              -- disable Voice Activity Detector (VAD) or Silence
                       Detector (SD)
ilbc_mode           -- specify iLBC codec mode (must be 30 for now)
tx_drop_pct         -- randomly drop transmitted RTP packets (for
                       simulation). Number is in percent.
rx_drop_pct         -- randomly drop received RTP packets (for
                       simulation). Number is in percent.
ec_options          -- Echo Canceller option (specify zero).
ec_tail_len         -- specify Echo Canceller tail length in milliseconds.
                       Value zero will disable the echo canceller.
jb_min              -- specify the minimum jitter buffer size in
                       milliseconds. Put -1 for default.
jb_max              -- specify the maximum jitter buffer size in
                       milliseconds. Put -1 for default.
enable_ice          -- enable Interactive Connectivity Establishment (ICE)
enable_turn         -- enable TURN relay. TURN server settings must also
                       be configured.
turn_server         -- specify the domain or hostname or IP address of
                       the TURN server, in "host[:port]" format.
turn_conn_type      -- specify connection type to the TURN server, from
                       the TURNConnType constant.
turn_cred           -- specify AuthCred for the TURN credential.
 
  Methods defined here:
__init__(self)

Data and other attributes defined here:
audio_frame_ptime = 20
channel_count = 1
clock_rate = 16000
ec_options = 0
ec_tail_len = 256
enable_ice = True
enable_turn = False
ilbc_mode = 30
jb_max = -1
jb_min = -1
max_media_ports = 32
no_vad = False
ptime = 0
quality = 6
rx_drop_pct = 0
snd_auto_close_time = 5
snd_clock_rate = 0
turn_conn_type = 17
turn_cred = None
turn_server = ''
tx_drop_pct = 0

 
class MediaDir
    Media direction constants.
 
Member documentation:
 
NULL              -- media is not active
ENCODING          -- media is active in transmit/encoding direction only.
DECODING          -- media is active in receive/decoding direction only
ENCODING_DECODING -- media is active in both directions.
 
  Data and other attributes defined here:
DECODING = 2
ENCODING = 1
ENCODING_DECODING = 3
NULL = 0

 
class MediaState
    Call media state constants.
 
Member documentation:
 
NULL        -- media is not available.
ACTIVE      -- media is active.
LOCAL_HOLD  -- media is put on-hold by local party.
REMOTE_HOLD -- media is put on-hold by remote party.
ERROR       -- media error (e.g. ICE negotiation failure).
 
  Data and other attributes defined here:
ACTIVE = 1
ERROR = 4
LOCAL_HOLD = 2
NULL = 0
REMOTE_HOLD = 3

 
class PresenceActivity
    Presence activities constants.
 
Member documentation:
 
UNKNOWN -- the person activity is unknown
AWAY    -- the person is currently away
BUSY    -- the person is currently engaging in other activity
 
  Data and other attributes defined here:
AWAY = 1
BUSY = 2
UNKNOWN = 0

 
class SIPUri
    Helper class to parse the most important components of SIP URI.
 
Member documentation:
 
scheme    -- URI scheme ("sip" or "sips")
user      -- user part of the URI (may be empty)
host      -- host name part
port      -- optional port number (zero if port is not specified).
transport -- transport parameter, or empty if transport is not
             specified.
 
  Methods defined here:
__init__(self, uri=None)
decode(self, uri)
Parse SIP URL.
 
Keyword argument:
uri -- the URI string.
encode(self)
Encode this object into SIP URI string.
 
Return:
    URI string.

Data and other attributes defined here:
host = ''
port = 0
scheme = ''
transport = ''
user = ''

 
class SoundDeviceInfo
    This described the sound device info.
 
Member documentation:
name                -- device name.
input_channels      -- number of capture channels supported.
output_channels     -- number of playback channels supported.
default_clock_rate  -- default sampling rate.
 
  Methods defined here:
__init__(self, sdi)

Data and other attributes defined here:
default_clock_rate = 0
input_channels = 0
name = ''
output_channels = 0

 
class SubscriptionState
    Presence subscription state constants.
 
  Data and other attributes defined here:
ACCEPTED = 2
ACTIVE = 4
NULL = 0
PENDING = 3
SENT = 1
TERMINATED = 5
UNKNOWN = 6

 
class TURNConnType
    These constants specifies the connection type to TURN server.
 
Member documentation:
UDP     -- use UDP transport.
TCP     -- use TCP transport.
TLS     -- use TLS transport.
 
  Data and other attributes defined here:
TCP = 6
TLS = 255
UDP = 17

 
class Transport
    SIP transport class.
 
  Methods defined here:
__del__(self)
__init__(self, lib, id)
__str__(self)
close(self, force=False)
Close and destroy this transport.
 
Keyword argument:
force   -- force deletion of this transport (not recommended).
disable(self)
Disable this transport.
enable(self)
Enable this transport.
info(self)
Get TransportInfo.

 
class TransportConfig
    SIP transport configuration class.
 
Member configuration:
 
port        -- port number.
bound_addr  -- optionally specify the address to bind the socket to.
               Default is empty to bind to INADDR_ANY.
public_addr -- optionally override the published address for this
               transport. If empty, the default behavior is to get
               the public address from STUN or from the selected
               local interface. Format is "host:port".
 
  Methods defined here:
__init__(self, port=5060, bound_addr='', public_addr='')

Data and other attributes defined here:
bound_addr = ''
port = 0
public_addr = ''

 
class TransportFlag
    Transport flags to indicate the characteristics of the transport.
 
Member documentation:
 
RELIABLE    -- transport is reliable.
SECURE      -- transport is secure.
DATAGRAM    -- transport is datagram based.
 
  Data and other attributes defined here:
DATAGRAM = 4
RELIABLE = 1
SECURE = 2

 
class TransportInfo
    SIP transport info.
 
Member documentation:
 
type        -- transport type, from TransportType constants.
description -- longer description for this transport.
is_reliable -- True if transport is reliable.
is_secure   -- True if transport is secure.
is_datagram -- True if transport is datagram based.
host        -- the IP address of this transport.
port        -- the port number.
ref_cnt     -- number of objects referencing this transport.
 
  Methods defined here:
__init__(self, ti)

Data and other attributes defined here:
description = ''
host = ''
is_datagram = False
is_reliable = False
is_secure = False
port = 0
ref_cnt = 0
type = ''

 
class TransportType
    SIP transport type constants.
 
Member documentation:
UNSPECIFIED -- transport type is unknown or unspecified
UDP         -- UDP transport
TCP         -- TCP transport
TLS         -- TLS transport
IPV6        -- this is not a transport type but rather a flag
               to select the IPv6 version of a transport
UDP_IPV6    -- IPv6 UDP transport
TCP_IPV6    -- IPv6 TCP transport
 
  Data and other attributes defined here:
IPV6 = 128
TCP = 2
TCP_IPV6 = 130
TLS = 3
UDP = 1
UDP_IPV6 = 129
UNSPECIFIED = 0

 
class UAConfig
    User agent configuration to be specified in Lib.init().
 
Member documentation:
 
max_calls   -- maximum number of calls to be supported.
nameserver  -- list of nameserver hostnames or IP addresses. Nameserver
               must be configured if DNS SRV resolution is desired.
stun_domain -- if nameserver is configured, this can be used to query
               the STUN server with DNS SRV.
stun_host   -- the hostname or IP address of the STUN server. This will
               also be used if DNS SRV resolution for stun_domain fails.
user_agent  -- Optionally specify the user agent name.
 
  Data and other attributes defined here:
max_calls = 4
nameserver = []
stun_domain = ''
stun_host = ''
user_agent = 'pjsip python'