SipCoreApiDocumentation

Version 73 (Ruud Klaver, 07/02/2009 02:45 pm)

1 12 Adrian Georgescu
= SIP core API =
2 1 Adrian Georgescu
3 28 Adrian Georgescu
[[TOC(Sip*, depth=3)]]
4 5 Adrian Georgescu
5 1 Adrian Georgescu
== Introduction ==
6 1 Adrian Georgescu
7 13 Adrian Georgescu
This chapter describes the internal architecture and API of the SIP core of the {{{sipsimple}}} library.
8 71 Adrian Georgescu
{{{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.
9 1 Adrian Georgescu
10 1 Adrian Georgescu
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,
11 1 Adrian Georgescu
modify and terminate multimedia sessions such as Internet telephony calls
12 1 Adrian Georgescu
(VoIP). Media can be added to (and removed from) an existing session.
13 1 Adrian Georgescu
14 1 Adrian Georgescu
SIP transparently supports name mapping and redirection services, which
15 1 Adrian Georgescu
supports personal mobility, users can maintain a single externally visible
16 1 Adrian Georgescu
address identifier, which can be in the form of a standard email address or
17 1 Adrian Georgescu
E.164 telephone number regardless of their physical network location.
18 1 Adrian Georgescu
19 1 Adrian Georgescu
SIP allows the endpoints to negotiate and combine any type of session they
20 1 Adrian Georgescu
mutually understand like video, instant messaging (IM), file transfer,
21 1 Adrian Georgescu
desktop sharing and provides a generic event notification system with
22 1 Adrian Georgescu
real-time publications and subscriptions about state changes that can be
23 1 Adrian Georgescu
used for asynchronous services like presence, message waiting indicator and
24 1 Adrian Georgescu
busy line appearance.
25 1 Adrian Georgescu
26 1 Adrian Georgescu
For a comprehensive overview of SIP related protocols and use cases visit http://www.tech-invite.com
27 1 Adrian Georgescu
28 30 Adrian Georgescu
== PJSIP library ==
29 1 Adrian Georgescu
30 1 Adrian Georgescu
{{{sipsimple}}} builds on PJSIP [http://www.pjsip.org], a set of static libraries, written in C, which provide SIP signaling and media capabilities.
31 1 Adrian Georgescu
PJSIP is considered to be the most mature and advanced open source SIP stack available.
32 1 Adrian Georgescu
The following diagram, taken from the PJSIP documentation, illustrates the library stack of PJSIP:
33 1 Adrian Georgescu
34 1 Adrian Georgescu
[[Image(http://www.pjsip.org/images/diagram.jpg, nolink)]]
35 1 Adrian Georgescu
36 1 Adrian Georgescu
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.
37 71 Adrian Georgescu
The latter also includes an abstraction layer for the sound-card.
38 1 Adrian Georgescu
Both of these stracks are integrated in the high level library, called PJSUA.
39 1 Adrian Georgescu
40 1 Adrian Georgescu
PJSIP itself provides a high-level [http://www.pjsip.org/python/pjsua.htm Python wrapper for PJSUA].
41 1 Adrian Georgescu
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.
42 1 Adrian Georgescu
The main reasons for this are the following:
43 1 Adrian Georgescu
 * 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.
44 1 Adrian Georgescu
 * 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.
45 1 Adrian Georgescu
 * 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.
46 1 Adrian Georgescu
47 1 Adrian Georgescu
PJSIP itself is by nature asynchronous.
48 1 Adrian Georgescu
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.
49 1 Adrian Georgescu
Whenever the application performs some action through a function, this function will return immediately.
50 1 Adrian Georgescu
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.
51 1 Adrian Georgescu
52 1 Adrian Georgescu
> NOTE: Currently the core starts the media handling as a separate C thread to avoid lag caused by the GIL.
53 71 Adrian Georgescu
> The sound-card also has its own C thread.
54 1 Adrian Georgescu
55 1 Adrian Georgescu
== Architecture ==
56 1 Adrian Georgescu
57 1 Adrian Georgescu
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]).
58 1 Adrian Georgescu
It allows a Python-like file with some added C manipulation statements to be compiled to C.
59 1 Adrian Georgescu
This in turn compiles to a Python C extension module, which links with the PJSIP static libraries.
60 1 Adrian Georgescu
61 1 Adrian Georgescu
The SIP core part of the {{{sipsimple}}} Python package is subdivided into three modules:
62 1 Adrian Georgescu
 '''sipsimple.engine'''::
63 1 Adrian Georgescu
  Python module that contains the {{{Engine}}} singleton class, which manages the thread that constantly polls the PJSIP library, i.e. the PJSIP worker thread.
64 1 Adrian Georgescu
  For the applications that use the core of {{{sipsimple}}}, the {{{Engine}}} object forms the main entry point.
65 1 Adrian Georgescu
 '''sipsimple.core'''::
66 1 Adrian Georgescu
  This is the Python C extension module ultimately compiled from the Cython file and PJSIP static libraries.
67 1 Adrian Georgescu
  It contains these types of classes:
68 1 Adrian Georgescu
   * The {{{PJSIPUA}}} class, which can only be instanced once, and is this case is only instanced once by the {{{Engine}}} object.
69 1 Adrian Georgescu
     In this way the {{{Engine}}} singleton class acts as a wrapper to the one {{{PJSIPUA}}} instance.
70 1 Adrian Georgescu
     The {{{PJSIPUA}}} class represents the SIP endpoint and manages the initialization and destruction of all the PJSIP libraries.
71 1 Adrian Georgescu
     It also provides a number of methods.
72 1 Adrian Georgescu
     The application however should never call these methods directly on the {{{PJSIPUA}}} object, rather it should call them on the {{{Engine}}} wrapper object.
73 1 Adrian Georgescu
     This object handles everything that for one reason or another cannot or should not be handled from Cython.
74 71 Adrian Georgescu
   * The classes that represent the main SIP primitives to be used by the application, or in the case of {{{Request}}} a generic SIP transaction.
75 1 Adrian Georgescu
     The application can instantiate these classes once the {{{Engine}}} class has been instantiated and the PJSIP worker thread has been started.
76 1 Adrian Georgescu
     All of these classes represent a state machine.
77 42 Ruud Klaver
     * {{{Request}}}
78 1 Adrian Georgescu
     * {{{Subscription}}}
79 1 Adrian Georgescu
     * {{{Invitation}}}
80 1 Adrian Georgescu
   * 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.
81 1 Adrian Georgescu
     * {{{SIPURI}}}
82 1 Adrian Georgescu
     * {{{Credentials}}}
83 1 Adrian Georgescu
     * {{{Route}}}
84 1 Adrian Georgescu
   * A number of SDP manipulation classes, which directly wrap the PJSIP structures representing either the parsed or to be generated SDP.
85 1 Adrian Georgescu
     {{{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.
86 1 Adrian Georgescu
     * {{{SDPSession}}}
87 1 Adrian Georgescu
     * {{{SDPMedia}}}
88 1 Adrian Georgescu
     * {{{SDPConnection}}}
89 1 Adrian Georgescu
     * {{{SDPAttribute}}}
90 1 Adrian Georgescu
   * Two classes related to transport of media traffic and audio traffic specifically, built on PJMEDIA.
91 1 Adrian Georgescu
     These classes can be instantiated independently from the other classes in order to keep signaling and media separate.
92 1 Adrian Georgescu
     * {{{RTPTransport}}}
93 1 Adrian Georgescu
     * {{{AudioTransport}}}
94 73 Ruud Klaver
   * 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.
95 73 Ruud Klaver
     * {{{ConferenceBridge}}}
96 73 Ruud Klaver
     * {{{ToneGenerator}}}
97 1 Adrian Georgescu
     * {{{WaveFile}}}
98 1 Adrian Georgescu
     * {{{RecordingWaveFile}}}
99 1 Adrian Georgescu
   * Two exception classes, the second being a subclass of the first.
100 1 Adrian Georgescu
     * {{{SIPCoreError}}}
101 1 Adrian Georgescu
     * {{{PJSIPError}}}
102 1 Adrian Georgescu
   * Classes used internally within the {{{core}}} module, e.g. to wrap a particular PJSIP library.
103 42 Ruud Klaver
     These classes should not be imported directly and are not included in the {{{__all__}}} variable of this module.
104 42 Ruud Klaver
 '''sipsimple.primitives'''::
105 42 Ruud Klaver
  This module contains several SIP primitive classes that are based on the {{{Request}}} object from the core:
106 42 Ruud Klaver
   * {{{Registration}}}
107 1 Adrian Georgescu
   * {{{Message}}}
108 68 Ruud Klaver
   * {{{Publication}}}
109 1 Adrian Georgescu
110 1 Adrian Georgescu
These classes (except the ones internal to the {{{core}}} module) are illustrated in the following diagram:
111 1 Adrian Georgescu
112 67 Ruud Klaver
[[Image(sipsimple-core-classes.png, nolink)]]
113 67 Ruud Klaver
114 11 Adrian Georgescu
== Integration ==
115 1 Adrian Georgescu
116 1 Adrian Georgescu
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.
117 1 Adrian Georgescu
These modules should be present on the system before the core can be used.
118 1 Adrian Georgescu
An application that uses the SIP core must use the notification system provided by the {{{application}}} module in order to receive notifications from it.
119 1 Adrian Georgescu
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.
120 1 Adrian Georgescu
This means that any call to instance an object from this class will result in the same object.
121 1 Adrian Georgescu
As an example, this bit of code will create an observer for logging messages only:
122 1 Adrian Georgescu
123 1 Adrian Georgescu
{{{
124 1 Adrian Georgescu
from zope.interface import implements
125 1 Adrian Georgescu
from application.notification import NotificationCenter, IObserver
126 1 Adrian Georgescu
127 29 Luci Stanescu
class SIPEngineLogObserver(object):
128 1 Adrian Georgescu
    implements(IObserver)
129 1 Adrian Georgescu
130 1 Adrian Georgescu
    def handle_notification(self, notification):
131 1 Adrian Georgescu
        print "%(timestamp)s (%(level)d) %(sender)14s: %(message)s" % notification.data.__dict__
132 1 Adrian Georgescu
133 1 Adrian Georgescu
notification_center = NotificationCenter()
134 1 Adrian Georgescu
log_observer = EngineLogObserver()
135 29 Luci Stanescu
notification_center.add_observer(self, name="SIPEngineLog")
136 1 Adrian Georgescu
}}}
137 1 Adrian Georgescu
138 1 Adrian Georgescu
Each notification object has three attributes:
139 1 Adrian Georgescu
 '''sender'''::
140 1 Adrian Georgescu
  The object that sent the notification.
141 1 Adrian Georgescu
  For generic notifications the sender will be the {{{Engine}}} instance, otherwise the relevant object.
142 1 Adrian Georgescu
 '''name'''::
143 1 Adrian Georgescu
  The name describing the notification.
144 29 Luci Stanescu
  All messages will be described in this document and start with the prefix "SIP".
145 1 Adrian Georgescu
 '''data'''::
146 1 Adrian Georgescu
  An instance of {{{application.notification.NotificationData}}} or a subclass of it.
147 1 Adrian Georgescu
  The attributes of this object provide additional data about the notification.
148 1 Adrian Georgescu
  Notifications described in this document will also have the data attributes described.
149 1 Adrian Georgescu
150 43 Ruud Klaver
Besides setting up the notification observers, the application should import the relevant objects from the {{{sipsimple.core}}}, {{{sipsimple.engine}}} and {{{sipsimple.primitives}}} modules.
151 1 Adrian Georgescu
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.
152 1 Adrian Georgescu
Most of these options can later be changed at runtime, by setting attributes of the same name on the {{{Engine}}} object.
153 1 Adrian Georgescu
The application may then instance one of the SIP primitive classes and perform operations on it.
154 1 Adrian Georgescu
155 1 Adrian Georgescu
When starting the {{{Engine}}} class, the application can pass a number of keyword arguments that influence the behaviour of the SIP endpoint.
156 1 Adrian Georgescu
For example, the SIP network ports may be set through the {{{local_udp_port}}}, {{{local_tcp_port}}} and {{{local_tls_port}}} arguments.
157 1 Adrian Georgescu
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.
158 1 Adrian Georgescu
159 1 Adrian Georgescu
The methods called on the SIP primitive objects and the {{{Engine}}} object (proxied to the {{{PJSIPUA}}} instance) may be called from any thread.
160 31 Ruud Klaver
They will return immediately and any delayed result, such as results depending on network traffic, will be returned later using a notification.
161 31 Ruud Klaver
In this manner the SIP core continues the asynchronous pattern of PJSIP.
162 1 Adrian Georgescu
If there is an error in processing the request, an instance of {{{SIPCoreError}}}, or its subclass {{{PJSIPError}}} will be raised.
163 1 Adrian Georgescu
The former will be raised whenever an error occurs inside the core, the latter whenever an underlying PJSIP function returns an error.
164 1 Adrian Georgescu
The {{{PJSIPError}}} object also contains a status attribute, which is the PJSIP errno as an integer.
165 1 Adrian Georgescu
166 43 Ruud Klaver
As a very basic example, one can {{{REGISTER}}} for a sip account by typing the following lines on a Python console:
167 1 Adrian Georgescu
{{{
168 43 Ruud Klaver
from sipsimple.engine import Engine
169 43 Ruud Klaver
from sipsimple.primitives import Registration
170 43 Ruud Klaver
from sipsimple.core import Credentials, SIPURI, Route
171 1 Adrian Georgescu
e = Engine()
172 1 Adrian Georgescu
e.start()
173 65 Ruud Klaver
uri = SIPURI(user="alice", host="example.com")
174 65 Ruud Klaver
cred = Credentials("alice", "mypassword")
175 65 Ruud Klaver
reg = Registration(uri, credentials=cred)
176 43 Ruud Klaver
reg.register(SIPURI("127.0.0.1",port=12345), Route("1.2.3.4"))
177 1 Adrian Georgescu
}}}
178 1 Adrian Georgescu
Note that in this example no observer for notifications from this {{{Registration}}} object are registered, so the result of the operation cannot be seen.
179 43 Ruud Klaver
Also note that this will not keep the registration registered when it is about to expire, as it is the application's responsibility.
180 43 Ruud Klaver
See the {{{Registration}}} documentation for more details.
181 43 Ruud Klaver
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.
182 43 Ruud Klaver
Failure to do so will keep the {{{Engine}}} running and will cause the program to hang.
183 1 Adrian Georgescu
184 1 Adrian Georgescu
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].
185 43 Ruud Klaver
186 43 Ruud Klaver
> NOTE: GreenRegistration is outdated and should probably not be used anymore.
187 43 Ruud Klaver
188 43 Ruud Klaver
Another convention that is worth mentioning at this point is that the SIP core will never perform DNS lookups.
189 43 Ruud Klaver
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.
190 32 Ruud Klaver
191 1 Adrian Georgescu
== Components ==
192 1 Adrian Georgescu
193 1 Adrian Georgescu
=== Engine ===
194 1 Adrian Georgescu
195 1 Adrian Georgescu
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.
196 1 Adrian Georgescu
Once the {{{start()}}} method is called, it instantiates the {{{core.PJSIPUA}}} object and will proxy attribute and methods from it to the application.
197 1 Adrian Georgescu
198 1 Adrian Georgescu
==== attributes ====
199 1 Adrian Georgescu
200 1 Adrian Georgescu
 '''default_start_options''' (class attribute)::
201 1 Adrian Georgescu
  This dictionary is a class attribute that describes the default values for the initialization options passed as keyword arguments to the {{{start()}}} method.
202 1 Adrian Georgescu
  Consult this method for documentation of the contents.
203 32 Ruud Klaver
 '''is_running'''::
204 32 Ruud Klaver
  A boolean property indicating if the {{{Engine}}} is running and if it is safe to try calling any proxied methods or attributes on it.
205 1 Adrian Georgescu
206 1 Adrian Georgescu
==== methods ====
207 1 Adrian Georgescu
208 1 Adrian Georgescu
 '''!__init!__'''(''self'')::
209 1 Adrian Georgescu
  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.
210 1 Adrian Georgescu
 '''start'''(''self'', '''**kwargs''')::
211 71 Adrian Georgescu
  Initialize all PJSIP libraries based on the keyword parameters provided and start the PJSIP worker thread.
212 1 Adrian Georgescu
  If this fails an appropriate exception is raised.
213 1 Adrian Georgescu
  After the {{{Engine}}} has been started successfully, it can never be started again after being stopped.
214 1 Adrian Georgescu
  The keyword arguments will be discussed here.
215 1 Adrian Georgescu
  Many of these values are also readable as (proxied) attributes on the Engine once the {{{start()}}} method has been called.
216 1 Adrian Georgescu
  Many of them can also be set at runtime, either by modifying the attribute or by calling a particular method.
217 1 Adrian Georgescu
  This will also be documented for each argument in the following list of options.
218 1 Adrian Georgescu
  [[BR]]''auto_sound'':[[BR]]
219 71 Adrian Georgescu
  A boolean indicating if PJSIP should automatically select and enable a sound-card to use for for recording and playing back sound.
220 39 Ruud Klaver
  If this is set to {{{False}}} the Dummy sound device is selected.
221 39 Ruud Klaver
  To be able to hear and contribute audio, the application will have to select a sound device manually through the {{{set_sound_devices}}} method.
222 1 Adrian Georgescu
  This option is not accessible as an attribute on the object, as it is transitory.
223 1 Adrian Georgescu
  [[BR]]''local_ip'': (Default: {{{None}}})[[BR]]
224 1 Adrian Georgescu
  IP address of a local interface to bind to.
225 44 Ruud Klaver
  If this is {{{None}}} or {{{0.0.0.0}}} on start, the {{{Engine}}} will listen on all network interfaces.
226 44 Ruud Klaver
  As an attribute, this value is read-only and cannot be changed at runtime.
227 1 Adrian Georgescu
  [[BR]]''local_udp_port'': (Default: {{{0}}})[[BR]]
228 1 Adrian Georgescu
  The local UDP port to listen on for UDP datagrams.
229 1 Adrian Georgescu
  If this is 0, a random port will be chosen.
230 1 Adrian Georgescu
  If it is {{{None}}}, the UDP transport is disabled, both for incoming and outgoing traffic.
231 1 Adrian Georgescu
  As an attribute, this value is read-only, but it can be changed at runtime using the {{{set_local_udp_port()}}} method.
232 1 Adrian Georgescu
  [[BR]]''local_tcp_port'': (Default: {{{0}}})[[BR]]
233 1 Adrian Georgescu
  The local TCP port to listen on for new TCP connections.
234 1 Adrian Georgescu
  If this is 0, a random port will be chosen.
235 1 Adrian Georgescu
  If it is {{{None}}}, the TCP transport is disabled, both for incoming and outgoing traffic.
236 1 Adrian Georgescu
  As an attribute, this value is read-only, but it can be changed at runtime using the {{{set_local_tcp_port()}}} method.
237 1 Adrian Georgescu
  [[BR]]''local_tls_port'': (Default: {{{0}}})[[BR]]
238 1 Adrian Georgescu
  The local TCP port to listen on for new TLS over TCP connections.
239 28 Adrian Georgescu
  If this is 0, a random port will be chosen.
240 1 Adrian Georgescu
  If it is {{{None}}}, the TLS transport is disabled, both for incoming and outgoing traffic.
241 35 Ruud Klaver
  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. 
242 32 Ruud Klaver
  [[BR]]''tls_protocol'': (Default: "TLSv1")[[BR]] 
243 32 Ruud Klaver
  This string describes the (minimum) TLS protocol that should be used. 
244 32 Ruud Klaver
  Its values should be either {{{None}}}, "SSLv2", "SSLv23", "SSLv3" or "TLSv1". 
245 32 Ruud Klaver
  If {{{None}}} is specified, the PJSIP default will be used, which is currently "TLSv1". 
246 1 Adrian Georgescu
  [[BR]]''tls_verify_server'': (Default: {{{False}}})[[BR]]
247 28 Adrian Georgescu
  This boolean indicates whether PJSIP should verify the certificate of the server against the local CA list when making an outgoing TLS connection.
248 32 Ruud Klaver
  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.
249 1 Adrian Georgescu
  [[BR]]''tls_ca_file'': (Default: {{{None}}})[[BR]]
250 1 Adrian Georgescu
  This string indicates the location of the file containing the local list of CA certificates, to be used for TLS connections.
251 32 Ruud Klaver
  If this is set to {{{None}}}, no CA certificates will be read. 
252 32 Ruud Klaver
  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. 
253 32 Ruud Klaver
  [[BR]]''tls_cert_file'': (Default: {{{None}}})[[BR]] 
254 32 Ruud Klaver
  This string indicates the location of a file containing the TLS certificate to be used for TLS connections. 
255 32 Ruud Klaver
  If this is set to {{{None}}}, no certificate file will be read. 
256 32 Ruud Klaver
  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. 
257 32 Ruud Klaver
  [[BR]]''tls_privkey_file'': (Default: {{{None}}})[[BR]] 
258 32 Ruud Klaver
  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. 
259 32 Ruud Klaver
  If this is set to {{{None}}}, no private key file will be read. 
260 32 Ruud Klaver
  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. 
261 32 Ruud Klaver
  [[BR]]''tls_timeout'': (Default: 1000)[[BR]] 
262 32 Ruud Klaver
  The timeout value for a TLS negotiation in milliseconds. 
263 32 Ruud Klaver
  Note that this value should be reasonably small, as a TLS negotiation blocks the whole PJSIP polling thread. 
264 32 Ruud Klaver
  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.
265 1 Adrian Georgescu
  [[BR]]''ec_tail_length'': (Default: {{{50}}})[[BR]]
266 1 Adrian Georgescu
  Echo cancellation tail length in milliseconds.
267 1 Adrian Georgescu
  A longer value should provide better echo cancellation but incurs more processing cost.
268 1 Adrian Georgescu
  Setting this to 0 will disable echo cancellation.
269 20 Ruud Klaver
  As an attribute, this value is read-only, but it can be set as an argument to the {{{set_sound_devices}}} method.
270 71 Adrian Georgescu
  [[BR]]''user_agent'': (Default: {{{"sipsimple-%version"}}})[[BR]]
271 1 Adrian Georgescu
  This value indicates what should be set in the {{{User-Agent}}} header, which is included in each request or response sent.
272 1 Adrian Georgescu
  It can be read and set directly as an attribute at runtime.
273 1 Adrian Georgescu
  [[BR]]''log_level'': (Default: 5)[[BR]]
274 29 Luci Stanescu
  This integer dictates the maximum log level that may be reported to the application by PJSIP through the {{{SIPEngineLog}}} notification.
275 1 Adrian Georgescu
  By default the maximum amount of logging information is reported.
276 1 Adrian Georgescu
  This value can be read and set directly as an attribute at runtime.
277 1 Adrian Georgescu
  [[BR]]''trace_sip'': (Default: {{{False}}})[[BR]]
278 29 Luci Stanescu
  This boolean indicates if the SIP core should send the application SIP messages as seen on the wire through the {{{SIPEngineSIPTrace}}} notification.
279 1 Adrian Georgescu
  It can be read and set directly as an attribute at runtime.
280 1 Adrian Georgescu
  [[BR]]''sample_rate'': (Default: {{{32}}})[[BR]]
281 1 Adrian Georgescu
  The sample rate in kHz at which the sound card should operate.
282 1 Adrian Georgescu
  Higher values allow some codecs (such as speex) to achieve better quality but will incur higher processing cost, particularly in combination with echo cancellation.
283 1 Adrian Georgescu
  This parameter should be either 8, 16 or 32.
284 1 Adrian Georgescu
  The corresponding attribute of this value is read-only.
285 1 Adrian Georgescu
  [[BR]]''playback_dtmf'': (Default: {{{True}}})[[BR]]
286 1 Adrian Georgescu
  If this boolean is set to {{{True}}}, both incoming and outgoing DTMF signals have their corresponding audio tones played back on the sound card.
287 1 Adrian Georgescu
  This value can be read and set directly as an attribute at runtime.
288 1 Adrian Georgescu
  [[BR]]''rtp_port_range'': (Default: (40000, 40100))[[BR]]
289 71 Adrian Georgescu
  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.
290 1 Adrian Georgescu
  It can be read and set directly as an attribute at runtime, but the ports of previously created {{{RTPTransport}}} objects remain unaffected.
291 40 Ruud Klaver
  [[BR]]''codecs'': (Default: {{{["speex", "G722", "PCMU", "PCMA", "iLBC", "GSM"]}}})[[BR]]
292 1 Adrian Georgescu
  This list specifies the codecs to use for audio sessions and their preferred order.
293 1 Adrian Georgescu
  It can be read and set directly as an attribute at runtime.
294 40 Ruud Klaver
  Note that this global option can be overridden by an argument passed to {{{AudioTransport.__init__()}}}.
295 40 Ruud Klaver
  The strings in this list is case insensitive.
296 1 Adrian Georgescu
  [[BR]]''events'': (Default: <some sensible events>)[[BR]]
297 1 Adrian Georgescu
  PJSIP needs a mapping between SIP SIMPLE event packages and content types.
298 1 Adrian Georgescu
  This dictionary provides some default packages and their event types.
299 1 Adrian Georgescu
  As an attribute, this value is read-only, but it can be changed at runtime using the {{{set_local_tls_port()}}} method.
300 32 Ruud Klaver
 '''start_cfg'''(''self'', '''enable_sound'''={{{True}}}, '''**kwargs''')::
301 36 Adrian Georgescu
  This provides a [wiki:SipConfigurationAPI Configuration API] aware start method.
302 32 Ruud Klaver
  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.
303 32 Ruud Klaver
  Any argument that can be passed to {{{start()}}} may be specified, except for {{{auto_sound}}}.
304 35 Ruud Klaver
  [[BR]]''enable_sound'':[[BR]]
305 1 Adrian Georgescu
  If this is set to {{{True}}}, the sound devices set up in the configuration framework will be started.
306 39 Ruud Klaver
  If it is {{{False}}}, the Dummy sound device will be used.
307 1 Adrian Georgescu
 '''stop'''(''self'')::
308 1 Adrian Georgescu
  Stop the PJSIP worker thread and unload all PJSIP libraries.
309 1 Adrian Georgescu
  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}}}.
310 1 Adrian Georgescu
  Also note that, once stopped the {{{Engine}}} cannot be started again.
311 1 Adrian Georgescu
  This method is automatically called when the Python interpreter exits.
312 1 Adrian Georgescu
313 1 Adrian Georgescu
==== proxied attributes ====
314 1 Adrian Georgescu
315 1 Adrian Georgescu
Besides all the proxied attributes described for the {{{__init__}}} method above, two other attributes are provided once the {{{Engine}}} has been started.
316 1 Adrian Georgescu
317 1 Adrian Georgescu
 '''playback_devices'''::
318 20 Ruud Klaver
  This read-only attribute is a list of string, representing all audio playback devices on the system that can be used.
319 20 Ruud Klaver
  These device names can be passed as the {{{playback_device}}} argument of the {{{set_sound_devices()}}} method.
320 1 Adrian Georgescu
 '''recording_devices'''::
321 1 Adrian Georgescu
  This read-only attribute is a list of string, representing all audio recording devices on the system that can be used.
322 1 Adrian Georgescu
  These device names can be passed as the {{{recording_device}}} argument of the {{{set_sound_devices()}}} method.
323 44 Ruud Klaver
 '''current_playback_device'''::
324 44 Ruud Klaver
  The name of the audio playback device currently in use.
325 44 Ruud Klaver
 '''current_recording_device'''::
326 44 Ruud Klaver
  The name of the audio recording device currently in use.
327 40 Ruud Klaver
 '''available_codecs'''::
328 40 Ruud Klaver
  A read-only list of codecs available in the core, regardless of the codecs configured through the {{{codecs}}} attribute.
329 1 Adrian Georgescu
330 1 Adrian Georgescu
==== proxied methods ====
331 1 Adrian Georgescu
332 1 Adrian Georgescu
 '''add_event'''(''self'', '''event''', '''accept_types''')::
333 1 Adrian Georgescu
  Couple a certain event package to a list of content types.
334 1 Adrian Georgescu
  Once added it cannot be removed or modified.
335 20 Ruud Klaver
 '''set_sound_devices'''(''self'', '''playback_device'''={{{None}}}, '''recording_device'''={{{None}}}, '''tail_length'''={{{None}}})::
336 1 Adrian Georgescu
  Set and open the playback and recording device, using the specified echo cancellation tail length in milliseconds.
337 1 Adrian Georgescu
  If no echo cancellation value is specified, either the value set while calling the {{{start()}}} method will be used or the default value will be used (see the documentation of this method).
338 1 Adrian Georgescu
  A {{{tail_length}}} of 0 disables echo cancellation.
339 1 Adrian Georgescu
  The device attributes need to be strings and should be obtained from the {{{playback_devices}}} and {{{recording_devices}}} attributes respectively.
340 1 Adrian Georgescu
  Passing either of these as {{{None}}} means that PJSIP should select a sound device automatically.
341 1 Adrian Georgescu
  If sound devices were already opened these will be closed first.
342 1 Adrian Georgescu
 '''connect_audio_transport'''(''self'', '''transport''')::
343 1 Adrian Georgescu
  Connect a started audio transport, in the form of a {{{AudioTransport}}} object, to the recording and playback audio devices and other connected audio transports.
344 1 Adrian Georgescu
  This means that when more than one audio stream is connected they will form a conference.
345 29 Luci Stanescu
 '''disconnect_audio_transport'''(''self'', '''transport''')::
346 1 Adrian Georgescu
  Disconnect a previously connected audio transport, in the form of a {{{AudioTransport}}} object.
347 1 Adrian Georgescu
  Stopped audio streams are disconnected automatically.
348 38 Ruud Klaver
 '''detect_nat_type'''(''self'', '''stun_server_address''', '''stun_server_port'''=3478, '''user_data'''=None)::
349 1 Adrian Georgescu
  Will start a series of STUN requests which detect the type of NAT this host is behind.
350 1 Adrian Georgescu
  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.
351 38 Ruud Klaver
  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.
352 1 Adrian Georgescu
 '''set_local_udp_port'''(''self'', '''value''')::
353 28 Adrian Georgescu
  Update the {{{local_udp_port}}} attribute to the newly specified value.
354 28 Adrian Georgescu
 '''set_local_tcp_port'''(''self'', '''value''')::
355 28 Adrian Georgescu
  Update the {{{local_tcp_port}}} attribute to the newly specified value.
356 32 Ruud Klaver
 '''set_tls_options'''(''self'', '''local_port'''={{{None}}}, '''protocol'''="TLSv1", '''verify_server'''={{{False}}}, '''ca_file'''={{{None}}}, '''cert_file'''={{{None}}}, '''privkey_file'''={{{None}}}, '''timeout'''=1000):: 
357 32 Ruud Klaver
  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}}}. 
358 1 Adrian Georgescu
  The semantics of the arguments are the same as on the {{{start()}}} method. 
359 1 Adrian Georgescu
 '''parse_sip_uri(''self'', '''uri_string''')::
360 1 Adrian Georgescu
  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.
361 44 Ruud Klaver
 '''play_tones(''self'', '''tones''')::
362 44 Ruud Klaver
  Play a sequence of single or dual frequency tones over the audio device.
363 44 Ruud Klaver
  The tones 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.
364 44 Ruud Klaver
  If {{{freq2}}} is 0, this indicates that only {{{freq1}}} should be used for the tone.
365 44 Ruud Klaver
  If {{{freq1}}} is 0, this indicates a pause when no tone should be played for the set duration.
366 1 Adrian Georgescu
367 1 Adrian Georgescu
==== notifications ====
368 1 Adrian Georgescu
369 16 Ruud Klaver
Notifications sent by the {{{Engine}}} are notifications that are related to the {{{Engine}}} itself or unrelated to any SIP primitive object.
370 1 Adrian Georgescu
They are described here including the data attributes that is included with them.
371 1 Adrian Georgescu
372 29 Luci Stanescu
 '''SIPEngineWillStart'''::
373 16 Ruud Klaver
  This notification is sent when the {{{Engine}}} is about to start.
374 16 Ruud Klaver
  [[BR]]''timestamp'':[[BR]]
375 16 Ruud Klaver
  A {{{datetime.datetime}}} object indicating when the notification was sent.
376 29 Luci Stanescu
 '''SIPEngineDidStart'''::
377 16 Ruud Klaver
  This notification is sent when the {{{Engine}}} is has just been started.
378 16 Ruud Klaver
  [[BR]]''timestamp'':[[BR]]
379 16 Ruud Klaver
  A {{{datetime.datetime}}} object indicating when the notification was sent.
380 29 Luci Stanescu
 '''SIPEngineDidFail'''::
381 16 Ruud Klaver
  This notification is sent whenever the {{{Engine}}} has failed fatally and either cannot start or is about to stop.
382 16 Ruud Klaver
  It is not recommended to call any methods on the {{{Engine}}} at this point.
383 16 Ruud Klaver
  [[BR]]''timestamp'':[[BR]]
384 16 Ruud Klaver
  A {{{datetime.datetime}}} object indicating when the notification was sent.
385 29 Luci Stanescu
 '''SIPEngineWillEnd'''::
386 16 Ruud Klaver
  This notification is sent when the {{{Engine}}} is about to stop because the application called the {{{stop()}}} method.
387 16 Ruud Klaver
  Methods on the {{{Engine}}} can be called at this point, but anything that has a delayed result will probably not return any notification.
388 16 Ruud Klaver
  [[BR]]''timestamp'':[[BR]]
389 16 Ruud Klaver
  A {{{datetime.datetime}}} object indicating when the notification was sent.
390 29 Luci Stanescu
 '''SIPEngineDidEnd'''::
391 16 Ruud Klaver
  This notification is sent when the {{{Engine}}} was running and is now stopped, either because of failure or because the application requested it.
392 16 Ruud Klaver
  [[BR]]''timestamp'':[[BR]]
393 16 Ruud Klaver
  A {{{datetime.datetime}}} object indicating when the notification was sent.
394 29 Luci Stanescu
 '''SIPEngineLog'''::
395 1 Adrian Georgescu
  This notification is a wrapper for PJSIP logging messages.
396 1 Adrian Georgescu
  It can be used by the application to output PJSIP logging to somewhere meaningful, possibly doing filtering based on log level.
397 1 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
398 1 Adrian Georgescu
  A {{{datetime.datetime}}} object representing the time when the log message was output by PJSIP.
399 1 Adrian Georgescu
  [[BR]]''sender'':[[BR]]
400 1 Adrian Georgescu
  The PJSIP module that originated this log message.
401 1 Adrian Georgescu
  [[BR]]''level'':[[BR]]
402 1 Adrian Georgescu
  The logging level of the message as an integer.
403 1 Adrian Georgescu
  Currently this is 1 through 5, 1 being the most critical.
404 1 Adrian Georgescu
  [[BR]]''message'':[[BR]]
405 1 Adrian Georgescu
  The actual log message.
406 29 Luci Stanescu
 '''SIPEngineSIPTrace'''::
407 1 Adrian Georgescu
  Will be sent only when the {{{do_siptrace}}} attribute of the {{{Engine}}} instance is set to {{{True}}}.
408 1 Adrian Georgescu
  The notification data attributes will contain the SIP messages as they are sent and received on the wire.
409 1 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
410 1 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
411 1 Adrian Georgescu
  [[BR]]''received'':[[BR]]
412 1 Adrian Georgescu
  A boolean indicating if this message was sent from or received by PJSIP (i.e. the direction of the message).
413 1 Adrian Georgescu
  [[BR]]''source_ip'':[[BR]]
414 1 Adrian Georgescu
  The source IP address as a string.
415 1 Adrian Georgescu
  [[BR]]''source_port'':[[BR]]
416 29 Luci Stanescu
  The source port of the message as an integer.
417 1 Adrian Georgescu
  [[BR]]''destination_ip'':[[BR]]
418 1 Adrian Georgescu
  The destination IP address as a string.
419 1 Adrian Georgescu
  [[BR]]''source_port'':[[BR]]
420 1 Adrian Georgescu
  The source port of the message as an integer.
421 1 Adrian Georgescu
  [[BR]]''data'':[[BR]]
422 1 Adrian Georgescu
  The contents of the message as a string.
423 1 Adrian Georgescu
424 1 Adrian Georgescu
> For received message the destination_ip and for sent messages the source_ip may not be reliable.
425 1 Adrian Georgescu
426 29 Luci Stanescu
 '''SIPEngineDetectedNATType'''::
427 1 Adrian Georgescu
  This notification is sent some time after the application request the NAT type this host behind to be detected using a STUN server.
428 1 Adrian Georgescu
  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.
429 1 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
430 1 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
431 1 Adrian Georgescu
  [[BR]]''succeeded'':[[BR]]
432 1 Adrian Georgescu
  A boolean indicating if the NAT detection succeeded.
433 38 Ruud Klaver
  [[BR]]''user_data'':[[BR]]
434 38 Ruud Klaver
  The {{{user_data}}} argument passed while calling the {{{detect_nat_type()}}} method.
435 38 Ruud Klaver
  This can be any object and could be used for matching requests to responses.
436 1 Adrian Georgescu
  [[BR]]''nat_type'':[[BR]]
437 1 Adrian Georgescu
  A string describing the type of NAT found.
438 1 Adrian Georgescu
  This value is only present if NAT detection succeeded.
439 1 Adrian Georgescu
  [[BR]]''error'':[[BR]]
440 1 Adrian Georgescu
  A string indicating the error that occurred while attempting to detect the type of NAT.
441 1 Adrian Georgescu
  This value only present if NAT detection did not succeed.
442 1 Adrian Georgescu
 '''SIPEngineGotException'''::
443 1 Adrian Georgescu
  This notification is sent whenever there is an unexpected exception within the PJSIP working thread.
444 1 Adrian Georgescu
  The application should show the traceback to the user somehow.
445 1 Adrian Georgescu
  An exception need not be fatal, but if it is it will be followed by a '''SIPEngineDidFail''' notification.
446 1 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
447 1 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
448 1 Adrian Georgescu
  [[BR]]''traceback'':[[BR]]
449 1 Adrian Georgescu
  A string containing the traceback of the exception.
450 1 Adrian Georgescu
  In general this should be printed on the console.
451 1 Adrian Georgescu
452 1 Adrian Georgescu
=== SIPURI ===
453 1 Adrian Georgescu
454 1 Adrian Georgescu
This is a helper object for representing a SIP URI.
455 1 Adrian Georgescu
This object needs to be used whenever a SIP URI should be specified to the SIP core.
456 1 Adrian Georgescu
It supports comparison to other {{{SIPURI}}} objects using the == and != expressions.
457 1 Adrian Georgescu
As all of its attributes are set by the {{{__init__}}} method, the individual attributes will not be documented here.
458 1 Adrian Georgescu
459 1 Adrian Georgescu
==== methods ====
460 1 Adrian Georgescu
461 23 Ruud Klaver
 '''!__init!__'''(''self'', '''host''', '''user'''={{{None}}}, '''port'''={{{None}}}, '''display'''={{{None}}}, '''secure'''={{{False}}}, '''parameters'''={{{None}}}, '''headers'''={{{None}}})::
462 1 Adrian Georgescu
  Creates the SIPURI object with the specified parameters as attributes.
463 1 Adrian Georgescu
  Each of these attributes can be accessed and changed on the object once instanced.
464 1 Adrian Georgescu
  {{{host}}} is the only mandatory attribute.
465 1 Adrian Georgescu
  [[BR]]''host'':[[BR]]
466 1 Adrian Georgescu
  The host part of the SIP URI as a string.
467 1 Adrian Georgescu
  [[BR]]''user'':[[BR]]
468 1 Adrian Georgescu
  The username part of the SIP URI as a string, or None if not set.
469 1 Adrian Georgescu
  [[BR]]''port'':[[BR]]
470 1 Adrian Georgescu
  The port part of the SIP URI as an int, or None or 0 if not set.
471 1 Adrian Georgescu
  [[BR]]''display'':[[BR]]
472 1 Adrian Georgescu
  The optional display name of the SIP URI as a string, or None if not set.
473 1 Adrian Georgescu
  [[BR]]''secure'':[[BR]]
474 1 Adrian Georgescu
  A boolean indicating whether this is a SIP or SIPS URI, the latter being indicated by a value of {{{True}}}.
475 1 Adrian Georgescu
  [[BR]]''parameters'':[[BR]]
476 1 Adrian Georgescu
  The URI parameters. represented by a dictionary.
477 1 Adrian Georgescu
  [[BR]]''headers'':[[BR]]
478 1 Adrian Georgescu
  The URI headers, represented by a dictionary.
479 1 Adrian Georgescu
 '''!__str!__'''(''self'')::
480 1 Adrian Georgescu
  The special Python method to represent this object as a string, the output is the properly formatted SIP URI.
481 1 Adrian Georgescu
 '''copy'''(''self'')::
482 1 Adrian Georgescu
  Returns a copy of the {{{SIPURI}}} object.
483 1 Adrian Georgescu
484 1 Adrian Georgescu
=== Credentials ===
485 1 Adrian Georgescu
486 61 Ruud Klaver
This simple object represents authentication credentials for a particular SIP account.
487 61 Ruud Klaver
These can be included whenever creating a SIP primitive object that originates SIP requests.
488 1 Adrian Georgescu
As with the {{{SIPURI}}} object, the attributes of this object are the same as the arguments to the {{{__init__}}} method.
489 61 Ruud Klaver
Note that the domain name of the SIP account is not stored on this object.
490 1 Adrian Georgescu
491 1 Adrian Georgescu
==== methods ====
492 1 Adrian Georgescu
493 61 Ruud Klaver
 '''!__init!__'''(''self'', '''username''', '''password''')::
494 1 Adrian Georgescu
  Creates the Credentials object with the specified parameters as attributes.
495 1 Adrian Georgescu
  Each of these attributes can be accessed and changed on the object once instanced.
496 61 Ruud Klaver
  [[BR]]''username'':[[BR]]
497 61 Ruud Klaver
  A string representing the username of the account for which these are the credentials.
498 1 Adrian Georgescu
  [[BR]]''password'':[[BR]]
499 1 Adrian Georgescu
  The password for this SIP account as a string.
500 1 Adrian Georgescu
 '''copy'''(''self'')::
501 1 Adrian Georgescu
  Returns a copy of the {{{Credentials}}} object.
502 1 Adrian Georgescu
503 1 Adrian Georgescu
=== Route ===
504 1 Adrian Georgescu
505 22 Ruud Klaver
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.
506 33 Ruud Klaver
As it is the application's responsibility to look this up and pass it as an argument for every SIP primitive class it creates.
507 22 Ruud Klaver
The contents of the {{{Route}}} object will be placed in the {{{Route}}} header of the request.
508 1 Adrian Georgescu
As with the {{{SIPURI}}} object, the attributes of this object are the same as the arguments to the {{{__init__}}} method.
509 1 Adrian Georgescu
510 1 Adrian Georgescu
==== methods ====
511 1 Adrian Georgescu
512 22 Ruud Klaver
 '''!__init!__'''(''self'', '''address''', '''port'''=5060, '''transport'''={{{None}}})::
513 1 Adrian Georgescu
  Creates the Route object with the specified parameters as attributes.
514 1 Adrian Georgescu
  Each of these attributes can be accessed on the object once instanced.
515 22 Ruud Klaver
  [[BR]]''address'':[[BR]]
516 45 Ruud Klaver
  The IPv4 address that the request in question should be sent to as a string.
517 1 Adrian Georgescu
  [[BR]]''port'':[[BR]]
518 22 Ruud Klaver
  The port to send the requests to, represented as an int.
519 1 Adrian Georgescu
  [[BR]]''transport'':[[BR]]
520 35 Ruud Klaver
  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.
521 1 Adrian Georgescu
 '''copy'''(''self'')::
522 1 Adrian Georgescu
  Returns a copy of the {{{Route}}} object.
523 22 Ruud Klaver
524 46 Ruud Klaver
=== Request ===
525 46 Ruud Klaver
526 46 Ruud Klaver
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.
527 46 Ruud Klaver
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.
528 46 Ruud Klaver
529 46 Ruud Klaver
The lifetime of this object is linear and is described by the following diagram:
530 46 Ruud Klaver
531 46 Ruud Klaver
[[Image(sipsimple-request-lifetime.png, nolink)]]
532 46 Ruud Klaver
533 46 Ruud Klaver
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.
534 46 Ruud Klaver
Directly after the object is instantiated, it will be in the {{{INIT}}} state.
535 46 Ruud Klaver
The request will be sent over the network once its {{{send()}}} method is called, moving the object into the {{{IN_PROGRESS}}} state.
536 46 Ruud Klaver
On each provisional response that is received in reply to this request, the {{{SIPRequestGotProvisionalResponse}}} notification is sent, with data describing the response.
537 46 Ruud Klaver
Note that this may not occur at all if not provisional responses are received.
538 46 Ruud Klaver
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.
539 46 Ruud Klaver
Both of these notifications include data on the response that triggered it.
540 46 Ruud Klaver
Note that a SIP response that requests authentication (401 or 407) will be handled internally the first time, if a {{{Credentials}}} object was supplied.
541 46 Ruud Klaver
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.
542 46 Ruud Klaver
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.
543 46 Ruud Klaver
This should usually trigger whomever is using this {{{Request}}} object to construct a new {{{Request}}} for a refreshing operation.
544 46 Ruud Klaver
When the {{{Request}}} actually expires, or when the {{{EXPIRING}}} state is skipped directly after sending {{{SIPRequestDidSucceed}}} or {{{SIPRequestDidFail}}}, a {{{SIPRequestDidEnd}}} notification will be sent.
545 46 Ruud Klaver
546 46 Ruud Klaver
==== attributes ====
547 46 Ruud Klaver
548 49 Ruud Klaver
 '''expire_warning_time''' (class attribute)::
549 49 Ruud Klaver
  The {{{SIPRequestWillExpire}}} notification will be sent halfway between the positive response and the actual expiration time, but at least this amount of seconds before.
550 49 Ruud Klaver
  The default value is 30 seconds.
551 47 Ruud Klaver
 '''state'''::
552 47 Ruud Klaver
  Indicates the state the {{{Request}}} object is in, in the form of a string.
553 47 Ruud Klaver
  Refer to the diagram above for possible states.
554 47 Ruud Klaver
  This attribute is read-only.
555 47 Ruud Klaver
 '''method'''::
556 47 Ruud Klaver
  The method of the SIP request as a string.
557 47 Ruud Klaver
  This attribute is set on instantiation and is read-only.
558 47 Ruud Klaver
 '''from_uri'''::
559 47 Ruud Klaver
  The SIP URI to put in the {{{From}}} header of the request, in the form of a {{{SIPURI}}} object.
560 62 Ruud Klaver
  This attribute is set on instantiation and is read-only.
561 47 Ruud Klaver
 '''to_uri'''::
562 47 Ruud Klaver
  The SIP URI to put in the {{{To}}} header of the request, in the form of a {{{SIPURI}}} object.
563 47 Ruud Klaver
  This attribute is set on instantiation and is read-only.
564 47 Ruud Klaver
 '''request_uri'''::
565 47 Ruud Klaver
  The SIP URI to put as request URI in the request, in the form of a {{{SIPURI}}} object.
566 47 Ruud Klaver
  This attribute is set on instantiation and is read-only.
567 1 Adrian Georgescu
 '''route'''::
568 1 Adrian Georgescu
  Where to send the SIP request to, including IP, port and transport, in the form of a {{{SIPURI}}} object.
569 1 Adrian Georgescu
  This will also be included in the {{{Route}}} header of the request.
570 1 Adrian Georgescu
  This attribute is set on instantiation and is read-only.
571 62 Ruud Klaver
 '''credentials'''::
572 62 Ruud Klaver
  The credentials to be used when challenged for authentication, represented by a {{{Credentials}}} object.
573 62 Ruud Klaver
  If no credentials were supplied when the object was created this attribute is {{{None}}}.
574 62 Ruud Klaver
  This attribute is set on instantiation and is read-only.
575 47 Ruud Klaver
 '''contact_uri'''::
576 47 Ruud Klaver
  The SIP URI to put in the {{{Contact}}} header of the request, in the form of a {{{SIPURI}}} object.
577 47 Ruud Klaver
  If this was not specified, this attribute is {{{None}}}.
578 47 Ruud Klaver
  It is set on instantiation and is read-only.
579 47 Ruud Klaver
 '''call_id'''::
580 47 Ruud Klaver
  The {{{Call-ID}}} to be used for this transaction as a string.
581 47 Ruud Klaver
  If no call id was specified on instantiation, this attribute contains the generated id.
582 47 Ruud Klaver
  This attribute is set on instantiation and is read-only.
583 47 Ruud Klaver
 '''cseq'''::
584 47 Ruud Klaver
  The sequence number to use in the request as an int.
585 47 Ruud Klaver
  If no sequence number was specified on instantiation, this attribute contains the generated sequence number.
586 47 Ruud Klaver
  Note that this number may be increased by one if an authentication challenge is received and a {{{Credentials}}} object is given.
587 47 Ruud Klaver
  This attribute is read-only.
588 47 Ruud Klaver
 '''extra_headers'''::
589 47 Ruud Klaver
  Extra headers to include in the request as a dictionary.
590 47 Ruud Klaver
  This attribute is set on instantiation and is read-only.
591 47 Ruud Klaver
 '''content_type'''::
592 47 Ruud Klaver
  What string to put as content type in the {{{Content-Type}}} headers, if the request contains a body.
593 47 Ruud Klaver
  If no body was specified, this attribute is {{{None}}}
594 47 Ruud Klaver
  It is set on instantiation and is read-only.
595 47 Ruud Klaver
 '''body'''::
596 47 Ruud Klaver
  The body of the request as a string.
597 47 Ruud Klaver
  If no body was specified, this attribute is {{{None}}}
598 47 Ruud Klaver
  It is set on instantiation and is read-only.
599 47 Ruud Klaver
 '''expires_in'''::
600 1 Adrian Georgescu
  This read-only property indicates in how many seconds from now this {{{Request}}} will expire, if it is in the {{{EXPIRING}}} state.
601 47 Ruud Klaver
  If this is not the case, this property is 0.
602 47 Ruud Klaver
603 46 Ruud Klaver
==== methods ====
604 46 Ruud Klaver
605 62 Ruud Klaver
 '''!__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}}})::
606 48 Ruud Klaver
  Creates a new {{{Request}}} object in the {{{INIT}}} state.
607 48 Ruud Klaver
  The arguments to this method are documented in the attributes section.
608 48 Ruud Klaver
 '''send'''(''self'', '''timeout'''={{{None}}})::
609 48 Ruud Klaver
   Compose the SIP request and send it to the destination.
610 48 Ruud Klaver
   This moves the {{{Request}}} object into the {{{IN_PROGRESS}}} state.
611 48 Ruud Klaver
  [[BR]]''timeout'':[[BR]]
612 48 Ruud Klaver
  This can be either an int or a float, indicating in how many seconds the request should timeout with an internally generated 408 response.
613 48 Ruud Klaver
  This is is {{{None}}}, the internal 408 is only triggered by the internal PJSIP transaction timeout.
614 48 Ruud Klaver
  Note that, even if the timeout is specified, the PJSIP timeout is also still valid.
615 57 Ruud Klaver
 '''end'''(''self'')::
616 48 Ruud Klaver
  Terminate the transaction, whichever state it is in, sending the appropriate notifications.
617 48 Ruud Klaver
  Note that calling this method while in the {{{INIT}}} state does nothing.
618 48 Ruud Klaver
619 46 Ruud Klaver
==== notifications ====
620 49 Ruud Klaver
621 49 Ruud Klaver
 '''SIPRequestGotProvisionalResponse'''::
622 49 Ruud Klaver
  This notification will be sent on every provisional response received in reply to the sent request.
623 49 Ruud Klaver
  [[BR]]''timestamp'':[[BR]]
624 49 Ruud Klaver
  A {{{datetime.datetime}}} object indicating when the notification was sent.
625 49 Ruud Klaver
  [[BR]]''code'':[[BR]]
626 49 Ruud Klaver
  The SIP response code of the received provisional response as an int, which will be in the 1xx range.
627 49 Ruud Klaver
  [[BR]]''reason'':[[BR]]
628 49 Ruud Klaver
  The reason text string included with the SIP response code.
629 49 Ruud Klaver
  [[BR]]''headers'':[[BR]]
630 49 Ruud Klaver
  The headers included in the provisional response as a dictionary.
631 49 Ruud Klaver
  [[BR]]''body'':[[BR]]
632 49 Ruud Klaver
  The body of the provisional response as a string, or {{{None}}} if there was no body.
633 49 Ruud Klaver
 '''SIPRequestDidSucceed'''::
634 49 Ruud Klaver
  This notification will be sent when a positive final response was received in reply to the request.
635 49 Ruud Klaver
  [[BR]]''timestamp'':[[BR]]
636 49 Ruud Klaver
  A {{{datetime.datetime}}} object indicating when the notification was sent.
637 49 Ruud Klaver
  [[BR]]''code'':[[BR]]
638 49 Ruud Klaver
  The SIP response code of the received positive final response as an int, which will be in the 2xx range.
639 49 Ruud Klaver
  [[BR]]''reason'':[[BR]]
640 49 Ruud Klaver
  The reason text string included with the SIP response code.
641 49 Ruud Klaver
  [[BR]]''headers'':[[BR]]
642 49 Ruud Klaver
  The headers included in the positive final response as a dictionary.
643 49 Ruud Klaver
  [[BR]]''body'':[[BR]]
644 49 Ruud Klaver
  The body of the positive final response as a string, or {{{None}}} if there was no body.
645 49 Ruud Klaver
  [[BR]]''expires'':[[BR]]
646 49 Ruud Klaver
  Indicates in how many seconds the {{{Request}}} will expire as an int.
647 49 Ruud Klaver
  If it does not expire and the {{{EXPIRING}}} state is skipped, this attribute is 0.
648 49 Ruud Klaver
 '''SIPRequestDidFail'''::
649 49 Ruud Klaver
  This notification will be sent when a negative final response is received in reply to the request or if an internal error occurs.
650 49 Ruud Klaver
  [[BR]]''timestamp'':[[BR]]
651 49 Ruud Klaver
  A {{{datetime.datetime}}} object indicating when the notification was sent.
652 49 Ruud Klaver
  [[BR]]''code'':[[BR]]
653 49 Ruud Klaver
  The SIP response code of the received negative final response as an int.
654 49 Ruud Klaver
  This could also be a response code generated by PJSIP internally, or 0 when an internal error occurs.
655 49 Ruud Klaver
  [[BR]]''reason'':[[BR]]
656 49 Ruud Klaver
  The reason text string included with the SIP response code or error.
657 49 Ruud Klaver
  [[BR]]''headers'': (only if a negative final response was received)[[BR]]
658 49 Ruud Klaver
  The headers included in the negative final response as a dictionary, if this is what triggered the notification.
659 49 Ruud Klaver
  [[BR]]''body'': (only if a negative final response was received)[[BR]]
660 49 Ruud Klaver
  The body of the negative final response as a string, or {{{None}}} if there was no body.
661 49 Ruud Klaver
  This attribute is absent if no response was received.
662 49 Ruud Klaver
 '''SIPRequestWillExpire'''::
663 49 Ruud Klaver
  This notification will be sent when a {{{Request}}} in the {{{EXPIRING}}} state will expire soon.
664 49 Ruud Klaver
  [[BR]]''timestamp'':[[BR]]
665 49 Ruud Klaver
  A {{{datetime.datetime}}} object indicating when the notification was sent.
666 49 Ruud Klaver
  [[BR]]''expires'':[[BR]]
667 49 Ruud Klaver
  An int indicating in how many seconds from now the {{{Request}}} will actually expire.
668 49 Ruud Klaver
 '''SIPRequestDidEnd'''::
669 49 Ruud Klaver
  This notification will be sent when a {{{Request}}} object enters the {{{TERMINATED}}} state and can no longer be used.
670 49 Ruud Klaver
  [[BR]]''timestamp'':[[BR]]
671 49 Ruud Klaver
  A {{{datetime.datetime}}} object indicating when the notification was sent.
672 46 Ruud Klaver
673 51 Ruud Klaver
=== Message ===
674 51 Ruud Klaver
675 51 Ruud Klaver
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].
676 51 Ruud Klaver
It is a one-shot object that manages only one {{{Request}}} object.
677 51 Ruud Klaver
678 51 Ruud Klaver
==== attributes ====
679 51 Ruud Klaver
680 64 Ruud Klaver
 '''from_uri'''::
681 64 Ruud Klaver
  The SIP URI to put in the {{{From}}} header of the {{{MESSAGE}}} request, in the form of a {{{SIPURI}}} object.
682 51 Ruud Klaver
  This attribute is set on instantiation and is read-only.
683 51 Ruud Klaver
 '''to_uri'''::
684 51 Ruud Klaver
  The SIP URI to put in the {{{To}}} header of the {{{MESSAGE}}} request, in the form of a {{{SIPURI}}} object.
685 51 Ruud Klaver
  This attribute is set on instantiation and is read-only.
686 51 Ruud Klaver
 '''route'''::
687 51 Ruud Klaver
  Where to send the {{{MESSAGE}}} request to, including IP, port and transport, in the form of a {{{SIPURI}}} object.
688 51 Ruud Klaver
  This will also be included in the {{{Route}}} header of the request.
689 51 Ruud Klaver
  This attribute is set on instantiation and is read-only.
690 51 Ruud Klaver
 '''content_type'''::
691 51 Ruud Klaver
  What string to put as content type in the {{{Content-Type}}} headers.
692 51 Ruud Klaver
  It is set on instantiation and is read-only.
693 51 Ruud Klaver
 '''body'''::
694 51 Ruud Klaver
  The body of the {{{MESSAGE}}} request as a string.
695 1 Adrian Georgescu
  If no body was specified, this attribute is {{{None}}}
696 1 Adrian Georgescu
  It is set on instantiation and is read-only.
697 64 Ruud Klaver
 '''credentials'''::
698 64 Ruud Klaver
  The credentials to be used when challenged for authentication, represented by a {{{Credentials}}} object.
699 64 Ruud Klaver
  If no credentials were specified, this attribute is {{{None}}}.
700 64 Ruud Klaver
  This attribute is set on instantiation and is read-only.
701 51 Ruud Klaver
 '''is_sent'''::
702 51 Ruud Klaver
  A boolean read-only property indicating if the {{{MESSAGE}}} request was sent.
703 51 Ruud Klaver
 '''in_progress'''::
704 51 Ruud Klaver
  A boolean read-only property indicating if the object is waiting for the response from the remote party.
705 51 Ruud Klaver
706 51 Ruud Klaver
==== methods ====
707 51 Ruud Klaver
708 51 Ruud Klaver
 '''!__init!__'''(''self'', '''credentials''', '''to_uri''', '''route''', '''content_type''', '''body''')::
709 51 Ruud Klaver
  Creates a new {{{Message}}} object with the specified arguments.
710 51 Ruud Klaver
  These arguments are documented in the attributes section for this class.
711 51 Ruud Klaver
 '''send'''(''self'', '''timeout'''={{{None}}})::
712 51 Ruud Klaver
  Send the {{{MESSAGE}}} request to the remote party.
713 51 Ruud Klaver
  [[BR]]''timeout'':[[BR]]
714 51 Ruud Klaver
  This argument as the same meaning as it does for {{{Request.send()}}}.
715 51 Ruud Klaver
 '''end'''(''self'')::
716 51 Ruud Klaver
  Stop trying to send the {{{MESSAGE}}} request.
717 51 Ruud Klaver
  If it was not sent yet, calling this method does nothing.
718 51 Ruud Klaver
719 51 Ruud Klaver
==== notifications ====
720 51 Ruud Klaver
721 51 Ruud Klaver
 '''SIPMessageDidSucceed'''::
722 51 Ruud Klaver
  This notification will be sent when the remote party acknowledged the reception of the {{{MESSAGE}}} request.
723 52 Ruud Klaver
  It has not data attributes.
724 51 Ruud Klaver
 '''SIPMessageDidFail'''::
725 51 Ruud Klaver
  This notification will be sent when transmission of the {{{MESSAGE}}} request fails for whatever reason.
726 51 Ruud Klaver
  [[BR]]''code'':[[BR]]
727 1 Adrian Georgescu
  An int indicating the SIP or internal PJSIP code that was given in response to the {{{MESSAGE}}} request.
728 1 Adrian Georgescu
  This is 0 if the failure is caused by an internal error.
729 1 Adrian Georgescu
  [[BR]]''reason'':[[BR]]
730 1 Adrian Georgescu
  A status string describing the failure, either taken from the SIP response or the internal error.
731 52 Ruud Klaver
732 52 Ruud Klaver
=== Registration ===
733 52 Ruud Klaver
734 52 Ruud Klaver
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.
735 52 Ruud Klaver
For details, see [http://tools.ietf.org/html/rfc3261 RFC 3261].
736 52 Ruud Klaver
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.
737 1 Adrian Georgescu
The application should then perform a DNS lookup to find the relevant SIP registrar and call the {{{register()}}} method on this object.
738 1 Adrian Georgescu
739 52 Ruud Klaver
==== attributes ====
740 69 Ruud Klaver
741 64 Ruud Klaver
 '''uri''::
742 64 Ruud Klaver
  The SIP URI of the account the {{{Registration}}} is for in the form of a {{{SIPURI}}} object.
743 52 Ruud Klaver
 '''credentials'''::
744 64 Ruud Klaver
  The credentials to be used when challenged for authentication by the registrar, represented by a {{{Credentials}}} object. 
745 64 Ruud Klaver
  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.
746 52 Ruud Klaver
  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.
747 52 Ruud Klaver
 '''duration'''::
748 52 Ruud Klaver
  The amount of time in seconds to request the registration for at the registrar.
749 52 Ruud Klaver
  This attribute is set at object instantiation and can be updated for subsequent {{{REGISTER}}} requests.
750 52 Ruud Klaver
 '''is_registered'''::
751 52 Ruud Klaver
  A boolean read-only property indicating if this object is currently registered.
752 52 Ruud Klaver
 '''contact_uri'''::
753 52 Ruud Klaver
  If the {{{Registration}}} object is registered, this attribute contains the latest contact URI that was sent to the registrar as a {{{SIPURI}}} object.
754 1 Adrian Georgescu
  Otherwise, this attribute is {{{None}}}
755 52 Ruud Klaver
 '''expires_in'''::
756 52 Ruud Klaver
  If registered, this read-only property indicates in how many seconds from now this {{{Registration}}} will expire.
757 52 Ruud Klaver
  If this is not the case, this property is 0.
758 52 Ruud Klaver
759 52 Ruud Klaver
==== methods ====
760 52 Ruud Klaver
761 64 Ruud Klaver
 '''!__init!__'''(''self'', '''uri''', '''credentials'''={{{None}}}, '''duration'''=300)::
762 52 Ruud Klaver
  Creates a new {{{Registration}}} object with the specified arguments.
763 52 Ruud Klaver
  These arguments are documented in the attributes section for this class.
764 52 Ruud Klaver
 '''register'''(''self'', '''contact_uri''', '''route''', '''timeout'''={{{None}}})::
765 52 Ruud Klaver
  Calling this method will attempt to send a new {{{REGISTER}}} request to the registrar provided, whatever state the object is in.
766 52 Ruud Klaver
  If the object is currently busy sending a {{{REGISTER}}}, this request will be preempted for the new one.
767 52 Ruud Klaver
  Once sent, the {{{Registration}}} object will send either a {{{SIPRegistrationDidSucceed}}} or a {{{SIPRegistrationDidFail}}} notification.
768 58 Ruud Klaver
  The {{{contact_uri}}} argument is mentioned in the attributes section of this class.
769 52 Ruud Klaver
  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()}}}.
770 52 Ruud Klaver
 '''end'''(''self'', '''timeout'''={{{None}}})::
771 52 Ruud Klaver
  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.
772 52 Ruud Klaver
  The {{{Route}}} used for this will be the same as the last successfully sent {{{REGISTER}}} request.
773 52 Ruud Klaver
  If another {{{REGISTER}}} is currently being sent, it will be preempted.
774 71 Adrian Georgescu
  When the unregistering {{{REGISTER}}} request is sent, a {{{SIPRegistrationWillEnd}}} notification is sent.
775 52 Ruud Klaver
  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.
776 52 Ruud Klaver
  Calling this method when the object is not registered will do nothing.
777 52 Ruud Klaver
  The {{{timeout}}} argument has the same meaning as for the {{{register()}}} method.
778 52 Ruud Klaver
779 52 Ruud Klaver
==== notifications ====
780 52 Ruud Klaver
781 52 Ruud Klaver
 '''SIPRegistrationDidSucceed'''::
782 52 Ruud Klaver
  This notification will be sent when the {{{register()}}} method was called and the registration succeeded.
783 52 Ruud Klaver
  [[BR]]''code'':[[BR]]
784 52 Ruud Klaver
  The SIP response code as received from the registrar as an int.
785 52 Ruud Klaver
  [[BR]]''reason'':[[BR]]
786 52 Ruud Klaver
  The reason string received from the SIP registrar.
787 52 Ruud Klaver
  [[BR]]''route'':[[BR]]
788 52 Ruud Klaver
  The {{{Route}}} object passed as an argument to the {{{register()}}} method.
789 52 Ruud Klaver
  [[BR]]''contact_uri'':[[BR]]
790 52 Ruud Klaver
  The contact URI that was sent to the registrar as a {{{SIPURI}}} object.
791 52 Ruud Klaver
  [[BR]]''contact_uri_list'':[[BR]]
792 52 Ruud Klaver
  A full list of contact URIs that are registered for this SIP account, including the one used for this registration.
793 52 Ruud Klaver
  The format of this data attribute is a list of 2-item tuples.
794 52 Ruud Klaver
  The first item is a SIP URI indicating the contact URI, the second item is a dictionary of additional parameters, including the {{{expires}}} parameter.
795 52 Ruud Klaver
  [[BR]]''expires_in'':[[BR]]
796 52 Ruud Klaver
  The number of seconds before this registration expires
797 52 Ruud Klaver
 '''SIPRegistrationDidFail'''::
798 52 Ruud Klaver
  This notification will be sent when the {{{register()}}} method was called and the registration failed, for whatever reason.
799 52 Ruud Klaver
  [[BR]]''code'':[[BR]]
800 52 Ruud Klaver
  The SIP response code as received from the registrar as an int.
801 52 Ruud Klaver
  This can also be a PJSIP generated response code, or 0 if the failure was because of an internal error.
802 52 Ruud Klaver
  [[BR]]''reason'':[[BR]]
803 52 Ruud Klaver
  The reason string received from the SIP registrar or the error string.
804 52 Ruud Klaver
  [[BR]]''route'':[[BR]]
805 52 Ruud Klaver
  The {{{Route}}} object passed as an argument to the {{{register()}}} method.
806 52 Ruud Klaver
 '''SIPRegistrationWillExpire'''::
807 52 Ruud Klaver
  This notification will be sent when a registration will expire soon.
808 1 Adrian Georgescu
  It should be used as an indication to re-perform DNS lookup of the registrar and call the {{{register()}}} method.
809 69 Ruud Klaver
  [[BR]]''expires'':[[BR]]
810 58 Ruud Klaver
  The number of seconds in which the registration will expire.
811 52 Ruud Klaver
 '''SIPRegistrationWillEnd'''::
812 52 Ruud Klaver
  Will be sent whenever the {{{end()}}} method was called and an unregistering {{{REGISTER}}} is sent.
813 52 Ruud Klaver
 '''SIPRegistrationDidNotEnd'''::
814 52 Ruud Klaver
  This notification will be sent when the unregistering {{{REGISTER}}} request failed for some reason.
815 52 Ruud Klaver
  [[BR]]''code'':[[BR]]
816 52 Ruud Klaver
  The SIP response code as received from the registrar as an int.
817 52 Ruud Klaver
  This can also be a PJSIP generated response code, or 0 if the failure was because of an internal error.
818 52 Ruud Klaver
  [[BR]]''reason'':[[BR]]
819 52 Ruud Klaver
  The reason string received from the SIP registrar or the error string.
820 52 Ruud Klaver
 '''SIPRegistrationDidEnd'''::
821 52 Ruud Klaver
  This notification will be sent when a {{{Registration}}} has become unregistered.
822 58 Ruud Klaver
  [[BR]]''expired'':[[BR]]
823 52 Ruud Klaver
  This boolean indicates if the object is unregistered because the registration expired, in which case it will be set to {{{True}}}.
824 52 Ruud Klaver
  If this data attribute is {{{False}}}, it means that unregistration was explicitly requested through the {{{end()}}} method.
825 52 Ruud Klaver
826 52 Ruud Klaver
==== example code ====
827 51 Ruud Klaver
828 1 Adrian Georgescu
For an example on how to use this object, see the Integration section.
829 1 Adrian Georgescu
830 1 Adrian Georgescu
=== Publication ===
831 1 Adrian Georgescu
832 1 Adrian Georgescu
Publication of SIP events is an Internet standard published at [http://tools.ietf.org/html/rfc3903 RFC 3903]. 
833 70 Ruud Klaver
{{{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.
834 1 Adrian Georgescu
835 69 Ruud Klaver
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.
836 69 Ruud Klaver
This object is similar in behaviour to the {{{Registration}}} object, as it is also based on a sequence of {{{Request}}} objects.
837 69 Ruud Klaver
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.
838 1 Adrian Georgescu
839 1 Adrian Georgescu
==== attributes ====
840 1 Adrian Georgescu
841 69 Ruud Klaver
 '''uri''::
842 69 Ruud Klaver
  The SIP URI of the account the {{{Publication}}} is for in the form of a {{{SIPURI}}} object.
843 69 Ruud Klaver
 '''event''::
844 69 Ruud Klaver
  The name of the event this object is publishing for the specified SIP URI, as a string.
845 69 Ruud Klaver
 '''content_type''::
846 69 Ruud Klaver
  The {{{Content-Type}}} of the body that will be in the {{{PUBLISH}}} requests.
847 69 Ruud Klaver
  Typically this will remain the same throughout the publication session, but the attribute may be updated by the application if needed.
848 69 Ruud Klaver
  Note that this attribute needs to be in the typical MIME type form, containing a "/" character.
849 1 Adrian Georgescu
 '''credentials'''::
850 69 Ruud Klaver
  The credentials to be used when challenged for authentication by the presence agent, represented by a {{{Credentials}}} object. 
851 69 Ruud Klaver
  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.
852 69 Ruud Klaver
  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.
853 69 Ruud Klaver
 '''duration'''::
854 69 Ruud Klaver
  The amount of time in seconds that the publication should be valid for.
855 69 Ruud Klaver
  This attribute is set at object instantiation and can be updated for subsequent {{{PUBLISH}}} requests.
856 69 Ruud Klaver
 '''is_published'''::
857 69 Ruud Klaver
  A boolean read-only property indicating if this object is currently published.
858 69 Ruud Klaver
 '''expires_in'''::
859 69 Ruud Klaver
  If published, this read-only property indicates in how many seconds from now this {{{Publication}}} will expire.
860 69 Ruud Klaver
  If this is not the case, this property is 0.
861 1 Adrian Georgescu
862 1 Adrian Georgescu
==== methods ====
863 1 Adrian Georgescu
864 69 Ruud Klaver
 '''!__init!__'''(''self'', '''uri''', '''event''', '''content_type''', '''credentials'''={{{None}}}, '''duration'''=300)::
865 69 Ruud Klaver
  Creates a new {{{Publication}}} object with the specified arguments.
866 69 Ruud Klaver
  These arguments are documented in the attributes section for this class.
867 69 Ruud Klaver
 '''publish'''(''self'', '''body''', '''route''', '''timeout'''={{{None}}})::
868 69 Ruud Klaver
  Send an actual {{{PUBLISH}}} request to the specified presence agent.
869 69 Ruud Klaver
  [[BR]]''body'':[[BR]]
870 69 Ruud Klaver
  The body to place in the {{{PUBLISH}}} request as a string.
871 69 Ruud Klaver
  This body needs to be of the content type specified at object creation.
872 69 Ruud Klaver
  For the initial request, a body will need to be specified.
873 69 Ruud Klaver
  For subsequent refreshing {{{PUBLISH}}} requests, the body can be {{{None}}} to indicate that the last published body should be refreshed.
874 69 Ruud Klaver
  If there was an ETag error with the previous refreshing {{{PUBLISH}}}, calling this method with a body of {{{None}}} will throw a {{{PublicationError}}}.
875 1 Adrian Georgescu
  [[BR]]''route'':[[BR]]
876 69 Ruud Klaver
  The host where the request should be sent to in the form of a {{{Route}}} object.
877 69 Ruud Klaver
  [[BR]]''timeout'':[[BR]]
878 69 Ruud Klaver
  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.
879 69 Ruud Klaver
  This is is {{{None}}}, the internal 408 is only triggered by the internal PJSIP transaction timeout.
880 69 Ruud Klaver
  Note that, even if the timeout is specified, the PJSIP timeout is also still valid.
881 69 Ruud Klaver
 '''end'''(''self'', '''timeout'''={{{None}}})::
882 69 Ruud Klaver
  End the publication by sending a {{{PUBLISH}}} request with an {{{Expires}}} header of 0.
883 69 Ruud Klaver
  If the object is not published, this will result in a {{{PublicationError}}} being thrown.
884 69 Ruud Klaver
  [[BR]]''timeout'':[[BR]]
885 69 Ruud Klaver
  The meaning of this argument is the same as it is for the {{{publish()}}} method.
886 1 Adrian Georgescu
887 1 Adrian Georgescu
==== notifications ====
888 1 Adrian Georgescu
889 69 Ruud Klaver
 '''SIPPublicationDidSucceed'''::
890 69 Ruud Klaver
  This notification will be sent when the {{{publish()}}} method was called and the publication succeeded.
891 69 Ruud Klaver
  [[BR]]''code'':[[BR]]
892 69 Ruud Klaver
  The SIP response code as received from the SIP presence agent as an int.
893 69 Ruud Klaver
  [[BR]]''reason'':[[BR]]
894 69 Ruud Klaver
  The reason string received from the SIP presence agent.
895 69 Ruud Klaver
  [[BR]]''route'':[[BR]]
896 69 Ruud Klaver
  The {{{Route}}} object passed as an argument to the {{{publish()}}} method.
897 69 Ruud Klaver
  [[BR]]''expires_in'':[[BR]]
898 69 Ruud Klaver
  The number of seconds before this publication expires
899 69 Ruud Klaver
 '''SIPPublicationDidFail'''::
900 69 Ruud Klaver
  This notification will be sent when the {{{publish()}}} method was called and the publication failed, for whatever reason.
901 69 Ruud Klaver
  [[BR]]''code'':[[BR]]
902 69 Ruud Klaver
  The SIP response code as received from the presence agent as an int.
903 69 Ruud Klaver
  This can also be a PJSIP generated response code, or 0 if the failure was because of an internal error.
904 69 Ruud Klaver
  [[BR]]''reason'':[[BR]]
905 69 Ruud Klaver
  The reason string received from the presence agent or the error string.
906 69 Ruud Klaver
  [[BR]]''route'':[[BR]]
907 69 Ruud Klaver
  The {{{Route}}} object passed as an argument to the {{{publish()}}} method.
908 69 Ruud Klaver
 '''SIPPublicationWillExpire'''::
909 69 Ruud Klaver
  This notification will be sent when a publication will expire soon.
910 69 Ruud Klaver
  It should be used as an indication to re-perform DNS lookup of the presence agent and call the {{{publish()}}} method.
911 69 Ruud Klaver
  [[BR]]''expires'':[[BR]]
912 69 Ruud Klaver
  The number of seconds in which the publication will expire.
913 69 Ruud Klaver
 '''SIPPublicationWillEnd'''::
914 69 Ruud Klaver
  Will be sent whenever the {{{end()}}} method was called and an unpublishing {{{PUBLISH}}} is sent.
915 69 Ruud Klaver
 '''SIPPublicationDidNotEnd'''::
916 69 Ruud Klaver
  This notification will be sent when the unpublishing {{{PUBLISH}}} request failed for some reason.
917 69 Ruud Klaver
  [[BR]]''code'':[[BR]]
918 69 Ruud Klaver
  The SIP response code as received from the presence agent as an int.
919 69 Ruud Klaver
  This can also be a PJSIP generated response code, or 0 if the failure was because of an internal error.
920 69 Ruud Klaver
  [[BR]]''reason'':[[BR]]
921 69 Ruud Klaver
  The reason string received from the presence agent or the error string.
922 69 Ruud Klaver
 '''SIPPublicationDidEnd'''::
923 69 Ruud Klaver
  This notification will be sent when a {{{Publication}}} has become unpublished.
924 69 Ruud Klaver
  [[BR]]''expired'':[[BR]]
925 69 Ruud Klaver
  This boolean indicates if the object is unpublished because the publication expired, in which case it will be set to {{{True}}}.
926 69 Ruud Klaver
  If this data attribute is {{{False}}}, it means that unpublication was explicitly requested through the {{{end()}}} method.
927 1 Adrian Georgescu
928 1 Adrian Georgescu
=== Subscription ===
929 1 Adrian Georgescu
930 1 Adrian Georgescu
Subscription and notifications for SIP events is an Internet standard published at [http://tools.ietf.org/html/rfc3856 RFC 3856].
931 1 Adrian Georgescu
932 59 Ruud Klaver
This SIP primitive class represents a subscription to a specific event type of a particular SIP URI.
933 1 Adrian Georgescu
This means that the application should instance this class for each combination of event and SIP URI that it wishes to subscribe to.
934 1 Adrian Georgescu
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.
935 1 Adrian Georgescu
Whenever a {{{NOTIFY}}} is received, the application will receive the {{{SIPSubscriptionGotNotify}}} event.
936 1 Adrian Georgescu
937 1 Adrian Georgescu
Internally a {{{Subscription}}} object has a state machine, which reflects the state of the subscription.
938 59 Ruud Klaver
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}}}.
939 59 Ruud Klaver
The last three states are directly copied from the contents of the {{{Subscription-State}}} header of the received {{{NOTIFY}}} request.
940 1 Adrian Georgescu
Also, the state can be an arbitrary string if the contents of the {{{Subscription-State}}} header are not one of the three above.
941 1 Adrian Georgescu
The state of the object is presented in the {{{state}}} attribute and changes of the state are indicated by means of the {{{SIPSubscriptionChangedState}}} notification.
942 1 Adrian Georgescu
This notification is only informational, an application using this object should take actions based on the other notifications sent by this object.
943 1 Adrian Georgescu
944 1 Adrian Georgescu
==== attributes ====
945 1 Adrian Georgescu
946 59 Ruud Klaver
 '''state'''::
947 59 Ruud Klaver
  Indicates which state the internal state machine is in.
948 1 Adrian Georgescu
  See the previous section for a list of states the state machine can be in.
949 1 Adrian Georgescu
 '''from_uri'''::
950 71 Adrian Georgescu
  The SIP URI to be put in the {{{From}}} header of the {{{SUBSCRIBE}}} requests in the form of a {{{SIPURI}}} object.
951 1 Adrian Georgescu
  This attribute is set on object instantiation and is read-only.
952 59 Ruud Klaver
 '''to_uri'''::
953 59 Ruud Klaver
  The SIP URI that is the target for the subscription in the form of a {{{SIPURI}}} object.
954 59 Ruud Klaver
  This attribute is set on object instantiation and is read-only.
955 1 Adrian Georgescu
 '''contact_uri'''::
956 71 Adrian Georgescu
  The SIP URI to be put in the {{{Contact}}} header of the {{{SUBSCRIBE}}} requests in the form of a {{{SIPURI}}} object.
957 1 Adrian Georgescu
  This attribute is set on object instantiation and is read-only.
958 1 Adrian Georgescu
 '''event'''::
959 1 Adrian Georgescu
  The event package for which the subscription is as a string.
960 1 Adrian Georgescu
  This attribute is set on object instantiation and is read-only.
961 59 Ruud Klaver
 '''route'''::
962 59 Ruud Klaver
  The outbound proxy to use in the form of a {{{Route}}} object.
963 59 Ruud Klaver
  This attribute is set on object instantiation and is read-only.
964 1 Adrian Georgescu
 '''credentials'''::
965 59 Ruud Klaver
  The SIP credentials needed to authenticate at the SIP proxy in the form of a {{{Credentials}}} object.
966 59 Ruud Klaver
  If none was specified when creating the {{{Subscription}}} object, this attribute is {{{None}}}.
967 59 Ruud Klaver
  This attribute is set on object instantiation and is read-only.
968 59 Ruud Klaver
 '''refresh'''::
969 59 Ruud Klaver
  The refresh interval in seconds that was requested on object instantiation as an int.
970 59 Ruud Klaver
  This attribute is set on object instantiation and is read-only.
971 59 Ruud Klaver
 '''extra_headers'''::
972 59 Ruud Klaver
  This contains the dictionary of extra headers that was last passed to a successful call to the {{{subscribe()}}} method.
973 59 Ruud Klaver
  If the argument was not provided, this attribute is an empty dictionary.
974 59 Ruud Klaver
  This attribute is read-only.
975 59 Ruud Klaver
 '''content_type'''::
976 59 Ruud Klaver
  This attribute contains the {{{Content-Type}}} of the body that was last passed to a successful call to the {{{subscribe()}}} method.
977 59 Ruud Klaver
  If the argument was not provided, this attribute is {{{None}}}.
978 1 Adrian Georgescu
 '''body'''::
979 1 Adrian Georgescu
  This attribute contains the {{{body}}} string argument that was last passed to a successful call to the {{{subscribe()}}} method.
980 1 Adrian Georgescu
  If the argument was not provided, this attribute is {{{None}}}.
981 59 Ruud Klaver
982 59 Ruud Klaver
==== methods ====
983 59 Ruud Klaver
984 59 Ruud Klaver
 '''!__init!__'''(''self'', '''from_uri''', '''to_uri''', '''contact_uri, '''event''', '''route''', '''credentials'''={{{None}}}, '''refresh'''=300)::
985 59 Ruud Klaver
  Creates a new {{{Subscription}}} object which will be in the {{{NULL}}} state.
986 59 Ruud Klaver
  The arguments for this method are documented in the attributes section above.
987 59 Ruud Klaver
 '''subscribe'''(''self'', '''extra_headers'''={{{None}}}, '''content_type'''={{{None}}}, '''body'''={{{None}}}, '''timeout'''={{{None}}})::
988 59 Ruud Klaver
  Calling this method triggers sending a {{{SUBSCRIBE}}} request to the presence agent.
989 1 Adrian Georgescu
  The arguments passed will be stored and used for subsequent refreshing {{{SUBSCRIBE}}} requests.
990 59 Ruud Klaver
  This method may be used both to send the initial request and to update the arguments while the subscription is ongoing.
991 59 Ruud Klaver
  It may not be called when the object is in the {{{TERMINATED}}} state.
992 59 Ruud Klaver
  [[BR]]''extra_headers'':[[BR]]
993 59 Ruud Klaver
  A dictionary of additional headers to include in the {{{SUBSCRIBE}}} requests.
994 59 Ruud Klaver
  [[BR]]''content_type'':[[BR]]
995 59 Ruud Klaver
  The {{{Content-Type}}} of the supplied {{{body}}} argument as a string.
996 59 Ruud Klaver
  If this argument is supplied, the {{{body}}} argument cannot be {{{None}}}.
997 59 Ruud Klaver
  [[BR]]''body'':[[BR]]
998 59 Ruud Klaver
  The optional body to include in the {{{SUBSCRIBE}}} request as a string.
999 59 Ruud Klaver
  If this argument is supplied, the {{{content_type}}} argument cannot be {{{None}}}.
1000 59 Ruud Klaver
  [[BR]]''timeout'':[[BR]]
1001 59 Ruud Klaver
  This can be either an int or a float, indicating in how many seconds the request should timeout with an internally generated 408 response.
1002 59 Ruud Klaver
  If this is {{{None}}}, the internal 408 is only triggered by the internal PJSIP transaction timeout.
1003 59 Ruud Klaver
  Note that, even if the timeout is specified, the PJSIP timeout is also still valid.
1004 59 Ruud Klaver
 '''end'''(''self'', '''timeout'''={{{None}}})::
1005 59 Ruud Klaver
  This will end the subscription by sending a {{{SUBSCRIBE}}} request with an {{{Expires}}} value of 0.
1006 1 Adrian Georgescu
  If this object is no longer subscribed, this method will return without performing any action.
1007 1 Adrian Georgescu
  This method cannot be called when the object is in the {{{NULL}}} state.
1008 1 Adrian Georgescu
  The {{{timeout}}} argument has the same meaning as it does for the {{{subscribe()}}} method.
1009 1 Adrian Georgescu
1010 1 Adrian Georgescu
==== notifications ====
1011 1 Adrian Georgescu
1012 1 Adrian Georgescu
 '''SIPSubscriptionChangedState'''::
1013 59 Ruud Klaver
  This notification will be sent every time the internal state machine of a {{{Subscription}}} object changes state.
1014 59 Ruud Klaver
  [[BR]]''timestamp'':[[BR]]
1015 1 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1016 1 Adrian Georgescu
  [[BR]]''prev_state'':[[BR]]
1017 59 Ruud Klaver
  The previous state that the sate machine was in.
1018 59 Ruud Klaver
  [[BR]]''state'':[[BR]]
1019 59 Ruud Klaver
  The new state the state machine moved into.
1020 59 Ruud Klaver
 '''SIPSubscriptionWillStart'''::
1021 59 Ruud Klaver
  This notification will be emitted when the initial {{{SUBSCRIBE}}} request is sent.
1022 59 Ruud Klaver
  [[BR]]''timestamp'':[[BR]]
1023 59 Ruud Klaver
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1024 59 Ruud Klaver
 '''SIPSubscriptionDidStart'''::
1025 29 Luci Stanescu
  This notification will be sent when the initial {{{SUBSCRIBE}}} was accepted by the presence agent.
1026 29 Luci Stanescu
  [[BR]]''timestamp'':[[BR]]
1027 59 Ruud Klaver
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1028 1 Adrian Georgescu
 '''SIPSubscriptionGotNotify'''::
1029 1 Adrian Georgescu
  This notification will be sent when a {{{NOTIFY}}} is received that corresponds to a particular {{{Subscription}}} object.
1030 59 Ruud Klaver
  Note that this notification could be sent when a {{{NOTIFY}}} without a body is received.
1031 59 Ruud Klaver
  [[BR]]''timestamp'':[[BR]]
1032 59 Ruud Klaver
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1033 59 Ruud Klaver
  [[BR]]''method'':[[BR]]
1034 59 Ruud Klaver
  The method of the SIP request as a string.
1035 59 Ruud Klaver
  This will always be {{{NOTIFY}}}.
1036 59 Ruud Klaver
  [[BR]]''request_uri'':[[BR]]
1037 59 Ruud Klaver
  The request URI of the {{{NOTIFY}}} request as a {{{SIPURI}}} object.
1038 59 Ruud Klaver
  [[BR]]''headers'':[[BR]]
1039 1 Adrian Georgescu
  The headers of the {{{NOTIFY}}} request as a dict.
1040 59 Ruud Klaver
  Each SIP header is represented in its parsed for as long as PJSIP supports it.
1041 59 Ruud Klaver
  The format of the parsed value depends on the header.
1042 59 Ruud Klaver
  [[BR]]''body'':[[BR]]
1043 59 Ruud Klaver
  The body of the {{{NOTIFY}}} request as a string, or {{{None}}} if no body was included.
1044 59 Ruud Klaver
  The content type of the body can be learned from the {{{Content-Type}}} header in the headers data attribute.
1045 59 Ruud Klaver
 '''SIPSubscriptionDidFail'''::
1046 59 Ruud Klaver
  This notification will be sent whenever there is a failure, such as a rejected initial or refreshing {{{SUBSCRIBE}}}.
1047 59 Ruud Klaver
  After this notification the {{{Subscription}}} object is in the {{{TERMINATED}}} state and can no longer be used.
1048 59 Ruud Klaver
  [[BR]]''timestamp'':[[BR]]
1049 59 Ruud Klaver
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1050 59 Ruud Klaver
  [[BR]]''code'':[[BR]]
1051 59 Ruud Klaver
  An integer SIP code from the fatal response that was received from the remote party of generated by PJSIP.
1052 59 Ruud Klaver
  If the error is internal to the SIP core, this attribute will have a value of 0.
1053 59 Ruud Klaver
  [[BR]]''reason'':[[BR]]
1054 71 Adrian Georgescu
  An text string describing the failure that occurred.
1055 59 Ruud Klaver
 '''SIPSubscriptionDidEnd'''::
1056 59 Ruud Klaver
  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.
1057 1 Adrian Georgescu
  After this notification the {{{Subscription}}} object is in the {{{TERMINATED}}} state and can no longer be used.
1058 56 Ruud Klaver
  [[BR]]''timestamp'':[[BR]]
1059 1 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1060 1 Adrian Georgescu
1061 1 Adrian Georgescu
=== Invitation ===
1062 29 Luci Stanescu
1063 1 Adrian Georgescu
The {{{Invitation}}} class represents an {{{INVITE}}} session, which governs a complete session of media exchange between two SIP endpoints from start to finish.
1064 1 Adrian Georgescu
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.
1065 1 Adrian Georgescu
The {{{Invitation}}} class represents both incoming and outgoing sessions.
1066 29 Luci Stanescu
1067 1 Adrian Georgescu
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.
1068 1 Adrian Georgescu
In order to represent re-{{{INVITE}}}s and user-requested disconnections, three more states have been added to this state machine.
1069 1 Adrian Georgescu
The progression through this state machine is fairly linear and is dependent on whether this is an incoming or an outgoing session.
1070 1 Adrian Georgescu
State changes are triggered either by incoming or by outgoing SIP requests and responses.
1071 1 Adrian Georgescu
The states and the transitions between them are shown in the following diagram:
1072 1 Adrian Georgescu
1073 1 Adrian Georgescu
[[Image(sipsimple-core-invite-state-machine.png, nolink)]]
1074 1 Adrian Georgescu
1075 1 Adrian Georgescu
The state changes of this machine are triggered by the following:
1076 1 Adrian Georgescu
 1. An {{{Invitation}}} object is newly created, either by the application for an outgoing session, or by the core for an incoming session.
1077 1 Adrian Georgescu
 2. The application requested an outgoing session by calling the {{{send_invite()}}} method and and initial {{{INVITE}}} request is sent.
1078 1 Adrian Georgescu
 3. A new incoming session is received by the core.
1079 1 Adrian Georgescu
    The application should look out for state change to this state in order to be notified of new incoming sessions.
1080 1 Adrian Georgescu
 4. A provisional response (1xx) is received from the remove party.
1081 1 Adrian Georgescu
 5. A provisional response (1xx) is sent to the remote party, after the application called the {{{respond_to_invite_provisionally()}}} method.
1082 1 Adrian Georgescu
 6. A positive final response (2xx) is received from the remote party.
1083 1 Adrian Georgescu
 7. A positive final response (2xx) is sent to the remote party, after the application called the {{{accept_invite()}}} method.
1084 1 Adrian Georgescu
 8. A positive final response (2xx) is sent or received, depending on the orientation of the session.
1085 1 Adrian Georgescu
 9. An {{{ACK}}} is sent or received, depending on the orientation of the session.
1086 1 Adrian Georgescu
    If the {{{ACK}}} is sent from the local to the remote party, it is initiated by PJSIP, not by a call from the application.
1087 1 Adrian Georgescu
 10. The local party sent a re-{{{INVITE}}} to the remote party by calling the {{{send_reinvite()}}} method.
1088 1 Adrian Georgescu
 11. The remote party has sent a final response to the re-{{{INVITE}}}.
1089 1 Adrian Georgescu
 12. The remote party has sent a re-{{{INVITE}}}.
1090 1 Adrian Georgescu
 13. The local party has responded to the re-{{{INVITE}}} by calling the {{{respond_to_reinvite()}}} method.
1091 1 Adrian Georgescu
 14. The application requests that the session ends by calling the {{{end()}}} method.
1092 1 Adrian Georgescu
 15. A response is received from the remote party to whichever message was sent by the local party to end the session.
1093 1 Adrian Georgescu
 16. A message is received from the remote party which ends the session.
1094 1 Adrian Georgescu
1095 1 Adrian Georgescu
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.
1096 1 Adrian Georgescu
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.
1097 1 Adrian Georgescu
The application should compare the previous and current states and perform the appropriate action.
1098 1 Adrian Georgescu
1099 1 Adrian Georgescu
An {{{Invitiation}}} object also emits the {{{SIPInvitationGotSDPUpdate}}} notification, which indicates that SDP negotiation between the two parties has been completed.
1100 1 Adrian Georgescu
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.
1101 1 Adrian Georgescu
In the last case, the {{{Invitation}}} object will automatically include the current local SDP in the response.
1102 1 Adrian Georgescu
1103 1 Adrian Georgescu
==== attributes ====
1104 1 Adrian Georgescu
1105 33 Ruud Klaver
 '''state'''::
1106 33 Ruud Klaver
  The state the {{{Invitation}}} state machine is currently in.
1107 33 Ruud Klaver
  See the diagram above for possible states.
1108 33 Ruud Klaver
  This attribute is read-only.
1109 33 Ruud Klaver
 '''is_outgoing'''::
1110 1 Adrian Georgescu
  Boolean indicating if the original {{{INVITE}}} was outgoing, or incoming if set to {{{False}}}.
1111 63 Ruud Klaver
 '''credentials'''::
1112 1 Adrian Georgescu
  The SIP credentials needed to authenticate at the SIP proxy in the form of a {{{Credentials}}} object.
1113 60 Ruud Klaver
  If this {{{Invitation}}} object represents an incoming {{{INVITE}}} session this attribute will be {{{None}}}.
1114 1 Adrian Georgescu
  On an outgoing session this attribute will be {{{None}}} if it was not specified when the object was created.
1115 63 Ruud Klaver
  This attribute is set on object instantiation and is read-only.
1116 1 Adrian Georgescu
 '''from_uri'''::
1117 22 Ruud Klaver
  The SIP URI of the caller represented by a {{{SIPURI}}} object.
1118 60 Ruud Klaver
  If this is an outgoing {{{INVITE}}} session, this is the from_uri from the !__init!__ method.
1119 1 Adrian Georgescu
  Otherwise the URI is taken from the {{{From:}}} header of the initial {{{INVITE}}}.
1120 60 Ruud Klaver
  This attribute is set on object instantiation and is read-only.
1121 1 Adrian Georgescu
 '''to_uri'''::
1122 1 Adrian Georgescu
  The SIP URI of the callee represented by a {{{SIPURI}}} object.
1123 1 Adrian Georgescu
  If this is an outgoing {{{INVITE}}} session, this is the to_uri from the !__init!__ method.
1124 33 Ruud Klaver
  Otherwise the URI is taken from the {{{To:}}} header of the initial {{{INVITE}}}.
1125 60 Ruud Klaver
  This attribute is set on object instantiation and is read-only.
1126 33 Ruud Klaver
 '''local_uri'''::
1127 1 Adrian Georgescu
  The local SIP URI used in this session.
1128 60 Ruud Klaver
  If the original {{{INVITE}}} was incoming, this is the same as {{{to_uri}}}, otherwise it will be the same as {{{from_uri}}}.
1129 1 Adrian Georgescu
 '''remote_uri'''::
1130 1 Adrian Georgescu
  The SIP URI of the remote party in this session.
1131 1 Adrian Georgescu
  If the original {{{INVITE}}} was incoming, this is the same as {{{from_uri}}}, otherwise it will be the same as {{{to_uri}}}.
1132 1 Adrian Georgescu
 '''route'''::
1133 1 Adrian Georgescu
  The outbound proxy that was requested to be used in the form of a {{{Route}}} object, including the desired transport.
1134 1 Adrian Georgescu
  If this {{{Invitation}}} object represents an incoming {{{INVITE}}} session this attribute will always be {{{None}}}.
1135 1 Adrian Georgescu
  This attribute is set on object instantiation and is read-only.
1136 1 Adrian Georgescu
 '''call_id'''::
1137 1 Adrian Georgescu
  The call ID of the {{{INVITE}}} session as a read-only string.
1138 1 Adrian Georgescu
  In the {{{NULL}}} and {{{DISCONNECTED}}} states, this attribute is {{{None}}}.
1139 1 Adrian Georgescu
 '''transport'''::
1140 1 Adrian Georgescu
  A string indicating the transport used for the application.
1141 1 Adrian Georgescu
  This can be "udp", "tcp" or "tls".
1142 1 Adrian Georgescu
 '''local_contact_uri'''::
1143 60 Ruud Klaver
  The Contact URI that the local side provided to the remote side within this {{{INVITE}}} session as a {{{SIPURI}}} object.
1144 72 Ruud Klaver
  Note that this can either be set on object creation or updated using the {{{update_local_contact()}}} method.
1145 72 Ruud Klaver
 '''local_contact_parameters'''::
1146 72 Ruud Klaver
  The Contact header parameters that the local side provided to the remote side within this {{{INVITE}}} session as dictionary.
1147 72 Ruud Klaver
  Note that this can either be set on object creation or updated using the {{{update_local_contact()}}} method.
1148 1 Adrian Georgescu
1149 63 Ruud Klaver
==== methods ====
1150 1 Adrian Georgescu
1151 72 Ruud Klaver
 '''!__init!__'''(''self'', '''from_uri''', '''to_uri''', '''route''', '''credentials'''={{{None}}}, '''contact_uri'''={{{None}}}, '''contact_parameters'''={{{None}}})::
1152 1 Adrian Georgescu
  Creates a new {{{Invitation}}} object for an outgoing session.
1153 1 Adrian Georgescu
  [[BR]]''from_uri'':[[BR]]
1154 60 Ruud Klaver
  The SIP URI of the local account in the form of a {{{SIPURI}}} object.
1155 53 Ruud Klaver
  [[BR]]''to_uri'':[[BR]]
1156 1 Adrian Georgescu
  The SIP URI we want to send the {{{INVITE}}} to, represented as a {{{SIPURI}}} object.
1157 63 Ruud Klaver
  [[BR]]''route'':[[BR]]
1158 63 Ruud Klaver
  The outbound proxy to use in the form of a {{{Route}}} object.
1159 1 Adrian Georgescu
  This includes the desired transport to use.
1160 1 Adrian Georgescu
  [[BR]]''credentials'':[[BR]]
1161 1 Adrian Georgescu
  The optional SIP credentials needed to authenticate at the SIP proxy in the form of a {{{Credentials}}} object.
1162 1 Adrian Georgescu
  [[BR]]''contact_uri'':[[BR]]
1163 1 Adrian Georgescu
  The Contact URI to include in the {{{INVITE}}} request, a {{{SIPURI}}} object.
1164 1 Adrian Georgescu
  If this is {{{None}}}, a Contact URI will be internally generated.
1165 72 Ruud Klaver
  [[BR]]''contact_parameters'':[[BR]]
1166 72 Ruud Klaver
  The parameters to be included in the Contact header of the {{{INVITE}}} request as a dictionary.
1167 72 Ruud Klaver
  Entries that have their value set to {{{None}}} will have only the key set as a header parameter.
1168 72 Ruud Klaver
  If this argument is {{{None}}}, no Contact header parameters will be included.
1169 1 Adrian Georgescu
 '''get_active_local_sdp'''(''self'')::
1170 1 Adrian Georgescu
  Returns a new {{{SDPSession}}} object representing the currently active local SDP.
1171 1 Adrian Georgescu
  If no SDP was negotiated yet, this returns {{{None}}}.
1172 1 Adrian Georgescu
 '''get_active_remote_sdp'''(''self'')::
1173 56 Ruud Klaver
  Returns a new {{{SDPSession}}} object representing the currently active local SDP.
1174 1 Adrian Georgescu
  If no SDP was negotiated yet, this returns {{{None}}}.
1175 1 Adrian Georgescu
 '''get_offered_local_sdp'''(''self'')::
1176 1 Adrian Georgescu
  Returns a new {{{SDPSession}}} object representing the currently proposed local SDP.
1177 1 Adrian Georgescu
  If no local offered SDP has been set, this returns {{{None}}}.
1178 1 Adrian Georgescu
 '''set_offered_local_sdp'''(''self'', '''local_sdp''')::
1179 1 Adrian Georgescu
  Sets the offered local SDP, either for an initial {{{INVITE}}} or re-{{{INVITE}}}, or as an SDP answer in response to an initial {{{INVITE}}} or re-{{{INVITE}}}.
1180 41 Ruud Klaver
  [[BR]]''local_sdp'':[[BR]]
1181 1 Adrian Georgescu
  The SDP to send as offer or answer to the remote party.
1182 41 Ruud Klaver
 '''get_offered_remote_sdp'''(''self'')::
1183 53 Ruud Klaver
  Returns a new {{{SDPSession}}} object representing the currently proposed remote SDP.
1184 1 Adrian Georgescu
  If no remote SDP has been offered in the current state, this returns {{{None}}}.
1185 72 Ruud Klaver
 '''update_local_contact'''(''self'', '''contact_uri''', '''parameters'''={{{None}}})::
1186 72 Ruud Klaver
  This method allows the application to update the contents of the Contact header sent in (re-){{{INVITE}}} requests.
1187 72 Ruud Klaver
  It can be useful to set to Contact URI to something different than the default on an incoming {{{INVITE}}} session, on a IP address change during the session.
1188 72 Ruud Klaver
  Note that that the number of calls to this method should be limited, as memory is allocated each time it is called which is only released when the {{{Invitation}}} object reaches the {{{DISCONNECTED}}} state.
1189 72 Ruud Klaver
  [[BR]]''contact_uri'':[[BR]]
1190 72 Ruud Klaver
  The Contact URI to include in the {{{INVITE}}} request, a {{{SIPURI}}} object.
1191 72 Ruud Klaver
  [[BR]]''contact_parameters'':[[BR]]
1192 72 Ruud Klaver
  The parameters to be included in the Contact header of the {{{INVITE}}} request as a dictionary.
1193 72 Ruud Klaver
  Entries that have their value set to {{{None}}} will have only the key set as a header parameter.
1194 72 Ruud Klaver
  If this argument is {{{None}}}, no Contact header parameters will be included.
1195 1 Adrian Georgescu
 '''send_invite'''(''self'', '''extra_headers'''={{{None}}}, '''timeout'''={{{None}}})::
1196 1 Adrian Georgescu
  This tries to move the state machine into the {{{CALLING}}} state by sending the initial {{{INVITE}}} request.
1197 1 Adrian Georgescu
  It may only be called from the {{{NULL}}} state on an outgoing {{{Invitation}}} object.
1198 1 Adrian Georgescu
  [[BR]]''extra_headers'':[[BR]]
1199 1 Adrian Georgescu
  Any extra headers that should be included in the {{{INVITE}}} request in the form of a dict.
1200 1 Adrian Georgescu
  [[BR]]''timeout'':[[BR]]
1201 1 Adrian Georgescu
  How many seconds to wait for the remote party to reply before changing the state to {{{DISCONNECTED}}} and internally replying with a 408, as an int or a float.
1202 1 Adrian Georgescu
  If this is set to {{{None}}}, the default PJSIP timeout will be used, which appears to be slightly longer than 30 seconds.
1203 1 Adrian Georgescu
 '''respond_to_invite_provisionally'''(''self'', '''response_code'''=180, '''extra_headers'''={{{None}}})::
1204 1 Adrian Georgescu
  This tries to move the state machine into the {{{EARLY}}} state by sending a provisional response to the initial {{{INVITE}}}.
1205 1 Adrian Georgescu
  It may only be called from the {{{INCOMING}}} state on an incoming {{{Invitation}}} object.
1206 1 Adrian Georgescu
  [[BR]]''response_code'':[[BR]]
1207 1 Adrian Georgescu
  The code of the provisional response to use as an int.
1208 1 Adrian Georgescu
  This should be in the 1xx range.
1209 1 Adrian Georgescu
  [[BR]]''extra_headers'':[[BR]]
1210 1 Adrian Georgescu
  Any extra headers that should be included in the response in the form of a dict.
1211 29 Luci Stanescu
 '''accept_invite'''(''self'', '''extra_headers'''={{{None}}})::
1212 1 Adrian Georgescu
  This tries to move the state machine into the {{{CONNECTING}}} state by sending a 200 OK response to the initial {{{INVITE}}}.
1213 1 Adrian Georgescu
  It may only be called from the {{{INCOMING}}} or {{{EARLY}}} states on an incoming {{{Invitation}}} object.
1214 1 Adrian Georgescu
  [[BR]]''extra_headers'':[[BR]]
1215 1 Adrian Georgescu
  Any extra headers that should be included in the response in the form of a dict.
1216 1 Adrian Georgescu
 '''end'''(''self'', '''response_code'''=603, '''extra_headers'''={{{None}}}, '''timeout'''={{{None}}})::
1217 1 Adrian Georgescu
  This moves the {{{INVITE}}} state machine into the {{{DISCONNECTING}}} state by sending the necessary SIP message.
1218 1 Adrian Georgescu
  When a response from the remote party is received, the state machine will go into the {{{DISCONNECTED}}} state.
1219 1 Adrian Georgescu
  Depending on the current state, this could be a CANCEL or BYE request or a negative response.
1220 1 Adrian Georgescu
  [[BR]]''response_code'':[[BR]]
1221 1 Adrian Georgescu
  The code of the response to use as an int, if transmission of a response is needed.
1222 1 Adrian Georgescu
  [[BR]]''extra_headers'':[[BR]]
1223 1 Adrian Georgescu
  Any extra headers that should be included in the request or response in the form of a dict.
1224 1 Adrian Georgescu
  [[BR]]''timeout'':[[BR]]
1225 1 Adrian Georgescu
  How many seconds to wait for the remote party to reply before changing the state to {{{DISCONNECTED}}}, as an int or a float.
1226 1 Adrian Georgescu
  If this is set to {{{None}}}, the default PJSIP timeout will be used, which currently appears to be 3.5 seconds for an established session.
1227 1 Adrian Georgescu
 '''respond_to_reinvite'''(''self'', '''response_code'''=200, '''extra_headers'''={{{None}}})::
1228 1 Adrian Georgescu
  Respond to a received re-{{{INVITE}}} with a response that is either provisional (1xx), positive (2xx) or negative (3xx and upwards).
1229 1 Adrian Georgescu
  This method can be called by the application when the state machine is in the {{{REINVITED}}} state and will move the state machine back into the {{{CONFIRMED}}} state.
1230 1 Adrian Georgescu
  Before giving a positive final response, the SDP needs to be set using the {{{set_offered_local_sdp()}}} method.
1231 1 Adrian Georgescu
  [[BR]]''response_code'':[[BR]]
1232 1 Adrian Georgescu
  The code of the response to use as an int.
1233 1 Adrian Georgescu
  This should be a 3 digit number.
1234 29 Luci Stanescu
  [[BR]]''extra_headers'':[[BR]]
1235 1 Adrian Georgescu
 '''send_reinvite'''(''self'', '''extra_headers'''={{{None}}})::
1236 1 Adrian Georgescu
  The application may only call this method when the state machine is in the {{{CONFIRMED}}} state to induce sending a re-{{{INVITE}}}.
1237 1 Adrian Georgescu
  Before doing this it needs to set the new local SDP offer by calling the {{{set_offered_local_sdp()}}} method.
1238 1 Adrian Georgescu
  After this method is called, the state machine will be in the {{{REINVITING}}} state, until a final response from the remote party is received.
1239 1 Adrian Georgescu
  [[BR]]''extra_headers'':[[BR]]
1240 1 Adrian Georgescu
  Any extra headers that should be included in the re-{{{INVITE}}} in the form of a dict.
1241 1 Adrian Georgescu
1242 1 Adrian Georgescu
==== notifications ====
1243 1 Adrian Georgescu
1244 1 Adrian Georgescu
 '''SIPInvitationChangedState'''::
1245 1 Adrian Georgescu
  This notification is sent by an {{{Invitation}}} object whenever its state machine changes state.
1246 1 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
1247 1 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1248 1 Adrian Georgescu
  [[BR]]''prev_state'':[[BR]]
1249 1 Adrian Georgescu
  The previous state of the INVITE state machine.
1250 1 Adrian Georgescu
  [[BR]]''state'':[[BR]]
1251 1 Adrian Georgescu
  The new state of the INVITE state machine, which may be the same as the previous state.
1252 1 Adrian Georgescu
  [[BR]]''method'': (only if the state change got triggered by an incoming SIP request)[[BR]]
1253 1 Adrian Georgescu
  The method of the SIP request as a string.
1254 1 Adrian Georgescu
  [[BR]]''request_uri'': (only if the state change got triggered by an incoming SIP request)[[BR]]
1255 1 Adrian Georgescu
  The request URI of the SIP request as a {{{SIPURI}}} object.
1256 1 Adrian Georgescu
  [[BR]]''code'': (only if the state change got triggered by an incoming SIP response or internal timeout or error)[[BR]]
1257 1 Adrian Georgescu
  The code of the SIP response or error as an int.
1258 1 Adrian Georgescu
  [[BR]]''reason'': (only if the state change got triggered by an incoming SIP response or internal timeout or error)[[BR]]
1259 1 Adrian Georgescu
  The reason text of the SIP response or error as an int.
1260 23 Ruud Klaver
  [[BR]]''headers'': (only if the state change got triggered by an incoming SIP request or response)[[BR]]
1261 1 Adrian Georgescu
  The headers of the SIP request or response as a dict.
1262 1 Adrian Georgescu
  Each SIP header is represented in its parsed for as long as PJSIP supports it.
1263 1 Adrian Georgescu
  The format of the parsed value depends on the header.
1264 1 Adrian Georgescu
  [[BR]]''body'': (only if the state change got triggered by an incoming SIP request or response)[[BR]]
1265 1 Adrian Georgescu
  The body of the SIP request or response as a string, or {{{None}}} if no body was included.
1266 1 Adrian Georgescu
  The content type of the body can be learned from the {{{Content-Type:}}} header in the headers argument.
1267 1 Adrian Georgescu
 '''SIPInvitationGotSDPUpdate'''::
1268 71 Adrian Georgescu
  This notification is sent by an {{{Invitation}}} object whenever SDP negotiation has been performed.
1269 1 Adrian Georgescu
  It should be used by the application as an indication to start, change or stop any associated media streams.
1270 1 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
1271 1 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1272 1 Adrian Georgescu
  [[BR]]''succeeded'':[[BR]]
1273 71 Adrian Georgescu
  A boolean indicating if the SDP negotiation has succeeded.
1274 71 Adrian Georgescu
  [[BR]]''error'': (only if SDP negotiation did not succeed)[[BR]]
1275 71 Adrian Georgescu
  A string indicating why SDP negotiation failed.
1276 71 Adrian Georgescu
  [[BR]]''local_sdp'': (only if SDP negotiation succeeded)[[BR]]
1277 1 Adrian Georgescu
  A SDPSession object indicating the local SDP that was negotiated.
1278 71 Adrian Georgescu
  [[BR]]''remote_sdp'': (only if SDP negotiation succeeded)[[BR]]
1279 1 Adrian Georgescu
  A SDPSession object indicating the remote SDP that was negotiated.
1280 1 Adrian Georgescu
1281 1 Adrian Georgescu
=== SDPSession ===
1282 1 Adrian Georgescu
1283 1 Adrian Georgescu
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. 
1284 1 Adrian Georgescu
1285 1 Adrian Georgescu
SDPSession object directly represents the contents of a SDP body, as carried e.g. in a 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.
1286 1 Adrian Georgescu
It can be passed to those methods of an {{{Invitation}}} object that result in transmission of a message that includes SDP, or is passed to the application through a notification that is triggered by reception of a message that includes SDP.
1287 1 Adrian Georgescu
A {{{SDPSession}}} object may contain {{{SDPMedia}}}, {{{SDPConnection}}} and {{{SDPAttribute}}} objects.
1288 1 Adrian Georgescu
It supports comparison to other {{{SDPSession}}} objects using the == and != expressions.
1289 1 Adrian Georgescu
As all the attributes of the {{{SDPSession}}} class are set by attributes of the {{{__init__}}} method, they will be documented along with that method.
1290 1 Adrian Georgescu
1291 1 Adrian Georgescu
==== methods ====
1292 1 Adrian Georgescu
1293 1 Adrian Georgescu
 '''!__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}}})::
1294 1 Adrian Georgescu
  Creates the SDPSession object with the specified parameters as attributes.
1295 1 Adrian Georgescu
  Each of these attributes can be accessed and changed on the object once instanced.
1296 1 Adrian Georgescu
  [[BR]]''address'':[[BR]]
1297 1 Adrian Georgescu
  The address that is contained in the "o" (origin) line of the SDP as a string.
1298 1 Adrian Georgescu
  [[BR]]''id'':[[BR]]
1299 1 Adrian Georgescu
  The session identifier contained in the "o" (origin) line of the SDP as an int.
1300 1 Adrian Georgescu
  If this is set to {{{None}}} on init, a session identifier will be generated.
1301 1 Adrian Georgescu
  [[BR]]''version'':[[BR]]
1302 1 Adrian Georgescu
  The version identifier contained in the "o" (origin) line of the SDP as an int.
1303 1 Adrian Georgescu
  If this is set to {{{None}}} on init, a version identifier will be generated.
1304 24 Ruud Klaver
  [[BR]]''user'':[[BR]]
1305 1 Adrian Georgescu
  The user name contained in the "o" (origin) line of the SDP as a string.
1306 1 Adrian Georgescu
  [[BR]]''net_type'':[[BR]]
1307 1 Adrian Georgescu
  The network type contained in the "o" (origin) line of the SDP as a string.
1308 1 Adrian Georgescu
  [[BR]]''address_type'':[[BR]]
1309 1 Adrian Georgescu
  The address type contained in the "o" (origin) line of the SDP as a string.
1310 1 Adrian Georgescu
  [[BR]]''name'':[[BR]]
1311 1 Adrian Georgescu
  The contents of the "s" (session name) line of the SDP as a string.
1312 1 Adrian Georgescu
  [[BR]]''info'':[[BR]]
1313 1 Adrian Georgescu
  The contents of the session level "i" (information) line of the SDP as a string.
1314 1 Adrian Georgescu
  If this is {{{None}}} or an empty string, the SDP has no "i" line.
1315 1 Adrian Georgescu
  [[BR]]''connection'':[[BR]]
1316 1 Adrian Georgescu
  The contents of the "c" (connection) line of the SDP as a {{{SDPConnection}}} object.
1317 1 Adrian Georgescu
  If this is set to {{{None}}}, the SDP has no session level "c" line.
1318 1 Adrian Georgescu
  [[BR]]''start_time'':[[BR]]
1319 1 Adrian Georgescu
  The first value of the "t" (time) line of the SDP as an int.
1320 1 Adrian Georgescu
  [[BR]]''stop_time'':[[BR]]
1321 1 Adrian Georgescu
  The second value of the "t" (time) line of the SDP as an int.
1322 1 Adrian Georgescu
  [[BR]]''attributes'':[[BR]]
1323 1 Adrian Georgescu
  The session level "a" lines (attributes) in the SDP represented by a list of {{{SDPAttribute}}} objects.
1324 1 Adrian Georgescu
  [[BR]]''media'':[[BR]]
1325 1 Adrian Georgescu
  The media sections of the SDP represented by a list of {{{SDPMedia}}} objects.
1326 1 Adrian Georgescu
1327 1 Adrian Georgescu
=== SDPMedia ===
1328 1 Adrian Georgescu
1329 1 Adrian Georgescu
This object represents the contents of a media section of a SDP body, i.e. a "m" line and everything under it until the next "m" line.
1330 1 Adrian Georgescu
It is a simple wrapper for the PJSIP [http://www.pjsip.org/pjmedia/docs/html/structpjmedia__sdp__media.htm pjmedia_sdp_media] structure.
1331 1 Adrian Georgescu
One or more {{{SDPMedia}}} objects are usually contained in a {{{SDPSession}}} object.
1332 1 Adrian Georgescu
It supports comparison to other {{{SDPMedia}}} objects using the == and != expressions.
1333 1 Adrian Georgescu
As all the attributes of this class are set by attributes of the {{{__init__}}} method, they will be documented along with that method.
1334 1 Adrian Georgescu
1335 1 Adrian Georgescu
==== methods ====
1336 1 Adrian Georgescu
1337 1 Adrian Georgescu
 '''!__init!__'''(''self'', '''media''', '''port''', '''transport''', '''port_count'''=1, '''formats'''={{{None}}}, '''info'''={{{None}}}, '''connection'''={{{None}}}, '''attributes'''={{{None}}})::
1338 1 Adrian Georgescu
  Creates the SDPMedia object with the specified parameters as attributes.
1339 1 Adrian Georgescu
  Each of these attributes can be accessed and changed on the object once instanced.
1340 1 Adrian Georgescu
  [[BR]]''media'':[[BR]]
1341 1 Adrian Georgescu
  The media type contained in the "m" (media) line as a string.
1342 1 Adrian Georgescu
  [[BR]]''port'':[[BR]]
1343 1 Adrian Georgescu
  The transport port contained in the "m" (media) line as an int.
1344 1 Adrian Georgescu
  [[BR]]''transport'':[[BR]]
1345 1 Adrian Georgescu
  The transport protocol in the "m" (media) line as a string.
1346 1 Adrian Georgescu
  [[BR]]''port_count'':[[BR]]
1347 1 Adrian Georgescu
  The port count in the "m" (media) line as an int.
1348 1 Adrian Georgescu
  If this is set to 1, it is not included in the SDP.
1349 1 Adrian Georgescu
  [[BR]]''formats'':[[BR]]
1350 1 Adrian Georgescu
  The media formats in the "m" (media) line represented by a list of strings.
1351 1 Adrian Georgescu
  [[BR]]''info'':[[BR]]
1352 1 Adrian Georgescu
  The contents of the "i" (information) line of this media section as a string.
1353 1 Adrian Georgescu
  If this is {{{None}}} or an empty string, the media section has no "i" line.
1354 1 Adrian Georgescu
  [[BR]]''connection'':[[BR]]
1355 1 Adrian Georgescu
  The contents of the "c" (connection) line that is somewhere below the "m" line of this section as a {{{SDPConnection}}} object.
1356 1 Adrian Georgescu
  If this is set to {{{None}}}, this media section has no "c" line.
1357 1 Adrian Georgescu
  [[BR]]''attributes'':[[BR]]
1358 1 Adrian Georgescu
  The "a" lines (attributes) that are somewhere below the "m" line of this section represented by a list of {{{SDPAttribute}}} objects.
1359 1 Adrian Georgescu
 '''get_direction'''(''self'')::
1360 1 Adrian Georgescu
  This is a convenience methods that goes through all the attributes of the media section and returns the direction, which is either "sendrecv", "sendonly", "recvonly" or "inactive".
1361 1 Adrian Georgescu
  If none of these attributes is present, the default direction is "sendrecv".
1362 1 Adrian Georgescu
1363 1 Adrian Georgescu
=== SDPConnection ===
1364 1 Adrian Georgescu
1365 1 Adrian Georgescu
This object represents the contents of a "c" (connection) line of a SDP body, either at the session level or for an individual media stream.
1366 1 Adrian Georgescu
It is a simple wrapper for the PJSIP [http://www.pjsip.org/pjmedia/docs/html/structpjmedia__sdp__conn.htm pjmedia_sdp_conn] structure.
1367 1 Adrian Georgescu
A {{{SDPConnection}}} object can be contained in a {{{SDPSession}}} object or {{{SDPMedia}}} object.
1368 1 Adrian Georgescu
It supports comparison to other {{{SDPConnection}}} objects using the == and != expressions.
1369 1 Adrian Georgescu
As all the attributes of this class are set by attributes of the {{{__init__}}} method, they will be documented along with that method.
1370 1 Adrian Georgescu
1371 1 Adrian Georgescu
==== methods ====
1372 1 Adrian Georgescu
1373 1 Adrian Georgescu
 '''!__init!__'''(''self'', '''address''', '''net_type'''="IN", '''address_type'''="IP4")::
1374 1 Adrian Georgescu
  Creates the SDPConnection object with the specified parameters as attributes.
1375 1 Adrian Georgescu
  Each of these attributes can be accessed and changed on the object once instanced.
1376 1 Adrian Georgescu
  [[BR]]''address'':[[BR]]
1377 1 Adrian Georgescu
  The address part of the connection line as a string.
1378 1 Adrian Georgescu
  [[BR]]''net_type'':[[BR]]
1379 1 Adrian Georgescu
  The network type part of the connection line as a string.
1380 1 Adrian Georgescu
  [[BR]]''address_type'':[[BR]]
1381 1 Adrian Georgescu
  The address type part of the connection line as a string.
1382 1 Adrian Georgescu
1383 1 Adrian Georgescu
=== SDPAttribute ===
1384 1 Adrian Georgescu
1385 18 Adrian Georgescu
This object represents the contents of a "a" (attribute) line of a SDP body, either at the session level or for an individual media stream.
1386 1 Adrian Georgescu
It is a simple wrapper for the PJSIP [http://www.pjsip.org/pjmedia/docs/html/structpjmedia__sdp__attr.htm pjmedia_sdp_attr] structure.
1387 1 Adrian Georgescu
One or more {{{SDPAttribute}}} objects can be contained in a {{{SDPSession}}} object or {{{SDPMedia}}} object.
1388 17 Ruud Klaver
It supports comparison to other {{{SDPAttribute}}} objects using the == and != expressions.
1389 17 Ruud Klaver
As all the attributes of this class are set by attributes of the {{{__init__}}} method, they will be documented along with that method.
1390 17 Ruud Klaver
1391 17 Ruud Klaver
==== methods ====
1392 17 Ruud Klaver
1393 17 Ruud Klaver
 '''!__init!__'''(''self'', '''name''', '''value''')::
1394 17 Ruud Klaver
  Creates the SDPAttribute object with the specified parameters as attributes.
1395 17 Ruud Klaver
  Each of these attributes can be accessed and changed on the object once instanced.
1396 17 Ruud Klaver
  [[BR]]''name'':[[BR]]
1397 1 Adrian Georgescu
  The name part of the attribute line as a string.
1398 1 Adrian Georgescu
  [[BR]]''value'':[[BR]]
1399 1 Adrian Georgescu
  The value part of the attribute line as a string.
1400 1 Adrian Georgescu
1401 1 Adrian Georgescu
=== RTPTransport ===
1402 1 Adrian Georgescu
1403 1 Adrian Georgescu
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.
1404 1 Adrian Georgescu
Internally it wraps a [http://www.pjsip.org/pjmedia/docs/html/group__PJMEDIA__TRANSPORT.htm pjmedia_transport] object.
1405 1 Adrian Georgescu
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].
1406 17 Ruud Klaver
For this reason the {{{AudioTransport}}} and {{{RTPTransport}}} are two distinct objects.
1407 1 Adrian Georgescu
1408 1 Adrian Georgescu
The {{{RTPTransport}}} object also allows support for ICE and SRTP functionality from PJSIP.
1409 1 Adrian Georgescu
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.
1410 1 Adrian Georgescu
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.
1411 1 Adrian Georgescu
This process of SDP negotiation is represented by the internal state machine of the object, as shown in the following diagram:
1412 1 Adrian Georgescu
1413 17 Ruud Klaver
> The Real-time Transport Protocol (or RTP) defines a standardized packet format for delivering audio and video over the Internet.
1414 1 Adrian Georgescu
> It was developed by the Audio-Video Transport Working Group of the IETF and published in [http://tools.ietf.org/html/rfc3550 RFC 3550].
1415 1 Adrian Georgescu
> RTP is used in streaming media systems (together with the RTSP) as well as in videoconferencing and push to talk systems.
1416 1 Adrian Georgescu
> 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.
1417 1 Adrian Georgescu
1418 1 Adrian Georgescu
[[Image(sipsimple-rtp-transport-state-machine.png, nolink)]]
1419 1 Adrian Georgescu
1420 1 Adrian Georgescu
State changes are triggered by the following events:
1421 1 Adrian Georgescu
 1. The application calls the {{{set_INIT()}}} method after object creation and ICE+STUN is not used.
1422 1 Adrian Georgescu
 2. The application calls the {{{set_INIT()}}} method after object creation and ICE+STUN is used.
1423 1 Adrian Georgescu
 3. A successful STUN response is received from the STUN server.
1424 1 Adrian Georgescu
 4. The {{{set_LOCAL()}}} method is called.
1425 1 Adrian Georgescu
 5. The {{{set_ESTABLISHED()}}} method is called.
1426 1 Adrian Georgescu
 6. The {{{set_INIT()}}} method is called while the object is in the {{{LOCAL}}} or {{{ESTABLISHED}}} state.
1427 45 Ruud Klaver
 7. A method is called on the application, but in the meantime the {{{Engine}}} has stopped.
1428 1 Adrian Georgescu
    The object can no longer be used.
1429 1 Adrian Georgescu
 8. There was an error in getting the STUN candidates from the STUN server.
1430 1 Adrian Georgescu
1431 71 Adrian Georgescu
> 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.
1432 1 Adrian Georgescu
> This means that the RTPTransport object is also unusable once it has reached the STUN_FAILED state.
1433 1 Adrian Georgescu
> A workaround would be destroy the RTPTransport object and create a new one that uses ICE without STUN.
1434 1 Adrian Georgescu
1435 1 Adrian Georgescu
These states allow for two SDP negotiation scenarios to occur, represented by two paths that can be followed through the state machine.
1436 1 Adrian Georgescu
In this example we will assume that ICE with STUN is not used, as it is independent of the SDP negotiation procedure.
1437 1 Adrian Georgescu
 * The first scenario is where the local party generates the SDP offer.
1438 1 Adrian Georgescu
   For a stream that it wishes to include in this SDP offer, it instantiates a {{{RTPTransport}}} object.
1439 1 Adrian Georgescu
   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}}} respectively, which can be used to generate the local SDP in the form of a {{{SDPSession}}} object (note that it needs the full object, not just the relevant {{{SDPMedia}}} object).
1440 1 Adrian Georgescu
   This local SDP then needs to be passed to the {{{set_LOCAL()}}} method, which moves the state machine into the {{{LOCAL}}} state.
1441 1 Adrian Georgescu
   Depending on the options used for the {{{RTPTransport}}} instantiation (such as ICE and SRTP), this may change the {{{SDPSession}}} object.
1442 1 Adrian Georgescu
   This (possibly changed) {{{SDPSession}}} object then needs to be passed to the {{{Invitation}}} object.
1443 1 Adrian Georgescu
   After SDP negotiation is completed, the application needs to pass both the local and remote SDP, in the form of {{{SDPSession}}} objects, to the {{{RTPTransport}}} object using the {{{set_ESTABLISHED()}}} method, moving the state machine into the {{{ESTABLISHED}}} state.
1444 1 Adrian Georgescu
   This will not change either of the {{{SDPSession}}} objects.
1445 1 Adrian Georgescu
 * The second scenario is where the local party is offered a media stream in SDP and wants to accept it.
1446 1 Adrian Georgescu
   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.
1447 1 Adrian Georgescu
   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.
1448 1 Adrian Georgescu
   In this case the local SDP object may be changed, after which it can be passed to the {{{Invitation}}} object.
1449 1 Adrian Georgescu
1450 1 Adrian Georgescu
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.
1451 1 Adrian Georgescu
Before doing this however, the internal transport object must no longer be in use.
1452 1 Adrian Georgescu
1453 1 Adrian Georgescu
==== attributes ====
1454 1 Adrian Georgescu
1455 1 Adrian Georgescu
 '''state'''::
1456 1 Adrian Georgescu
  Indicates which state the internal state machine is in.
1457 1 Adrian Georgescu
  See the previous section for a list of states the state machine can be in.
1458 1 Adrian Georgescu
  This attribute is read-only.
1459 1 Adrian Georgescu
 '''local_rtp_address'''::
1460 19 Ruud Klaver
  The local IPv4 address of the interface the {{{RTPTransport}}} object is listening on and the address that should be included in the SDP.
1461 1 Adrian Georgescu
  If no address was specified during object instantiation, PJSIP will take guess out of the IP addresses of all interfaces.
1462 1 Adrian Georgescu
  This attribute is read-only and will be {{{None}}} if PJSIP is not listening on the transport.
1463 1 Adrian Georgescu
 '''local_rtp_port'''::
1464 1 Adrian Georgescu
  The UDP port PJSIP is listening on for RTP traffic.
1465 1 Adrian Georgescu
  RTCP traffic will always be this port plus one.
1466 1 Adrian Georgescu
  This attribute is read-only and will be {{{None}}} if PJSIP is not listening on the transport.
1467 1 Adrian Georgescu
 '''remote_rtp_address_sdp'''::
1468 1 Adrian Georgescu
  The remote IP address that was seen in the SDP.
1469 1 Adrian Georgescu
  This attribute is read-only and will be {{{None}}} unless the object is in the {{{ESTABLISHED}}} state.
1470 1 Adrian Georgescu
 '''remote_rtp_port_sdp'''::
1471 1 Adrian Georgescu
  The remote UDP port for RTP that was seen in the SDP.
1472 1 Adrian Georgescu
  This attribute is read-only and will be {{{None}}} unless the object is in the {{{ESTABLISHED}}} state.
1473 45 Ruud Klaver
 '''remote_rtp_address_received'''::
1474 1 Adrian Georgescu
  The remote IP address from which RTP data was received.
1475 1 Adrian Georgescu
  This attribute is read-only and will be {{{None}}} unless RTP was actually received.
1476 1 Adrian Georgescu
 '''remote_rtp_port_received'''::
1477 1 Adrian Georgescu
  The remote UDP port from which RTP data was received.
1478 1 Adrian Georgescu
  This attribute is read-only and will be {{{None}}} unless RTP was actually received.
1479 1 Adrian Georgescu
 '''use_srtp'''::
1480 1 Adrian Georgescu
  A boolean indicating if the use of SRTP was requested when the object was instantiated.
1481 1 Adrian Georgescu
  This attribute is read-only.
1482 1 Adrian Georgescu
 '''force_srtp'''::
1483 1 Adrian Georgescu
  A boolean indicating if SRTP being mandatory for this transport if it is enabled was requested when the object was instantiated.
1484 1 Adrian Georgescu
  This attribute is read-only.
1485 1 Adrian Georgescu
 '''srtp_active'''::
1486 1 Adrian Georgescu
  A boolean indicating if SRTP encryption and decryption is running.
1487 1 Adrian Georgescu
  Querying this attribute only makes sense once the object is in the {{{ESTABLISHED}}} state and use of SRTP was requested.
1488 29 Luci Stanescu
  This attribute is read-only.
1489 1 Adrian Georgescu
 '''use_ice'''::
1490 1 Adrian Georgescu
  A boolean indicating if the use of ICE was requested when the object was instantiated.
1491 1 Adrian Georgescu
  This attribute is read-only.
1492 1 Adrian Georgescu
 '''ice_stun_address'''::
1493 34 Ruud Klaver
  A string indicating the IP address of the STUN server that was requested to be used.
1494 34 Ruud Klaver
  This attribute is read-only.
1495 34 Ruud Klaver
 '''ice_stun_port'''::
1496 34 Ruud Klaver
  A string indicating the UDP port of the STUN server that was requested to be used.
1497 1 Adrian Georgescu
  This attribute is read-only.
1498 1 Adrian Georgescu
1499 1 Adrian Georgescu
==== methods ====
1500 1 Adrian Georgescu
1501 1 Adrian Georgescu
 '''!__init!__'''(''self'', '''local_rtp_address'''={{{None}}}, '''use_srtp'''={{{False}}}, '''srtp_forced'''={{{False}}}, '''use_ice'''={{{False}}}, '''ice_stun_address'''={{{None}}}, '''ice_stun_port'''=3478)::
1502 1 Adrian Georgescu
  Creates a new {{{RTPTransport}}} object and opens the RTP and RTCP UDP sockets.
1503 71 Adrian Georgescu
  If additional features are requested, they will be initialized.
1504 1 Adrian Georgescu
  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.
1505 1 Adrian Georgescu
  [[BR]]''local_rtp_address'':[[BR]]
1506 1 Adrian Georgescu
  Optionally contains the local IPv4 address to listen on.
1507 1 Adrian Georgescu
  If this is not specified, PJSIP will listen on all network interfaces.
1508 1 Adrian Georgescu
  [[BR]]''use_srtp'':[[BR]]
1509 1 Adrian Georgescu
  A boolean indicating if SRTP should be used.
1510 17 Ruud Klaver
  If this is set to {{{True}}}, SRTP information will be added to the SDP when it passes this object.
1511 17 Ruud Klaver
  [[BR]]''srtp_forced'':[[BR]]
1512 1 Adrian Georgescu
  A boolean indicating if use of SRTP is set to mandatory in the SDP.
1513 71 Adrian Georgescu
  If this is set to {{{True}}} and the remote party does not support SRTP, the SDP negotiation for this stream will fail.
1514 1 Adrian Georgescu
  This argument is relevant only if {{{use_srtp}}} is set to {{{True}}}.
1515 29 Luci Stanescu
  [[BR]]''use_ice'':[[BR]]
1516 17 Ruud Klaver
  A boolean indicating if ICE should be used.
1517 17 Ruud Klaver
  If this is set to {{{True}}}, ICE candidates will be added to the SDP when it passes this object.
1518 1 Adrian Georgescu
  [[BR]]''ice_stun_address'':[[BR]]
1519 1 Adrian Georgescu
  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.
1520 29 Luci Stanescu
  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.
1521 17 Ruud Klaver
  When this happens a {{{RTPTransportGotSTUNResponse}}} notification is sent.
1522 17 Ruud Klaver
  This argument is relevant only if {{{use_ice}}} is set to {{{True}}}.
1523 17 Ruud Klaver
  [[BR]]''ice_stun_address'':[[BR]]
1524 17 Ruud Klaver
  An int indicating the UDP port of the STUN server that should be used to add a STUN candidate to the ICE candidates.
1525 17 Ruud Klaver
  This argument is relevant only if {{{use_ice}}} is set to {{{True}}} and {{{ice_stun_address}}} is not {{{None}}}.
1526 1 Adrian Georgescu
 '''set_INIT'''(''self'')::
1527 1 Adrian Georgescu
  This moves the internal state machine into the {{{INIT}}} state.
1528 1 Adrian Georgescu
  If the state machine is in the {{{LOCAL}}} or {{{ESTABLISHED}}} states, this effectively resets the {{{RTPTransport}}} object for re-use.
1529 1 Adrian Georgescu
 '''set_LOCAL'''(''self'', '''local_sdp''', '''sdp_index''')::
1530 1 Adrian Georgescu
  This moves the the internal state machine into the {{{LOCAL}}} state.
1531 1 Adrian Georgescu
  [[BR]]''local_sdp'':[[BR]]
1532 1 Adrian Georgescu
  The local SDP to be proposed in the form of a {{{SDPSession}}} object.
1533 1 Adrian Georgescu
  Note that this object may be modified by this method.
1534 1 Adrian Georgescu
  [[BR]]''sdp_index'':[[BR]]
1535 1 Adrian Georgescu
  The index in the SDP for the media stream for which this object was created.
1536 1 Adrian Georgescu
 '''set_ESTABLISHED'''(''self'', '''local_sdp''', '''remote_sdp''', '''sdp_index''')::
1537 1 Adrian Georgescu
  This moves the the internal state machine into the {{{ESTABLISHED}}} state.
1538 1 Adrian Georgescu
  [[BR]]''local_sdp'':[[BR]]
1539 1 Adrian Georgescu
  The local SDP to be proposed in the form of a {{{SDPSession}}} object.
1540 1 Adrian Georgescu
  Note that this object may be modified by this method, but only when moving from the {{{LOCAL}}} to the {{{ESTABLISHED}}} state.
1541 1 Adrian Georgescu
  [[BR]]''remote_sdp'':[[BR]]
1542 1 Adrian Georgescu
  The remote SDP that was received in in the form of a {{{SDPSession}}} object.
1543 1 Adrian Georgescu
  [[BR]]''sdp_index'':[[BR]]
1544 1 Adrian Georgescu
  The index in the SDP for the media stream for which this object was created.
1545 1 Adrian Georgescu
1546 1 Adrian Georgescu
==== notifications ====
1547 1 Adrian Georgescu
1548 1 Adrian Georgescu
 '''RTPTransportDidInitialize'''::
1549 1 Adrian Georgescu
  This notification is sent when a {{{RTPTransport}}} object has successfully initialized.
1550 1 Adrian Georgescu
  If STUN+ICE is not requested, this is sent immediately on {{{set_INIT()}}}, otherwise it is sent after the STUN query has succeeded.
1551 1 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
1552 1 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1553 1 Adrian Georgescu
 '''RTPTransportDidFail'''::
1554 1 Adrian Georgescu
  This notification is sent by a {{{RTPTransport}}} object that fails to retrieve ICE candidates from the STUN server after {{{set_INIT()}}} is called.
1555 1 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
1556 1 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1557 1 Adrian Georgescu
  [[BR]]''reason'':[[BR]]
1558 1 Adrian Georgescu
  A string describing the failure reason.
1559 1 Adrian Georgescu
1560 1 Adrian Georgescu
=== AudioTransport ===
1561 1 Adrian Georgescu
1562 1 Adrian Georgescu
This object represent an audio stream as it is transported over the network.
1563 1 Adrian Georgescu
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.
1564 1 Adrian Georgescu
It also generates a {{{SDPMedia}}} object to be included in the local SDP.
1565 1 Adrian Georgescu
1566 1 Adrian Georgescu
Like the {{{RTPTransport}}} object there are two usage scenarios.
1567 1 Adrian Georgescu
 * In the first scenario, only the {{{RTPTransport}}} instance to be used is passed to the AudioTransport object.
1568 1 Adrian Georgescu
   The application can then generate the {{{SDPMedia}}} object by calling the {{{get_local_media()}}} method and should include it in the SDP offer.
1569 40 Ruud Klaver
   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.
1570 1 Adrian Georgescu
   The stream can then be connected to the conference bridge.
1571 1 Adrian Georgescu
 * 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.
1572 1 Adrian Georgescu
   The local {{{SDPMedia}}} object can again be generated by calling the {{{get_local_media()}}} method and is to be included in the SDP answer.
1573 1 Adrian Georgescu
   The audio stream is started directly when the object is created.
1574 1 Adrian Georgescu
1575 1 Adrian Georgescu
Unlike the {{{RTPTransport}}} object, this object cannot be reused.
1576 1 Adrian Georgescu
1577 1 Adrian Georgescu
==== attributes ====
1578 1 Adrian Georgescu
1579 1 Adrian Georgescu
 '''transport'''::
1580 71 Adrian Georgescu
  The {{{RTPTransport}}} object that was passed when the object got instantiated.
1581 40 Ruud Klaver
  This attribute is read-only.
1582 40 Ruud Klaver
 '''is_active'''::
1583 40 Ruud Klaver
  A boolean indicating if the object is currently sending and receiving audio.
1584 1 Adrian Georgescu
  This attribute is read-only.
1585 1 Adrian Georgescu
 '''is_started'''::
1586 1 Adrian Georgescu
  A boolean indicating if the object has been started.
1587 1 Adrian Georgescu
  Both this attribute and the {{{is_active}}} attribute get set to {{{True}}} once the {{{start()}}} method is called, but unlike the {{{is_active}}} attribute this attribute does not get set to {{{False}}} once {{{stop()}}} is called.
1588 1 Adrian Georgescu
  This is to prevent the object from being re-used.
1589 1 Adrian Georgescu
  This attribute is read-only.
1590 1 Adrian Georgescu
 '''codec'''::
1591 1 Adrian Georgescu
  Once the SDP negotiation is complete, this attribute indicates the audio codec that was negotiated, otherwise it will be {{{None}}}.
1592 1 Adrian Georgescu
  This attribute is read-only.
1593 54 Ruud Klaver
 '''sample_rate'''::
1594 1 Adrian Georgescu
  Once the SDP negotiation is complete, this attribute indicates the sample rate of the audio codec that was negotiated, otherwise it will be {{{None}}}.
1595 1 Adrian Georgescu
  This attribute is read-only.
1596 1 Adrian Georgescu
 '''direction'''::
1597 1 Adrian Georgescu
  The current direction of the audio transport, which is one of "sendrecv", "sendonly", "recvonly" or "inactive".
1598 1 Adrian Georgescu
  This attribute is read-only, although it can be set using the {{{update_direction()}}} method.
1599 1 Adrian Georgescu
1600 1 Adrian Georgescu
==== methods ====
1601 54 Ruud Klaver
1602 55 Ruud Klaver
 '''!__init!__'''(''self'', '''transport''', '''remote_sdp'''={{{None}}}, '''sdp_index'''=0, '''enable_silence_detection'''=True, '''codecs'''={{{None}}})::
1603 55 Ruud Klaver
  Creates a new {{{AudioTransport}}} object and start the underlying stream if the remote SDP is already known.
1604 1 Adrian Georgescu
  [[BR]]''transport'':[[BR]]
1605 1 Adrian Georgescu
  The transport to use in the form of a {{{RTPTransport}}} object.
1606 55 Ruud Klaver
  [[BR]]''remote_sdp'':[[BR]]
1607 55 Ruud Klaver
  The remote SDP that was received in the form of a {{{SDPSession}}} object.
1608 55 Ruud Klaver
  [[BR]]''sdp_index'':[[BR]]
1609 1 Adrian Georgescu
  The index within the SDP of the audio stream that should be created.
1610 1 Adrian Georgescu
  [[BR]]''enable_silence_detection''[[BR]]
1611 1 Adrian Georgescu
  Boolean that indicates if silence detection should be used for this audio stream.
1612 1 Adrian Georgescu
  When enabled, this {{{AudioTransport}}} object will stop sending audio to the remote party if the input volume is below a certain threshold.
1613 1 Adrian Georgescu
  [[BR]]''codecs''[[BR]]
1614 1 Adrian Georgescu
  A list of strings indicating the codecs that should be proposed in the SDP of this {{{AudioTransport}}}, in order of preference.
1615 1 Adrian Georgescu
  This overrides the global codecs list set on the {{{Engine}}}.
1616 1 Adrian Georgescu
  The values of this list are case insensitive.
1617 1 Adrian Georgescu
 '''get_local_media'''(''self'', '''is_offer''', '''direction'''="sendrecv")::
1618 1 Adrian Georgescu
  Generates a {{{SDPMedia}}} object which describes the audio stream.
1619 1 Adrian Georgescu
  This object should be included in a {{{SDPSession}}} object that gets passed to the {{{Invitation}}} object.
1620 1 Adrian Georgescu
  This method should also be used to obtain the SDP to include in re-INVITEs and replies to re-INVITEs.
1621 1 Adrian Georgescu
  [[BR]]''is_offer'':[[BR]]
1622 1 Adrian Georgescu
  A boolean indicating if the SDP requested is to be included in an offer.
1623 1 Adrian Georgescu
  If this is {{{False}}} it is to be included in an answer.
1624 1 Adrian Georgescu
  [[BR]]''direction'':[[BR]]
1625 29 Luci Stanescu
  The direction attribute to put in the SDP.
1626 1 Adrian Georgescu
 '''start'''(''self'', '''local_sdp''', '''remote_sdp''', '''sdp_index''', '''no_media_timeout'''=10, '''media_check_interval'''=30)::
1627 1 Adrian Georgescu
  This method should only be called once, when the application has previously sent an SDP offer and the answer has been received.
1628 1 Adrian Georgescu
  [[BR]]''local_sdp'':[[BR]]
1629 1 Adrian Georgescu
  The full local SDP that was included in the SDP negotiation in the form of a {{{SDPSession}}} object.
1630 1 Adrian Georgescu
  [[BR]]''remote_sdp'':[[BR]]
1631 1 Adrian Georgescu
  The remote SDP that was received in the form of a {{{SDPSession}}} object.
1632 55 Ruud Klaver
  [[BR]]''sdp_index'':[[BR]]
1633 54 Ruud Klaver
  The index within the SDP of the audio stream.
1634 54 Ruud Klaver
  [[BR]]''no_media_timeout'':[[BR]]
1635 54 Ruud Klaver
  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.
1636 54 Ruud Klaver
  Setting this to 0 disables this an all subsequent RTP checks.
1637 54 Ruud Klaver
  [[BR]]''media_check_interval'':[[BR]]
1638 54 Ruud Klaver
  This indicates the interval at which the RTP stream should be checked, after it has initially received RTP at after {{{no_media_timeout}}} seconds.
1639 54 Ruud Klaver
  It means that if between two of these interval checks no RTP has been received, a {{{RTPAudioTransportDidNotGetRTP}}} notification will be sent.
1640 1 Adrian Georgescu
  Setting this to 0 will disable checking the RTP at intervals.
1641 1 Adrian Georgescu
  The initial check may still be performed if its timeout is non-zero.
1642 1 Adrian Georgescu
 '''stop'''(''self'')::
1643 1 Adrian Georgescu
  This method stops and destroys the audio stream encapsulated by this object.
1644 1 Adrian Georgescu
  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.
1645 1 Adrian Georgescu
  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.
1646 1 Adrian Georgescu
 '''send_dtmf'''(''self'', '''digit''')::
1647 1 Adrian Georgescu
  For a negotiated audio transport this sends one DTMF digit to the other party
1648 1 Adrian Georgescu
  [[BR]]''digit'':[[BR]]
1649 29 Luci Stanescu
  A string of length one indicating the DTMF digit to send.
1650 1 Adrian Georgescu
  This can be either a number or letters A through D.
1651 1 Adrian Georgescu
 '''update_direction'''(''self'', '''direction''')::
1652 1 Adrian Georgescu
  This method should be called after SDP negotiation has completed to update the direction of the media stream.
1653 1 Adrian Georgescu
  [[BR]]''direction'':[[BR]]
1654 1 Adrian Georgescu
  The direction that has been negotiated.
1655 1 Adrian Georgescu
1656 1 Adrian Georgescu
==== notifications ====
1657 1 Adrian Georgescu
1658 1 Adrian Georgescu
 '''RTPAudioTransportGotDTMF'''::
1659 1 Adrian Georgescu
  This notification will be sent when an incoming DTMF digit is received from the remote party.
1660 1 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
1661 1 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1662 1 Adrian Georgescu
  [[BR]]''digit'':[[BR]]
1663 1 Adrian Georgescu
  The DTMF digit that was received, in the form of a string of length one.
1664 1 Adrian Georgescu
  This can be either a number or letters A through D.
1665 1 Adrian Georgescu
 '''RTPAudioTransportDidNotGetRTP'''::
1666 1 Adrian Georgescu
  This notification will be sent when no RTP packets have been received from the remote party for some time.
1667 1 Adrian Georgescu
  See the {{{start()}}} method for a more exact description.
1668 1 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
1669 1 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1670 1 Adrian Georgescu
  [[BR]]''got_any'':[[BR]]
1671 1 Adrian Georgescu
  A boolean data attribute indicating if the {{{AudioTransport}}} every saw any RTP packets from the remote party.
1672 1 Adrian Georgescu
  In effect, if no RTP was received after {{{no_media_timeout}}} seconds, its value will be {{{False}}}.
1673 1 Adrian Georgescu
1674 1 Adrian Georgescu
=== WaveFile ===
1675 1 Adrian Georgescu
1676 1 Adrian Georgescu
This is a simple object that allows playing back of a {{{.wav}}} file over the PJSIP conference bridge, possibly looping a number of times.
1677 1 Adrian Georgescu
Only 16-bit PCM and A-law/U-law formats are supported.
1678 1 Adrian Georgescu
Its main purpose is the playback of ringtones.
1679 1 Adrian Georgescu
1680 1 Adrian Georgescu
This class can be instantiated by the application before the {{{Engine}}} is running, but in order to actually start playback, through the {{{start()}}} method, the {{{Engine}}} must have been started as well.
1681 1 Adrian Georgescu
Once the {{{start()}}} method is called, the {{{.wav}}} file will continue playing until the loop count specified is reached( or forever if the specified loop count is 0), or until the {{{stop()}}} method is called.
1682 1 Adrian Georgescu
When playback stops for either of these reasons, a {{{WaveFileDidFinishPlaying}}} notification is sent by the object.
1683 1 Adrian Georgescu
After this the {{{start()}}} method may be called again in order to re-use the object.
1684 1 Adrian Georgescu
1685 1 Adrian Georgescu
It is the application's responsibility to keep a reference to the {{{WaveFile}}} object for the duration of playback.
1686 1 Adrian Georgescu
If the reference count of the object reaches 0, playback will be stopped.
1687 29 Luci Stanescu
In this case no notification will be sent.
1688 1 Adrian Georgescu
1689 1 Adrian Georgescu
==== attributes ====
1690 1 Adrian Georgescu
1691 1 Adrian Georgescu
 '''file_name'''::
1692 1 Adrian Georgescu
  The name of the {{{.wav}}} file, as specified when the object was created.
1693 1 Adrian Georgescu
 '''is_active'''::
1694 1 Adrian Georgescu
  A boolean read-only property that indicates if the file is currently being played back.
1695 1 Adrian Georgescu
  Note that if the playback loop is currently in a pause between playbacks, this attribute will also be {{{True}}}.
1696 1 Adrian Georgescu
1697 1 Adrian Georgescu
==== methods ====
1698 1 Adrian Georgescu
1699 1 Adrian Georgescu
 '''!__init!__'''(''self'', '''file_name''')::
1700 1 Adrian Georgescu
  Creates a new {{{WaveFile}}} object.
1701 1 Adrian Georgescu
  [[BR]]''file_name'':[[BR]]
1702 1 Adrian Georgescu
  The name of the {{{.wav}}} file to be played back as a string.
1703 1 Adrian Georgescu
  This should include the full path to the file.
1704 1 Adrian Georgescu
 '''start'''(''self'', '''level'''=100, '''loop_count'''=1, '''pause_time'''=0)::
1705 15 Ruud Klaver
  Start playback of the {{{.wav}}} file, optionally looping it.
1706 15 Ruud Klaver
  [[BR]]''level'':[[BR]]
1707 15 Ruud Klaver
  The level to play the file back at, in percentage.
1708 1 Adrian Georgescu
  A percentage lower than 100 means playback will be attenuated, a percentage higher than 100 means it will amplified.
1709 1 Adrian Georgescu
  [[BR]]''loop_count'':[[BR]]
1710 1 Adrian Georgescu
  The number of time to loop playing this file.
1711 1 Adrian Georgescu
  A value of 0 means looping infinitely.
1712 1 Adrian Georgescu
  [[BR]]''pause_time'':[[BR]]
1713 1 Adrian Georgescu
  The number of seconds to pause between consecutive loops.
1714 1 Adrian Georgescu
  This can be either an int or a float.
1715 1 Adrian Georgescu
 '''stop'''(''self'')::
1716 1 Adrian Georgescu
  Stop playback of the file.
1717 1 Adrian Georgescu
1718 15 Ruud Klaver
==== notifications ====
1719 15 Ruud Klaver
1720 15 Ruud Klaver
 '''WaveFileDidFinishPlaying'''::
1721 15 Ruud Klaver
  This notification will be sent whenever the {{{.wav}}} file has been played back the specified number of times.
1722 1 Adrian Georgescu
  After sending this event, the playback may be re-started.
1723 1 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
1724 1 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1725 1 Adrian Georgescu
1726 1 Adrian Georgescu
=== RecordingWaveFile ===
1727 1 Adrian Georgescu
1728 1 Adrian Georgescu
This is a simple object that allows recording whatever is heard on the PJSIP conference bridge to a PCM {{{.wav}}} file.
1729 1 Adrian Georgescu
1730 1 Adrian Georgescu
This class can be instantiated by the application before the {{{Engine}}} is running, but in order to actually start playback, through the {{{start()}}} method, the {{{Engine}}} must have been started as well.
1731 1 Adrian Georgescu
Recording to the file can be stopped either by calling the {{{stop()}}} method or by removing all references to the object.
1732 1 Adrian Georgescu
Once the {{{stop()}}} method has been called, the {{{start()}}} method may not be called again.
1733 1 Adrian Georgescu
It is the application's responsibility to keep a reference to the {{{RecordingWaveFile}}} object for the duration of the recording.
1734 1 Adrian Georgescu
1735 1 Adrian Georgescu
==== attributes ====
1736 1 Adrian Georgescu
1737 1 Adrian Georgescu
 '''file_name'''::
1738 1 Adrian Georgescu
  The name of the {{{.wav}}} file, as specified when the object was created.
1739 1 Adrian Georgescu
 '''is_active'''::
1740 1 Adrian Georgescu
  A boolean read-only attribute that indicates if the file is currently being written to.
1741 1 Adrian Georgescu
 '''is_paused'''::
1742 1 Adrian Georgescu
  A boolean read-only attribute that indicates if the active recording is currently paused.
1743 1 Adrian Georgescu
1744 1 Adrian Georgescu
==== methods ====
1745 1 Adrian Georgescu
1746 1 Adrian Georgescu
 '''!__init!__'''(''self'', '''file_name''')::
1747 1 Adrian Georgescu
  Creates a new {{{RecordingWaveFile}}} object.
1748 1 Adrian Georgescu
  [[BR]]''file_name'':[[BR]]
1749 1 Adrian Georgescu
  The name of the {{{.wav}}} file to record to as a string.
1750 1 Adrian Georgescu
  This should include the full path to the file.
1751 1 Adrian Georgescu
 '''start'''(''self'')::
1752 1 Adrian Georgescu
  Start recording the sound on the conference bridge to the {{{.wav}}} file.
1753 1 Adrian Georgescu
 '''pause'''(''self'')::
1754 1 Adrian Georgescu
  Pause recording to the {{{.wav}}} file.
1755 1 Adrian Georgescu
 '''resume'''(''self'')::
1756 1 Adrian Georgescu
  Resume a previously paused recording.
1757 1 Adrian Georgescu
 '''stop'''(''self'')::
1758 1 Adrian Georgescu
  Stop recording to the file.