SIP SIMPLE Client SDK

= SIP core API =

[[TOC(Sip*, depth=3)]]

== Introduction ==

This chapter describes the internal architecture and API of the SIP core of the {{{sipsimple}}} library.

{{{sipsimple}}} is a Python package, the core of which wraps the PJSIP C library, which handles SIP signaling and audio media for the SIP SIMPLE client.

SIP stands for 'Sessions Initiation Protocol', an IETF standard described by [http://tools.ietf.org/html/rfc3261 RFC 3261]. SIP is an application-layer control protocol that can establish,

modify and terminate multimedia sessions such as Internet telephony calls

(VoIP). Media can be added to (and removed from) an existing session.

SIP transparently supports name mapping and redirection services, which

supports personal mobility, users can maintain a single externally visible

address identifier, which can be in the form of a standard email address or

E.164 telephone number regardless of their physical network location.

SIP allows the endpoints to negotiate and combine any type of session they

mutually understand like video, instant messaging (IM), file transfer,

desktop sharing and provides a generic event notification system with

real-time publications and subscriptions about state changes that can be

used for asynchronous services like presence, message waiting indicator and

busy line appearance.

For a comprehensive overview of SIP related protocols and use cases visit http://www.tech-invite.com

== PJSIP library ==

{{{sipsimple}}} builds on PJSIP [http://www.pjsip.org], a set of static libraries, written in C, which provide SIP signaling and media capabilities.

PJSIP is considered to be the most mature and advanced open source SIP stack available.

The following diagram, taken from the PJSIP documentation, illustrates the library stack of PJSIP:

[[Image(http://www.pjsip.org/images/diagram.jpg, nolink)]]

The diagram shows that there is a common base library, and two more or less independent stacks of libraries, one for SIP signaling and one for SIP media.

The latter also includes an abstraction layer for the sound-card.

Both of these stracks are integrated in the high level library, called PJSUA.

PJSIP itself provides a high-level [http://www.pjsip.org/python/pjsua.htm Python wrapper for PJSUA].

Despite this, the choice was made to bypass PJSUA and write the SIP core of the {{{sipsimple}}} package as a Python wrapper, which directly uses the PJSIP and PJMEDIA libraries.

The main reasons for this are the following:

 * PJSUA assumes a session with exactly one audio stream, whilst for the SIP SIMPLE client more advanced (i.e. low-level) manipulation of the SDP is needed.

 * What is advertised as SIMPLE functionality, it is minimal and incomplete subset of it. Only page mode messaging using SIP MESSAGE method and basic device status presence are possible, while session mode IM and rich presence are desired.

 * PJSUA integrates the decoding and encoding of payloads (e.g. presence related XML documents), while in the SIP SIMPLE client this should be done at a high level, not by the SIP stack.

PJSIP itself is by nature asynchronous.

In the case of PJSIP it means that in general there will be one thread which handles reception and transmission of SIP signaling messages by means of a polling function which is continually called by the application.

Whenever the application performs some action through a function, this function will return immediately.

If PJSIP has a result for this action, it will notify the application by means of a callback function in the context of the polling function thread.

> NOTE: Currently the core starts the media handling as a separate C thread to avoid lag caused by the GIL.

> The sound-card also has its own C thread.

== Architecture ==

The {{{sipsimple}}} core wrapper itself is mostly written using [http://cython.org/ Cython] (formerly [http://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/ Pyrex]).

It allows a Python-like file with some added C manipulation statements to be compiled to C.

This in turn compiles to a Python C extension module, which links with the PJSIP static libraries.

The SIP core part of the {{{sipsimple}}} Python package is subdivided into three modules:

 '''sipsimple.engine'''::

  Python module that contains the {{{Engine}}} singleton class, which manages the thread that constantly polls the PJSIP library, i.e. the PJSIP worker thread.

  For the applications that use the core of {{{sipsimple}}}, the {{{Engine}}} object forms the main entry point.

 '''sipsimple.core'''::

  This is the Python C extension module ultimately compiled from the Cython file and PJSIP static libraries.

  It contains these types of classes:

   * The {{{PJSIPUA}}} class, which can only be instanced once, and is this case is only instanced once by the {{{Engine}}} object.

     In this way the {{{Engine}}} singleton class acts as a wrapper to the one {{{PJSIPUA}}} instance.

     The {{{PJSIPUA}}} class represents the SIP endpoint and manages the initialization and destruction of all the PJSIP libraries.

     It also provides a number of methods.

     The application however should never call these methods directly on the {{{PJSIPUA}}} object, rather it should call them on the {{{Engine}}} wrapper object.

     This object handles everything that for one reason or another cannot or should not be handled from Cython.

   * The classes that represent the main SIP primitives to be used by the application, or in the case of {{{Request}}} a generic SIP transaction.

     The application can instantiate these classes once the {{{Engine}}} class has been instantiated and the PJSIP worker thread has been started.

     All of these classes represent a state machine.

     * {{{Request}}}

     * {{{Subscription}}}

     * {{{Invitation}}}

   * Several helper classes, which represent some structured collection of data to be passed as parameter to methods of the SIP primitive classes and to parameters of notifications.

     * {{{SIPURI}}}

     * {{{Credentials}}}

     * {{{Route}}}

   * A number of SDP manipulation classes, which directly wrap the PJSIP structures representing either the parsed or to be generated SDP.

     {{{SDPSession}}} objects may contain references to the other classes and are passed as arguments to methods of a {{{Invitiation}}} object or notifications sent by it.

     * {{{SDPSession}}}

     * {{{SDPMedia}}}

     * {{{SDPConnection}}}

     * {{{SDPAttribute}}}

   * Two classes related to transport of media traffic and audio traffic specifically, built on PJMEDIA.

     These classes can be instantiated independently from the other classes in order to keep signaling and media separate.

     * {{{RTPTransport}}}

     * {{{AudioTransport}}}

   * Some other classes that are related to the PJSIP sound subsystem, the main one being the {{{ConferenceBirdge}}}, which audio mixing and input from and output to sound devices.

     * {{{ConferenceBridge}}}

     * {{{ToneGenerator}}}

     * {{{WaveFile}}}

     * {{{RecordingWaveFile}}}

   * Two exception classes, the second being a subclass of the first.

     * {{{SIPCoreError}}}

     * {{{PJSIPError}}}

   * Classes used internally within the {{{core}}} module, e.g. to wrap a particular PJSIP library.

     These classes should not be imported directly and are not included in the {{{__all__}}} variable of this module.

 '''sipsimple.primitives'''::

  This module contains several SIP primitive classes that are based on the {{{Request}}} object from the core:

   * {{{Registration}}}

   * {{{Message}}}

   * {{{Publication}}}

These classes (except the ones internal to the {{{core}}} module) are illustrated in the following diagram:

[[Image(sipsimple-core-classes.png, nolink)]]

== Integration ==

The core itself has one Python dependency, the [http://pypi.python.org/pypi/python-application application] module, which in turn depends on the [http://pypi.python.org/pypi/zope.interface zope.interface] module.

These modules should be present on the system before the core can be used.

An application that uses the SIP core must use the notification system provided by the {{{application}}} module in order to receive notifications from it.

It does this by creating one or more classes that act as an observer for particular messages and registering it with the {{{NotificationCenter}}}, which is a singleton class.

This means that any call to instance an object from this class will result in the same object.

As an example, this bit of code will create an observer for logging messages only:

{{{

from zope.interface import implements

from application.notification import NotificationCenter, IObserver

class SIPEngineLogObserver(object):

    implements(IObserver)

    def handle_notification(self, notification):

        print "%(timestamp)s (%(level)d) %(sender)14s: %(message)s" % notification.data.__dict__

notification_center = NotificationCenter()

log_observer = EngineLogObserver()

notification_center.add_observer(self, name="SIPEngineLog")

}}}

Each notification object has three attributes:

 '''sender'''::

  The object that sent the notification.

  For generic notifications the sender will be the {{{Engine}}} instance, otherwise the relevant object.

 '''name'''::

  The name describing the notification.

  All messages will be described in this document and start with the prefix "SIP".

 '''data'''::

  An instance of {{{application.notification.NotificationData}}} or a subclass of it.

  The attributes of this object provide additional data about the notification.

  Notifications described in this document will also have the data attributes described.

Besides setting up the notification observers, the application should import the relevant objects from the {{{sipsimple.core}}}, {{{sipsimple.engine}}} and {{{sipsimple.primitives}}} modules.

It can then instance the {{{Engine}}} class, which is also a singleton, and start the PJSIP worker thread by calling {{{Engine.start()}}}, optionally providing a number of initialization options.

Most of these options can later be changed at runtime, by setting attributes of the same name on the {{{Engine}}} object.

The application may then instance one of the SIP primitive classes and perform operations on it.

When starting the {{{Engine}}} class, the application can pass a number of keyword arguments that influence the behaviour of the SIP endpoint.

For example, the SIP network ports may be set through the {{{local_udp_port}}}, {{{local_tcp_port}}} and {{{local_tls_port}}} arguments.

The UDP/RTP ports are described by a range of ports through {{{rtp_port_range}}}, two of which will be randomly selected for each {{{RTPTransport}}} object and effectively each audio stream.

The methods called on the SIP primitive objects and the {{{Engine}}} object (proxied to the {{{PJSIPUA}}} instance) may be called from any thread.

They will return immediately and any delayed result, such as results depending on network traffic, will be returned later using a notification.

In this manner the SIP core continues the asynchronous pattern of PJSIP.

If there is an error in processing the request, an instance of {{{SIPCoreError}}}, or its subclass {{{PJSIPError}}} will be raised.

The former will be raised whenever an error occurs inside the core, the latter whenever an underlying PJSIP function returns an error.

The {{{PJSIPError}}} object also contains a status attribute, which is the PJSIP errno as an integer.

As a very basic example, one can {{{REGISTER}}} for a sip account by typing the following lines on a Python console:

{{{

from sipsimple.engine import Engine

from sipsimple.primitives import Registration

from sipsimple.core import Credentials, SIPURI, Route

e = Engine()

e.start()

uri = SIPURI(user="alice", host="example.com")

cred = Credentials("alice", "mypassword")

reg = Registration(uri, credentials=cred)

reg.register(SIPURI("127.0.0.1",port=12345), Route("1.2.3.4"))

}}}

Note that in this example no observer for notifications from this {{{Registration}}} object are registered, so the result of the operation cannot be seen.

Also note that this will not keep the registration registered when it is about to expire, as it is the application's responsibility.

See the {{{Registration}}} documentation for more details.

When performing operations with a running {{{Engine}}} on a Python console, be sure to call the {{{stop()}}} method of the {{{Engine}}} before exiting the console.

Failure to do so will keep the {{{Engine}}} running and will cause the program to hang.

To see how this example can be converted to actually wait for the response without creating an observer, see the example for GreenRegistration at [wiki:SipSynchronousAPI#sipsimple.green.core.GreenRegistration SynchronousAPI].

> NOTE: GreenRegistration is outdated and should probably not be used anymore.

Another convention that is worth mentioning at this point is that the SIP core will never perform DNS lookups.

For the sake of flexibility, it is the responsibility of the application to do this and pass the result to SIP core objects using the {{{Route}}} helper object, indicating the destination IP address the resulting SIP request should be sent to.

== Components ==

=== Engine ===

As explained above, this singleton class needs to be instantiated by the application using the SIP core of {{{sipsimple}}} and represents the whole SIP core stack.

Once the {{{start()}}} method is called, it instantiates the {{{core.PJSIPUA}}} object and will proxy attribute and methods from it to the application.

==== attributes ====

 '''default_start_options''' (class attribute)::

  This dictionary is a class attribute that describes the default values for the initialization options passed as keyword arguments to the {{{start()}}} method.

  Consult this method for documentation of the contents.

 '''is_running'''::

  A boolean property indicating if the {{{Engine}}} is running and if it is safe to try calling any proxied methods or attributes on it.

==== methods ====

 '''!__init!__'''(''self'')::

  This will either create the {{{Engine}}} if it is called for the first time or return the one {{{Engine}}} instance if it is called subsequently.

 '''start'''(''self'', '''**kwargs''')::

  Initialize all PJSIP libraries based on the keyword parameters provided and start the PJSIP worker thread.

  If this fails an appropriate exception is raised.

  After the {{{Engine}}} has been started successfully, it can never be started again after being stopped.

  The keyword arguments will be discussed here.

  Many of these values are also readable as (proxied) attributes on the Engine once the {{{start()}}} method has been called.

  Many of them can also be set at runtime, either by modifying the attribute or by calling a particular method.

  This will also be documented for each argument in the following list of options.

  [[BR]]''local_ip'': (Default: {{{None}}})[[BR]]

  IP address of a local interface to bind to.

  If this is {{{None}}} or {{{0.0.0.0}}} on start, the {{{Engine}}} will listen on all network interfaces.

  As an attribute, this value is read-only and cannot be changed at runtime.

  [[BR]]''local_udp_port'': (Default: {{{0}}})[[BR]]

  The local UDP port to listen on for UDP datagrams.

  If this is 0, a random port will be chosen.

  If it is {{{None}}}, the UDP transport is disabled, both for incoming and outgoing traffic.

  As an attribute, this value is read-only, but it can be changed at runtime using the {{{set_local_udp_port()}}} method.

  [[BR]]''local_tcp_port'': (Default: {{{0}}})[[BR]]

  The local TCP port to listen on for new TCP connections.

  If this is 0, a random port will be chosen.

  If it is {{{None}}}, the TCP transport is disabled, both for incoming and outgoing traffic.

  As an attribute, this value is read-only, but it can be changed at runtime using the {{{set_local_tcp_port()}}} method.

  [[BR]]''local_tls_port'': (Default: {{{0}}})[[BR]]

  The local TCP port to listen on for new TLS over TCP connections.

  If this is 0, a random port will be chosen.

  If it is {{{None}}}, the TLS transport is disabled, both for incoming and outgoing traffic.

  As an attribute, this value is read-only, but it can be changed at runtime using the {{{set_tls_options()}}} method, as internally the TLS transport needs to be restarted for this operation. 

  [[BR]]''tls_protocol'': (Default: "TLSv1")[[BR]] 

  This string describes the (minimum) TLS protocol that should be used. 

  Its values should be either {{{None}}}, "SSLv2", "SSLv23", "SSLv3" or "TLSv1". 

  If {{{None}}} is specified, the PJSIP default will be used, which is currently "TLSv1". 

  [[BR]]''tls_verify_server'': (Default: {{{False}}})[[BR]]

  This boolean indicates whether PJSIP should verify the certificate of the server against the local CA list when making an outgoing TLS connection.

  As an attribute, this value is read-only, but it can be changed at runtime using the {{{set_tls_options()}}} method, as internally the TLS transport needs to be restarted for this operation.

  [[BR]]''tls_ca_file'': (Default: {{{None}}})[[BR]]

  This string indicates the location of the file containing the local list of CA certificates, to be used for TLS connections.

  If this is set to {{{None}}}, no CA certificates will be read. 

  As an attribute, this value is read-only, but it can be changed at runtime using the {{{set_tls_options()}}} method, as internally the TLS transport needs to be restarted for this operation. 

  [[BR]]''tls_cert_file'': (Default: {{{None}}})[[BR]] 

  This string indicates the location of a file containing the TLS certificate to be used for TLS connections. 

  If this is set to {{{None}}}, no certificate file will be read. 

  As an attribute, this value is read-only, but it can be changed at runtime using the {{{set_tls_options()}}} method, as internally the TLS transport needs to be restarted for this operation. 

  [[BR]]''tls_privkey_file'': (Default: {{{None}}})[[BR]] 

  This string indicates the location of a file containing the TLS private key associated with the above mentioned certificated to be used for TLS connections. 

  If this is set to {{{None}}}, no private key file will be read. 

  As an attribute, this value is read-only, but it can be changed at runtime using the {{{set_tls_options()}}} method, as internally the TLS transport needs to be restarted for this operation. 

  [[BR]]''tls_timeout'': (Default: 1000)[[BR]] 

  The timeout value for a TLS negotiation in milliseconds. 

  Note that this value should be reasonably small, as a TLS negotiation blocks the whole PJSIP polling thread. 

  As an attribute, this value is read-only, but it can be changed at runtime using the {{{set_tls_options()}}} method, as internally the TLS transport needs to be restarted for this operation.

  [[BR]]''user_agent'': (Default: {{{"sipsimple-%version"}}})[[BR]]

  This value indicates what should be set in the {{{User-Agent}}} header, which is included in each request or response sent.

  It can be read and set directly as an attribute at runtime.

  [[BR]]''log_level'': (Default: 5)[[BR]]

  This integer dictates the maximum log level that may be reported to the application by PJSIP through the {{{SIPEngineLog}}} notification.

  By default the maximum amount of logging information is reported.

  This value can be read and set directly as an attribute at runtime.

  [[BR]]''trace_sip'': (Default: {{{False}}})[[BR]]

  This boolean indicates if the SIP core should send the application SIP messages as seen on the wire through the {{{SIPEngineSIPTrace}}} notification.

  It can be read and set directly as an attribute at runtime.

  [[BR]]''rtp_port_range'': (Default: (40000, 40100))[[BR]]

  This tuple of two integers indicates the range to select UDP ports from when creating a new {{{RTPTransport}}} object, which is used to transport media.

  It can be read and set directly as an attribute at runtime, but the ports of previously created {{{RTPTransport}}} objects remain unaffected.

  [[BR]]''codecs'': (Default: {{{["speex", "G722", "PCMU", "PCMA", "iLBC", "GSM"]}}})[[BR]]

  This list specifies the codecs to use for audio sessions and their preferred order.

  It can be read and set directly as an attribute at runtime.

  Note that this global option can be overridden by an argument passed to {{{AudioTransport.__init__()}}}.

  The strings in this list is case insensitive.

  [[BR]]''events'': (Default: <some sensible events>)[[BR]]

  PJSIP needs a mapping between SIP SIMPLE event packages and content types.

  This dictionary provides some default packages and their event types.

  As an attribute, this value is read-only, but it can be changed at runtime using the {{{set_local_tls_port()}}} method.

 '''start_cfg'''(''self'', '''**kwargs''')::

  This provides a [wiki:SipConfigurationAPI Configuration API] aware start method.

  It will retrieve all the arguments that can be passed to {{{start()}}} from the configuration framework, unless they are overridden by the keyword arguments to this method.

  Any argument that can be passed to {{{start()}}} may be specified.

 '''stop'''(''self'')::

  Stop the PJSIP worker thread and unload all PJSIP libraries.

  Note that after this all references to SIP core objects can no longer be used, these should be properly removed by the application itself before stopping the {{{Engine}}}.

  Also note that, once stopped the {{{Engine}}} cannot be started again.

  This method is automatically called when the Python interpreter exits.

==== proxied attributes ====

Besides all the proxied attributes described for the {{{__init__}}} method above, two other attributes are provided once the {{{Engine}}} has been started.

 '''input_devices'''::

  This read-only attribute is a list of strings, representing all audio input devices on the system that can be used.

  One of these device names can be passed as the {{{input_device}}} argument when creating a {{{ConferenceBridge}}} object.

 '''output_devices'''::

  This read-only attribute is a list of string, representing all audio output devices on the system that can be used.

  One of these device names can be passed as the {{{output_device}}} argument when creating a {{{ConferenceBridge}}} object.

 '''available_codecs'''::

  A read-only list of codecs available in the core, regardless of the codecs configured through the {{{codecs}}} attribute.

==== proxied methods ====

 '''add_event'''(''self'', '''event''', '''accept_types''')::

  Couple a certain event package to a list of content types.

  Once added it cannot be removed or modified.

 '''detect_nat_type'''(''self'', '''stun_server_address''', '''stun_server_port'''=3478, '''user_data'''=None)::

  Will start a series of STUN requests which detect the type of NAT this host is behind.

  The {{{stun_server_address}}} parameter indicates the IP address or hostname of the STUN server to be used and {{{stun_server_port}}} specifies the remote UDP port to use.

  When the type of NAT is detected, this will be reported back to the application by means of a {{{SIPEngineDetectedNATType}}} notification, including the user_data object passed with this method.

 '''set_local_udp_port'''(''self'', '''value''')::

  Update the {{{local_udp_port}}} attribute to the newly specified value.

 '''set_local_tcp_port'''(''self'', '''value''')::

  Update the {{{local_tcp_port}}} attribute to the newly specified value.

 '''set_tls_options'''(''self'', '''local_port'''={{{None}}}, '''protocol'''="TLSv1", '''verify_server'''={{{False}}}, '''ca_file'''={{{None}}}, '''cert_file'''={{{None}}}, '''privkey_file'''={{{None}}}, '''timeout'''=1000):: 

  Calling this method will (re)start the TLS transport with the specified arguments, or stop it in the case that the '''local_port''' argument is set to {{{None}}}. 

  The semantics of the arguments are the same as on the {{{start()}}} method. 

 '''parse_sip_uri(''self'', '''uri_string''')::

  Will parse the provided SIP URI string using the PJSIP parsing capabilities and return a {{{SIPURI}}} object, or raise an exception if there was an error parsing the URI.

==== notifications ====

Notifications sent by the {{{Engine}}} are notifications that are related to the {{{Engine}}} itself or unrelated to any SIP primitive object.

They are described here including the data attributes that is included with them.

 '''SIPEngineWillStart'''::

  This notification is sent when the {{{Engine}}} is about to start.

  [[BR]]''timestamp'':[[BR]]

  A {{{datetime.datetime}}} object indicating when the notification was sent.

 '''SIPEngineDidStart'''::

  This notification is sent when the {{{Engine}}} is has just been started.

  [[BR]]''timestamp'':[[BR]]

  A {{{datetime.datetime}}} object indicating when the notification was sent.

 '''SIPEngineDidFail'''::

  This notification is sent whenever the {{{Engine}}} has failed fatally and either cannot start or is about to stop.

  It is not recommended to call any methods on the {{{Engine}}} at this point.

  [[BR]]''timestamp'':[[BR]]

  A {{{datetime.datetime}}} object indicating when the notification was sent.

 '''SIPEngineWillEnd'''::

  This notification is sent when the {{{Engine}}} is about to stop because the application called the {{{stop()}}} method.

  Methods on the {{{Engine}}} can be called at this point, but anything that has a delayed result will probably not return any notification.

  [[BR]]''timestamp'':[[BR]]

  A {{{datetime.datetime}}} object indicating when the notification was sent.

 '''SIPEngineDidEnd'''::

  This notification is sent when the {{{Engine}}} was running and is now stopped, either because of failure or because the application requested it.

  [[BR]]''timestamp'':[[BR]]

  A {{{datetime.datetime}}} object indicating when the notification was sent.

 '''SIPEngineLog'''::

  This notification is a wrapper for PJSIP logging messages.

  It can be used by the application to output PJSIP logging to somewhere meaningful, possibly doing filtering based on log level.

  [[BR]]''timestamp'':[[BR]]

  A {{{datetime.datetime}}} object representing the time when the log message was output by PJSIP.

  [[BR]]''sender'':[[BR]]

  The PJSIP module that originated this log message.

  [[BR]]''level'':[[BR]]

  The logging level of the message as an integer.

  Currently this is 1 through 5, 1 being the most critical.

  [[BR]]''message'':[[BR]]

  The actual log message.

 '''SIPEngineSIPTrace'''::

  Will be sent only when the {{{do_siptrace}}} attribute of the {{{Engine}}} instance is set to {{{True}}}.

  The notification data attributes will contain the SIP messages as they are sent and received on the wire.

  [[BR]]''timestamp'':[[BR]]

  A {{{datetime.datetime}}} object indicating when the notification was sent.

  [[BR]]''received'':[[BR]]

  A boolean indicating if this message was sent from or received by PJSIP (i.e. the direction of the message).

  [[BR]]''source_ip'':[[BR]]

  The source IP address as a string.

  [[BR]]''source_port'':[[BR]]

  The source port of the message as an integer.

  [[BR]]''destination_ip'':[[BR]]

  The destination IP address as a string.

  [[BR]]''source_port'':[[BR]]

  The source port of the message as an integer.

  [[BR]]''data'':[[BR]]

  The contents of the message as a string.

> For received message the destination_ip and for sent messages the source_ip may not be reliable.

 '''SIPEngineDetectedNATType'''::

  This notification is sent some time after the application request the NAT type this host behind to be detected using a STUN server.

  Note that there is no way to associate a request to do this with a notification, although every call to the {{{detect_nat_type()}}} method will generate exactly one notification.

  [[BR]]''timestamp'':[[BR]]

  A {{{datetime.datetime}}} object indicating when the notification was sent.

  [[BR]]''succeeded'':[[BR]]

  A boolean indicating if the NAT detection succeeded.

  [[BR]]''user_data'':[[BR]]

  The {{{user_data}}} argument passed while calling the {{{detect_nat_type()}}} method.

  This can be any object and could be used for matching requests to responses.

  [[BR]]''nat_type'':[[BR]]

  A string describing the type of NAT found.

  This value is only present if NAT detection succeeded.

  [[BR]]''error'':[[BR]]

  A string indicating the error that occurred while attempting to detect the type of NAT.

  This value only present if NAT detection did not succeed.

 '''SIPEngineGotException'''::

  This notification is sent whenever there is an unexpected exception within the PJSIP working thread.

  The application should show the traceback to the user somehow.

  An exception need not be fatal, but if it is it will be followed by a '''SIPEngineDidFail''' notification.

  [[BR]]''timestamp'':[[BR]]

  A {{{datetime.datetime}}} object indicating when the notification was sent.

  [[BR]]''traceback'':[[BR]]

  A string containing the traceback of the exception.

  In general this should be printed on the console.

=== ConferenceBridge ===

A {{{ConferenceBridges}}} manages two audio devices, on for input and one for output, and a fully routable audio mixer for a number of sources.

It wraps a [http://www.pjsip.org/pjmedia/docs/html/group__PJMEDIA__CONF.htm PJSIP conference bridge], the concept of which is explained in the [http://trac.pjsip.org/repos/wiki/Python_SIP/Media PJSIP documentation].

Any component in the core that either produces or consumes sound, i.e. {{{AudioTransport}}}, {{{ToneGenerator}}}, {{{WaveFile}}} and {{{RecordingWaveFile}}} objects, has a {{{ConferenceBridge}}} associated with it and a corresponding slot on that conference bridge.

The sound devices, both input and output, together always occupy slot 0.

It is up to the application to setup the desired routing between these components.

==== attributes ====

 '''input_device'''::

  A string specifying the audio input device that is currently being used.

  If there is no input device, this attribute will be {{{None}}}.

  This attribute is read-only, but may be updated by calling the {{{set_sound_devices()}}} method.

 '''output_device'''::

  A string specifying the audio output device that is currently being used.

  If there is no output device, this attribute will be {{{None}}}.

  This attribute is read-only, but may be updated by calling the {{{set_sound_devices()}}} method.

 '''sample_rate'''::

  The sample rate in Hz that the conference bridge is currently operating on.

  This read-only attribute is passed when the object is created.

 '''ec_tail_length'''::

  The current echo cancellation tail length in ms.

  If this value is 0, no echo cancellation is used.

  This attribute is read-only, but may be updated by calling the {{{set_sound_devices()}}} method.

 '''slot_count'''::

  The total number of slots that is available on the conference bridge

  This read-only attribute is passed when the object is created.

 '''used_slot_count'''::

  A read-only attribute indicating the number of slots that are used by objects.

 '''volume'''::

  This writable property indicates the % of volume that is sent to the audio output device.

  By default this value is 100.

 '''is_muted'''::

  This writable boolean property indicates if the input audio device is muted.

 '''connected_slots'''::

  A read-only list of tupples indicating which slot is connected to which.

  Connections are directional.

==== methods ====

 '''!__init!__'''(''self'', '''input_device''', '''output_device''', '''sample_rate''', '''ec_tail_length'''=200, '''slot_count'''=254)::

  Creates a new {{{ConferenceBridge}}} object.

  [[BR]]''input_device'':[[BR]]

  The name of the audio input device to use as a string, or {{{None}}} if no input device is to be used.

  A list of known input devices can be queried through the {{{Engine.input_devices}}} attribute.

  If {{{"default"}}} is used, PJSIP will select the system default output device, or {{{None}}} if no audio input device is present.

  The device that was selected can be queried afterwards through the {{{input_device}}} attribute.

  [[BR]]''output_device'':[[BR]]

  The name of the audio output device to use as a string, or {{{None}}} if no output device is to be used.

  A list of known output devices can be queried through the {{{Engine.output_devices}}} attribute.

  If {{{"default"}}} is used, PJSIP will select the system default output device, or {{{None}}} if no audio output device is present.

  The device that was selected can be queried afterwards through the {{{output_device}}} attribute.

  [[BR]]''sample_rate'':[[BR]]

  The sample rate on which the conference bridge and sound devices should operate in Hz.

  This must be a multiple of 50.

  [[BR]]''ec_tail_length'':[[BR]]

  The echo cancellation tail length in ms.

  If this value is 0, no echo cancellation is used.

  [[BR]]''slot_count'':[[BR]]

  The number of slots to allocate on the conference bridge.

  Not that this includes the slot that is occupied by the sound devices.

 '''set_sound_devices'''(''self'', '''input_device''', '''output_device''', '''ec_tail_length''')::

  Change the sound devices used (including echo cancellation) by the conference bridge.

  The meaning of the parameters is that same as for {{{__init__()}}}.

 '''connect_slots'''(''self'', '''src_slot''', '''dst_slot''')::

  Connect two slots on the conference bridge, making audio flow from {{{src_slot}}} to {{{dst_slot}}}.

 '''disconnect_slots'''(''self'', '''src_slot''', '''dst_slot''')::

  Break the connection between the specified slots.

  Note that when an audio object is stopped or destroyed, its connections on the conference bridge will automatically be removed.

=== SIPURI ===

This is a helper object for representing a SIP URI.

This object needs to be used whenever a SIP URI should be specified to the SIP core.

It supports comparison to other {{{SIPURI}}} objects using the == and != expressions.

As all of its attributes are set by the {{{__init__}}} method, the individual attributes will not be documented here.

==== methods ====

 '''!__init!__'''(''self'', '''host''', '''user'''={{{None}}}, '''port'''={{{None}}}, '''display'''={{{None}}}, '''secure'''={{{False}}}, '''parameters'''={{{None}}}, '''headers'''={{{None}}})::

  Creates the SIPURI object with the specified parameters as attributes.

  Each of these attributes can be accessed and changed on the object once instanced.

  {{{host}}} is the only mandatory attribute.

  [[BR]]''host'':[[BR]]

  The host part of the SIP URI as a string.

  [[BR]]''user'':[[BR]]

  The username part of the SIP URI as a string, or None if not set.

  [[BR]]''port'':[[BR]]

  The port part of the SIP URI as an int, or None or 0 if not set.

  [[BR]]''display'':[[BR]]

  The optional display name of the SIP URI as a string, or None if not set.

  [[BR]]''secure'':[[BR]]

  A boolean indicating whether this is a SIP or SIPS URI, the latter being indicated by a value of {{{True}}}.

  [[BR]]''parameters'':[[BR]]

  The URI parameters. represented by a dictionary.

  [[BR]]''headers'':[[BR]]

  The URI headers, represented by a dictionary.

 '''!__str!__'''(''self'')::

  The special Python method to represent this object as a string, the output is the properly formatted SIP URI.

 '''copy'''(''self'')::

  Returns a copy of the {{{SIPURI}}} object.

=== Credentials ===

This simple object represents authentication credentials for a particular SIP account.

These can be included whenever creating a SIP primitive object that originates SIP requests.

As with the {{{SIPURI}}} object, the attributes of this object are the same as the arguments to the {{{__init__}}} method.

Note that the domain name of the SIP account is not stored on this object.

==== methods ====

 '''!__init!__'''(''self'', '''username''', '''password''')::

  Creates the Credentials object with the specified parameters as attributes.

  Each of these attributes can be accessed and changed on the object once instanced.

  [[BR]]''username'':[[BR]]

  A string representing the username of the account for which these are the credentials.

  [[BR]]''password'':[[BR]]

  The password for this SIP account as a string.

 '''copy'''(''self'')::

  Returns a copy of the {{{Credentials}}} object.

=== Route ===

This class provides a means for the application using the SIP core to set the destination address, port and transport for a particular request, i.e. the outbound proxy.

As it is the application's responsibility to look this up and pass it as an argument for every SIP primitive class it creates.

The contents of the {{{Route}}} object will be placed in the {{{Route}}} header of the request.

As with the {{{SIPURI}}} object, the attributes of this object are the same as the arguments to the {{{__init__}}} method.

==== methods ====

 '''!__init!__'''(''self'', '''address''', '''port'''=5060, '''transport'''={{{None}}})::

  Creates the Route object with the specified parameters as attributes.

  Each of these attributes can be accessed on the object once instanced.

  [[BR]]''address'':[[BR]]

  The IPv4 address that the request in question should be sent to as a string.

  [[BR]]''port'':[[BR]]

  The port to send the requests to, represented as an int.

  [[BR]]''transport'':[[BR]]

  The transport to use, this can be a string of either "udp", "tcp" or "tls" (case insensitive), depending on what transports are enabled on the {{{PJSIPUA}}} object.

 '''copy'''(''self'')::

  Returns a copy of the {{{Route}}} object.

=== Request ===

The {{{sipsimple.core.Request}}} object encapsulates a single SIP request transaction from the client side, which includes sending the request, receiving the response and possibly waiting for the result of the request to expire.

Although this class can be used by the application to construct and send an arbitrary SIP request, most applications will use the classes provided in the {{{sipsimple.primitives}}} module, which are built on top of one or several {{{Request}}} objects and deal with instances of specific SIP methods.

The lifetime of this object is linear and is described by the following diagram:

[[Image(sipsimple-request-lifetime.png, nolink)]]

The bar denotes which state the object is in and at the top are the notifications which may be emitted at certain points in time.

Directly after the object is instantiated, it will be in the {{{INIT}}} state.

The request will be sent over the network once its {{{send()}}} method is called, moving the object into the {{{IN_PROGRESS}}} state.

On each provisional response that is received in reply to this request, the {{{SIPRequestGotProvisionalResponse}}} notification is sent, with data describing the response.

Note that this may not occur at all if not provisional responses are received.

When the {{{send()}}} method has been called and it does not return an exception, the object will send either a {{{SIPRequestDidSucceed}}} or a {{{SIPRequestDidFail}}} notification.

Both of these notifications include data on the response that triggered it.

Note that a SIP response that requests authentication (401 or 407) will be handled internally the first time, if a {{{Credentials}}} object was supplied.

If this is the sort of request that expires (detected by a {{{Expires}}} header in the response or a {{{expires}}} parameter in the {{{Contact}}} header of the response), and the request was successful, the object will go into the {{{EXPIRING}}} state.

A certain amount of time before the result of the request will expire, governed by the {{{expire_warning_time}}} class attribute and the actual returned expiration time, a {{{SIPRequestWillExpire}}} notification will be sent.

This should usually trigger whomever is using this {{{Request}}} object to construct a new {{{Request}}} for a refreshing operation.

When the {{{Request}}} actually expires, or when the {{{EXPIRING}}} state is skipped directly after sending {{{SIPRequestDidSucceed}}} or {{{SIPRequestDidFail}}}, a {{{SIPRequestDidEnd}}} notification will be sent.

==== attributes ====

 '''expire_warning_time''' (class attribute)::

  The {{{SIPRequestWillExpire}}} notification will be sent halfway between the positive response and the actual expiration time, but at least this amount of seconds before.

  The default value is 30 seconds.

 '''state'''::

  Indicates the state the {{{Request}}} object is in, in the form of a string.

  Refer to the diagram above for possible states.

  This attribute is read-only.

 '''method'''::

  The method of the SIP request as a string.

  This attribute is set on instantiation and is read-only.

 '''from_uri'''::

  The SIP URI to put in the {{{From}}} header of the request, in the form of a {{{SIPURI}}} object.

  This attribute is set on instantiation and is read-only.

 '''to_uri'''::

  The SIP URI to put in the {{{To}}} header of the request, in the form of a {{{SIPURI}}} object.

  This attribute is set on instantiation and is read-only.

 '''request_uri'''::

  The SIP URI to put as request URI in the request, in the form of a {{{SIPURI}}} object.

  This attribute is set on instantiation and is read-only.

 '''route'''::

  Where to send the SIP request to, including IP, port and transport, in the form of a {{{SIPURI}}} object.

  This will also be included in the {{{Route}}} header of the request.

  This attribute is set on instantiation and is read-only.

 '''credentials'''::

  The credentials to be used when challenged for authentication, represented by a {{{Credentials}}} object.

  If no credentials were supplied when the object was created this attribute is {{{None}}}.

  This attribute is set on instantiation and is read-only.

 '''contact_uri'''::

  The SIP URI to put in the {{{Contact}}} header of the request, in the form of a {{{SIPURI}}} object.

  If this was not specified, this attribute is {{{None}}}.

  It is set on instantiation and is read-only.

 '''call_id'''::

  The {{{Call-ID}}} to be used for this transaction as a string.

  If no call id was specified on instantiation, this attribute contains the generated id.

  This attribute is set on instantiation and is read-only.

 '''cseq'''::

  The sequence number to use in the request as an int.

  If no sequence number was specified on instantiation, this attribute contains the generated sequence number.

  Note that this number may be increased by one if an authentication challenge is received and a {{{Credentials}}} object is given.

  This attribute is read-only.

 '''extra_headers'''::

  Extra headers to include in the request as a dictionary.

  This attribute is set on instantiation and is read-only.

 '''content_type'''::

  What string to put as content type in the {{{Content-Type}}} headers, if the request contains a body.

  If no body was specified, this attribute is {{{None}}}

  It is set on instantiation and is read-only.

 '''body'''::

  The body of the request as a string.

  If no body was specified, this attribute is {{{None}}}

  It is set on instantiation and is read-only.

 '''expires_in'''::

  This read-only property indicates in how many seconds from now this {{{Request}}} will expire, if it is in the {{{EXPIRING}}} state.

  If this is not the case, this property is 0.

==== methods ====

 '''!__init!__'''(''self'', '''method''', '''from_uri''', '''to_uri''', '''request_uri''', '''route''', '''credentials'''={{{None}}}, '''contact_uri'''={{{None}}}, '''call_id'''={{{None}}}, '''cseq'''={{{None}}}, '''extra_headers'''={{{None}}}, '''content_type'''={{{None}}}, '''body'''={{{None}}})::

  Creates a new {{{Request}}} object in the {{{INIT}}} state.

  The arguments to this method are documented in the attributes section.

 '''send'''(''self'', '''timeout'''={{{None}}})::

   Compose the SIP request and send it to the destination.

   This moves the {{{Request}}} object into the {{{IN_PROGRESS}}} state.

  [[BR]]''timeout'':[[BR]]

  This can be either an int or a float, indicating in how many seconds the request should timeout with an internally generated 408 response.

  This is is {{{None}}}, the internal 408 is only triggered by the internal PJSIP transaction timeout.

  Note that, even if the timeout is specified, the PJSIP timeout is also still valid.

 '''end'''(''self'')::

  Terminate the transaction, whichever state it is in, sending the appropriate notifications.

  Note that calling this method while in the {{{INIT}}} state does nothing.

==== notifications ====

 '''SIPRequestGotProvisionalResponse'''::

  This notification will be sent on every provisional response received in reply to the sent request.

  [[BR]]''timestamp'':[[BR]]

  A {{{datetime.datetime}}} object indicating when the notification was sent.

  [[BR]]''code'':[[BR]]

  The SIP response code of the received provisional response as an int, which will be in the 1xx range.

  [[BR]]''reason'':[[BR]]

  The reason text string included with the SIP response code.

  [[BR]]''headers'':[[BR]]

  The headers included in the provisional response as a dictionary.

  [[BR]]''body'':[[BR]]

  The body of the provisional response as a string, or {{{None}}} if there was no body.

 '''SIPRequestDidSucceed'''::

  This notification will be sent when a positive final response was received in reply to the request.

  [[BR]]''timestamp'':[[BR]]

  A {{{datetime.datetime}}} object indicating when the notification was sent.

  [[BR]]''code'':[[BR]]

  The SIP response code of the received positive final response as an int, which will be in the 2xx range.

  [[BR]]''reason'':[[BR]]

  The reason text string included with the SIP response code.

  [[BR]]''headers'':[[BR]]

  The headers included in the positive final response as a dictionary.

  [[BR]]''body'':[[BR]]

  The body of the positive final response as a string, or {{{None}}} if there was no body.

  [[BR]]''expires'':[[BR]]

  Indicates in how many seconds the {{{Request}}} will expire as an int.

  If it does not expire and the {{{EXPIRING}}} state is skipped, this attribute is 0.

 '''SIPRequestDidFail'''::

  This notification will be sent when a negative final response is received in reply to the request or if an internal error occurs.

  [[BR]]''timestamp'':[[BR]]

  A {{{datetime.datetime}}} object indicating when the notification was sent.

  [[BR]]''code'':[[BR]]

  The SIP response code of the received negative final response as an int.

  This could also be a response code generated by PJSIP internally, or 0 when an internal error occurs.

  [[BR]]''reason'':[[BR]]

  The reason text string included with the SIP response code or error.

  [[BR]]''headers'': (only if a negative final response was received)[[BR]]

  The headers included in the negative final response as a dictionary, if this is what triggered the notification.

  [[BR]]''body'': (only if a negative final response was received)[[BR]]

  The body of the negative final response as a string, or {{{None}}} if there was no body.

  This attribute is absent if no response was received.

 '''SIPRequestWillExpire'''::

  This notification will be sent when a {{{Request}}} in the {{{EXPIRING}}} state will expire soon.

  [[BR]]''timestamp'':[[BR]]

  A {{{datetime.datetime}}} object indicating when the notification was sent.

  [[BR]]''expires'':[[BR]]

  An int indicating in how many seconds from now the {{{Request}}} will actually expire.

 '''SIPRequestDidEnd'''::

  This notification will be sent when a {{{Request}}} object enters the {{{TERMINATED}}} state and can no longer be used.

  [[BR]]''timestamp'':[[BR]]

  A {{{datetime.datetime}}} object indicating when the notification was sent.

=== Message ===

The {{{sipsimple.primitives.Message}}} class is a simple wrapper for the {{{Request}}} class, with the purpose of sending {{{MESSAGE}}} requests, as described in [http://tools.ietf.org/html/rfc3428 RFC 3428].

It is a one-shot object that manages only one {{{Request}}} object.

==== attributes ====

 '''from_uri'''::

  The SIP URI to put in the {{{From}}} header of the {{{MESSAGE}}} request, in the form of a {{{SIPURI}}} object.

  This attribute is set on instantiation and is read-only.

 '''to_uri'''::

  The SIP URI to put in the {{{To}}} header of the {{{MESSAGE}}} request, in the form of a {{{SIPURI}}} object.

  This attribute is set on instantiation and is read-only.

 '''route'''::

  Where to send the {{{MESSAGE}}} request to, including IP, port and transport, in the form of a {{{SIPURI}}} object.

  This will also be included in the {{{Route}}} header of the request.

  This attribute is set on instantiation and is read-only.

 '''content_type'''::

  What string to put as content type in the {{{Content-Type}}} headers.

  It is set on instantiation and is read-only.

 '''body'''::

  The body of the {{{MESSAGE}}} request as a string.

  If no body was specified, this attribute is {{{None}}}

  It is set on instantiation and is read-only.

 '''credentials'''::

  The credentials to be used when challenged for authentication, represented by a {{{Credentials}}} object.

  If no credentials were specified, this attribute is {{{None}}}.

  This attribute is set on instantiation and is read-only.

 '''is_sent'''::

  A boolean read-only property indicating if the {{{MESSAGE}}} request was sent.

 '''in_progress'''::

  A boolean read-only property indicating if the object is waiting for the response from the remote party.

==== methods ====

 '''!__init!__'''(''self'', '''credentials''', '''to_uri''', '''route''', '''content_type''', '''body''')::

  Creates a new {{{Message}}} object with the specified arguments.

  These arguments are documented in the attributes section for this class.

 '''send'''(''self'', '''timeout'''={{{None}}})::

  Send the {{{MESSAGE}}} request to the remote party.

  [[BR]]''timeout'':[[BR]]

  This argument as the same meaning as it does for {{{Request.send()}}}.

 '''end'''(''self'')::

  Stop trying to send the {{{MESSAGE}}} request.

  If it was not sent yet, calling this method does nothing.

==== notifications ====

 '''SIPMessageDidSucceed'''::

  This notification will be sent when the remote party acknowledged the reception of the {{{MESSAGE}}} request.

  It has not data attributes.

 '''SIPMessageDidFail'''::

  This notification will be sent when transmission of the {{{MESSAGE}}} request fails for whatever reason.

  [[BR]]''code'':[[BR]]

  An int indicating the SIP or internal PJSIP code that was given in response to the {{{MESSAGE}}} request.

  This is 0 if the failure is caused by an internal error.

  [[BR]]''reason'':[[BR]]

  A status string describing the failure, either taken from the SIP response or the internal error.

=== Registration ===

The {{{sipsimple.primitives.Registration}}} class wraps a series of {{{Request}}} objects, managing the registration of a particular contact URI at a SIP registrar through the sending of {{{REGISTER}}} requests.

For details, see [http://tools.ietf.org/html/rfc3261 RFC 3261].

This object is designed in such a way that it will not initiate sending a refreshing {{{REGISTER}}} itself, rather it will inform the application that a registration is about to expire.

The application should then perform a DNS lookup to find the relevant SIP registrar and call the {{{register()}}} method on this object.

==== attributes ====

 '''uri''::

  The SIP URI of the account the {{{Registration}}} is for in the form of a {{{SIPURI}}} object.

 '''credentials'''::

  The credentials to be used when challenged for authentication by the registrar, represented by a {{{Credentials}}} object. 

  This attribute is set at instantiation, can be {{{None}}} if it was not specified and can be updated to be used for the next {{{REGISTER}}} request.

  Note that, in contrast to other classes mentioned in this document, the {{{Registration}}} class does not make a copy of the {{{Credentials}}} object on instantiation, but instead retains a reference to it.

 '''duration'''::

  The amount of time in seconds to request the registration for at the registrar.

  This attribute is set at object instantiation and can be updated for subsequent {{{REGISTER}}} requests.

 '''is_registered'''::

  A boolean read-only property indicating if this object is currently registered.

 '''contact_uri'''::

  If the {{{Registration}}} object is registered, this attribute contains the latest contact URI that was sent to the registrar as a {{{SIPURI}}} object.

  Otherwise, this attribute is {{{None}}}

 '''expires_in'''::

  If registered, this read-only property indicates in how many seconds from now this {{{Registration}}} will expire.

  If this is not the case, this property is 0.

==== methods ====

 '''!__init!__'''(''self'', '''uri''', '''credentials'''={{{None}}}, '''duration'''=300)::

  Creates a new {{{Registration}}} object with the specified arguments.

  These arguments are documented in the attributes section for this class.

 '''register'''(''self'', '''contact_uri''', '''route''', '''timeout'''={{{None}}})::

  Calling this method will attempt to send a new {{{REGISTER}}} request to the registrar provided, whatever state the object is in.

  If the object is currently busy sending a {{{REGISTER}}}, this request will be preempted for the new one.

  Once sent, the {{{Registration}}} object will send either a {{{SIPRegistrationDidSucceed}}} or a {{{SIPRegistrationDidFail}}} notification.

  The {{{contact_uri}}} argument is mentioned in the attributes section of this class.

  The {{{route}}} argument specifies the IP address, port and transport of the SIP registrar in the form of a {{{Route}}} object and {{{timeout}}} has the same meaning as it does for {{{Request.send()}}}.

 '''end'''(''self'', '''timeout'''={{{None}}})::

  Calling this method while the object is registered will attempt to send a {{{REGISTER}}} request with the {{{Expires}}} headers set to 0, effectively unregistering the contact URI at the registrar.

  The {{{Route}}} used for this will be the same as the last successfully sent {{{REGISTER}}} request.

  If another {{{REGISTER}}} is currently being sent, it will be preempted.

  When the unregistering {{{REGISTER}}} request is sent, a {{{SIPRegistrationWillEnd}}} notification is sent.

  After this, either a {{{SIPRegistrationDidEnd}}} with the {{{expired}}} data attribute set to {{{False}}} will be sent, indicating a successful unregister, or a {{{SIPRegistrationDidNotEnd}}} notification is send if unregistering fails for some reason.

  Calling this method when the object is not registered will do nothing.

  The {{{timeout}}} argument has the same meaning as for the {{{register()}}} method.

==== notifications ====

 '''SIPRegistrationDidSucceed'''::

  This notification will be sent when the {{{register()}}} method was called and the registration succeeded.

  [[BR]]''code'':[[BR]]

  The SIP response code as received from the registrar as an int.

  [[BR]]''reason'':[[BR]]

  The reason string received from the SIP registrar.

  [[BR]]''route'':[[BR]]

  The {{{Route}}} object passed as an argument to the {{{register()}}} method.

  [[BR]]''contact_uri'':[[BR]]

  The contact URI that was sent to the registrar as a {{{SIPURI}}} object.

  [[BR]]''contact_uri_list'':[[BR]]

  A full list of contact URIs that are registered for this SIP account, including the one used for this registration.

  The format of this data attribute is a list of 2-item tuples.

  The first item is a SIP URI indicating the contact URI, the second item is a dictionary of additional parameters, including the {{{expires}}} parameter.

  [[BR]]''expires_in'':[[BR]]

  The number of seconds before this registration expires

 '''SIPRegistrationDidFail'''::

  This notification will be sent when the {{{register()}}} method was called and the registration failed, for whatever reason.

  [[BR]]''code'':[[BR]]

  The SIP response code as received from the registrar as an int.

  This can also be a PJSIP generated response code, or 0 if the failure was because of an internal error.

  [[BR]]''reason'':[[BR]]

  The reason string received from the SIP registrar or the error string.

  [[BR]]''route'':[[BR]]

  The {{{Route}}} object passed as an argument to the {{{register()}}} method.

 '''SIPRegistrationWillExpire'''::

  This notification will be sent when a registration will expire soon.

  It should be used as an indication to re-perform DNS lookup of the registrar and call the {{{register()}}} method.

  [[BR]]''expires'':[[BR]]

  The number of seconds in which the registration will expire.

 '''SIPRegistrationWillEnd'''::

  Will be sent whenever the {{{end()}}} method was called and an unregistering {{{REGISTER}}} is sent.

 '''SIPRegistrationDidNotEnd'''::

  This notification will be sent when the unregistering {{{REGISTER}}} request failed for some reason.

  [[BR]]''code'':[[BR]]

  The SIP response code as received from the registrar as an int.

  This can also be a PJSIP generated response code, or 0 if the failure was because of an internal error.

  [[BR]]''reason'':[[BR]]

  The reason string received from the SIP registrar or the error string.

 '''SIPRegistrationDidEnd'''::

  This notification will be sent when a {{{Registration}}} has become unregistered.

  [[BR]]''expired'':[[BR]]

  This boolean indicates if the object is unregistered because the registration expired, in which case it will be set to {{{True}}}.

  If this data attribute is {{{False}}}, it means that unregistration was explicitly requested through the {{{end()}}} method.

==== example code ====

For an example on how to use this object, see the Integration section.

=== Publication ===

Publication of SIP events is an Internet standard published at [http://tools.ietf.org/html/rfc3903 RFC 3903]. 

{{{PUBLISH}}} is similar to {{{REGISTER}}} in that it allows a user to create, modify, and remove state in another entity which manages this state on behalf of the user.

A {{{Publication}}} object represents publishing some content for a particular SIP account and a particular event type at the SIP presence agent through a series of {{{PUBLISH}}} request.

This object is similar in behaviour to the {{{Registration}}} object, as it is also based on a sequence of {{{Request}}} objects.

As with this other object, the {{{Publication}}} object will notify the application when a published item is about to expire and it is the applications responsibility to perform a DNS lookup and call the {{{publish()}}} method in order to send the {{{PUBLISH}}} request.

==== attributes ====

 '''uri''::

  The SIP URI of the account the {{{Publication}}} is for in the form of a {{{SIPURI}}} object.

 '''event''::

  The name of the event this object is publishing for the specified SIP URI, as a string.

 '''content_type''::

  The {{{Content-Type}}} of the body that will be in the {{{PUBLISH}}} requests.

  Typically this will remain the same throughout the publication session, but the attribute may be updated by the application if needed.

  Note that this attribute needs to be in the typical MIME type form, containing a "/" character.

 '''credentials'''::

  The credentials to be used when challenged for authentication by the presence agent, represented by a {{{Credentials}}} object. 

  This attribute is set at instantiation, can be {{{None}}} if it was not specified and can be updated to be used for the next {{{PUBLISH}}} request.

  Note that, in contrast to most other classes mentioned in this document, the {{{Publication}}} class does not make a copy of the {{{Credentials}}} object on instantiation, but instead retains a reference to it.

 '''duration'''::

  The amount of time in seconds that the publication should be valid for.

  This attribute is set at object instantiation and can be updated for subsequent {{{PUBLISH}}} requests.

 '''is_published'''::

  A boolean read-only property indicating if this object is currently published.

 '''expires_in'''::

  If published, this read-only property indicates in how many seconds from now this {{{Publication}}} will expire.

  If this is not the case, this property is 0.

==== methods ====

 '''!__init!__'''(''self'', '''uri''', '''event''', '''content_type''', '''credentials'''={{{None}}}, '''duration'''=300)::

  Creates a new {{{Publication}}} object with the specified arguments.

  These arguments are documented in the attributes section for this class.

 '''publish'''(''self'', '''body''', '''route''', '''timeout'''={{{None}}})::

  Send an actual {{{PUBLISH}}} request to the specified presence agent.

  [[BR]]''body'':[[BR]]

  The body to place in the {{{PUBLISH}}} request as a string.

  This body needs to be of the content type specified at object creation.

  For the initial request, a body will need to be specified.

  For subsequent refreshing {{{PUBLISH}}} requests, the body can be {{{None}}} to indicate that the last published body should be refreshed.

  If there was an ETag error with the previous refreshing {{{PUBLISH}}}, calling this method with a body of {{{None}}} will throw a {{{PublicationError}}}.

  [[BR]]''route'':[[BR]]

  The host where the request should be sent to in the form of a {{{Route}}} object.

  [[BR]]''timeout'':[[BR]]

  This can be either an int or a float, indicating in how many seconds the {{{SUBSCRIBE}}} request should timeout with an internally generated 408 response.

  This is is {{{None}}}, the internal 408 is only triggered by the internal PJSIP transaction timeout.

  Note that, even if the timeout is specified, the PJSIP timeout is also still valid.

 '''end'''(''self'', '''timeout'''={{{None}}})::

  End the publication by sending a {{{PUBLISH}}} request with an {{{Expires}}} header of 0.

  If the object is not published, this will result in a {{{PublicationError}}} being thrown.

  [[BR]]''timeout'':[[BR]]

  The meaning of this argument is the same as it is for the {{{publish()}}} method.

==== notifications ====

 '''SIPPublicationDidSucceed'''::

  This notification will be sent when the {{{publish()}}} method was called and the publication succeeded.

  [[BR]]''code'':[[BR]]

  The SIP response code as received from the SIP presence agent as an int.

  [[BR]]''reason'':[[BR]]

  The reason string received from the SIP presence agent.

  [[BR]]''route'':[[BR]]

  The {{{Route}}} object passed as an argument to the {{{publish()}}} method.

  [[BR]]''expires_in'':[[BR]]

  The number of seconds before this publication expires

 '''SIPPublicationDidFail'''::

  This notification will be sent when the {{{publish()}}} method was called and the publication failed, for whatever reason.

  [[BR]]''code'':[[BR]]

  The SIP response code as received from the presence agent as an int.

  This can also be a PJSIP generated response code, or 0 if the failure was because of an internal error.

  [[BR]]''reason'':[[BR]]

  The reason string received from the presence agent or the error string.

  [[BR]]''route'':[[BR]]

  The {{{Route}}} object passed as an argument to the {{{publish()}}} method.

 '''SIPPublicationWillExpire'''::

  This notification will be sent when a publication will expire soon.

  It should be used as an indication to re-perform DNS lookup of the presence agent and call the {{{publish()}}} method.

  [[BR]]''expires'':[[BR]]

  The number of seconds in which the publication will expire.

 '''SIPPublicationWillEnd'''::

  Will be sent whenever the {{{end()}}} method was called and an unpublishing {{{PUBLISH}}} is sent.

 '''SIPPublicationDidNotEnd'''::

  This notification will be sent when the unpublishing {{{PUBLISH}}} request failed for some reason.

  [[BR]]''code'':[[BR]]

  The SIP response code as received from the presence agent as an int.

  This can also be a PJSIP generated response code, or 0 if the failure was because of an internal error.

  [[BR]]''reason'':[[BR]]

  The reason string received from the presence agent or the error string.

 '''SIPPublicationDidEnd'''::

  This notification will be sent when a {{{Publication}}} has become unpublished.

  [[BR]]''expired'':[[BR]]

  This boolean indicates if the object is unpublished because the publication expired, in which case it will be set to {{{True}}}.

  If this data attribute is {{{False}}}, it means that unpublication was explicitly requested through the {{{end()}}} method.

=== Subscription ===

Subscription and notifications for SIP events is an Internet standard published at [http://tools.ietf.org/html/rfc3856 RFC 3856].

This SIP primitive class represents a subscription to a specific event type of a particular SIP URI.

This means that the application should instance this class for each combination of event and SIP URI that it wishes to subscribe to.

The event type and the content types that are acceptable for it need to be registered first, either through the {{{init_options}}} attribute of {{{Engine}}} (before starting it), or by calling the {{{add_event()}}} method of the {{{Engine}}} instance.

Whenever a {{{NOTIFY}}} is received, the application will receive the {{{SIPSubscriptionGotNotify}}} event.

Internally a {{{Subscription}}} object has a state machine, which reflects the state of the subscription.

It is a direct mirror of the state machine of the underlying {{{pjsip_evsub}}} object, whose possible states are at least {{{NULL}}}, {{{SENT}}}, {{{ACCEPTED}}}, {{{PENDING}}}, {{{ACTIVE}}} or {{{TERMINATED}}}.

The last three states are directly copied from the contents of the {{{Subscription-State}}} header of the received {{{NOTIFY}}} request.

Also, the state can be an arbitrary string if the contents of the {{{Subscription-State}}} header are not one of the three above.

The state of the object is presented in the {{{state}}} attribute and changes of the state are indicated by means of the {{{SIPSubscriptionChangedState}}} notification.

This notification is only informational, an application using this object should take actions based on the other notifications sent by this object.

==== attributes ====

 '''state'''::

  Indicates which state the internal state machine is in.

  See the previous section for a list of states the state machine can be in.

 '''from_uri'''::

  The SIP URI to be put in the {{{From}}} header of the {{{SUBSCRIBE}}} requests in the form of a {{{SIPURI}}} object.

  This attribute is set on object instantiation and is read-only.

 '''to_uri'''::

  The SIP URI that is the target for the subscription in the form of a {{{SIPURI}}} object.

  This attribute is set on object instantiation and is read-only.

 '''contact_uri'''::

  The SIP URI to be put in the {{{Contact}}} header of the {{{SUBSCRIBE}}} requests in the form of a {{{SIPURI}}} object.

  This attribute is set on object instantiation and is read-only.

 '''event'''::

  The event package for which the subscription is as a string.

  This attribute is set on object instantiation and is read-only.

 '''route'''::

  The outbound proxy to use in the form of a {{{Route}}} object.

  This attribute is set on object instantiation and is read-only.

 '''credentials'''::

  The SIP credentials needed to authenticate at the SIP proxy in the form of a {{{Credentials}}} object.

  If none was specified when creating the {{{Subscription}}} object, this attribute is {{{None}}}.

  This attribute is set on object instantiation and is read-only.

 '''refresh'''::

  The refresh interval in seconds that was requested on object instantiation as an int.

  This attribute is set on object instantiation and is read-only.

 '''extra_headers'''::

  This contains the dictionary of extra headers that was last passed to a successful call to the {{{subscribe()}}} method.

  If the argument was not provided, this attribute is an empty dictionary.

  This attribute is read-only.

 '''content_type'''::

  This attribute contains the {{{Content-Type}}} of the body that was last passed to a successful call to the {{{subscribe()}}} method.

  If the argument was not provided, this attribute is {{{None}}}.

 '''body'''::

  This attribute contains the {{{body}}} string argument that was last passed to a successful call to the {{{subscribe()}}} method.

  If the argument was not provided, this attribute is {{{None}}}.

==== methods ====

 '''!__init!__'''(''self'', '''from_uri''', '''to_uri''', '''contact_uri, '''event''', '''route''', '''credentials'''={{{None}}}, '''refresh'''=300)::

  Creates a new {{{Subscription}}} object which will be in the {{{NULL}}} state.

  The arguments for this method are documented in the attributes section above.

 '''subscribe'''(''self'', '''extra_headers'''={{{None}}}, '''content_type'''={{{None}}}, '''body'''={{{None}}}, '''timeout'''={{{None}}})::

  Calling this method triggers sending a {{{SUBSCRIBE}}} request to the presence agent.

  The arguments passed will be stored and used for subsequent refreshing {{{SUBSCRIBE}}} requests.

  This method may be used both to send the initial request and to update the arguments while the subscription is ongoing.

  It may not be called when the object is in the {{{TERMINATED}}} state.

  [[BR]]''extra_headers'':[[BR]]

  A dictionary of additional headers to include in the {{{SUBSCRIBE}}} requests.

  [[BR]]''content_type'':[[BR]]

  The {{{Content-Type}}} of the supplied {{{body}}} argument as a string.

  If this argument is supplied, the {{{body}}} argument cannot be {{{None}}}.

  [[BR]]''body'':[[BR]]

  The optional body to include in the {{{SUBSCRIBE}}} request as a string.

  If this argument is supplied, the {{{content_type}}} argument cannot be {{{None}}}.

  [[BR]]''timeout'':[[BR]]

  This can be either an int or a float, indicating in how many seconds the request should timeout with an internally generated 408 response.

  If this is {{{None}}}, the internal 408 is only triggered by the internal PJSIP transaction timeout.

  Note that, even if the timeout is specified, the PJSIP timeout is also still valid.

 '''end'''(''self'', '''timeout'''={{{None}}})::

  This will end the subscription by sending a {{{SUBSCRIBE}}} request with an {{{Expires}}} value of 0.

  If this object is no longer subscribed, this method will return without performing any action.

  This method cannot be called when the object is in the {{{NULL}}} state.

  The {{{timeout}}} argument has the same meaning as it does for the {{{subscribe()}}} method.

==== notifications ====

 '''SIPSubscriptionChangedState'''::

  This notification will be sent every time the internal state machine of a {{{Subscription}}} object changes state.

  [[BR]]''timestamp'':[[BR]]

  A {{{datetime.datetime}}} object indicating when the notification was sent.

  [[BR]]''prev_state'':[[BR]]

  The previous state that the sate machine was in.

  [[BR]]''state'':[[BR]]

  The new state the state machine moved into.

 '''SIPSubscriptionWillStart'''::

  This notification will be emitted when the initial {{{SUBSCRIBE}}} request is sent.

  [[BR]]''timestamp'':[[BR]]

  A {{{datetime.datetime}}} object indicating when the notification was sent.

 '''SIPSubscriptionDidStart'''::

  This notification will be sent when the initial {{{SUBSCRIBE}}} was accepted by the presence agent.

  [[BR]]''timestamp'':[[BR]]

  A {{{datetime.datetime}}} object indicating when the notification was sent.

 '''SIPSubscriptionGotNotify'''::

  This notification will be sent when a {{{NOTIFY}}} is received that corresponds to a particular {{{Subscription}}} object.

  Note that this notification could be sent when a {{{NOTIFY}}} without a body is received.

  [[BR]]''timestamp'':[[BR]]

  A {{{datetime.datetime}}} object indicating when the notification was sent.

  [[BR]]''method'':[[BR]]

  The method of the SIP request as a string.

  This will always be {{{NOTIFY}}}.

  [[BR]]''request_uri'':[[BR]]

  The request URI of the {{{NOTIFY}}} request as a {{{SIPURI}}} object.

  [[BR]]''headers'':[[BR]]

  The headers of the {{{NOTIFY}}} request as a dict.

  Each SIP header is represented in its parsed for as long as PJSIP supports it.

  The format of the parsed value depends on the header.

  [[BR]]''body'':[[BR]]

  The body of the {{{NOTIFY}}} request as a string, or {{{None}}} if no body was included.

  The content type of the body can be learned from the {{{Content-Type}}} header in the headers data attribute.

 '''SIPSubscriptionDidFail'''::

  This notification will be sent whenever there is a failure, such as a rejected initial or refreshing {{{SUBSCRIBE}}}.

  After this notification the {{{Subscription}}} object is in the {{{TERMINATED}}} state and can no longer be used.

  [[BR]]''timestamp'':[[BR]]

  A {{{datetime.datetime}}} object indicating when the notification was sent.

  [[BR]]''code'':[[BR]]

  An integer SIP code from the fatal response that was received from the remote party of generated by PJSIP.

  If the error is internal to the SIP core, this attribute will have a value of 0.

  [[BR]]''reason'':[[BR]]

  An text string describing the failure that occurred.

 '''SIPSubscriptionDidEnd'''::

  This notification will be sent when the subscription ends normally, i.e. the {{{end()}}} method was called and the remote party sent a positive response.

  After this notification the {{{Subscription}}} object is in the {{{TERMINATED}}} state and can no longer be used.

  [[BR]]''timestamp'':[[BR]]

  A {{{datetime.datetime}}} object indicating when the notification was sent.

=== Invitation ===

The {{{Invitation}}} class represents an {{{INVITE}}} session, which governs a complete session of media exchange between two SIP endpoints from start to finish.

It is implemented to be agnostic to the media stream or streams negotiated, which is achieved by using the {{{SDPSession}}} class and its companion classes, which directly represents the parsed SDP.

The {{{Invitation}}} class represents both incoming and outgoing sessions.

The state machine contained in each {{{Invitation}}} object is based on the one used by the underlying PJSIP [http://www.pjsip.org/pjsip/docs/html/group__PJSIP__INV.htm pjsip_inv_session] object.

In order to represent re-{{{INVITE}}}s and user-requested disconnections, three more states have been added to this state machine.

The progression through this state machine is fairly linear and is dependent on whether this is an incoming or an outgoing session.

State changes are triggered either by incoming or by outgoing SIP requests and responses.

The states and the transitions between them are shown in the following diagram:

[[Image(sipsimple-core-invite-state-machine.png, nolink)]]

The state changes of this machine are triggered by the following:

 1. An {{{Invitation}}} object is newly created, either by the application for an outgoing session, or by the core for an incoming session.

 2. The application requested an outgoing session by calling the {{{send_invite()}}} method and and initial {{{INVITE}}} request is sent.

 3. A new incoming session is received by the core.

    The application should look out for state change to this state in order to be notified of new incoming sessions.

 4. A provisional response (1xx) is received from the remove party.

 5. A provisional response (1xx) is sent to the remote party, after the application called the {{{respond_to_invite_provisionally()}}} method.

 6. A positive final response (2xx) is received from the remote party.

 7. A positive final response (2xx) is sent to the remote party, after the application called the {{{accept_invite()}}} method.

 8. A positive final response (2xx) is sent or received, depending on the orientation of the session.

 9. An {{{ACK}}} is sent or received, depending on the orientation of the session.

    If the {{{ACK}}} is sent from the local to the remote party, it is initiated by PJSIP, not by a call from the application.

 10. The local party sent a re-{{{INVITE}}} to the remote party by calling the {{{send_reinvite()}}} method.

 11. The remote party has sent a final response to the re-{{{INVITE}}}.

 12. The remote party has sent a re-{{{INVITE}}}.

 13. The local party has responded to the re-{{{INVITE}}} by calling the {{{respond_to_reinvite()}}} method.

 14. The application requests that the session ends by calling the {{{end()}}} method.

 15. A response is received from the remote party to whichever message was sent by the local party to end the session.

 16. A message is received from the remote party which ends the session.

The application is notified of a state change in either state machine through the {{{SIPInvitationChangedState}}} notification, which has as data the current and previous states.

If the event is triggered by and incoming message, extensive data about that message, such as method/code, headers and body, is also included with the notification.

The application should compare the previous and current states and perform the appropriate action.

An {{{Invitiation}}} object also emits the {{{SIPInvitationGotSDPUpdate}}} notification, which indicates that SDP negotiation between the two parties has been completed.

This will occur (at least) once during the initial session negotiation steps, during re-{{{INVITE}}}s in both directions and whenever an {{{UPDATE}}} request is received.

In the last case, the {{{Invitation}}} object will automatically include the current local SDP in the response.

==== attributes ====

 '''state'''::

  The state the {{{Invitation}}} state machine is currently in.

  See the diagram above for possible states.