Project

General

Profile

SipCoreApiDocumentation » History » Version 88

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