SIP SIMPLE Client SDK

= SIP Core API =

[[TOC(SipMiddlewareApi, SipConfigurationAPI, SipCoreApiDocumentation, 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 library resides in the {{{sipsimple.core}}} package. This package aggregates three modules, {{{sipsimple.core._core}}}, {{{sipsimple.core._engine}}} and {{{sipsimple.core._primitives}}}. The former is a Python C extension module which makes wrappers around PJSIP objects available in Python, while the latter two contain SIP core objects written in Python. All core objects should be accessed from the enclosing {{{sipsimple.core}}} module. The following list enumerates the various SIP core objects available:

 * The {{{Engine}}} class which is a Python wrapper around the low-level {{{PJSIPUA}}} class. The latter represents the SIP endpoint and manages the initialization and destruction of all the PJSIP libraries. It is also the central management point to the SIP core. The application should not use the {{{PJSIPUA}}} class directly, but rather through the wrapping {{{Engine}}}, which is a singleton class.

 * Utility classes used throughout the core:

   * {{{frozenlist}}} and {{{frozendict}}}: classes which relate respectively to {{{list}}} and {{{dict}}} similarly to how the standard {{{frozenset}}} relates to {{{set}}}.

 * Helper classes which represent a structured collection of data which is used throughout the core:

   * {{{BaseSIPURI}}}, {{{SIPURI}}} and {{{FrozenSIPURI}}}

   * {{{BaseCredentials}}}, {{{Credentials}}} and {{{FrozenCredentials}}}

 * SDP manipulation classes, which directly wrap the PJSIP structures representing either the parsed or to be generated SDP:

   * {{{BaseSDPSession}}}, {{{SDPSession}}} and {{{FrozenSDPSession}}}

   * {{{BaseSDPMediaStream}}}, {{{SDPMediaStream}}} and {{{FrozenSDPMediaStream}}}

   * {{{BaseSDPConnection}}}, {{{SDPConnection}}} and {{{FrozenSDPConnection}}}

   * {{{SDPAttributeList}}} and {{{FrozenSDPAttributeList}}}

   * {{{BaseSDPAttribute}}}, {{{SDPAttribute}}} and {{{FrozenSDPAttribute}}}

 * Audio handling classes:

   * {{{AudioMixer}}}

   * {{{MixerPort}}}

   * {{{WaveFile}}}

   * {{{RecordingWaveFile}}}

   * {{{ToneGenerator}}}

 * Media transport handling classes, using the functionality built into PJMEDIA:

   * {{{RTPTransport}}}

   * {{{AudioTransport}}}

 * SIP signalling related classes:

   * {{{Request}}} and {{{IncomingRequest}}}: low-level transaction support

   * {{{Invitation}}}: INVITE-dialog support

   * {{{Subscription}}} and {{{IncomingSubscription}}}: SUBSCRIBE-dialog support (including NOTIFY handling within the SUBSCRIBE dialog)

   * {{{Registration}}}: Python object based on {{{Request}}} for REGISTER support

   * {{{Message}}}: Python object based on {{{Request}}} for MESSAGE support

   * {{{Publication}}}: Python object based on {{{Request}}} for PUBLISH support

 * Exceptions:

   * {{{SIPCoreError}}}: generic error used throught the core

   * {{{PJSIPError}}}: subclass of {{{SIPCoreError}}} which offers more information related to errors from PJSIP

   * {{{PJSIPTLSError}}}: subclass of {{{PJSIPError}}} to distinguish between TLS-related errors and the rest

   * {{{SIPCoreInvalidStateError}}}: subclass of {{{SIPCoreError}}} used by objects which are based on a state-machine

Most of the objects cannot be used until the {{{Engine}}} has been started. The following diagram illustrates these classes:

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

Most of the SIP core does not allow duck-typing due to the nature of the integration between it and PJSIP. If these checks had not been employed, any errors could have resulted in a segmentation fault and a core dump. This also explains why several objects have a '''Frozen''' counterpart: the frozen objects are simply immutable versions of their non-frozen variants which make sure that low-level data is kept consistent and cannot be modified from Python. The '''Base''' versions are just base classes for the frozen and non-frozen versions provided mostly for convinience: they cannot be instantiated.

== 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.

  Most of the notifications in the core have 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}}} module.

It can then instantiate 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 instantiate 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.core import ContactHeader, Credentials, Engine, Registration, RouteHeader, SIPURI

e = Engine()

e.start()

identity = FromHeader(SIPURI(user="alice", host="example.com"), display_name="Alice")

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

reg = Registration(identity, credentials=cred)

reg.register(ContactHeader(SIPURI("127.0.0.1",port=12345)), RouteHeader(SIPURI("1.2.3.4", port=5060)))

}}}

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.

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 {{{RouteHeader}}} object, indicating the destination IP address, port and transport the resulting SIP request should be sent to. The [wiki:SipMiddlewareApi#Lookup {{{sipsimple.lookup}}}] module of the middleware can be used to perform DNS lookups according to RFC3263.

== 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]]''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_udp_port()}}} method.

  [[BR]]''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_tcp_port()}}} method.

  [[BR]]''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-pjsip-%pjsip_version-r%pjsip_svn_revision"}}})[[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 {{{add_event()}}} method.

  [[BR]]''incoming_events'': (Default: {{{set()}}})[[BR]]

  A list that specifies for which SIP SIMPLE event packages the application wishes to receive {{{IncomingSubscribe}}} objects.

  When a {{{SUBSCRIBE}}} request is received containing an event name that is not in this list, a 489 "Bad event" response is internally generated.

  When the event is in the list, an {{{IncomingSubscribe}}} object is created based on the request and passed to the application by means of a notification.

  Note that each of the events specified here should also be a key in the {{{events}}} dictionary argument.

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

  [[BR]]''incoming_requests'': (Default: {{{set()}}})[[BR]]

  A set of methods for which {{{IncomingRequest}}} objects are created and sent to the application if they are received.

  Note that receiving requests using the {{{INVITE}}}, {{{SUBSCRIBE}}}, {{{ACK}}} or {{{BYE}}} methods in this way is not allowed.

  Requests using the {{{OPTIONS}}} or {{{MESSAGE}}} method are handled internally, but may be overridden.

 '''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, thse 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 {{{AudioMixer}}} object.

 '''output_devices'''::

  This read-only attribute is a list of strings, 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 {{{AudioMixer}}} object.

 '''sound_devices'''::

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

 '''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.

 '''add_incoming_event'''(''self'', '''event''')::

  Adds a SIP SIMPLE event package to the set of events for which the {{{Engine}}} should create an {{{IncomingSubscribe}}} object when a {{{SUBSCRIBE}}} request is received.

  Note that this event should be known to the {{{Engine}}} by means of the {{{events}}} attribute.

 '''remove_incoming_event'''(''self'', '''event''')::

  Removes an event from the {{{incoming_events}}} attribute.

  Incoming {{{SUBSCRIBE}}} requests with this event package will automatically be replied to with a 489 "Bad Event" response.

 '''add_incoming_request'''(''self'', '''method''')::

  Add a method to the set of methods for which incoming requests should be turned into {{{IncomingRequest}}} objects.

  For the rules on which methods are allowed, see the description of the Engine attribute above.

 '''remove_incoming_request'''(''self'', '''method''')::

  Removes a method from the set of methods that should be received.

 '''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_udp_port'''(''self'', '''value''')::

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

 '''set_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. 

==== 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.

=== SIPURI ===

These are helper objects 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. The FrozenSIPURI object does not allow any of its attributes to be changed after initialization.

==== 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.

  {{{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.

 '''new'''(''cls'', ''sipuri'')::

  Classmethod that returns an instance of the class on which it has been called which is a copy of the {{{sipuri}}} object (which must be either a SIPURI or a FrozenSIPURI).

 '''parse'''(''cls'', ''uri_str'')::

  Classmethod that returns an instance of the class on which it has been called which is represents the parsed version of the URI provided as a string. A SIPCoreError is raised if the string is invalid or if the Engine has not been started yet.

=== Credentials ===

The {{{Credentials}}} and {{{FrozenCredentails}}} simple objects represent authentication credentials for a particular SIP account.

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

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.

 '''new'''(''cls'', ''credentials'')::

  Classmethod that returns an instance of the class on which it has been called which is a copy of the {{{credentials}}} object (which must be either a Credentials or a FrozenCredentials).

=== SDPSession ===

SDP stands for Session Description Protocol. Session Description Protocol (SDP) is a format for describing streaming media initialization parameters in an ASCII string. SDP is intended for describing multimedia communication sessions for the purposes of session announcement, session invitation, and other forms of multimedia session initiation. It is an IETF standard described by [http://tools.ietf.org/html/rfc4566 RFC 4566]. [http://tools.ietf.org/html/rfc3264 RFC 3264] defines an Offer/Answer Model with the Session Description Protocol (SDP), a mechanism by which two entities can make use of the Session Description Protocol (SDP) to arrive at a common view of a multimedia session between them. 

{{{SDPSession}}} and {{{FrozenSDPSession}}} objects directly represent the contents of a SDP body, as carried e.g. in an INVITE request, and is a simple wrapper for the PJSIP [http://www.pjsip.org/pjmedia/docs/html/structpjmedia__sdp__session.htm pjmedia_sdp_session] structure.

They can be passed to those methods of an {{{Invitation}}} object that result in transmission of a message that includes SDP, or are passed to the application through a notification that is triggered by reception of a message that includes SDP.

A {{{(Frozen)SDPSession}}} object may contain {{{(Frozen)SDPMediaStream}}}, {{{(Frozen)SDPConnection}}} and {{{(Frozen)SDPAttribute}}} objects.

It supports comparison to other {{{(Frozen)SDPSession}}} objects using the == and != expressions.

As all the attributes of the {{{(Frozen)SDPSession}}} class are set by attributes of the {{{__init__}}} method, they will be documented along with that method.

==== methods ====

 '''!__init!__'''(''self'', '''address''', '''id'''={{{None}}}, '''version'''={{{None}}}, '''user='''"-", net_type="IN", '''address_type'''="IP4", '''name'''=" ", '''info'''={{{None}}}, '''connection'''={{{None}}}, '''start_time'''=0, '''stop_time'''=0, '''attributes'''={{{None}}}, '''media'''={{{None}}})::

  Creates the SDPSession object with the specified parameters as attributes.

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

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

  The address that is contained in the "o" (origin) line of the SDP as a string.

  [[BR]]''id'':[[BR]]

  The session identifier contained in the "o" (origin) line of the SDP as an int.

  If this is set to {{{None}}} on init, a session identifier will be generated.

  [[BR]]''version'':[[BR]]

  The version identifier contained in the "o" (origin) line of the SDP as an int.

  If this is set to {{{None}}} on init, a version identifier will be generated.

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

  The user name contained in the "o" (origin) line of the SDP as a string.

  [[BR]]''net_type'':[[BR]]

  The network type contained in the "o" (origin) line of the SDP as a string.

  [[BR]]''address_type'':[[BR]]

  The address type contained in the "o" (origin) line of the SDP as a string.

  [[BR]]''name'':[[BR]]

  The contents of the "s" (session name) line of the SDP as a string.

  [[BR]]''info'':[[BR]]

  The contents of the session level "i" (information) line of the SDP as a string.

  If this is {{{None}}} or an empty string, the SDP has no "i" line.

  [[BR]]''connection'':[[BR]]

  The contents of the "c" (connection) line of the SDP as a {{{(Frozen)SDPConnection}}} object.

  If this is set to {{{None}}}, the SDP has no session level "c" line.

  [[BR]]''start_time'':[[BR]]

  The first value of the "t" (time) line of the SDP as an int.

  [[BR]]''stop_time'':[[BR]]

  The second value of the "t" (time) line of the SDP as an int.

  [[BR]]''attributes'':[[BR]]

  The session level "a" lines (attributes) in the SDP represented by a list of {{{(Frozen)SDPAttribute}}} objects.

  [[BR]]''media'':[[BR]]

  The media sections of the SDP represented by a list of {{{(Frozen)SDPMediaStream}}} objects.

 '''new'''(''cls'', ''sdp_session'')::

  Classmethod that returns an instance of the class on which it has been called which is a copy of the {{{sdp_session}}} object (which must be either a SDPSession or a FrozenSDPSession).

==== attributes ====

 '''has_ice_proposal'''::

  This read-only attribute returns {{{True}}} if the SDP contains any attributes which indicate the existence of an ice proposal and {{{False}}} otherwise.

=== SDPMediaStream ===

The {{{SDPMediaStream}}} and {{{FrozenSDPMediaStream}}} objects represent the contents of a media section of a SDP body, i.e. a "m" line and everything under it until the next "m" line.

It is a simple wrapper for the PJSIP [http://www.pjsip.org/pjmedia/docs/html/structpjmedia__sdp__media.htm pjmedia_sdp_media] structure.

One or more {{{(Frozen)SDPMediaStream}}} objects are usually contained in a {{{(Frozen)SDPSession}}} object.

It supports comparison to other {{{(Frozen)SDPMedia}}} objects using the == and != expressions.

As all the attributes of this class are set by attributes of the {{{__init__}}} method, they will be documented along with that method.

==== methods ====

 '''!__init!__'''(''self'', '''media''', '''port''', '''transport''', '''port_count'''=1, '''formats'''={{{None}}}, '''info'''={{{None}}}, '''connection'''={{{None}}}, '''attributes'''={{{None}}})::

  Creates the SDPMedia object with the specified parameters as attributes.

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

  [[BR]]''media'':[[BR]]

  The media type contained in the "m" (media) line as a string.

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

  The transport port contained in the "m" (media) line as an int.

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

  The transport protocol in the "m" (media) line as a string.

  [[BR]]''port_count'':[[BR]]

  The port count in the "m" (media) line as an int.

  If this is set to 1, it is not included in the SDP.

  [[BR]]''formats'':[[BR]]

  The media formats in the "m" (media) line represented by a list of strings.

  [[BR]]''info'':[[BR]]

  The contents of the "i" (information) line of this media section as a string.

  If this is {{{None}}} or an empty string, the media section has no "i" line.

  [[BR]]''connection'':[[BR]]

  The contents of the "c" (connection) line that is somewhere below the "m" line of this section as a {{{(Frozen)SDPConnection}}} object.

  If this is set to {{{None}}}, this media section has no "c" line.

  [[BR]]''attributes'':[[BR]]

  The "a" lines (attributes) that are somewhere below the "m" line of this section represented by a list of {{{(Frozen)SDPAttribute}}} objects.

 '''new'''(''cls'', ''sdp_media'')::

  Classmethod that returns an instance of the class on which it has been called which is a copy of the {{{sdp_media}}} object (which must be either a SDPMediaStream or a FrozenSDPMediaStream).

==== attributes ====

 '''direction'''::

  This is a convenience read-only attribute that goes through all the attributes of the media section and returns the direction, which is either "sendrecv", "sendonly", "recvonly" or "inactive".

  If none of these attributes is present, the default direction is "sendrecv".

=== SDPConnection ===

The {{{SDPConnection}}} and {{{FrozenSDPConnection}}} objects represents the contents of a "c" (connection) line of a SDP body, either at the session level or for an individual media stream.

It is a simple wrapper for the PJSIP [http://www.pjsip.org/pjmedia/docs/html/structpjmedia__sdp__conn.htm pjmedia_sdp_conn] structure.

A {{{(Frozen)SDPConnection}}} object can be contained in a {{{(Frozen)SDPSession}}} object or {{{(Frozen)SDPMediaStream}}} object.

It supports comparison to other {{{(Frozen)SDPConnection}}} objects using the == and != expressions.

As all the attributes of this class are set by attributes of the {{{__init__}}} method, they will be documented along with that method.

==== methods ====

 '''!__init!__'''(''self'', '''address''', '''net_type'''="IN", '''address_type'''="IP4")::

  Creates the SDPConnection object with the specified parameters as attributes.

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

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

  The address part of the connection line as a string.

  [[BR]]''net_type'':[[BR]]

  The network type part of the connection line as a string.

  [[BR]]''address_type'':[[BR]]

  The address type part of the connection line as a string.

 '''new'''(''cls'', ''sdp_connection'')::

  Classmethod that returns an instance of the class on which it has been called which is a copy of the {{{sdp_connection}}} object (which must be either a SDPConnection or a FrozenSDPConnection).

=== SDPAttributeList ===

{{{SDPAttributeList}}} and {{{FrozenSDPAttributeList}}} are subclasses of {{{list}}} and {{{frozenlist}}} respectively and are used as the types of the {{{attributes}}} attributes of {{{(Frozen)SDPSession}}} and {{{(Frozen)SDPMediaStream}}}. They provide convinience methods for accessing SDP attributes. Apart from the standard {{{list}}} and {{{frozenlist}}} methods, they also provide the following:

 '''!__contains!__'''(''self'', ''item'')::

  If ''item'' is an instance of BaseSDPAttribute, the normal {{{(frozen)list}}} method is called. Otherwise, the method returns whether or not ''item'' is in the list of the names of the attributes. This allows tests such as the following to be possible:

  {{{

  'ice-pwd' in sdp_session.attributes

  }}}

 '''getall'''(''self'', ''name'')::

  Returns all the values of the attributes with the given name in a list.

 '''getfirst'''(''self'', ''name'', ''default''={{{None}}})::

  Return the first value of the attribute with the given name, or ''default'' is no such attribute exists.

=== SDPAttribute ===

The {{{SDPAttribute}}} and {{{FrozenSDPAttribute}}} objects represent the contents of a "a" (attribute) line of a SDP body, either at the session level or for an individual media stream.

It is a simple wrapper for the PJSIP [http://www.pjsip.org/pjmedia/docs/html/structpjmedia__sdp__attr.htm pjmedia_sdp_attr] structure.

One or more {{{(Frozen)SDPAttribute}}} objects can be contained in a {{{(Frozen)SDPSession}}} object or {{{(Frozen)SDPMediaStream}}} object.

It supports comparison to other {{{(Frozen)SDPAttribute}}} objects using the == and != expressions.

As all the attributes of this class are set by attributes of the {{{__init__}}} method, they will be documented along with that method.

==== methods ====

 '''!__init!__'''(''self'', '''name''', '''value''')::

  Creates the SDPAttribute object with the specified parameters as attributes.

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

  [[BR]]''name'':[[BR]]

  The name part of the attribute line as a string.

  [[BR]]''value'':[[BR]]

  The value part of the attribute line as a string.

 '''new'''(''cls'', ''sdp_attribute'')::

  Classmethod that returns an instance of the class on which it has been called which is a copy of the {{{sdp_attribute}}} object (which must be either a SDPAttribute or a FrozenSDPAttribute).

=== AudioMixer ===

A {{{AudioMixer}}} manages two audio devices, on for input and one for output, and is able to route audio data 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. Note that the middleware provides an abstracted API which hides the complexity of using the low-level PJSIP concepts. This is mainly provided in the [wiki:SipMiddlewareApi#Audio {{{sipsimple.audio}}}] module, but also consists of other audio-enabled objects (such as the AudioStream).

==== 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.

==== 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.

 '''input_volume'''::

  This writable property indicates the % of volume that is read from the audio input device.

  By default this value is 100.

 '''output_volume'''::

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

  By default this value is 100.

 '''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.

=== MixerPort ===

This a simple object which simply copies all the audio data it gets as input to it output. It's main purpose is that of facilitating the creation the of the middleware {{{AudioBridge}}} object.

==== methods ====

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

  Create a new MixerPort which is associated with the specified AudioMixer.

 '''start'''(''self'')::

  Activate the mixer port. This will reserve a slot on the AudioMixer and allow it to be connected to other slots.

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

  Deactivate the mixer port. This will release the slot previously allocated on the AudioMixer and all connections which it had will be discarded.

==== attributes ====

 '''mixer'''::

  The AudioMixer this MixerPort is associated with

  This attribute is read-only.

 '''is_active'''::

  Whether or not this MixerPort has a slot associated in its AudioMixer.

  This attribute is read-only.

 '''slot'''::

  The slot this MixerPort has reserved on AudioMixer or {{{None}}} if it is not active.

  This attribute is read-only.

=== WaveFile ===

This is a simple object that allows playing back of a {{{.wav}}} file over the PJSIP conference bridge.

Only 16-bit PCM and A-law/U-law formats are supported.

Its main purpose is the playback of ringtones or previously recorded conversations.

This object is associated with a {{{AudioMixer}}} instance and, once the {{{start()}}} method is called, connects to it and sends the sound to all its connections.

Note that the slot of the {{{WaveFile}}} object will not start playing until it is connected to another slot on the AudioMixer.

If the {{{stop()}}} method is called or the end of the {{{.wav}}} file is reached, a {{{WaveFileDidFinishPlaying}}} notification is sent by the object.

After this the {{{start()}}} method may be called again in order to re-use the object.

It is the application's responsibility to keep a reference to the {{{WaveFile}}} object for the duration of playback.

If the reference count of the object reaches 0, playback will be stopped automatically.

In this case no notification will be sent.

==== methods ====

 '''!__init!__'''(''self'', '''mixer''', '''filename''')::

  Creates a new {{{WaveFile}}} object.

  [[BR]]''mixer'':[[BR]]

  The {{{AudioMixer}}} object that this object is to be connected to.

  [[BR]]''filename'':[[BR]]

  The name of the {{{.wav}}} file to be played back as a string.

  This should include the full path to the file.

 '''start'''(''self'')::

  Start playback of the {{{.wav}}} file.

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

  Stop playback of the file.

==== attributes ====

 '''mixer'''::

  The {{{AudioMixer}}} this object is associated with.

  This attribute is read-only.

 '''filename'''::

  The name of the {{{.wav}}} file, as specified when the object was created.

  This attribute is read-only.

 '''slot'''::

  A read-only property indicating the slot number at which this object is attached to the associated AudioMixer.

  If the {{{WaveFile}}} is not active, this attribute will be {{{None}}}.

 '''volume'''::

  A writable property indicating the % of volume at which this object contributes audio to the AudioMixer.

  By default this is set to 100.

 '''is_active'''::

  A boolean read-only property that indicates if the file is currently being played.

==== notifications ====

 '''WaveFileDidFinishPlaying'''::

  This notification will be sent whenever playing of the {{{.wav}}} has stopped.

  After sending this event, the playback may be re-started.

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

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

=== RecordingWaveFile ===

This is a simple object that allows recording audio to a PCM {{{.wav}}} file.

This object is associated with a {{{AudioMixer}}} instance and, once the {{{start()}}} method is called, crecords sound from its connections.

Note that the {{{RecordingWaveFile}}} will not record anything if it does not have any connections.

Recording to the file can be stopped either by calling the {{{stop()}}} method or by removing all references to the object.

Once the {{{stop()}}} method has been called, the {{{start()}}} method may not be called again.

It is the application's responsibility to keep a reference to the {{{RecordingWaveFile}}} object for the duration of the recording, it will be stopped automatically when the reference count reaches 0.

==== methods ====

 '''!__init!__'''(''self'', '''mixer''', '''filename''')::

  Creates a new {{{RecordingWaveFile}}} object.

  [[BR]]''mixer'':[[BR]]

  The {{{AudioMixer}}} object that this object is to be associated with.

  [[BR]]''filename'':[[BR]]

  The name of the {{{.wav}}} file to record to as a string.

  This should include the full path to the file.

 '''start'''(''self'')::

  Start recording the sound to the {{{.wav}}} file.

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

  Stop recording to the file.

==== attributes ====

 '''mixer'''::

  The {{{AudioMixer}}} this object is associated with.

  This attribute is read-only.

 '''filename'''::

  The name of the {{{.wav}}} file, as specified when the object was created.

  This attribute is read-only.

 '''slot'''::

  A read-only property indicating the slot number at which this object is attached to the associated AudioMixer.

  If the {{{RecordingWaveFile}}} is not active, this attribute will be {{{None}}}.

 '''is_active'''::

  A boolean read-only attribute that indicates if the file is currently being written to.

=== ToneGenerator ===

A {{{ToneGenerator}}} can generate a series of dual frequency tones and has a shortcut method for generating valid DTMF tones.

Each instance of this object is associated with a {{{AudioMixer}}} object, which it will connect to once started.

The tones will be sent to the slots on the AudioMixer its slot is connected to.

Once started, a {{{ToneGenerator}}} can be stopped by calling the {{{stop()}}} method and is automatically destroyed when the reference count reaches 0.

> Note: this object has threading issues when the application uses multiple AudioMixers. It should not be used.

==== methods ====

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

  Creates a new {{{ToneGenerator}}} object.

  [[BR]]''mixer'':[[BR]]

  The {{{AudioMixer}}} object that this object is to be connected to.

 '''start'''(''self'')::

  Start the tone generator and connect it to its associated {{{AudioMixer}}}.

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

  Stop the tone generator and remove it from the conference bridge.

 '''play_tones(''self'', '''tones''')::

  Play a sequence of single or dual frequency tones over the audio device.

  [[BR]]''tones'':[[BR]]

  This should be a list of 3-item tuples, in the form of {{{[(<freq1>, <freq2>, <duration>), ...]}}}, with Hz as unit for the frequencies and ms as unit for the duration.

  If {{{freq2}}} is 0, this indicates that only {{{freq1}}} should be used for the tone.

  If {{{freq1}}} is 0, this indicates a pause when no tone should be played for the set duration.

 '''play_dtmf(''self'', '''digit''')::

  Play a single DTMF digit.

  [[BR]]''digit'':[[BR]]

  A string of length 1 containing a valid DTMF digit, i.e. 0 through 9, #, * or A through D.

==== attributes ====

 '''mixer'''::

  The {{{AudioMixer}}} this object is associated with.

  This attribute is read-only.

 '''slot'''::

  A read-only property indicating the slot number at which this object is attached to the associated AudioMixer.

  If the {{{ToneGenerator}}} has not been started, this attribute will be {{{None}}}.

 '''volume'''::

  A writable property indicating the % of volume at which this object contributes audio.

  By default this is set to 100.

 '''is_active'''::

  A boolean read-only property that indicates if the object has been started.

 '''is_busy'''::

  A boolean read-only property indicating if the {{{ToneGenerator}}} is busy playing tones.

==== notifications ====

 '''ToneGeneratorDidFinishPlaying'''::

  This notification will be sent whenever playing of the queued tones has finished.

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

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

=== RTPTransport ===

This object represents a transport for RTP media, the basis of which is a pair of UDP sockets, one for RTP and one for RTCP.

Internally it wraps a [http://www.pjsip.org/pjmedia/docs/html/group__PJMEDIA__TRANSPORT.htm pjmedia_transport] object.

Initially this object will only be used by the {{{AudioTransport}}} object, but in the future it can also be used for video and [wiki:RTTProposal Real-Time Text].

For this reason the {{{AudioTransport}}} and {{{RTPTransport}}} are two distinct objects.

The {{{RTPTransport}}} object also allows support for ICE and SRTP functionality from PJSIP.

Because these features are related to both the UDP transport and the SDP formatting, the SDP carried in SIP signaling message will need to "pass through" this object during the SDP negotiation.

The code using this object, which in most cases will be the {{{AudioTransport}}} object, will need to call certain methods on the object at appropriate times.

This process of SDP negotiation is represented by the internal state machine of the object, as shown in the following diagram:

> The Real-time Transport Protocol (or RTP) defines a standardized packet format for delivering audio and video over the Internet.

> It was developed by the Audio-Video Transport Working Group of the IETF and published in [http://tools.ietf.org/html/rfc3550 RFC 3550].

> RTP is used in streaming media systems (together with the RTSP) as well as in videoconferencing and push to talk systems.

> For these it carries media streams controlled by Session Initiation Protocol (SIP) signaling protocols, making it the technical foundation of the Voice over IP industry.

[[Image(sipsimple-rtp-transport-state-machine.png, nolink)]]

State changes are triggered by the following events:

 1. The application calls the {{{set_INIT()}}} method after object creation and ICE+STUN is not used.

 2. The application calls the {{{set_INIT()}}} method after object creation and ICE+STUN is used.

 3. A successful STUN response is received from the STUN server.

 4. The {{{set_LOCAL()}}} method is called.

 5. The {{{set_ESTABLISHED()}}} method is called.

 6. The {{{set_INIT()}}} method is called while the object is in the {{{LOCAL}}} or {{{ESTABLISHED}}} state.

 7. A method is called on the application, but in the meantime the {{{Engine}}} has stopped.

    The object can no longer be used.

 8. There was an error in getting the STUN candidates from the STUN server.

> It would make sense to be able to use the object even if the STUN request fails (and have ICE not include a STUN candidate), but for some reason the pjmedia_transport is unusable once STUN negotiation has failed.

> This means that the RTPTransport object is also unusable once it has reached the STUN_FAILED state.

> A workaround would be destroy the RTPTransport object and create a new one that uses ICE without STUN.

These states allow for two SDP negotiation scenarios to occur, represented by two paths that can be followed through the state machine.

In this example we will assume that ICE with STUN is not used, as it is independent of the SDP negotiation procedure.

 * The first scenario is where the local party generates the SDP offer.

   For a stream that it wishes to include in this SDP offer, it instantiates a {{{RTPTransport}}} object.

   After instantiation the object is initialized by calling the {{{set_INIT()}}} method and the local RTP address and port can be fetched from it using the {{{local_rtp_address}}} and {{{local_rtp_port}}} attributes respectively, which can be used to generate the local SDP in the form of a {{{SDPSession}}} object.

   This local SDP then needs to be passed to the {{{set_LOCAL()}}} method, which moves the state machine into the {{{LOCAL}}} state (note that it needs the full object, not just the relevant {{{SDPMediaStream}}} object).

   Depending on the options used for the {{{RTPTransport}}} instantiation (such as ICE and SRTP), this may change the {{{SDPSession}}} object.

   This (possibly changed) {{{SDPSession}}} object then needs to be passed to the {{{Invitation}}} object.

   After SDP negotiation is completed, the application needs to pass both the local and remote SDP, in the form of {{{(Frozen)SDPSession}}} objects, to the {{{RTPTransport}}} object using the {{{set_ESTABLISHED()}}} method, moving the state machine into the {{{ESTABLISHED}}} state.

   This will not change either of the {{{(Frozen)SDPSession}}} objects (which is why they can also be frozen).

 * The second scenario is where the local party is offered a media stream in SDP and wants to accept it.

   In this case a {{{RTPTransport}}} is also instantiated and initialized using the {{{set_INIT()}}} method, and the application can generate the local SDP in response to the remote SDP, using the {{{local_rtp_address}}} and {{{local_rtp_port}}} attributes.

   Directly after this it should pass the generated local SDP and received remote SDP, in the form of {{{SDPSession}}} objects, to the {{{set_ESTABLISHED()}}} method.

   In this case the local SDP object may be changed, after which it can be passed to the {{{Invitation}}} object.

Whenever the {{{RTPTransport}}} object is in the {{{LOCAL}}} or {{{ESTABLISHED}}} states, it may be reset to the {{{INIT}}} state to facilitate re-use of the existing transport and its features.

Before doing this however, the internal transport object must no longer be in use.

==== methods ====

 '''!__init!__'''(''self'', '''local_rtp_address'''={{{None}}}, '''use_srtp'''={{{False}}}, '''srtp_forced'''={{{False}}}, '''use_ice'''={{{False}}}, '''ice_stun_address'''={{{None}}}, '''ice_stun_port'''=3478)::

  Creates a new {{{RTPTransport}}} object and opens the RTP and RTCP UDP sockets.

  If additional features are requested, they will be initialized.

  After object instantiation, it is either in the {{{INIT}}} or the {{{WAIT_STUN}}} state, depending on the values of the {{{use_ice}}} and {{{ice_stun_address}}} arguments.

  [[BR]]''local_rtp_address'':[[BR]]

  Optionally contains the local IPv4 address to listen on.

  If this is not specified, PJSIP will listen on all network interfaces.

  [[BR]]''use_srtp'':[[BR]]

  A boolean indicating if SRTP should be used.

  If this is set to {{{True}}}, SRTP information will be added to the SDP when it passes this object.

  [[BR]]''srtp_forced'':[[BR]]

  A boolean indicating if use of SRTP is set to mandatory in the SDP.

  If this is set to {{{True}}} and the remote party does not support SRTP, the SDP negotiation for this stream will fail.

  This argument is relevant only if {{{use_srtp}}} is set to {{{True}}}.

  [[BR]]''use_ice'':[[BR]]

  A boolean indicating if ICE should be used.

  If this is set to {{{True}}}, ICE candidates will be added to the SDP when it passes this object.

  [[BR]]''ice_stun_address'':[[BR]]

  A string indicating the address (IP address or hostname) of the STUN server that should be used to add a STUN candidate to the ICE candidates.

  If this is set to {{{None}}} no STUN candidate will be added, otherwise the object will be put into the {{{WAIT_STUN}}} state until a reply, either positive or negative, is received from the specified STUN server.

  When this happens a {{{RTPTransportGotSTUNResponse}}} notification is sent.

  This argument is relevant only if {{{use_ice}}} is set to {{{True}}}.

  [[BR]]''ice_stun_address'':[[BR]]

  An int indicating the UDP port of the STUN server that should be used to add a STUN candidate to the ICE candidates.

  This argument is relevant only if {{{use_ice}}} is set to {{{True}}} and {{{ice_stun_address}}} is not {{{None}}}.

 '''set_INIT'''(''self'')::

  This moves the internal state machine into the {{{INIT}}} state.

  If the state machine is in the {{{LOCAL}}} or {{{ESTABLISHED}}} states, this effectively resets the {{{RTPTransport}}} object for re-use.

 '''set_LOCAL'''(''self'', '''local_sdp''', '''sdp_index''')::

  This moves the the internal state machine into the {{{LOCAL}}} state.

  [[BR]]''local_sdp'':[[BR]]

  The local SDP to be proposed in the form of a {{{SDPSession}}} object.

  Note that this object may be modified by this method.

  [[BR]]''sdp_index'':[[BR]]

  The index in the SDP for the media stream for which this object was created.

 '''set_ESTABLISHED'''(''self'', '''local_sdp''', '''remote_sdp''', '''sdp_index''')::

  This moves the the internal state machine into the {{{ESTABLISHED}}} state.

  [[BR]]''local_sdp'':[[BR]]

  The local SDP to be proposed in the form of a {{{SDPSession}}} object.

  Note that this object may be modified by this method, but only when moving from the {{{LOCAL}}} to the {{{ESTABLISHED}}} state.

  [[BR]]''remote_sdp'':[[BR]]

  The remote SDP that was received in in the form of a {{{SDPSession}}} object.

  [[BR]]''sdp_index'':[[BR]]

  The index in the SDP for the media stream for which this object was created.

==== 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.

  This attribute is read-only.

 '''local_rtp_address'''::

  The local IPv4 address of the interface the {{{RTPTransport}}} object is listening on and the address that should be included in the SDP.

  If no address was specified during object instantiation, PJSIP will take guess out of the IP addresses of all interfaces.

  This attribute is read-only and will be {{{None}}} if PJSIP is not listening on the transport.

 '''local_rtp_port'''::

  The UDP port PJSIP is listening on for RTP traffic.

  RTCP traffic will always be this port plus one.

  This attribute is read-only and will be {{{None}}} if PJSIP is not listening on the transport.

 '''remote_rtp_address_sdp'''::

  The remote IP address that was seen in the SDP.

  This attribute is read-only and will be {{{None}}} unless the object is in the {{{ESTABLISHED}}} state.

 '''remote_rtp_port_sdp'''::

  The remote UDP port for RTP that was seen in the SDP.

  This attribute is read-only and will be {{{None}}} unless the object is in the {{{ESTABLISHED}}} state.

 '''remote_rtp_address_ice'''::

  The remote IP address that was selected by the ICE negotation.

  This attribute is read-only and will be {{{None}}} until the ICE negotation succeeds.

 '''remote_rtp_port_ice'''::

  The remote port that was selected by the ICE negotation.

  This attribute is read-only and will be {{{None}}} until the ICE negotation succeeds.

 '''remote_rtp_address_received'''::

  The remote IP address from which RTP data was received.

  This attribute is read-only and will be {{{None}}} unless RTP was actually received.

 '''remote_rtp_port_received'''::

  The remote UDP port from which RTP data was received.

  This attribute is read-only and will be {{{None}}} unless RTP was actually received.

 '''use_srtp'''::

  A boolean indicating if the use of SRTP was requested when the object was instantiated.

  This attribute is read-only.

 '''force_srtp'''::

  A boolean indicating if SRTP being mandatory for this transport if it is enabled was requested when the object was instantiated.

  This attribute is read-only.

 '''srtp_active'''::

  A boolean indicating if SRTP encryption and decryption is running.

  Querying this attribute only makes sense once the object is in the {{{ESTABLISHED}}} state and use of SRTP was requested.

  This attribute is read-only.

 '''use_ice'''::

  A boolean indicating if the use of ICE was requested when the object was instantiated.

  This attribute is read-only.

 '''ice_active''::

  A boolean indicating if ICE is being used.

  This attribute is read-only.

 '''ice_stun_address'''::

  A string indicating the IP address of the STUN server that was requested to be used.

  This attribute is read-only.

 '''ice_stun_port'''::

  A string indicating the UDP port of the STUN server that was requested to be used.

  This attribute is read-only.

 '''local_rtp_candidate_type'''::

  Returns the ICE candidate type which has been selected for the local endpoint.

 '''remote_rtp_candidate_type'''::

  Returns the ICE candidate type which has been selected for the remote endpoint.

==== notifications ====

 '''RTPTransportDidInitialize'''::

  This notification is sent when a {{{RTPTransport}}} object has successfully initialized.

  If STUN+ICE is not requested, this is sent immediately on {{{set_INIT()}}}, otherwise it is sent after the STUN query has succeeded.

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

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

 '''RTPTransportDidFail'''::

  This notification is sent by a {{{RTPTransport}}} object that fails to retrieve ICE candidates from the STUN server after {{{set_INIT()}}} is called.

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

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

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

  A string describing the failure reason.

 '''RTPTransportICENegotiationStateDidChange'''::

  This notification is sent to indicate the progress of the ICE negotiation.

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

  A string describing the current ICE negotiation state.

 '''RTPTransportICENegotiationDidFail'''::

  This notification is sent when the ICE negotiation fails.

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

  A string describing the failure reason of ICE negotation.

 '''RTPTransportICENegotiationDidSucceed'''::

  This notification is sent when the ICE negotation succeeds.

  [[BR]]''chosen_local_candidates'' and ''chosen_remote_candidates'':[[BR]]

  Dictionaries with the following keys:

   * rtp_cand_type: the type of the RTP candidate

   * rtp_cand_ip: the IP address of the RTP candidate

   * rtcp_cand_type: the type of the RTCP candidate

   * rtcp_cand_ip: the IP address of teh RTCP candidate

  [[BR]]''duration'':[[BR]]

  The amount of time the ICE negotiation took.

  [[BR]]''local_candidates'' and ''remote_candidates'':[[BR]]

  Lists of tuples with the following elements:

   * Item ID

   * Component ID

   * Address

   * Component Type

  [[BR]]''connectivity_checks_results'':[[BR]]

  A list of tuples with the following elements:

   * Item ID

   * Component ID

   * Source

   * Destination

   * Nomination

   * State

=== AudioTransport ===

This object represent an audio stream as it is transported over the network.

It contains an instance of {{{RTPTransport}}} and wraps a [http://www.pjsip.org/pjmedia/docs/html/group__PJMED__STRM.htm pjmedia_stream] object, which in turn manages the RTP encapsulation, RTCP session, audio codec and adaptive jitter buffer.

It also generates a {{{SDPMediaStream}}} object to be included in the local SDP.

The {{{AudioTransport}}} is an object that, once started, is connected to a {{{AudioMixer}}} instance, and both produces and consumes sound.

Like the {{{RTPTransport}}} object there are two usage scenarios.

 * In the first scenario, only the {{{RTPTransport}}} instance to be used is passed to the AudioTransport object.

   The application can then generate the {{{SDPMediaStream}}} object by calling the {{{get_local_media()}}} method and should include it in the SDP offer.

   Once the remote SDP is received, it should be set along with the complete local SDP by calling the {{{start()}}} method, which will start the audio stream.

   The stream can then be connected to the conference bridge.

 * In the other scenario the remote SDP is already known because it was received in an SDP offer and can be passed directly on object instantiation.

   The local {{{SDPMediaStream}}} object can again be generated by calling the {{{get_local_media()}}} method and is to be included in the SDP answer.

   The audio stream is started directly when the object is created.

Unlike the {{{RTPTransport}}} object, this object cannot be reused.

==== methods ====

 '''!__init!__'''(''self'', '''mixer''', '''transport''', '''remote_sdp'''={{{None}}}, '''sdp_index'''=0, '''enable_silence_detection'''=True, '''codecs'''={{{None}}})::

  Creates a new {{{AudioTransport}}} object and start the underlying stream if the remote SDP is already known.

  [[BR]]''mixer'':[[BR]]

  The {{{AudioMixer}}} object that this object is to be connected to.

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

  The transport to use in the form of a {{{RTPTransport}}} object.

  [[BR]]''remote_sdp'':[[BR]]

  The remote SDP that was received in the form of a {{{SDPSession}}} object.

  [[BR]]''sdp_index'':[[BR]]

  The index within the SDP of the audio stream that should be created.

  [[BR]]''enable_silence_detection''[[BR]]

  Boolean that indicates if silence detection should be used for this audio stream.

  When enabled, this {{{AudioTransport}}} object will stop sending audio to the remote party if the input volume is below a certain threshold.

  [[BR]]''codecs''[[BR]]

  A list of strings indicating the codecs that should be proposed in the SDP of this {{{AudioTransport}}}, in order of preference.

  This overrides the global codecs list set on the {{{Engine}}}.

  The values of this list are case insensitive.

 '''get_local_media'''(''self'', '''is_offer''', '''direction'''="sendrecv")::

  Generates a {{{SDPMediaStream}}} object which describes the audio stream.

  This object should be included in a {{{SDPSession}}} object that gets passed to the {{{Invitation}}} object.

  This method should also be used to obtain the SDP to include in re-INVITEs and replies to re-INVITEs.

  [[BR]]''is_offer'':[[BR]]

  A boolean indicating if the SDP requested is to be included in an offer.

  If this is {{{False}}} it is to be included in an answer.

  [[BR]]''direction'':[[BR]]

  The direction attribute to put in the SDP.

 '''start'''(''self'', '''local_sdp''', '''remote_sdp''', '''sdp_index''', '''no_media_timeout'''=10, '''media_check_interval'''=30)::

  This method should only be called once, when the application has previously sent an SDP offer and the answer has been received.

  [[BR]]''local_sdp'':[[BR]]

  The full local SDP that was included in the SDP negotiation in the form of a {{{SDPSession}}} object.

  [[BR]]''remote_sdp'':[[BR]]

  The remote SDP that was received in the form of a {{{SDPSession}}} object.

  [[BR]]''sdp_index'':[[BR]]

  The index within the SDP of the audio stream.

  [[BR]]''no_media_timeout'':[[BR]]

  This argument indicates after how many seconds after starting the {{{AudioTransport}}} the {{{RTPAudioTransportDidNotGetRTP}}} notification should be sent, if no RTP has been received at all.

  Setting this to 0 disables this an all subsequent RTP checks.

  [[BR]]''media_check_interval'':[[BR]]

  This indicates the interval at which the RTP stream should be checked, after it has initially received RTP at after {{{no_media_timeout}}} seconds.

  It means that if between two of these interval checks no RTP has been received, a {{{RTPAudioTransportDidNotGetRTP}}} notification will be sent.

  Setting this to 0 will disable checking the RTP at intervals.

  The initial check may still be performed if its timeout is non-zero.

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

  This method stops and destroys the audio stream encapsulated by this object.

  After this it can no longer be used and should be deleted, while the {{{RTPTransport}}} object used by it can be re-used for something else.

  This method will be called automatically when the object is deleted after it was started, but this should not be relied on because of possible reference counting issues.

 '''send_dtmf'''(''self'', '''digit''')::

  For a negotiated audio transport this sends one DTMF digit to the other party