Project

General

Profile

SipCoreApiDocumentation » History » Version 119

Dan Pascu, 03/14/2019 10:51 AM

1 117 Adrian Georgescu
h1. SIP Core API
2 1 Adrian Georgescu
3
4
5 117 Adrian Georgescu
6
7
h2. Introduction
8
9
10
This chapter describes the internal architecture and API of the SIP core of the @sipsimple@ library.
11
@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.
12
13
SIP stands for 'Sessions Initiation Protocol', an IETF standard described by "RFC 3261":http://tools.ietf.org/html/rfc3261. SIP is an application-layer control protocol that can establish,
14 1 Adrian Georgescu
modify and terminate multimedia sessions such as Internet telephony calls
15
(VoIP). Media can be added to (and removed from) an existing session.
16
17
SIP transparently supports name mapping and redirection services, which
18
supports personal mobility, users can maintain a single externally visible
19
address identifier, which can be in the form of a standard email address or
20
E.164 telephone number regardless of their physical network location.
21
22
SIP allows the endpoints to negotiate and combine any type of session they
23
mutually understand like video, instant messaging (IM), file transfer,
24
desktop sharing and provides a generic event notification system with
25
real-time publications and subscriptions about state changes that can be
26
used for asynchronous services like presence, message waiting indicator and
27
busy line appearance.
28
29
For a comprehensive overview of SIP related protocols and use cases visit http://www.tech-invite.com
30
31
32 117 Adrian Georgescu
h2. PJSIP library
33
34
35
@sipsimple@ builds on PJSIP http://www.pjsip.org, a set of static libraries, written in C, which provide SIP signaling and media capabilities.
36 1 Adrian Georgescu
PJSIP is considered to be the most mature and advanced open source SIP stack available.
37
The following diagram, taken from the PJSIP documentation, illustrates the library stack of PJSIP:
38
39 117 Adrian Georgescu
!{ nolink}http://www.pjsip.org/images/diagram.jpg!
40 1 Adrian Georgescu
41
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.
42
The latter also includes an abstraction layer for the sound-card.
43
Both of these stracks are integrated in the high level library, called PJSUA.
44
45 117 Adrian Georgescu
PJSIP itself provides a high-level "Python wrapper for PJSUA":http://www.pjsip.org/python/pjsua.htm.
46
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.
47 1 Adrian Georgescu
The main reasons for this are the following:
48 117 Adrian Georgescu
* PJSUA assumes a session with exactly one audio stream, whilst for the SIP SIMPLE client more advanced (i.e. low-level) manipulation of the SDP is needed.
49
* 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.
50
* 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.
51 1 Adrian Georgescu
52
PJSIP itself is by nature asynchronous.
53
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.
54
Whenever the application performs some action through a function, this function will return immediately.
55
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.
56
57
> NOTE: Currently the core starts the media handling as a separate C thread to avoid lag caused by the GIL.
58
> The sound-card also has its own C thread.
59
60
61 117 Adrian Georgescu
h2. Architecture
62
63
64
The @sipsimple@ core wrapper itself is mostly written using "Cython":http://cython.org/ (formerly "Pyrex":http://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/).
65 90 Luci Stanescu
It allows a Python-like file with some added C manipulation statements to be compiled to C.
66
This in turn compiles to a Python C extension module, which links with the PJSIP static libraries.
67
68 117 Adrian Georgescu
The SIP core part of the @sipsimple@ Python library resides in the @sipsimple.core@ package. This package aggregates three modules, @sipsimple.core._core@, @sipsimple.core._engine@ and @sipsimple.core._primitives@. The former is a Python C extension module which makes wrappers around PJSIP objects available in Python, while the latter two contain SIP core objects written in Python. All core objects should be accessed from the enclosing @sipsimple.core@ module. The following list enumerates the various SIP core objects available:
69
* The @Engine@ class which is a Python wrapper around the low-level @PJSIPUA@ class. The latter represents the SIP endpoint and manages the initialization and destruction of all the PJSIP libraries. It is also the central management point to the SIP core. The application should not use the @PJSIPUA@ class directly, but rather through the wrapping @Engine@, which is a singleton class.
70
* Utility classes used throughout the core:
71
*** @frozenlist@ and @frozendict@: classes which relate respectively to @list@ and @dict@ similarly to how the standard @frozenset@ relates to @set@.
72
* Helper classes which represent a structured collection of data which is used throughout the core:
73
*** @BaseSIPURI@, @SIPURI@ and @FrozenSIPURI@
74
*** @BaseCredentials@, @Credentials@ and @FrozenCredentials@
75
* SDP manipulation classes, which directly wrap the PJSIP structures representing either the parsed or to be generated SDP:
76
*** @BaseSDPSession@, @SDPSession@ and @FrozenSDPSession@
77
*** @BaseSDPMediaStream@, @SDPMediaStream@ and @FrozenSDPMediaStream@
78
*** @BaseSDPConnection@, @SDPConnection@ and @FrozenSDPConnection@
79
*** @SDPAttributeList@ and @FrozenSDPAttributeList@
80
*** @BaseSDPAttribute@, @SDPAttribute@ and @FrozenSDPAttribute@
81
* Audio handling classes:
82
*** @AudioMixer@
83
*** @MixerPort@
84
*** @WaveFile@
85
*** @RecordingWaveFile@
86
*** @ToneGenerator@
87
* Media transport handling classes, using the functionality built into PJMEDIA:
88
*** @RTPTransport@
89
*** @AudioTransport@
90
* SIP signalling related classes:
91
*** @Request@ and @IncomingRequest@: low-level transaction support
92
*** @Invitation@: INVITE-dialog support
93
*** @Subscription@ and @IncomingSubscription@: SUBSCRIBE-dialog support (including NOTIFY handling within the SUBSCRIBE dialog)
94
*** @Referral@ and @IncomingReferral@: REFER-dialog support (including NOTIFY handling within the dialog)
95
*** @Registration@: Python object based on @Request@ for REGISTER support
96
*** @Message@: Python object based on @Request@ for MESSAGE support
97
*** @Publication@: Python object based on @Request@ for PUBLISH support
98
* Exceptions:
99
*** @SIPCoreError@: generic error used throught the core
100
*** @PJSIPError@: subclass of @SIPCoreError@ which offers more information related to errors from PJSIP
101
*** @PJSIPTLSError@: subclass of @PJSIPError@ to distinguish between TLS-related errors and the rest
102
*** @SIPCoreInvalidStateError@: subclass of @SIPCoreError@ used by objects which are based on a state-machine
103 1 Adrian Georgescu
104 117 Adrian Georgescu
Most of the objects cannot be used until the @Engine@ has been started. The following diagram illustrates these classes:
105 1 Adrian Georgescu
106 117 Adrian Georgescu
!{ nolink}sipsimple-core-classes.png!
107 1 Adrian Georgescu
108 117 Adrian Georgescu
Most of the SIP core does not allow duck-typing due to the nature of the integration between it and PJSIP. If these checks had not been employed, any errors could have resulted in a segmentation fault and a core dump. This also explains why several objects have a *Frozen* counterpart: the frozen objects are simply immutable versions of their non-frozen variants which make sure that low-level data is kept consistent and cannot be modified from Python. The *Base* versions are just base classes for the frozen and non-frozen versions provided mostly for convinience: they cannot be instantiated.
109 1 Adrian Georgescu
110
111 117 Adrian Georgescu
h2. Integration
112
113
114
The core itself has one Python dependency, the "application":http://pypi.python.org/pypi/python-application module, which in turn depends on the "zope.interface":http://pypi.python.org/pypi/zope.interface module.
115 1 Adrian Georgescu
These modules should be present on the system before the core can be used.
116 117 Adrian Georgescu
An application that uses the SIP core must use the notification system provided by the @application@ module in order to receive notifications from it.
117
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.
118 1 Adrian Georgescu
This means that any call to instance an object from this class will result in the same object.
119
As an example, this bit of code will create an observer for logging messages only:
120
121 117 Adrian Georgescu
<pre>
122 1 Adrian Georgescu
from zope.interface import implements
123
from application.notification import NotificationCenter, IObserver
124
125
class SIPEngineLogObserver(object):
126
    implements(IObserver)
127
128
    def handle_notification(self, notification):
129
        print "%(timestamp)s (%(level)d) %(sender)14s: %(message)s" % notification.data.__dict__
130
131
log_observer = SIPEngineLogObserver()
132
notification_center = NotificationCenter()
133
notification_center.add_observer(log_observer, name="SIPEngineLog")
134 117 Adrian Georgescu
</pre>
135 1 Adrian Georgescu
136
Each notification object has three attributes:
137
138 117 Adrian Georgescu
*sender*
139
>The object that sent the notification.
140
>For generic notifications the sender will be the @Engine@ instance, otherwise the relevant object.
141 1 Adrian Georgescu
142 117 Adrian Georgescu
*name*
143
>The name describing the notification.
144
>Most of the notifications in the core have the prefix "SIP".
145 1 Adrian Georgescu
146 117 Adrian Georgescu
*data*
147
>An instance of @application.notification.NotificationData@ or a subclass of it.
148
>The attributes of this object provide additional data about the notification.
149
>Notifications described in this document will also have the data attributes described.
150 1 Adrian Georgescu
151 117 Adrian Georgescu
Besides setting up the notification observers, the application should import the relevant objects from the @sipsimple.core@ module.
152
It can then instantiate the @Engine@ class, which is also a singleton, and start the PJSIP worker thread by calling @Engine.start()@, optionally providing a number of initialization options.
153
Most of these options can later be changed at runtime, by setting attributes of the same name on the @Engine@ object.
154 1 Adrian Georgescu
The application may then instantiate one of the SIP primitive classes and perform operations on it.
155
156 117 Adrian Georgescu
When starting the @Engine@ class, the application can pass a number of keyword arguments that influence the behaviour of the SIP endpoint.
157
For example, the SIP network ports may be set through the @local_udp_port@, @local_tcp_port@ and @local_tls_port@ arguments.
158
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.
159 1 Adrian Georgescu
160 117 Adrian Georgescu
The methods called on the SIP primitive objects and the @Engine@ object (proxied to the @PJSIPUA@ instance) may be called from any thread.
161 1 Adrian Georgescu
They will return immediately and any delayed result, such as results depending on network traffic, will be returned later using a notification.
162
In this manner the SIP core continues the asynchronous pattern of PJSIP.
163 117 Adrian Georgescu
If there is an error in processing the request, an instance of @SIPCoreError@, or its subclass @PJSIPError@ will be raised.
164 1 Adrian Georgescu
The former will be raised whenever an error occurs inside the core, the latter whenever an underlying PJSIP function returns an error.
165 117 Adrian Georgescu
The @PJSIPError@ object also contains a status attribute, which is the PJSIP errno as an integer.
166 1 Adrian Georgescu
167 117 Adrian Georgescu
As a very basic example, one can @REGISTER@ for a sip account by typing the following lines on a Python console:
168 1 Adrian Georgescu
<pre>
169 118 Chris Maciejewski
from sipsimple.core import ContactHeader, Credentials, Engine, Registration, RouteHeader, SIPURI, FromHeader
170 1 Adrian Georgescu
e = Engine()
171
e.start()
172 118 Chris Maciejewski
identity = FromHeader(SIPURI(user="alice", host="example.com"), display_name=unicode("Alice"))
173 1 Adrian Georgescu
cred = Credentials("alice", "mypassword")
174
reg = Registration(identity, credentials=cred)
175
reg.register(ContactHeader(SIPURI("127.0.0.1",port=12345)), RouteHeader(SIPURI("1.2.3.4", port=5060)))
176 117 Adrian Georgescu
</pre>
177
Note that in this example no observer for notifications from this @Registration@ object are registered, so the result of the operation cannot be seen.
178 1 Adrian Georgescu
Also note that this will not keep the registration registered when it is about to expire, as it is the application's responsibility.
179 117 Adrian Georgescu
See the @Registration@ documentation for more details.
180 1 Adrian Georgescu
181
Another convention that is worth mentioning at this point is that the SIP core will never perform DNS lookups.
182 117 Adrian Georgescu
For the sake of flexibility, it is the responsibility of the application to do this and pass the result to SIP core objects using the @RouteHeader@ object, indicating the destination IP address, port and transport the resulting SIP request should be sent to. The [[SipMiddlewareApi#Lookup|@sipsimple.lookup@]] module of the middleware can be used to perform DNS lookups according to RFC3263.
183 1 Adrian Georgescu
184
185 117 Adrian Georgescu
h2. Components
186 1 Adrian Georgescu
187
188
189 117 Adrian Georgescu
h3. Engine
190 1 Adrian Georgescu
191
192 117 Adrian Georgescu
As explained above, this singleton class needs to be instantiated by the application using the SIP core of @sipsimple@ and represents the whole SIP core stack.
193
Once the @start()@ method is called, it instantiates the @core.PJSIPUA@ object and will proxy attribute and methods from it to the application.
194 1 Adrian Georgescu
195
196 117 Adrian Georgescu
h4. attributes
197 1 Adrian Georgescu
198
199
200 117 Adrian Georgescu
*default_start_options* (class attribute)
201
>This dictionary is a class attribute that describes the default values for the initialization options passed as keyword arguments to the @start()@ method.
202
>Consult this method for documentation of the contents.
203 1 Adrian Georgescu
204 117 Adrian Georgescu
*is_running*
205
>A boolean property indicating if the @Engine@ is running and if it is safe to try calling any proxied methods or attributes on it.
206 1 Adrian Georgescu
207
208 117 Adrian Georgescu
h4. methods
209 1 Adrian Georgescu
210
211
212 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_)
213
>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.
214 1 Adrian Georgescu
215 117 Adrian Georgescu
*start*(_self_, ***kwargs*)
216
>Initialize all PJSIP libraries based on the keyword parameters provided and start the PJSIP worker thread.
217
>If this fails an appropriate exception is raised.
218
>After the @Engine@ has been started successfully, it can never be started again after being stopped.
219
>The keyword arguments will be discussed here.
220
>Many of these values are also readable as (proxied) attributes on the Engine once the @start()@ method has been called.
221
>Many of them can also be set at runtime, either by modifying the attribute or by calling a particular method.
222
>This will also be documented for each argument in the following list of options.
223
  
224
>+_udp_port_+: (Default: @0@)
225 1 Adrian Georgescu
226 117 Adrian Georgescu
>The local UDP port to listen on for UDP datagrams.
227
>If this is 0, a random port will be chosen.
228
>If it is @None@, the UDP transport is disabled, both for incoming and outgoing traffic.
229
>As an attribute, this value is read-only, but it can be changed at runtime using the @set_udp_port()@ method.
230
  
231
>+_tcp_port_+: (Default: @0@)
232 1 Adrian Georgescu
233 117 Adrian Georgescu
>The local TCP port to listen on for new TCP connections.
234
>If this is 0, a random port will be chosen.
235
>If it is @None@, the TCP transport is disabled, both for incoming and outgoing traffic.
236
>As an attribute, this value is read-only, but it can be changed at runtime using the @set_tcp_port()@ method.
237
  
238
>+_tls_port_+: (Default: @0@)
239 1 Adrian Georgescu
240 117 Adrian Georgescu
>The local TCP port to listen on for new TLS over TCP connections.
241
>If this is 0, a random port will be chosen.
242
>If it is @None@, the TLS transport is disabled, both for incoming and outgoing traffic.
243
>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.
244
  
245
>+_tls_protocol_+: (Default: "TLSv1")
246
 
247
>This string describes the (minimum) TLS protocol that should be used. 
248
>Its values should be either @None@, "SSLv2", "SSLv23", "SSLv3" or "TLSv1". 
249
>If @None@ is specified, the PJSIP default will be used, which is currently "TLSv1". 
250
  
251
>+_tls_verify_server_+: (Default: @False@)
252 1 Adrian Georgescu
253 117 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.
254
>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.
255
  
256
>+_tls_ca_file_+: (Default: @None@)
257 1 Adrian Georgescu
258 117 Adrian Georgescu
>This string indicates the location of the file containing the local list of CA certificates, to be used for TLS connections.
259
>If this is set to @None@, no CA certificates will be read. 
260
>As an attribute, this value is read-only, but it can be changed at runtime using the @set_tls_options()@ method, as internally the TLS transport needs to be restarted for this operation. 
261
  
262
>+_tls_cert_file_+: (Default: @None@)
263
 
264
>This string indicates the location of a file containing the TLS certificate to be used for TLS connections. 
265
>If this is set to @None@, no certificate file will be read. 
266
>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. 
267
  
268
>+_tls_privkey_file_+: (Default: @None@)
269
 
270
>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. 
271
>If this is set to @None@, no private key file will be read. 
272
>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. 
273
  
274
>+_tls_timeout_+: (Default: 1000)
275
 
276
>The timeout value for a TLS negotiation in milliseconds. 
277
>Note that this value should be reasonably small, as a TLS negotiation blocks the whole PJSIP polling thread. 
278
>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.
279
  
280
>+_user_agent_+: (Default: @"sipsimple-%version-pjsip-%pjsip_version-r%pjsip_svn_revision"@)
281 1 Adrian Georgescu
282 117 Adrian Georgescu
>This value indicates what should be set in the @User-Agent@ header, which is included in each request or response sent.
283
>It can be read and set directly as an attribute at runtime.
284
  
285
>+_log_level_+: (Default: 5)
286 1 Adrian Georgescu
287 117 Adrian Georgescu
>This integer dictates the maximum log level that may be reported to the application by PJSIP through the @SIPEngineLog@ notification.
288
>By default the maximum amount of logging information is reported.
289
>This value can be read and set directly as an attribute at runtime.
290
  
291
>+_trace_sip_+: (Default: @False@)
292 1 Adrian Georgescu
293 117 Adrian Georgescu
>This boolean indicates if the SIP core should send the application SIP messages as seen on the wire through the @SIPEngineSIPTrace@ notification.
294
>It can be read and set directly as an attribute at runtime.
295
  
296
>+_rtp_port_range_+: (Default: (40000, 40100))
297 1 Adrian Georgescu
298 117 Adrian Georgescu
>This tuple of two integers indicates the range to select UDP ports from when creating a new @RTPTransport@ object, which is used to transport media.
299
>It can be read and set directly as an attribute at runtime, but the ports of previously created @RTPTransport@ objects remain unaffected.
300
  
301
>+_codecs_+: (Default: @["speex", "G722", "PCMU", "PCMA", "iLBC", "GSM"]@)
302 1 Adrian Georgescu
303 117 Adrian Georgescu
>This list specifies the codecs to use for audio sessions and their preferred order.
304
>It can be read and set directly as an attribute at runtime.
305
>Note that this global option can be overridden by an argument passed to @AudioTransport.__init__()@.
306
>The strings in this list is case insensitive.
307
  
308
>+_events_+: (Default: <some sensible events>)
309 1 Adrian Georgescu
310 117 Adrian Georgescu
>PJSIP needs a mapping between SIP SIMPLE event packages and content types.
311
>This dictionary provides some default packages and their event types.
312
>As an attribute, this value is read-only, but it can be changed at runtime using the @add_event()@ method.
313
  
314
>+_incoming_events_+: (Default: @set()@)
315 1 Adrian Georgescu
316 117 Adrian Georgescu
>A list that specifies for which SIP SIMPLE event packages the application wishes to receive @IncomingSubscribe@ objects.
317
>When a @SUBSCRIBE@ request is received containing an event name that is not in this list, a 489 "Bad event" response is internally generated.
318
>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.
319
>Note that each of the events specified here should also be a key in the @events@ dictionary argument.
320
>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.
321
  
322
>+_incoming_requests_+: (Default: @set()@)
323 1 Adrian Georgescu
324 117 Adrian Georgescu
>A set of methods for which @IncomingRequest@ objects are created and sent to the application if they are received.
325
>Note that receiving requests using the @INVITE@, @SUBSCRIBE@, @ACK@ or @BYE@ methods in this way is not allowed.
326
>Requests using the @OPTIONS@ or @MESSAGE@ method are handled internally, but may be overridden.
327
328
*stop*(_self_)
329
>Stop the PJSIP worker thread and unload all PJSIP libraries.
330
>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@.
331
>Also note that, once stopped the @Engine@ cannot be started again.
332
>This method is automatically called when the Python interpreter exits.
333
334
335
h4. proxied attributes
336
337
338
Besides all the proxied attributes described for the @__init__@ method above, thse other attributes are provided once the @Engine@ has been started.
339
340
341
*input_devices*
342
>This read-only attribute is a list of strings, representing all audio input devices on the system that can be used.
343
>One of these device names can be passed as the @input_device@ argument when creating a @AudioMixer@ object.
344
345
*output_devices*
346
>This read-only attribute is a list of strings, representing all audio output devices on the system that can be used.
347
>One of these device names can be passed as the @output_device@ argument when creating a @AudioMixer@ object.
348
349
*sound_devices*
350
>This read-only attribute is a list of strings, representing all audio sound devices on the system that can be used.
351
352
*available_codecs*
353
>A read-only list of codecs available in the core, regardless of the codecs configured through the @codecs@ attribute.
354
355
356
h4. proxied methods
357
358
359
360
*add_event*(_self_, *event*, *accept_types*)
361
>Couple a certain event package to a list of content types.
362
>Once added it cannot be removed or modified.
363
364
*add_incoming_event*(_self_, *event*)
365
>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.
366
>Note that this event should be known to the @Engine@ by means of the @events@ attribute.
367
368
*remove_incoming_event*(_self_, *event*)
369
>Removes an event from the @incoming_events@ attribute.
370
>Incoming @SUBSCRIBE@ requests with this event package will automatically be replied to with a 489 "Bad Event" response.
371
372
*add_incoming_request*(_self_, *method*)
373
>Add a method to the set of methods for which incoming requests should be turned into @IncomingRequest@ objects.
374
>For the rules on which methods are allowed, see the description of the Engine attribute above.
375
376
*remove_incoming_request*(_self_, *method*)
377
>Removes a method from the set of methods that should be received.
378
379
*detect_nat_type*(_self_, *stun_server_address*, *stun_server_port*=3478, *user_data*=None)
380
>Will start a series of STUN requests which detect the type of NAT this host is behind.
381
>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.
382
>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.
383
384
*set_udp_port*(_self_, *value*)
385
>Update the @local_udp_port@ attribute to the newly specified value.
386
387
*set_tcp_port*(_self_, *value*)
388
>Update the @local_tcp_port@ attribute to the newly specified value.
389
390
*set_tls_options*(_self_, *local_port*=@None@, *protocol*="TLSv1", *verify_server*=@False@, *ca_file*=@None@, *cert_file*=@None@, *privkey_file*=@None@, *timeout*=1000) 
391
>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@. 
392
>The semantics of the arguments are the same as on the @start()@ method. 
393
394
395
h4. notifications
396
397
398
Notifications sent by the @Engine@ are notifications that are related to the @Engine@ itself or unrelated to any SIP primitive object.
399 1 Adrian Georgescu
They are described here including the data attributes that is included with them.
400
401
402 117 Adrian Georgescu
*SIPEngineWillStart*
403
>This notification is sent when the @Engine@ is about to start.
404
  
405
>+_timestamp_+:
406 1 Adrian Georgescu
407 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
408 1 Adrian Georgescu
409 117 Adrian Georgescu
*SIPEngineDidStart*
410
>This notification is sent when the @Engine@ is has just been started.
411
  
412
>+_timestamp_+:
413 1 Adrian Georgescu
414 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
415 1 Adrian Georgescu
416 117 Adrian Georgescu
*SIPEngineDidFail*
417
>This notification is sent whenever the @Engine@ has failed fatally and either cannot start or is about to stop.
418
>It is not recommended to call any methods on the @Engine@ at this point.
419
  
420
>+_timestamp_+:
421 1 Adrian Georgescu
422 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
423 1 Adrian Georgescu
424 117 Adrian Georgescu
*SIPEngineWillEnd*
425
>This notification is sent when the @Engine@ is about to stop because the application called the @stop()@ method.
426
>Methods on the @Engine@ can be called at this point, but anything that has a delayed result will probably not return any notification.
427
  
428
>+_timestamp_+:
429 1 Adrian Georgescu
430 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
431
432
*SIPEngineDidEnd*
433
>This notification is sent when the @Engine@ was running and is now stopped, either because of failure or because the application requested it.
434
  
435
>+_timestamp_+:
436
437
>A @datetime.datetime@ object indicating when the notification was sent.
438
439
*SIPEngineLog*
440
>This notification is a wrapper for PJSIP logging messages.
441
>It can be used by the application to output PJSIP logging to somewhere meaningful, possibly doing filtering based on log level.
442
  
443
>+_timestamp_+:
444
445
>A @datetime.datetime@ object representing the time when the log message was output by PJSIP.
446
  
447
>+_sender_+:
448
449
>The PJSIP module that originated this log message.
450
  
451
>+_level_+:
452
453
>The logging level of the message as an integer.
454
>Currently this is 1 through 5, 1 being the most critical.
455
  
456
>+_message_+:
457
458
>The actual log message.
459
460
*SIPEngineSIPTrace*
461
>Will be sent only when the @do_siptrace@ attribute of the @Engine@ instance is set to @True@.
462
>The notification data attributes will contain the SIP messages as they are sent and received on the wire.
463
  
464
>+_timestamp_+:
465
466
>A @datetime.datetime@ object indicating when the notification was sent.
467
  
468
>+_received_+:
469
470
>A boolean indicating if this message was sent from or received by PJSIP (i.e. the direction of the message).
471
  
472
>+_source_ip_+:
473
474
>The source IP address as a string.
475
  
476
>+_source_port_+:
477
478
>The source port of the message as an integer.
479
  
480
>+_destination_ip_+:
481
482
>The destination IP address as a string.
483
  
484
>+_source_port_+:
485
486
>The source port of the message as an integer.
487
  
488
>+_data_+:
489
490
>The contents of the message as a string.
491
492 1 Adrian Georgescu
> For received message the destination_ip and for sent messages the source_ip may not be reliable.
493
494
495 117 Adrian Georgescu
*SIPEngineDetectedNATType*
496
>This notification is sent some time after the application request the NAT type this host behind to be detected using a STUN server.
497
>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.
498
  
499
>+_timestamp_+:
500 1 Adrian Georgescu
501 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
502
  
503
>+_succeeded_+:
504 1 Adrian Georgescu
505 117 Adrian Georgescu
>A boolean indicating if the NAT detection succeeded.
506
  
507
>+_user_data_+:
508 1 Adrian Georgescu
509 117 Adrian Georgescu
>The @user_data@ argument passed while calling the @detect_nat_type()@ method.
510
>This can be any object and could be used for matching requests to responses.
511
  
512
>+_nat_type_+:
513 1 Adrian Georgescu
514 117 Adrian Georgescu
>A string describing the type of NAT found.
515
>This value is only present if NAT detection succeeded.
516
  
517
>+_error_+:
518
519
>A string indicating the error that occurred while attempting to detect the type of NAT.
520
>This value only present if NAT detection did not succeed.
521
522
*SIPEngineGotException*
523
>This notification is sent whenever there is an unexpected exception within the PJSIP working thread.
524
>The application should show the traceback to the user somehow.
525
>An exception need not be fatal, but if it is it will be followed by a *SIPEngineDidFail* notification.
526
  
527
>+_timestamp_+:
528
529
>A @datetime.datetime@ object indicating when the notification was sent.
530
  
531
>+_traceback_+:
532
533
>A string containing the traceback of the exception.
534
>In general this should be printed on the console.
535
536
*SIPEngineGotMessage*
537
>This notification is sent whenever the Engine receives a @MESSAGE@ request.
538
  
539
>+_request_uri_+:
540
541
>The request URI of the @MESSAGE@ request as a @SIPURI@ object.
542
  
543
>+_from_header_+:
544
545
>The From header of the @MESSAGE@ request as a @FrozenFromHeader@ object.
546
  
547
>+_to_header_+:
548
549
>The To header of the @MESSAGE@ request as a @FrozenToHeader@ object.
550
  
551
>+_content_type_+:
552
553
>The Content-Type header value of the @MESSAGE@ request as a @ContentType@ object.
554
  
555
>+_headers_+:
556
557
>The headers of the @MESSAGE@ request as a dict.
558
>Each SIP header is represented in its parsed for as long as PJSIP supports it.
559
>The format of the parsed value depends on the header.
560
  
561
>+_body_+:
562
563
>The body of the @MESSAGE@ request as a string, or @None@ if no body was included.
564
  
565
>+_timestamp_+:
566
567
>A @datetime.datetime@ object indicating when the notification was sent.
568
569
570
h3. SIPURI
571
572
573 1 Adrian Georgescu
These are helper objects for representing a SIP URI.
574
This object needs to be used whenever a SIP URI should be specified to the SIP core.
575 117 Adrian Georgescu
It supports comparison to other @SIPURI@ objects using the == and != expressions.
576
As all of its attributes are set by the @__init__@ method, the individual attributes will not be documented here. The FrozenSIPURI object does not allow any of its attributes to be changed after initialization.
577 1 Adrian Georgescu
578
579 117 Adrian Georgescu
h4. methods
580 1 Adrian Georgescu
581
582
583 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_, *host*, *user*=@None@, *port*=@None@, *display*=@None@, *secure*=@False@, *parameters*=@None@, *headers*=@None@)
584
>Creates the SIPURI object with the specified parameters as attributes.
585
  @host@ is the only mandatory attribute.
586
  
587
>+_host_+:
588 1 Adrian Georgescu
589 117 Adrian Georgescu
>The host part of the SIP URI as a string.
590
  
591
>+_user_+:
592 1 Adrian Georgescu
593 117 Adrian Georgescu
>The username part of the SIP URI as a string, or None if not set.
594
  
595
>+_port_+:
596 1 Adrian Georgescu
597 117 Adrian Georgescu
>The port part of the SIP URI as an int, or None or 0 if not set.
598
  
599
>+_display_+:
600 1 Adrian Georgescu
601 117 Adrian Georgescu
>The optional display name of the SIP URI as a string, or None if not set.
602
  
603
>+_secure_+:
604
605
>A boolean indicating whether this is a SIP or SIPS URI, the latter being indicated by a value of @True@.
606
  
607
>+_parameters_+:
608
609
>The URI parameters. represented by a dictionary.
610
  
611
>+_headers_+:
612
613
>The URI headers, represented by a dictionary.
614
615
*<notextile>__str__</notextile>*(_self_)
616
>The special Python method to represent this object as a string, the output is the properly formatted SIP URI.
617
618
*new*(_cls_, _sipuri_)
619
>Classmethod that returns an instance of the class on which it has been called which is a copy of the @sipuri@ object (which must be either a SIPURI or a FrozenSIPURI).
620
621
*parse*(_cls_, _uri_str_)
622
>Classmethod that returns an instance of the class on which it has been called which is represents the parsed version of the URI provided as a string. A SIPCoreError is raised if the string is invalid or if the Engine has not been started yet.
623
624
*matches*(_self_, _address_)
625
>This method returns @True@ or @False@ depending on whether the string address contains a SIP address whose components are a subset of the components of self. For example, @SIPURI.parse('sip:alice@example.org:54321;transport=tls').matches('alice@example.org')@ returns @True@ while @SIPURI.parse('sip:alice@example.org;transport=tls').matches('sips:alice@example.org')@ returns @False@.
626
627
628
h3. Credentials
629
630
631
The @Credentials@ and @FrozenCredentails@ simple objects represent authentication credentials for a particular SIP account.
632 1 Adrian Georgescu
These can be included whenever creating a SIP primitive object that originates SIP requests.
633 117 Adrian Georgescu
The attributes of this object are the same as the arguments to the @__init__@ method.
634 1 Adrian Georgescu
Note that the domain name of the SIP account is not stored on this object.
635
636
637 117 Adrian Georgescu
h4. methods
638 1 Adrian Georgescu
639
640
641 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_, *username*, *password*)
642
>Creates the Credentials object with the specified parameters as attributes.
643
>Each of these attributes can be accessed and changed on the object once instanced.
644
  
645
>+_username_+:
646 1 Adrian Georgescu
647 117 Adrian Georgescu
>A string representing the username of the account for which these are the credentials.
648
  
649
>+_password_+:
650 1 Adrian Georgescu
651 117 Adrian Georgescu
>The password for this SIP account as a string.
652
653
*new*(_cls_, _credentials_)
654
>Classmethod that returns an instance of the class on which it has been called which is a copy of the @credentials@ object (which must be either a Credentials or a FrozenCredentials).
655
656
657
h3. Invitation
658
659
660
The @Invitation@ class represents an @INVITE@ session, which governs a complete session of media exchange between two SIP endpoints from start to finish.
661
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.
662
The @Invitation@ class represents both incoming and outgoing sessions.
663
664
The state machine contained in each @Invitation@ object is based on the one used by the underlying PJSIP "pjsip_inv_session":http://www.pjsip.org/pjsip/docs/html/group+PJSIP+INV.htm object.
665
In order to represent re-@INVITE@s and user-requested disconnections, three more states have been added to this state machine.
666 1 Adrian Georgescu
The progression through this state machine is fairly linear and is dependent on whether this is an incoming or an outgoing session.
667
State changes are triggered either by incoming or by outgoing SIP requests and responses.
668
The states and the transitions between them are shown in the following diagram:
669
670 117 Adrian Georgescu
!{ nolink}sipsimple-core-invite-state-machine.png!
671 1 Adrian Georgescu
672
The state changes of this machine are triggered by the following:
673 117 Adrian Georgescu
# An @Invitation@ object is newly created, either by the application for an outgoing session, or by the core for an incoming session.
674
# The application requested an outgoing session by calling the @send_invite()@ method and and initial @INVITE@ request is sent.
675
# A new incoming session is received by the core.
676 1 Adrian Georgescu
    The application should look out for state change to this state in order to be notified of new incoming sessions.
677 117 Adrian Georgescu
# A provisional response (1xx) is received from the remove party.
678
# A provisional response (1xx) is sent to the remote party, after the application called the @respond_to_invite_provisionally()@ method.
679
# A positive final response (2xx) is received from the remote party.
680
# A positive final response (2xx) is sent to the remote party, after the application called the @accept_invite()@ method.
681
# A positive final response (2xx) is sent or received, depending on the orientation of the session.
682
# An @ACK@ is sent or received, depending on the orientation of the session.
683
    If the @ACK@ is sent from the local to the remote party, it is initiated by PJSIP, not by a call from the application.
684
# The local party sent a re-@INVITE@ to the remote party by calling the @send_reinvite()@ method.
685
# The remote party has sent a final response to the re-@INVITE@.
686
# The remote party has sent a re-@INVITE@.
687
# The local party has responded to the re-@INVITE@ by calling the @respond_to_reinvite()@ method.
688
# The application requests that the session ends by calling the @end()@ method.
689
# A response is received from the remote party to whichever message was sent by the local party to end the session.
690
# A message is received from the remote party which ends the session.
691 1 Adrian Georgescu
692 117 Adrian Georgescu
The application is notified of a state change in either state machine through the @SIPInvitationChangedState@ notification, which has as data the current and previous states.
693 1 Adrian Georgescu
If the event is triggered by and incoming message, extensive data about that message, such as method/code, headers and body, is also included with the notification.
694
The application should compare the previous and current states and perform the appropriate action.
695
696 117 Adrian Georgescu
An @Invitiation@ object also emits the @SIPInvitationGotSDPUpdate@ notification, which indicates that SDP negotiation between the two parties has been completed.
697
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.
698
In the last case, the @Invitation@ object will automatically include the current local SDP in the response.
699 1 Adrian Georgescu
700
701 117 Adrian Georgescu
h4. attributes
702 1 Adrian Georgescu
703
704
705 117 Adrian Georgescu
*state*
706
>The state the @Invitation@ state machine is currently in.
707
>See the diagram above for possible states.
708
>This attribute is read-only.
709 1 Adrian Georgescu
710 117 Adrian Georgescu
*sub_state*
711
>The sub-state the @Invitation@ state machine is currently in.
712
>See the diagram above for possible states.
713
>This attribute is read-only.
714 1 Adrian Georgescu
715 117 Adrian Georgescu
*directing*
716
>A string with the values @"incoming"@ or @"outgoing"@ depending on the direction of the original INVITE request.
717 1 Adrian Georgescu
718 117 Adrian Georgescu
*credentials*
719
>The SIP credentials needed to authenticate at the SIP proxy in the form of a @FrozenCredentials@ object.
720
>If this @Invitation@ object represents an incoming @INVITE@ session this attribute will be @None@.
721
>On an outgoing session this attribute will be @None@ if it was not specified when the object was created.
722
>This attribute is set on object instantiation and is read-only.
723 1 Adrian Georgescu
724 117 Adrian Georgescu
*from_header*
725
>The From header of the caller represented by a @FrozenFromHeader@ object.
726
>If this is an outgoing @INVITE@ session, this is the from_header from the @send_invite()@ method.
727
>Otherwise the URI is taken from the @From:@ header of the initial @INVITE@.
728
>This attribute is set on object instantiation and is read-only.
729 1 Adrian Georgescu
730 117 Adrian Georgescu
*to_header*
731
>The To header of the callee represented by a @FrozenToHeader@ object.
732
>If this is an outgoing @INVITE@ session, this is the to_header from the @send_invite()@ method.
733
>Otherwise the URI is taken from the @To:@ header of the initial @INVITE@.
734
>This attribute is set on object instantiation and is read-only.
735 1 Adrian Georgescu
736 117 Adrian Georgescu
*local_identity*
737
>The From or To header representing the local identity used in this session.
738
>If the original @INVITE@ was incoming, this is the same as @to_header@, otherwise it will be the same as @from_header@.
739 1 Adrian Georgescu
740 117 Adrian Georgescu
*remote_identity*
741
>The From or To header representing the remote party in this session.
742
>If the original @INVITE@ was incoming, this is the same as @from_header@, otherwise it will be the same as @to_header@.
743 1 Adrian Georgescu
744 117 Adrian Georgescu
*route_header*
745
>The outbound proxy that was requested to be used in the form of a @FrozenRouteHeader@ object, including the desired transport.
746
>If this @Invitation@ object represents an incoming @INVITE@ session this attribute will always be @None@.
747
>This attribute is set on object instantiation and is read-only.
748 1 Adrian Georgescu
749 117 Adrian Georgescu
*call_id*
750
>The call ID of the @INVITE@ session as a read-only string.
751
>In the @NULL@ and @DISCONNECTED@ states, this attribute is @None@.
752 1 Adrian Georgescu
753 117 Adrian Georgescu
*transport*
754
>A string indicating the transport used for the application.
755
>This can be "udp", "tcp" or "tls".
756 1 Adrian Georgescu
757 117 Adrian Georgescu
*local_contact_header*
758
>The Contact header that the local side provided to the remote side within this @INVITE@ session as a @FrozenContactHeader@ object.
759
>Note that this can either be set on object creation or updated using the @send_reinvite()@ method.
760 1 Adrian Georgescu
761 117 Adrian Georgescu
*remote_contact_header*
762
>The Contact header that the remote side provided to us within this @INVITE@ session as a @FrozenContactHeader@ object.
763 1 Adrian Georgescu
764 117 Adrian Georgescu
*call_id*
765
>A string representing the Call-Id header value of this INVITE dialog.
766 1 Adrian Georgescu
767 117 Adrian Georgescu
*remote_user_agent*
768
>A string representing the remote user agent taken from the User-Agent or Server headers (depending on the direction of the original INVITE).
769 1 Adrian Georgescu
770 117 Adrian Georgescu
*sdp.proposed_local*
771
>The currently proposed sdp by the local party in the form of a @FrozenSDPSession@ object. This attribute is None when an SDP proposal is not in progress.
772 1 Adrian Georgescu
773 117 Adrian Georgescu
*sdp.proposed_remote*
774
>The currently proposed sdp by the remote party in the form of a @FrozenSDPSession@ object. This attribute is None when an SDP proposal is not in progress.
775 1 Adrian Georgescu
776 117 Adrian Georgescu
*sdp.active_local*
777
>The currently active sdp of the local party in the form of a @FrozenSDPSession@ object. This attribute is None if no SDP proposal has succeeded before.
778 1 Adrian Georgescu
779 117 Adrian Georgescu
*sdp.active_remote*
780
>The currently active sdp of the remote party in the form of a @FrozenSDPSession@ object. This attribute is None if no SDP proposal has succeeded before.
781 1 Adrian Georgescu
782 117 Adrian Georgescu
*peer_address*
783
>This read-only attribute contains the remote endpoint IP and port information. It can be accessed by accessing this object's @ip@ and @port@ attributes.
784 1 Adrian Georgescu
785
786 117 Adrian Georgescu
h4. methods
787 1 Adrian Georgescu
788
789
790 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_)
791
>Creates a new @Invitation@ object.
792 1 Adrian Georgescu
793 117 Adrian Georgescu
*send_invite*(_self_, *request_uri*,*from_header*, *to_header*, *route_header*, *contact_header*, *sdp*, *credentials*=@None@, *extra_headers*=@[]@, *timeout*=None)
794
  
795
>+_request_uri_+:
796 1 Adrian Georgescu
797 117 Adrian Georgescu
>Request URI to be set inthe outgoing INVITE request.
798
  
799
>+_from_header_+:
800 1 Adrian Georgescu
801 117 Adrian Georgescu
>The identity of the local account in the form of a @FromHeader@ object.
802
  
803
>+_to_header_+:
804 1 Adrian Georgescu
805 117 Adrian Georgescu
>The identity we want to send the @INVITE@ to, represented as a @ToHeader@ object.
806
  
807
>+_route_header_+:
808 1 Adrian Georgescu
809 117 Adrian Georgescu
>The outbound proxy to use in the form of a @RouteHeader@ object.
810
>This includes the desired transport to use.
811
  
812
>+_contact_header_+:
813 1 Adrian Georgescu
814 117 Adrian Georgescu
>The Contact header to include in the @INVITE@ request, a @ContactHeader@ object.
815
  
816
>+_sdp_+:
817 1 Adrian Georgescu
818 117 Adrian Georgescu
>The SDP to send as offer to the remote party.
819
  
820
>+_credentials_+:
821 1 Adrian Georgescu
822 117 Adrian Georgescu
>The optional SIP credentials needed to authenticate at the SIP proxy in the form of a @Credentials@ object.
823
  
824
>+_extra_headers_+:
825 1 Adrian Georgescu
826 117 Adrian Georgescu
>Any extra headers that should be included in the @INVITE@ request in the form of a list of header objects.
827
  
828
>+_timeout_+:
829 1 Adrian Georgescu
830 117 Adrian Georgescu
>How many seconds to wait for the remote party to reply before changing the state to @DISCONNECTED@ and internally replying with a 408, as an int or a float.
831
>If this is set to @None@, the default PJSIP timeout will be used, which appears to be slightly longer than 30 seconds.
832 1 Adrian Georgescu
833 117 Adrian Georgescu
*send_response*(_self_, *code*, *reason*, *contact_header*, *sdp*, *extra_headers*)
834
>Send a response to a INVITE request. 
835
  
836
>+_code_+:
837 1 Adrian Georgescu
838 117 Adrian Georgescu
>The code of the response to use as an int.
839
  
840
>+_reason_+:
841 1 Adrian Georgescu
842 117 Adrian Georgescu
>The reason of the response as a str.
843
  
844
>+_contact_header_+:
845 1 Adrian Georgescu
846 117 Adrian Georgescu
>The Contact header to include in the response, a @ContactHeader@ object.
847
  
848
>+_sdp_+:
849 1 Adrian Georgescu
850 117 Adrian Georgescu
>The SDP to send as offer/response to the remote party.
851
  
852
>+_extra_headers_+:
853 1 Adrian Georgescu
854 117 Adrian Georgescu
>Any extra headers that should be included in the response in the form of a list of header objects.
855 1 Adrian Georgescu
856 117 Adrian Georgescu
*send_reinvite*(_self_, *contact_header*=@None@, *sdp*=@None@, *extra_header*=@[]@)
857
  
858
>+_contact_header_+:
859 1 Adrian Georgescu
860 117 Adrian Georgescu
>The Contact header if it needs to be changed by the re-INVITE or None if it shouldn't be changed; a @BaseContactHeader@ object.
861
  
862
>+_sdp_+:
863 1 Adrian Georgescu
864 117 Adrian Georgescu
>The SDP to send as offer to the remote party or None if the re-INVITE should not change the SDP; a @BaseSDPSession@ object.
865
  
866
>+_extra_headers_+:
867 1 Adrian Georgescu
868 117 Adrian Georgescu
>Any extra headers that should be included in the response in the form of a list of header objects.
869 1 Adrian Georgescu
870 117 Adrian Georgescu
*cancel_reinvite*(_self_)
871
>Send a CANCEL after a re-INVITE has been sent to cancel the action of the re-INVITE.
872 1 Adrian Georgescu
873 117 Adrian Georgescu
*end*(_self_, *extra_headers*=@[]@, *timeout*=@None@)
874
>This moves the @INVITE@ state machine into the @DISCONNECTING@ state by sending the necessary SIP request.
875
>When a response from the remote party is received, the state machine will go into the @DISCONNECTED@ state.
876
>Depending on the current state, this could be a CANCEL or a BYE request.
877
  
878
>+_extra_headers_+:
879 1 Adrian Georgescu
880 117 Adrian Georgescu
>Any extra headers that should be included in the request or response in the form of a dict.
881
  
882
>+_timeout_+:
883 1 Adrian Georgescu
884 117 Adrian Georgescu
>How many seconds to wait for the remote party to reply before changing the state to @DISCONNECTED@, as an int or a float.
885
>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.
886 1 Adrian Georgescu
887
888 117 Adrian Georgescu
h4. notifications
889 1 Adrian Georgescu
890
891
892 117 Adrian Georgescu
*SIPInvitationChangedState*
893
>This notification is sent by an @Invitation@ object whenever its state machine changes state.
894
  
895
>+_timestamp_+:
896 1 Adrian Georgescu
897 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
898
  
899
>+_prev_state_+:
900 1 Adrian Georgescu
901 117 Adrian Georgescu
>The previous state of the INVITE state machine.
902
  
903
>+_prev_sub_state_+:
904 1 Adrian Georgescu
905 117 Adrian Georgescu
>THe previous sub-state of the INVITE state machine.
906
  
907
>+_state_+:
908 1 Adrian Georgescu
909 117 Adrian Georgescu
>The new state of the INVITE state machine, which may be the same as the previous state.
910
  
911
>+_sub_state_+:
912 1 Adrian Georgescu
913 117 Adrian Georgescu
>The new sub-state of teh INVITE state machine, which may be the same as the previous sub-state.
914
  
915
>+_method_+: (only if the state change got triggered by an incoming SIP request)
916 1 Adrian Georgescu
917 117 Adrian Georgescu
>The method of the SIP request as a string.
918
  
919
>+_request_uri_+: (only if the state change got triggered by an incoming SIP request)
920
921
>The request URI of the SIP request as a @SIPURI@ object.
922
  
923
>+_code_+: (only if the state change got triggered by an incoming SIP response or internal timeout or error)
924
925
>The code of the SIP response or error as an int.
926
  
927
>+_reason_+: (only if the state change got triggered by an incoming SIP response or internal timeout or error)
928
929
>The reason text of the SIP response or error as a string.
930
  
931
>+_headers_+: (only if the state change got triggered by an incoming SIP request or response)
932
933
>The headers of the SIP request or response as a dict.
934
>Each SIP header is represented in its parsed for as long as PJSIP supports it.
935
>The format of the parsed value depends on the header.
936
  
937
>+_body_+: (only if the state change got triggered by an incoming SIP request or response)
938
939
>The body of the SIP request or response as a string, or @None@ if no body was included.
940
>The content type of the body can be learned from the @Content-Type:@ header in the headers argument.
941
942
*SIPInvitationGotSDPUpdate*
943
>This notification is sent by an @Invitation@ object whenever SDP negotiation has been performed.
944
>It should be used by the application as an indication to start, change or stop any associated media streams.
945
  
946
>+_timestamp_+:
947
948
>A @datetime.datetime@ object indicating when the notification was sent.
949
  
950
>+_succeeded_+:
951
952
>A boolean indicating if the SDP negotiation has succeeded.
953
  
954
>+_error_+: (only if SDP negotiation did not succeed)
955
956
>A string indicating why SDP negotiation failed.
957
  
958
>+_local_sdp_+: (only if SDP negotiation succeeded)
959
960
>A SDPSession object indicating the local SDP that was negotiated.
961
  
962
>+_remote_sdp_+: (only if SDP negotiation succeeded)
963
964
>A SDPSession object indicating the remote SDP that was negotiated.
965
966
967
968
h3. SDPSession
969
970
971
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 "RFC 4566":http://tools.ietf.org/html/rfc4566. "RFC 3264":http://tools.ietf.org/html/rfc3264 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. 
972
973
@SDPSession@ and @FrozenSDPSession@ objects directly represent the contents of a SDP body, as carried e.g. in an INVITE request, and is a simple wrapper for the PJSIP "pjmedia_sdp_session":http://www.pjsip.org/pjmedia/docs/html/structpjmedia+sdp+session.htm structure.
974
They can be passed to those methods of an @Invitation@ object that result in transmission of a message that includes SDP, or are passed to the application through a notification that is triggered by reception of a message that includes SDP.
975
A @(Frozen)SDPSession@ object may contain @(Frozen)SDPMediaStream@, @(Frozen)SDPConnection@ and @(Frozen)SDPAttribute@ objects.
976
It supports comparison to other @(Frozen)SDPSession@ objects using the == and != expressions.
977
As all the attributes of the @(Frozen)SDPSession@ class are set by attributes of the @__init__@ method, they will be documented along with that method.
978
979
980
h4. methods
981
982
983
984
*<notextile>__init__</notextile>*(_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@)
985
>Creates the SDPSession object with the specified parameters as attributes.
986
>Each of these attributes can be accessed and changed on the object once instanced.
987
  
988
>+_address_+:
989
990
>The address that is contained in the "o" (origin) line of the SDP as a string.
991
  
992
>+_id_+:
993
994
>The session identifier contained in the "o" (origin) line of the SDP as an int.
995
>If this is set to @None@ on init, a session identifier will be generated.
996
  
997
>+_version_+:
998
999
>The version identifier contained in the "o" (origin) line of the SDP as an int.
1000
>If this is set to @None@ on init, a version identifier will be generated.
1001
  
1002
>+_user_+:
1003
1004
>The user name contained in the "o" (origin) line of the SDP as a string.
1005
  
1006
>+_net_type_+:
1007
1008
>The network type contained in the "o" (origin) line of the SDP as a string.
1009
  
1010
>+_address_type_+:
1011
1012
>The address type contained in the "o" (origin) line of the SDP as a string.
1013
  
1014
>+_name_+:
1015
1016
>The contents of the "s" (session name) line of the SDP as a string.
1017
  
1018
>+_info_+:
1019
1020
>The contents of the session level "i" (information) line of the SDP as a string.
1021
>If this is @None@ or an empty string, the SDP has no "i" line.
1022
  
1023
>+_connection_+:
1024
1025
>The contents of the "c" (connection) line of the SDP as a @(Frozen)SDPConnection@ object.
1026
>If this is set to @None@, the SDP has no session level "c" line.
1027
  
1028
>+_start_time_+:
1029
1030
>The first value of the "t" (time) line of the SDP as an int.
1031
  
1032
>+_stop_time_+:
1033
1034
>The second value of the "t" (time) line of the SDP as an int.
1035
  
1036
>+_attributes_+:
1037
1038
>The session level "a" lines (attributes) in the SDP represented by a list of @(Frozen)SDPAttribute@ objects.
1039
  
1040
>+_media_+:
1041
1042
>The media sections of the SDP represented by a list of @(Frozen)SDPMediaStream@ objects.
1043
1044
*new*(_cls_, _sdp_session_)
1045
>Classmethod that returns an instance of the class on which it has been called which is a copy of the @sdp_session@ object (which must be either a SDPSession or a FrozenSDPSession).
1046
1047
1048
h4. attributes
1049
1050
1051
1052
*has_ice_proposal*
1053
>This read-only attribute returns @True@ if the SDP contains any attributes which indicate the existence of an ice proposal and @False@ otherwise.
1054
1055
1056
h3. SDPMediaStream
1057
1058
1059
The @SDPMediaStream@ and @FrozenSDPMediaStream@ objects represent the contents of a media section of a SDP body, i.e. a "m" line and everything under it until the next "m" line.
1060
It is a simple wrapper for the PJSIP "pjmedia_sdp_media":http://www.pjsip.org/pjmedia/docs/html/structpjmedia+sdp+media.htm structure.
1061
One or more @(Frozen)SDPMediaStream@ objects are usually contained in a @(Frozen)SDPSession@ object.
1062
It supports comparison to other @(Frozen)SDPMedia@ objects using the == and != expressions.
1063
As all the attributes of this class are set by attributes of the @__init__@ method, they will be documented along with that method.
1064
1065
1066
h4. methods
1067
1068
1069
1070
*<notextile>__init__</notextile>*(_self_, *media*, *port*, *transport*, *port_count*=1, *formats*=@None@, *info*=@None@, *connection*=@None@, *attributes*=@None@)
1071
>Creates the SDPMedia object with the specified parameters as attributes.
1072
>Each of these attributes can be accessed and changed on the object once instanced.
1073
  
1074
>+_media_+:
1075
1076
>The media type contained in the "m" (media) line as a string.
1077
  
1078
>+_port_+:
1079
1080
>The transport port contained in the "m" (media) line as an int.
1081
  
1082
>+_transport_+:
1083
1084
>The transport protocol in the "m" (media) line as a string.
1085
  
1086
>+_port_count_+:
1087
1088
>The port count in the "m" (media) line as an int.
1089
>If this is set to 1, it is not included in the SDP.
1090
  
1091
>+_formats_+:
1092
1093
>The media formats in the "m" (media) line represented by a list of strings.
1094
  
1095
>+_info_+:
1096
1097
>The contents of the "i" (information) line of this media section as a string.
1098
>If this is @None@ or an empty string, the media section has no "i" line.
1099
  
1100
>+_connection_+:
1101
1102
>The contents of the "c" (connection) line that is somewhere below the "m" line of this section as a @(Frozen)SDPConnection@ object.
1103
>If this is set to @None@, this media section has no "c" line.
1104
  
1105
>+_attributes_+:
1106
1107
>The "a" lines (attributes) that are somewhere below the "m" line of this section represented by a list of @(Frozen)SDPAttribute@ objects.
1108
1109
*new*(_cls_, _sdp_media_)
1110
>Classmethod that returns an instance of the class on which it has been called which is a copy of the @sdp_media@ object (which must be either a SDPMediaStream or a FrozenSDPMediaStream).
1111
1112
1113
h4. attributes
1114
1115
1116
1117
*direction*
1118
>This is a convenience read-only attribute that goes through all the attributes of the media section and returns the direction, which is either "sendrecv", "sendonly", "recvonly" or "inactive".
1119
>If none of these attributes is present, the default direction is "sendrecv".
1120
1121
1122
h3. SDPConnection
1123
1124
1125
The @SDPConnection@ and @FrozenSDPConnection@ objects represents the contents of a "c" (connection) line of a SDP body, either at the session level or for an individual media stream.
1126
It is a simple wrapper for the PJSIP "pjmedia_sdp_conn":http://www.pjsip.org/pjmedia/docs/html/structpjmedia+sdp+conn.htm structure.
1127
A @(Frozen)SDPConnection@ object can be contained in a @(Frozen)SDPSession@ object or @(Frozen)SDPMediaStream@ object.
1128
It supports comparison to other @(Frozen)SDPConnection@ objects using the == and != expressions.
1129
As all the attributes of this class are set by attributes of the @__init__@ method, they will be documented along with that method.
1130
1131
1132
h4. methods
1133
1134
1135
1136
*<notextile>__init__</notextile>*(_self_, *address*, *net_type*="IN", *address_type*="IP4")
1137
>Creates the SDPConnection object with the specified parameters as attributes.
1138
>Each of these attributes can be accessed and changed on the object once instanced.
1139
  
1140
>+_address_+:
1141
1142
>The address part of the connection line as a string.
1143
  
1144
>+_net_type_+:
1145
1146
>The network type part of the connection line as a string.
1147
  
1148
>+_address_type_+:
1149
1150
>The address type part of the connection line as a string.
1151
1152
*new*(_cls_, _sdp_connection_)
1153
>Classmethod that returns an instance of the class on which it has been called which is a copy of the @sdp_connection@ object (which must be either a SDPConnection or a FrozenSDPConnection).
1154
1155
1156
h3. SDPAttributeList
1157
1158
1159
@SDPAttributeList@ and @FrozenSDPAttributeList@ are subclasses of @list@ and @frozenlist@ respectively and are used as the types of the @attributes@ attributes of @(Frozen)SDPSession@ and @(Frozen)SDPMediaStream@. They provide convinience methods for accessing SDP attributes. Apart from the standard @list@ and @frozenlist@ methods, they also provide the following:
1160
1161
1162
*<notextile>__contains__</notextile>*(_self_, _item_)
1163
>If _item_ is an instance of BaseSDPAttribute, the normal @(frozen)list@ method is called. Otherwise, the method returns whether or not _item_ is in the list of the names of the attributes. This allows tests such as the following to be possible:
1164
  <pre>
1165 1 Adrian Georgescu
  'ice-pwd' in sdp_session.attributes
1166 117 Adrian Georgescu
</pre>
1167 1 Adrian Georgescu
1168 117 Adrian Georgescu
*getall*(_self_, _name_)
1169
>Returns all the values of the attributes with the given name in a list.
1170 1 Adrian Georgescu
1171 117 Adrian Georgescu
*getfirst*(_self_, _name_, _default_=@None@)
1172
>Return the first value of the attribute with the given name, or _default_ is no such attribute exists.
1173 1 Adrian Georgescu
1174
1175 117 Adrian Georgescu
h3. SDPAttribute
1176 1 Adrian Georgescu
1177
1178 117 Adrian Georgescu
The @SDPAttribute@ and @FrozenSDPAttribute@ objects represent the contents of a "a" (attribute) line of a SDP body, either at the session level or for an individual media stream.
1179
It is a simple wrapper for the PJSIP "pjmedia_sdp_attr":http://www.pjsip.org/pjmedia/docs/html/structpjmedia+sdp+attr.htm structure.
1180
One or more @(Frozen)SDPAttribute@ objects can be contained in a @(Frozen)SDPSession@ object or @(Frozen)SDPMediaStream@ object.
1181
It supports comparison to other @(Frozen)SDPAttribute@ objects using the == and != expressions.
1182
As all the attributes of this class are set by attributes of the @__init__@ method, they will be documented along with that method.
1183 1 Adrian Georgescu
1184
1185 117 Adrian Georgescu
h4. methods
1186 1 Adrian Georgescu
1187
1188
1189 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_, *name*, *value*)
1190
>Creates the SDPAttribute object with the specified parameters as attributes.
1191
>Each of these attributes can be accessed and changed on the object once instanced.
1192
  
1193
>+_name_+:
1194
1195
>The name part of the attribute line as a string.
1196
  
1197
>+_value_+:
1198
1199
>The value part of the attribute line as a string.
1200
1201
*new*(_cls_, _sdp_attribute_)
1202
>Classmethod that returns an instance of the class on which it has been called which is a copy of the @sdp_attribute@ object (which must be either a SDPAttribute or a FrozenSDPAttribute).
1203
1204
1205
1206
h3. RTPTransport
1207
1208
1209 1 Adrian Georgescu
This object represents a transport for RTP media, the basis of which is a pair of UDP sockets, one for RTP and one for RTCP.
1210 117 Adrian Georgescu
Internally it wraps a "pjmedia_transport":http://www.pjsip.org/pjmedia/docs/html/group+PJMEDIA+TRANSPORT.htm object.
1211
Initially this object will only be used by the @AudioTransport@ object, but in the future it can also be used for video and [[RTTProposal|Real-Time Text]].
1212
For this reason the @AudioTransport@ and @RTPTransport@ are two distinct objects.
1213 1 Adrian Georgescu
1214 117 Adrian Georgescu
The @RTPTransport@ object also allows support for ICE and SRTP functionality from PJSIP.
1215 1 Adrian Georgescu
Because these features are related to both the UDP transport and the SDP formatting, the SDP carried in SIP signaling message will need to "pass through" this object during the SDP negotiation.
1216 117 Adrian Georgescu
The code using this object, which in most cases will be the @AudioTransport@ object, will need to call certain methods on the object at appropriate times.
1217 1 Adrian Georgescu
This process of SDP negotiation is represented by the internal state machine of the object, as shown in the following diagram:
1218
1219
> The Real-time Transport Protocol (or RTP) defines a standardized packet format for delivering audio and video over the Internet.
1220 117 Adrian Georgescu
> It was developed by the Audio-Video Transport Working Group of the IETF and published in "RFC 3550":http://tools.ietf.org/html/rfc3550.
1221 1 Adrian Georgescu
> RTP is used in streaming media systems (together with the RTSP) as well as in videoconferencing and push to talk systems.
1222
> 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.
1223
1224 117 Adrian Georgescu
!{ nolink}sipsimple-rtp-transport-state-machine.png!
1225 1 Adrian Georgescu
1226
State changes are triggered by the following events:
1227 117 Adrian Georgescu
# The application calls the @set_INIT()@ method after object creation and ICE+STUN is not used.
1228
# The application calls the @set_INIT()@ method after object creation and ICE+STUN is used.
1229
# A successful STUN response is received from the STUN server.
1230
# The @set_LOCAL()@ method is called.
1231
# The @set_ESTABLISHED()@ method is called.
1232
# The @set_INIT()@ method is called while the object is in the @LOCAL@ or @ESTABLISHED@ state.
1233
# A method is called on the application, but in the meantime the @Engine@ has stopped.
1234 1 Adrian Georgescu
    The object can no longer be used.
1235 117 Adrian Georgescu
# There was an error in getting the STUN candidates from the STUN server.
1236 1 Adrian Georgescu
1237
> 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.
1238
> This means that the RTPTransport object is also unusable once it has reached the STUN_FAILED state.
1239
> A workaround would be destroy the RTPTransport object and create a new one that uses ICE without STUN.
1240
1241
These states allow for two SDP negotiation scenarios to occur, represented by two paths that can be followed through the state machine.
1242
In this example we will assume that ICE with STUN is not used, as it is independent of the SDP negotiation procedure.
1243 117 Adrian Georgescu
* The first scenario is where the local party generates the SDP offer.
1244
   For a stream that it wishes to include in this SDP offer, it instantiates a @RTPTransport@ object.
1245
   After instantiation the object is initialized by calling the @set_INIT()@ method and the local RTP address and port can be fetched from it using the @local_rtp_address@ and @local_rtp_port@ attributes respectively, which can be used to generate the local SDP in the form of a @SDPSession@ object.
1246
   This local SDP then needs to be passed to the @set_LOCAL()@ method, which moves the state machine into the @LOCAL@ state (note that it needs the full object, not just the relevant @SDPMediaStream@ object).
1247
   Depending on the options used for the @RTPTransport@ instantiation (such as ICE and SRTP), this may change the @SDPSession@ object.
1248
   This (possibly changed) @SDPSession@ object then needs to be passed to the @Invitation@ object.
1249
   After SDP negotiation is completed, the application needs to pass both the local and remote SDP, in the form of @(Frozen)SDPSession@ objects, to the @RTPTransport@ object using the @set_ESTABLISHED()@ method, moving the state machine into the @ESTABLISHED@ state.
1250
   This will not change either of the @(Frozen)SDPSession@ objects (which is why they can also be frozen).
1251
* The second scenario is where the local party is offered a media stream in SDP and wants to accept it.
1252
   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.
1253
   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.
1254
   In this case the local SDP object may be changed, after which it can be passed to the @Invitation@ object.
1255 1 Adrian Georgescu
1256 117 Adrian Georgescu
Whenever the @RTPTransport@ object is in the @LOCAL@ or @ESTABLISHED@ states, it may be reset to the @INIT@ state to facilitate re-use of the existing transport and its features.
1257 1 Adrian Georgescu
Before doing this however, the internal transport object must no longer be in use.
1258
1259
1260 117 Adrian Georgescu
h4. methods
1261 1 Adrian Georgescu
1262
1263
1264 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_, *local_rtp_address*=@None@, *use_srtp*=@False@, *srtp_forced*=@False@, *use_ice*=@False@, *ice_stun_address*=@None@, *ice_stun_port*=3478)
1265
>Creates a new @RTPTransport@ object and opens the RTP and RTCP UDP sockets.
1266
>If additional features are requested, they will be initialized.
1267
>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.
1268
  
1269
>+_local_rtp_address_+:
1270 1 Adrian Georgescu
1271 117 Adrian Georgescu
>Optionally contains the local IPv4 address to listen on.
1272
>If this is not specified, PJSIP will listen on all network interfaces.
1273
  
1274
>+_use_srtp_+:
1275 1 Adrian Georgescu
1276 117 Adrian Georgescu
>A boolean indicating if SRTP should be used.
1277
>If this is set to @True@, SRTP information will be added to the SDP when it passes this object.
1278
  
1279
>+_srtp_forced_+:
1280 1 Adrian Georgescu
1281 117 Adrian Georgescu
>A boolean indicating if use of SRTP is set to mandatory in the SDP.
1282
>If this is set to @True@ and the remote party does not support SRTP, the SDP negotiation for this stream will fail.
1283
>This argument is relevant only if @use_srtp@ is set to @True@.
1284
  
1285
>+_use_ice_+:
1286 1 Adrian Georgescu
1287 117 Adrian Georgescu
>A boolean indicating if ICE should be used.
1288
>If this is set to @True@, ICE candidates will be added to the SDP when it passes this object.
1289
  
1290
>+_ice_stun_address_+:
1291 1 Adrian Georgescu
1292 117 Adrian Georgescu
>A string indicating the address (IP address or hostname) of the STUN server that should be used to add a STUN candidate to the ICE candidates.
1293
>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.
1294
>When this happens a @RTPTransportGotSTUNResponse@ notification is sent.
1295
>This argument is relevant only if @use_ice@ is set to @True@.
1296
  
1297
>+_ice_stun_address_+:
1298 1 Adrian Georgescu
1299 117 Adrian Georgescu
>An int indicating the UDP port of the STUN server that should be used to add a STUN candidate to the ICE candidates.
1300
>This argument is relevant only if @use_ice@ is set to @True@ and @ice_stun_address@ is not @None@.
1301 1 Adrian Georgescu
1302 117 Adrian Georgescu
*set_INIT*(_self_)
1303
>This moves the internal state machine into the @INIT@ state.
1304
>If the state machine is in the @LOCAL@ or @ESTABLISHED@ states, this effectively resets the @RTPTransport@ object for re-use.
1305 1 Adrian Georgescu
1306 117 Adrian Georgescu
*set_LOCAL*(_self_, *local_sdp*, *sdp_index*)
1307
>This moves the the internal state machine into the @LOCAL@ state.
1308
  
1309
>+_local_sdp_+:
1310 1 Adrian Georgescu
1311 117 Adrian Georgescu
>The local SDP to be proposed in the form of a @SDPSession@ object.
1312
>Note that this object may be modified by this method.
1313
  
1314
>+_sdp_index_+:
1315 1 Adrian Georgescu
1316 117 Adrian Georgescu
>The index in the SDP for the media stream for which this object was created.
1317 1 Adrian Georgescu
1318 117 Adrian Georgescu
*set_ESTABLISHED*(_self_, *local_sdp*, *remote_sdp*, *sdp_index*)
1319
>This moves the the internal state machine into the @ESTABLISHED@ state.
1320
  
1321
>+_local_sdp_+:
1322 1 Adrian Georgescu
1323 117 Adrian Georgescu
>The local SDP to be proposed in the form of a @SDPSession@ object.
1324
>Note that this object may be modified by this method, but only when moving from the @LOCAL@ to the @ESTABLISHED@ state.
1325
  
1326
>+_remote_sdp_+:
1327 1 Adrian Georgescu
1328 117 Adrian Georgescu
>The remote SDP that was received in in the form of a @SDPSession@ object.
1329
  
1330
>+_sdp_index_+:
1331 1 Adrian Georgescu
1332 117 Adrian Georgescu
>The index in the SDP for the media stream for which this object was created.
1333 1 Adrian Georgescu
1334
1335 117 Adrian Georgescu
h4. attributes
1336 1 Adrian Georgescu
1337
1338
1339 117 Adrian Georgescu
*state*
1340
>Indicates which state the internal state machine is in.
1341
>See the previous section for a list of states the state machine can be in.
1342
>This attribute is read-only.
1343 1 Adrian Georgescu
1344 117 Adrian Georgescu
*local_rtp_address*
1345
>The local IPv4 address of the interface the @RTPTransport@ object is listening on and the address that should be included in the SDP.
1346
>If no address was specified during object instantiation, PJSIP will take guess out of the IP addresses of all interfaces.
1347
>This attribute is read-only and will be @None@ if PJSIP is not listening on the transport.
1348 1 Adrian Georgescu
1349 117 Adrian Georgescu
*local_rtp_port*
1350
>The UDP port PJSIP is listening on for RTP traffic.
1351
>RTCP traffic will always be this port plus one.
1352
>This attribute is read-only and will be @None@ if PJSIP is not listening on the transport.
1353 1 Adrian Georgescu
1354 117 Adrian Georgescu
*remote_rtp_address_sdp*
1355
>The remote IP address that was seen in the SDP.
1356
>This attribute is read-only and will be @None@ unless the object is in the @ESTABLISHED@ state.
1357 1 Adrian Georgescu
1358 117 Adrian Georgescu
*remote_rtp_port_sdp*
1359
>The remote UDP port for RTP that was seen in the SDP.
1360
>This attribute is read-only and will be @None@ unless the object is in the @ESTABLISHED@ state.
1361 1 Adrian Georgescu
1362 117 Adrian Georgescu
*remote_rtp_address_ice*
1363
>The remote IP address that was selected by the ICE negotation.
1364
>This attribute is read-only and will be @None@ until the ICE negotation succeeds.
1365 1 Adrian Georgescu
1366 117 Adrian Georgescu
*remote_rtp_port_ice*
1367
>The remote port that was selected by the ICE negotation.
1368
>This attribute is read-only and will be @None@ until the ICE negotation succeeds.
1369 1 Adrian Georgescu
1370 117 Adrian Georgescu
*remote_rtp_address_received*
1371
>The remote IP address from which RTP data was received.
1372
>This attribute is read-only and will be @None@ unless RTP was actually received.
1373 1 Adrian Georgescu
1374 117 Adrian Georgescu
*remote_rtp_port_received*
1375
>The remote UDP port from which RTP data was received.
1376
>This attribute is read-only and will be @None@ unless RTP was actually received.
1377 1 Adrian Georgescu
1378 117 Adrian Georgescu
*use_srtp*
1379
>A boolean indicating if the use of SRTP was requested when the object was instantiated.
1380
>This attribute is read-only.
1381 1 Adrian Georgescu
1382 117 Adrian Georgescu
*force_srtp*
1383
>A boolean indicating if SRTP being mandatory for this transport if it is enabled was requested when the object was instantiated.
1384
>This attribute is read-only.
1385 1 Adrian Georgescu
1386 117 Adrian Georgescu
*srtp_active*
1387
>A boolean indicating if SRTP encryption and decryption is running.
1388
>Querying this attribute only makes sense once the object is in the @ESTABLISHED@ state and use of SRTP was requested.
1389
>This attribute is read-only.
1390
1391
*use_ice*
1392
>A boolean indicating if the use of ICE was requested when the object was instantiated.
1393
>This attribute is read-only.
1394
1395
*ice_active_
1396
>A boolean indicating if ICE is being used.
1397
>This attribute is read-only.
1398
1399
*ice_stun_address*
1400
>A string indicating the IP address of the STUN server that was requested to be used.
1401
>This attribute is read-only.
1402
1403
*ice_stun_port*
1404
>A string indicating the UDP port of the STUN server that was requested to be used.
1405
>This attribute is read-only.
1406
1407
*local_rtp_candidate_type*
1408
>Returns the ICE candidate type which has been selected for the local endpoint.
1409
1410
*remote_rtp_candidate_type*
1411
>Returns the ICE candidate type which has been selected for the remote endpoint.
1412
1413
1414
h4. notifications
1415
1416
1417
1418
*RTPTransportDidInitialize*
1419
>This notification is sent when a @RTPTransport@ object has successfully initialized.
1420
>If STUN+ICE is not requested, this is sent immediately on @set_INIT()@, otherwise it is sent after the STUN query has succeeded.
1421
  
1422
>+_timestamp_+:
1423
1424
>A @datetime.datetime@ object indicating when the notification was sent.
1425
1426
*RTPTransportDidFail*
1427
>This notification is sent by a @RTPTransport@ object that fails to retrieve ICE candidates from the STUN server after @set_INIT()@ is called.
1428
  
1429
>+_timestamp_+:
1430
1431
>A @datetime.datetime@ object indicating when the notification was sent.
1432
  
1433
>+_reason_+:
1434
1435
>A string describing the failure reason.
1436
1437
*RTPTransportICENegotiationStateDidChange*
1438
>This notification is sent to indicate the progress of the ICE negotiation.
1439
  
1440
>+_state_+:
1441
1442
>A string describing the current ICE negotiation state.
1443
1444
*RTPTransportICENegotiationDidFail*
1445
>This notification is sent when the ICE negotiation fails.
1446
  
1447
>+_reason_+:
1448
1449
>A string describing the failure reason of ICE negotation.
1450
1451
*RTPTransportICENegotiationDidSucceed*
1452
>This notification is sent when the ICE negotation succeeds.
1453
  
1454
>+_chosen_local_candidates_ and _chosen_remote_candidates_+:
1455
1456
>Dictionaries with the following keys:
1457
*** rtp_cand_type: the type of the RTP candidate
1458
*** rtp_cand_ip: the IP address of the RTP candidate
1459
*** rtcp_cand_type: the type of the RTCP candidate
1460
*** rtcp_cand_ip: the IP address of teh RTCP candidate
1461
  
1462
>+_duration_+:
1463
1464
>The amount of time the ICE negotiation took.
1465
  
1466
>+_local_candidates_ and _remote_candidates_+:
1467
1468
>Lists of tuples with the following elements:
1469
*** Item ID
1470
*** Component ID
1471
*** Address
1472
*** Component Type
1473
  
1474
>+_connectivity_checks_results_+:
1475
1476
>A list of tuples with the following elements:
1477
*** Item ID
1478
*** Component ID
1479
*** Source
1480
*** Destination
1481
*** Nomination
1482
*** State
1483
1484
1485
h3. AudioTransport
1486
1487
1488 1 Adrian Georgescu
This object represent an audio stream as it is transported over the network.
1489 117 Adrian Georgescu
It contains an instance of @RTPTransport@ and wraps a "pjmedia_stream":http://www.pjsip.org/pjmedia/docs/html/group+PJMED+STRM.htm object, which in turn manages the RTP encapsulation, RTCP session, audio codec and adaptive jitter buffer.
1490
It also generates a @SDPMediaStream@ object to be included in the local SDP.
1491 1 Adrian Georgescu
1492 117 Adrian Georgescu
The @AudioTransport@ is an object that, once started, is connected to a @AudioMixer@ instance, and both produces and consumes sound.
1493 1 Adrian Georgescu
1494 117 Adrian Georgescu
Like the @RTPTransport@ object there are two usage scenarios.
1495
* In the first scenario, only the @RTPTransport@ instance to be used is passed to the AudioTransport object.
1496
   The application can then generate the @SDPMediaStream@ object by calling the @get_local_media()@ method and should include it in the SDP offer.
1497
   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.
1498 1 Adrian Georgescu
   The stream can then be connected to the conference bridge.
1499 117 Adrian Georgescu
* In the other scenario the remote SDP is already known because it was received in an SDP offer and can be passed directly on object instantiation.
1500
   The local @SDPMediaStream@ object can again be generated by calling the @get_local_media()@ method and is to be included in the SDP answer.
1501 1 Adrian Georgescu
   The audio stream is started directly when the object is created.
1502
1503 117 Adrian Georgescu
Unlike the @RTPTransport@ object, this object cannot be reused.
1504 1 Adrian Georgescu
1505
1506 117 Adrian Georgescu
h4. methods
1507 1 Adrian Georgescu
1508
1509
1510 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_, *mixer*, *transport*, *remote_sdp*=@None@, *sdp_index*=0, *enable_silence_detection*=True, *codecs*=@None@)
1511
>Creates a new @AudioTransport@ object and start the underlying stream if the remote SDP is already known.
1512
  
1513
>+_mixer_+:
1514 1 Adrian Georgescu
1515 117 Adrian Georgescu
>The @AudioMixer@ object that this object is to be connected to.
1516
  
1517
>+_transport_+:
1518 1 Adrian Georgescu
1519 117 Adrian Georgescu
>The transport to use in the form of a @RTPTransport@ object.
1520
  
1521
>+_remote_sdp_+:
1522 1 Adrian Georgescu
1523 117 Adrian Georgescu
>The remote SDP that was received in the form of a @SDPSession@ object.
1524
  
1525
>+_sdp_index_+:
1526 1 Adrian Georgescu
1527 117 Adrian Georgescu
>The index within the SDP of the audio stream that should be created.
1528
  
1529
_enable_silence_detection_
1530 1 Adrian Georgescu
1531 117 Adrian Georgescu
>Boolean that indicates if silence detection should be used for this audio stream.
1532
>When enabled, this @AudioTransport@ object will stop sending audio to the remote party if the input volume is below a certain threshold.
1533
  
1534
_codecs_
1535 1 Adrian Georgescu
1536 117 Adrian Georgescu
>A list of strings indicating the codecs that should be proposed in the SDP of this @AudioTransport@, in order of preference.
1537
>This overrides the global codecs list set on the @Engine@.
1538
>The values of this list are case insensitive.
1539 1 Adrian Georgescu
1540 117 Adrian Georgescu
*get_local_media*(_self_, *is_offer*, *direction*="sendrecv")
1541
>Generates a @SDPMediaStream@ object which describes the audio stream.
1542
>This object should be included in a @SDPSession@ object that gets passed to the @Invitation@ object.
1543
>This method should also be used to obtain the SDP to include in re-INVITEs and replies to re-INVITEs.
1544
  
1545
>+_is_offer_+:
1546 1 Adrian Georgescu
1547 117 Adrian Georgescu
>A boolean indicating if the SDP requested is to be included in an offer.
1548
>If this is @False@ it is to be included in an answer.
1549
  
1550
>+_direction_+:
1551 1 Adrian Georgescu
1552 117 Adrian Georgescu
>The direction attribute to put in the SDP.
1553 1 Adrian Georgescu
1554 117 Adrian Georgescu
*start*(_self_, *local_sdp*, *remote_sdp*, *sdp_index*, *no_media_timeout*=10, *media_check_interval*=30)
1555
>This method should only be called once, when the application has previously sent an SDP offer and the answer has been received.
1556
  
1557
>+_local_sdp_+:
1558 1 Adrian Georgescu
1559 117 Adrian Georgescu
>The full local SDP that was included in the SDP negotiation in the form of a @SDPSession@ object.
1560
  
1561
>+_remote_sdp_+:
1562 1 Adrian Georgescu
1563 117 Adrian Georgescu
>The remote SDP that was received in the form of a @SDPSession@ object.
1564
  
1565
>+_sdp_index_+:
1566 1 Adrian Georgescu
1567 117 Adrian Georgescu
>The index within the SDP of the audio stream.
1568
  
1569
>+_no_media_timeout_+:
1570 1 Adrian Georgescu
1571 117 Adrian Georgescu
>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.
1572
>Setting this to 0 disables this an all subsequent RTP checks.
1573
  
1574
>+_media_check_interval_+:
1575 1 Adrian Georgescu
1576 117 Adrian Georgescu
>This indicates the interval at which the RTP stream should be checked, after it has initially received RTP at after @no_media_timeout@ seconds.
1577
>It means that if between two of these interval checks no RTP has been received, a @RTPAudioTransportDidNotGetRTP@ notification will be sent.
1578
>Setting this to 0 will disable checking the RTP at intervals.
1579
>The initial check may still be performed if its timeout is non-zero.
1580 84 Ruud Klaver
1581 117 Adrian Georgescu
*stop*(_self_)
1582
>This method stops and destroys the audio stream encapsulated by this object.
1583
>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.
1584
>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.
1585 84 Ruud Klaver
1586 117 Adrian Georgescu
*send_dtmf*(_self_, *digit*)
1587
>For a negotiated audio transport this sends one DTMF digit to the other party
1588
  
1589
>+_digit_+:
1590 84 Ruud Klaver
1591 117 Adrian Georgescu
>A string of length one indicating the DTMF digit to send.
1592
>This can be either a digit, the pound sign (#), the asterisk sign (*) or the letters A through D.
1593 1 Adrian Georgescu
1594 117 Adrian Georgescu
*update_direction*(_self_, *direction*)
1595
>This method should be called after SDP negotiation has completed to update the direction of the media stream.
1596
  
1597
>+_direction_+:
1598 1 Adrian Georgescu
1599 117 Adrian Georgescu
>The direction that has been negotiated.
1600 1 Adrian Georgescu
1601 117 Adrian Georgescu
1602
h4. attributes
1603
1604
1605
1606
*mixer*
1607
>The @AudioMixer@ object that was passed when the object got instantiated.
1608
>This attribute is read-only.
1609
1610
*transport*
1611
>The @RTPTransport@ object that was passed when the object got instantiated.
1612
>This attribute is read-only.
1613
1614
*slot*
1615
>A read-only property indicating the slot number at which this object is attached to the associated conference bridge.
1616
>If the @AudioTransport@ is not active (i.e. has not been started), this attribute will be @None@.
1617
1618
*volume*
1619
>A writable property indicating the % of volume at which this object contributes audio to the conference bridge.
1620
>By default this is set to 100.
1621
1622
*is_active*
1623
>A boolean indicating if the object is currently sending and receiving audio.
1624
>This attribute is read-only.
1625
1626
*is_started*
1627
>A boolean indicating if the object has been started.
1628
>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.
1629
>This is to prevent the object from being re-used.
1630
>This attribute is read-only.
1631
1632
*codec*
1633
>Once the SDP negotiation is complete, this attribute indicates the audio codec that was negotiated, otherwise it will be @None@.
1634
>This attribute is read-only.
1635
1636
*sample_rate*
1637
>Once the SDP negotiation is complete, this attribute indicates the sample rate of the audio codec that was negotiated, otherwise it will be @None@.
1638
>This attribute is read-only.
1639
1640
*direction*
1641
>The current direction of the audio transport, which is one of "sendrecv", "sendonly", "recvonly" or "inactive".
1642
>This attribute is read-only, although it can be set using the @update_direction()@ method.
1643
1644
1645
h4. notifications
1646
1647
1648
1649
*RTPAudioTransportGotDTMF*
1650
>This notification will be sent when an incoming DTMF digit is received from the remote party.
1651
  
1652
>+_timestamp_+:
1653
1654
>A @datetime.datetime@ object indicating when the notification was sent.
1655
  
1656
>+_digit_+:
1657
1658
>The DTMF digit that was received, in the form of a string of length one.
1659
>This can be either a number or letters A through D.
1660
1661
*RTPAudioTransportDidNotGetRTP*
1662
>This notification will be sent when no RTP packets have been received from the remote party for some time.
1663
>See the @start()@ method for a more exact description.
1664
  
1665
>+_timestamp_+:
1666
1667
>A @datetime.datetime@ object indicating when the notification was sent.
1668
  
1669
>+_got_any_+:
1670
1671
>A boolean data attribute indicating if the @AudioTransport@ every saw any RTP packets from the remote party.
1672
>In effect, if no RTP was received after @no_media_timeout@ seconds, its value will be @False@.
1673
1674
1675
h3. Request
1676
1677
1678
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.
1679
Although this class can be used by the application to construct and send an arbitrary SIP request, most applications will use the classes for primitive requests provided in the @sipsimple.core@ module, which are built on top of one or several @Request@ objects and deal with instances of specific SIP methods (REGISTER, MESSAGE and PUBLISH).
1680
1681 1 Adrian Georgescu
The lifetime of this object is linear and is described by the following diagram:
1682
1683 117 Adrian Georgescu
!{ nolink}sipsimple-request-lifetime.png!
1684 1 Adrian Georgescu
1685
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.
1686 117 Adrian Georgescu
Directly after the object is instantiated, it will be in the @INIT@ state.
1687
The request will be sent over the network once its @send()@ method is called, moving the object into the @IN_PROGRESS@ state.
1688
On each provisional response that is received in reply to this request, the @SIPRequestGotProvisionalResponse@ notification is sent, with data describing the response.
1689 1 Adrian Georgescu
Note that this may not occur at all if not provisional responses are received.
1690 117 Adrian Georgescu
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.
1691 1 Adrian Georgescu
Both of these notifications include data on the response that triggered it.
1692 117 Adrian Georgescu
Note that a SIP response that requests authentication (401 or 407) will be handled internally the first time, if a @Credentials@ object was supplied.
1693
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.
1694
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.
1695
This should usually trigger whomever is using this @Request@ object to construct a new @Request@ for a refreshing operation.
1696
When the @Request@ actually expires, or when the @EXPIRING@ state is skipped directly after sending @SIPRequestDidSucceed@ or @SIPRequestDidFail@, a @SIPRequestDidEnd@ notification will be sent.
1697 17 Ruud Klaver
1698
1699 117 Adrian Georgescu
h4. methods
1700 99 Adrian Georgescu
1701 17 Ruud Klaver
1702 117 Adrian Georgescu
1703
*<notextile>__init__</notextile>*(_self_, *method*, *request_uri*, *from_header*, *to_header*, *route_header*, *credentials*=@None@, *contact_header*=@None@, *call_id*=@None@, *cseq*=@None@, *extra_headers*=@None@, *content_type*=@None@, *body*=@None@)
1704
>Creates a new @Request@ object in the @INIT@ state.
1705
>The arguments to this method are documented in the attributes section.
1706
1707
*send*(_self_, *timeout*=@None@)
1708 1 Adrian Georgescu
   Compose the SIP request and send it to the destination.
1709 117 Adrian Georgescu
   This moves the @Request@ object into the @IN_PROGRESS@ state.
1710
  
1711
>+_timeout_+:
1712 1 Adrian Georgescu
1713 117 Adrian Georgescu
>This can be either an int or a float, indicating in how many seconds the request should timeout with an internally generated 408 response.
1714
>This is is @None@, the internal 408 is only triggered by the internal PJSIP transaction timeout.
1715
>Note that, even if the timeout is specified, the PJSIP timeout is also still valid.
1716 1 Adrian Georgescu
1717 117 Adrian Georgescu
*end*(_self_)
1718
>Terminate the transaction, whichever state it is in, sending the appropriate notifications.
1719
>Note that calling this method while in the @INIT@ state does nothing.
1720 1 Adrian Georgescu
1721
1722 117 Adrian Georgescu
h4. attributes
1723 1 Adrian Georgescu
1724 112 Adrian Georgescu
1725
1726 117 Adrian Georgescu
*expire_warning_time* (class attribute)
1727
>The @SIPRequestWillExpire@ notification will be sent halfway between the positive response and the actual expiration time, but at least this amount of seconds before.
1728
>The default value is 30 seconds.
1729 112 Adrian Georgescu
1730 117 Adrian Georgescu
*state*
1731
>Indicates the state the @Request@ object is in, in the form of a string.
1732
>Refer to the diagram above for possible states.
1733
>This attribute is read-only.
1734 112 Adrian Georgescu
1735 117 Adrian Georgescu
*method*
1736
>The method of the SIP request as a string.
1737
>This attribute is set on instantiation and is read-only.
1738 112 Adrian Georgescu
1739 117 Adrian Georgescu
*from_header*
1740
>The @FrozenFromHeader@ object to put in the @From@ header of the request.
1741
>This attribute is set on instantiation and is read-only.
1742 112 Adrian Georgescu
1743 117 Adrian Georgescu
*to_header*
1744
>The @FrozenToHeader@ object to put in the @To@ header of the request.
1745
>This attribute is set on instantiation and is read-only.
1746 112 Adrian Georgescu
1747 117 Adrian Georgescu
*request_uri*
1748
>The SIP URI to put as request URI in the request, in the form of a @FrozenSIPURI@ object.
1749
>This attribute is set on instantiation and is read-only.
1750 112 Adrian Georgescu
1751 117 Adrian Georgescu
*route_header*
1752
>Where to send the SIP request to, including IP, port and transport, in the form of a @FrozenRouteHeader@ object.
1753
>This will also be included in the @Route@ header of the request.
1754
>This attribute is set on instantiation and is read-only.
1755 112 Adrian Georgescu
1756 117 Adrian Georgescu
*credentials*
1757
>The credentials to be used when challenged for authentication, represented by a @FrozenCredentials@ object.
1758
>If no credentials were supplied when the object was created this attribute is @None@.
1759
>This attribute is set on instantiation and is read-only.
1760 112 Adrian Georgescu
1761 117 Adrian Georgescu
*contact_header*
1762
>The @FrozenContactHeader@ object to put in the @Contact@ header of the request.
1763
>If this was not specified, this attribute is @None@.
1764
>It is set on instantiation and is read-only.
1765 112 Adrian Georgescu
1766 117 Adrian Georgescu
*call_id*
1767
>The @Call-ID@ to be used for this transaction as a string.
1768
>If no call id was specified on instantiation, this attribute contains the generated id.
1769
>This attribute is set on instantiation and is read-only.
1770 112 Adrian Georgescu
1771 117 Adrian Georgescu
*cseq*
1772
>The sequence number to use in the request as an int.
1773
>If no sequence number was specified on instantiation, this attribute contains the generated sequence number.
1774
>Note that this number may be increased by one if an authentication challenge is received and a @Credentials@ object is given.
1775
>This attribute is read-only.
1776 112 Adrian Georgescu
1777 117 Adrian Georgescu
*extra_headers*
1778
>Extra headers to include in the request as a frozenlist of header objects.
1779
>This attribute is set on instantiation and is read-only.
1780 112 Adrian Georgescu
1781 117 Adrian Georgescu
*content_type*
1782
>What string to put as content type in the @Content-Type@ headers, if the request contains a body.
1783
>If no body was specified, this attribute is @None@
1784
>It is set on instantiation and is read-only.
1785 112 Adrian Georgescu
1786 117 Adrian Georgescu
*body*
1787
>The body of the request as a string.
1788
>If no body was specified, this attribute is @None@
1789
>It is set on instantiation and is read-only.
1790 112 Adrian Georgescu
1791 117 Adrian Georgescu
*expires_in*
1792
>This read-only property indicates in how many seconds from now this @Request@ will expire, if it is in the @EXPIRING@ state.
1793
>If this is not the case, this property is 0.
1794 112 Adrian Georgescu
1795 117 Adrian Georgescu
*peer_address*
1796
>This read-only attribute contains the remote endpoint IP and port information. It can be accessed by accessing this object's @ip@ and @port@ attributes.
1797 112 Adrian Georgescu
1798
1799 117 Adrian Georgescu
h4. notifications
1800 112 Adrian Georgescu
1801
1802
1803 117 Adrian Georgescu
*SIPRequestGotProvisionalResponse*
1804
>This notification will be sent on every provisional response received in reply to the sent request.
1805
  
1806
>+_timestamp_+:
1807 112 Adrian Georgescu
1808 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
1809
  
1810
>+_code_+:
1811
1812
>The SIP response code of the received provisional response as an int, which will be in the 1xx range.
1813
  
1814
>+_reason_+:
1815
1816
>The reason text string included with the SIP response code.
1817
  
1818
>+_headers_+:
1819
1820
>The headers included in the provisional response as a dict, the values of which are header objects.
1821
  
1822
>+_body_+:
1823
1824
>The body of the provisional response as a string, or @None@ if there was no body.
1825
1826
*SIPRequestDidSucceed*
1827
>This notification will be sent when a positive final response was received in reply to the request.
1828
  
1829
>+_timestamp_+:
1830
1831
>A @datetime.datetime@ object indicating when the notification was sent.
1832
  
1833
>+_code_+:
1834
1835
>The SIP response code of the received positive final response as an int, which will be in the 2xx range.
1836
  
1837
>+_reason_+:
1838
1839
>The reason text string included with the SIP response code.
1840
  
1841
>+_headers_+:
1842
1843
>The headers included in the positive final response as a dict, the values of which are header objects.
1844
  
1845
>+_body_+:
1846
1847
>The body of the positive final response as a string, or @None@ if there was no body.
1848
  
1849
>+_expires_+:
1850
1851
>Indicates in how many seconds the @Request@ will expire as an int.
1852
>If it does not expire and the @EXPIRING@ state is skipped, this attribute is 0.
1853
1854
*SIPRequestDidFail*
1855
>This notification will be sent when a negative final response is received in reply to the request or if an internal error occurs.
1856
  
1857
>+_timestamp_+:
1858
1859
>A @datetime.datetime@ object indicating when the notification was sent.
1860
  
1861
>+_code_+:
1862
1863
>The SIP response code of the received negative final response as an int.
1864
>This could also be a response code generated by PJSIP internally, or 0 when an internal error occurs.
1865
  
1866
>+_reason_+:
1867
1868
>The reason text string included with the SIP response code or error.
1869
  
1870
>+_headers_+: (only if a negative final response was received)
1871
1872
>The headers included in the negative final response as a dict, the values of which are header objects, if this is what triggered the notification.
1873
  
1874
>+_body_+: (only if a negative final response was received)
1875
1876
>The body of the negative final response as a string, or @None@ if there was no body.
1877
>This attribute is absent if no response was received.
1878
1879
*SIPRequestWillExpire*
1880
>This notification will be sent when a @Request@ in the @EXPIRING@ state will expire soon.
1881
  
1882
>+_timestamp_+:
1883
1884
>A @datetime.datetime@ object indicating when the notification was sent.
1885
  
1886
>+_expires_+:
1887
1888
>An int indicating in how many seconds from now the @Request@ will actually expire.
1889
1890
*SIPRequestDidEnd*
1891
>This notification will be sent when a @Request@ object enters the @TERMINATED@ state and can no longer be used.
1892
  
1893
>+_timestamp_+:
1894
1895
>A @datetime.datetime@ object indicating when the notification was sent.
1896
1897
1898
h3. IncomingRequest
1899
1900
1901 119 Dan Pascu
This is a relatively simple object that can manage responding to incoming requests in a single transaction. For this reason it does not handle requests that create a dialog.
1902
To register methods for which requests should be formed into an @IncomingRequest@ object, the application should either start the @Engine@ with the *incoming_requests*=[list_of_method_names] argument, or use the *add_incoming_request/remove_incoming_request methods* on the @Engine@ after it's started to modify the list of methods for which the @Engine@ will create @IncomingRequest@ instances.
1903
1904
Example:
1905
1906
engine = Engine()
1907
engine.start(incoming_requests=['OPTIONS'])
1908
1909
or after the @Engine@ was started
1910
1911
engine.add_incoming_request('OPTIONS')
1912
1913
Note: Receiving @INVITE@, @SUBSCRIBE@, @ACK@ and @BYE@ through this object is not supported.
1914 113 Adrian Georgescu
1915 117 Adrian Georgescu
The application is notified of an incoming request through the @SIPIncomingRequestGotRequest@ notification.
1916
It can answer this request by calling the @answer@ method on the sender of this notification.
1917
Note that if the @IncomingRequest@ object gets destroyed before it is answered, a 500 response is automatically sent.
1918 113 Adrian Georgescu
1919
1920 117 Adrian Georgescu
h4. attributes
1921 113 Adrian Georgescu
1922
1923
1924 117 Adrian Georgescu
*state*
1925
>This read-only attribute indicates the state the object is in.
1926
>This can be @None@ if the object was created by the application, essentially meaning the object is inert, @"incoming"@ or @"answered"@.
1927 113 Adrian Georgescu
1928
1929 117 Adrian Georgescu
h4. methods
1930 113 Adrian Georgescu
1931
1932
1933 117 Adrian Georgescu
*answer*(_self_, *code*, *reason*=@None@, *extra_headers*=@None@)
1934
>Reply to the received request with a final response.
1935
  
1936
>+_code_+:
1937 113 Adrian Georgescu
1938 117 Adrian Georgescu
>The SIP response code to send.
1939
>This should be 200 or higher.
1940
  
1941
>+_reason_+:
1942 113 Adrian Georgescu
1943 117 Adrian Georgescu
>The reason text to include in the response.
1944
>If this is @None@, the default text for the given response code is used.
1945
  
1946
>+_extra_headers_+:
1947 113 Adrian Georgescu
1948 117 Adrian Georgescu
>The extra headers to include in the response as an iterable of header objects.
1949 113 Adrian Georgescu
1950
1951 117 Adrian Georgescu
h4. notifications
1952 113 Adrian Georgescu
1953
1954
1955 117 Adrian Georgescu
*SIPIncomingRequestGotRequest*
1956
>This notification will be sent when a new @IncomingRequest@ is created as result of a received request.
1957
>The application should listen for this notification, retain a reference to the object that sent it and answer it.
1958
  
1959
>+_timestamp_+:
1960 113 Adrian Georgescu
1961 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
1962
  
1963
>+_method_+:
1964 113 Adrian Georgescu
1965 117 Adrian Georgescu
>The method of the SIP request as a string.
1966
  
1967
>+_request_uri_+:
1968 113 Adrian Georgescu
1969 117 Adrian Georgescu
>The request URI of the request as a @FrozenSIPURI@ object.
1970
  
1971
>+_headers_+:
1972 113 Adrian Georgescu
1973 117 Adrian Georgescu
>The headers of the request as a dict, the values of which are the relevant header objects.
1974
  
1975
>+_body_+:
1976 113 Adrian Georgescu
1977 117 Adrian Georgescu
>The body of the request as a string, or @None@ if no body was included.
1978 113 Adrian Georgescu
1979 117 Adrian Georgescu
*SIPIncomingRequestSentResponse*
1980
>This notification is sent when a response to the request is sent by the object.
1981
  
1982
>+_timestamp_+:
1983 113 Adrian Georgescu
1984 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
1985
  
1986
>+_code_+:
1987 113 Adrian Georgescu
1988 117 Adrian Georgescu
>The code of the SIP response as an int.
1989
  
1990
>+_reason_+:
1991 113 Adrian Georgescu
1992 117 Adrian Georgescu
>The reason text of the SIP response as an int.
1993
  
1994
>+_headers_+:
1995 113 Adrian Georgescu
1996 117 Adrian Georgescu
>The headers of the response as a dict, the values of which are the relevant header objects.
1997
  
1998
>+_body_+:
1999 113 Adrian Georgescu
2000 117 Adrian Georgescu
>This will be @None@.
2001 113 Adrian Georgescu
2002
2003 117 Adrian Georgescu
h3. Message
2004 113 Adrian Georgescu
2005
2006 117 Adrian Georgescu
The @Message@ class is a simple wrapper for the @Request@ class, with the purpose of sending @MESSAGE@ requests, as described in "RFC 3428":http://tools.ietf.org/html/rfc3428.
2007
It is a one-shot object that manages only one @Request@ object.
2008 113 Adrian Georgescu
2009
2010 117 Adrian Georgescu
h4. methods
2011 113 Adrian Georgescu
2012
2013
2014 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_, *from_header*, *to_header*, *route_header*, *content_type*, *body*, *credentials*=@None@, *extra_headers*=@[]@)
2015
>Creates a new @Message@ object with the specified arguments.
2016
>These arguments are documented in the attributes section for this class.
2017 113 Adrian Georgescu
2018 117 Adrian Georgescu
*send*(_self_, *timeout*=@None@)
2019
>Send the @MESSAGE@ request to the remote party.
2020
  
2021
>+_timeout_+:
2022 113 Adrian Georgescu
2023 117 Adrian Georgescu
>This argument as the same meaning as it does for @Request.send()@.
2024 113 Adrian Georgescu
2025 117 Adrian Georgescu
*end*(_self_)
2026
>Stop trying to send the @MESSAGE@ request.
2027
>If it was not sent yet, calling this method does nothing.
2028 113 Adrian Georgescu
2029
2030 117 Adrian Georgescu
h4. attributes
2031 113 Adrian Georgescu
2032
2033
2034 117 Adrian Georgescu
*from_header*
2035
>The @FrozenFromHeader@ to put in the @From@ header of the @MESSAGE@ request.
2036
>This attribute is set on instantiation and is read-only.
2037 113 Adrian Georgescu
2038 117 Adrian Georgescu
*to_header*
2039
>The @FrozenToHeader@ to put in the @To@ header of the @MESSAGE@ request.
2040
>This attribute is set on instantiation and is read-only.
2041 113 Adrian Georgescu
2042 117 Adrian Georgescu
*route_header*
2043
>Where to send the @MESSAGE@ request to, including IP, port and transport, in the form of a @FrozenRouteHeader@ object.
2044
>This will also be included in the @Route@ header of the request.
2045
>This attribute is set on instantiation and is read-only.
2046 113 Adrian Georgescu
2047 117 Adrian Georgescu
*content_type*
2048
>What string to put as content type in the @Content-Type@ headers.
2049
>It is set on instantiation and is read-only.
2050 113 Adrian Georgescu
2051 117 Adrian Georgescu
*body*
2052
>The body of the @MESSAGE@ request as a string.
2053
>If no body was specified, this attribute is @None@
2054
>It is set on instantiation and is read-only.
2055 113 Adrian Georgescu
2056 117 Adrian Georgescu
*credentials*
2057
>The credentials to be used when challenged for authentication, represented by a @FrozenCredentials@ object.
2058
>If no credentials were specified, this attribute is @None@.
2059
>This attribute is set on instantiation and is read-only.
2060 103 Adrian Georgescu
2061 117 Adrian Georgescu
*is_sent*
2062
>A boolean read-only property indicating if the @MESSAGE@ request was sent.
2063 103 Adrian Georgescu
2064 117 Adrian Georgescu
*in_progress*
2065
>A boolean read-only property indicating if the object is waiting for the response from the remote party.
2066 103 Adrian Georgescu
2067 117 Adrian Georgescu
*peer_address*
2068
>This read-only attribute contains the remote endpoint IP and port information. It can be accessed by accessing this object's @ip@ and @port@ attributes.
2069 103 Adrian Georgescu
2070
2071 117 Adrian Georgescu
h4. notifications
2072 103 Adrian Georgescu
2073
2074 117 Adrian Georgescu
2075
*SIPMessageDidSucceed*
2076
>This notification will be sent when the remote party acknowledged the reception of the @MESSAGE@ request.
2077
>It has not data attributes.
2078
2079
*SIPMessageDidFail*
2080
>This notification will be sent when transmission of the @MESSAGE@ request fails for whatever reason.
2081
  
2082
>+_code_+:
2083
2084
>An int indicating the SIP or internal PJSIP code that was given in response to the @MESSAGE@ request.
2085
>This is 0 if the failure is caused by an internal error.
2086
  
2087
>+_reason_+:
2088
2089
>A status string describing the failure, either taken from the SIP response or the internal error.
2090
2091
2092
h3. Registration
2093
2094
2095
The @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.
2096
For details, see "RFC 3261":http://tools.ietf.org/html/rfc3261.
2097
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.
2098
The application should then perform a DNS lookup to find the relevant SIP registrar and call the @register()@ method on this object.
2099
2100
2101
h4. methods
2102
2103
2104
2105
*<notextile>__init__</notextile>*(_self_, *from_header*, *credentials*=@None@, *duration*=300)
2106
>Creates a new @Registration@ object with the specified arguments.
2107
>These arguments are documented in the attributes section for this class.
2108
2109
*register*(_self_, *contact_header*, *route_header*, *timeout*=@None@)
2110
>Calling this method will attempt to send a new @REGISTER@ request to the registrar provided, whatever state the object is in.
2111
>If the object is currently busy sending a @REGISTER@, this request will be preempted for the new one.
2112
>Once sent, the @Registration@ object will send either a @SIPRegistrationDidSucceed@ or a @SIPRegistrationDidFail@ notification.
2113
>The @contact_header@ argument is mentioned in the attributes section of this class.
2114
>The @route_header@ argument specifies the IP address, port and transport of the SIP registrar in the form of a @RouteHeader@ object and @timeout@ has the same meaning as it does for @Request.send()@.
2115
2116
*end*(_self_, *timeout*=@None@)
2117
>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.
2118
>The @RouteHeader@ used for this will be the same as the last successfully sent @REGISTER@ request.
2119
>If another @REGISTER@ is currently being sent, it will be preempted.
2120
>When the unregistering @REGISTER@ request is sent, a @SIPRegistrationWillEnd@ notification is sent.
2121
>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.
2122
>Calling this method when the object is not registered will do nothing.
2123
>The @timeout@ argument has the same meaning as for the @register()@ method.
2124
2125
2126
h4. attributes
2127
2128
2129
2130
*from_header_
2131
>The @(Frozen)FromHeader@ the @Registration@ was sent with.
2132
2133
*credentials*
2134
>The credentials to be used when challenged for authentication by the registrar, represented by a @(Frozen)Credentials@ object. 
2135
>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.
2136
>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.
2137
2138
*duration*
2139
>The amount of time in seconds to request the registration for at the registrar.
2140
>This attribute is set at object instantiation and can be updated for subsequent @REGISTER@ requests.
2141
2142
*is_registered*
2143
>A boolean read-only property indicating if this object is currently registered.
2144
2145
*contact_header*
2146
>If the @Registration@ object is registered, this attribute contains the latest contact header that was sent to the registrar as a @FrozenContactHeader@ object.
2147
>Otherwise, this attribute is @None@
2148
2149
*expires_in*
2150
>If registered, this read-only property indicates in how many seconds from now this @Registration@ will expire.
2151
>If this is not the case, this property is 0.
2152
2153
*peer_address*
2154
>This read-only attribute contains the remote endpoint IP and port information. It can be accessed by accessing this object's @ip@ and @port@ attributes.
2155
2156
2157
h4. notifications
2158
2159
2160
2161
*SIPRegistrationDidSucceed*
2162
>This notification will be sent when the @register()@ method was called and the registration succeeded.
2163
  
2164
>+_code_+:
2165
2166
>The SIP response code as received from the registrar as an int.
2167
  
2168
>+_reason_+:
2169
2170
>The reason string received from the SIP registrar.
2171
  
2172
>+_route_header_+:
2173
2174
>The @(Frozen)RouteHeader@ object passed as an argument to the @register()@ method.
2175
  
2176
>+_contact_header_+:
2177
2178
>The contact header that was sent to the registrar as a @FrozenContactHeader@ object.
2179
  
2180
>+_contact_header_list_+:
2181
2182
>A full list of contact headers that are registered for this SIP account, including the one used for this registration.
2183
>The format of this data attribute is a list of FrozenContactHeader objects.
2184
  
2185
>+_expires_in_+:
2186
2187
>The number of seconds before this registration expires
2188
2189
*SIPRegistrationDidFail*
2190
>This notification will be sent when the @register()@ method was called and the registration failed, for whatever reason.
2191
  
2192
>+_code_+:
2193
2194
>The SIP response code as received from the registrar as an int.
2195
>This can also be a PJSIP generated response code, or 0 if the failure was because of an internal error.
2196
  
2197
>+_reason_+:
2198
2199
>The reason string received from the SIP registrar or the error string.
2200
  
2201
>+_route_header_+:
2202
2203
>The @(Frozen)RouteHeader@ object passed as an argument to the @register()@ method.
2204
2205
*SIPRegistrationWillExpire*
2206
>This notification will be sent when a registration will expire soon.
2207
>It should be used as an indication to re-perform DNS lookup of the registrar and call the @register()@ method.
2208
  
2209
>+_expires_+:
2210
2211
>The number of seconds in which the registration will expire.
2212
2213
*SIPRegistrationWillEnd*
2214
>Will be sent whenever the @end()@ method was called and an unregistering @REGISTER@ is sent.
2215
2216
*SIPRegistrationDidNotEnd*
2217
>This notification will be sent when the unregistering @REGISTER@ request failed for some reason.
2218
  
2219
>+_code_+:
2220
2221
>The SIP response code as received from the registrar as an int.
2222
>This can also be a PJSIP generated response code, or 0 if the failure was because of an internal error.
2223
  
2224
>+_reason_+:
2225
2226
>The reason string received from the SIP registrar or the error string.
2227
2228
*SIPRegistrationDidEnd*
2229
>This notification will be sent when a @Registration@ has become unregistered.
2230
  
2231
>+_expired_+:
2232
2233
>This boolean indicates if the object is unregistered because the registration expired, in which case it will be set to @True@.
2234
>If this data attribute is @False@, it means that unregistration was explicitly requested through the @end()@ method.
2235
2236
2237
h4. example code
2238
2239
2240 99 Adrian Georgescu
For an example on how to use this object, see the Integration section.
2241 103 Adrian Georgescu
2242
2243 117 Adrian Georgescu
h3. Publication
2244 103 Adrian Georgescu
2245
2246 117 Adrian Georgescu
Publication of SIP events is an Internet standard published at "RFC 3903":http://tools.ietf.org/html/rfc3903. 
2247
@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.
2248 103 Adrian Georgescu
2249 117 Adrian Georgescu
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.
2250
This object is similar in behaviour to the @Registration@ object, as it is also based on a sequence of @Request@ objects.
2251
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.
2252 103 Adrian Georgescu
2253
2254 117 Adrian Georgescu
h4. methods
2255 103 Adrian Georgescu
2256
2257
2258 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_, *from_header*, *event*, *content_type*, *credentials*=@None@, *duration*=300)
2259
>Creates a new @Publication@ object with the specified arguments.
2260
>These arguments are documented in the attributes section for this class.
2261 103 Adrian Georgescu
2262 117 Adrian Georgescu
*publish*(_self_, *body*, *route_header*, *timeout*=@None@)
2263
>Send an actual @PUBLISH@ request to the specified presence agent.
2264
  
2265
>+_body_+:
2266 103 Adrian Georgescu
2267 117 Adrian Georgescu
>The body to place in the @PUBLISH@ request as a string.
2268
>This body needs to be of the content type specified at object creation.
2269
>For the initial request, a body will need to be specified.
2270
>For subsequent refreshing @PUBLISH@ requests, the body can be @None@ to indicate that the last published body should be refreshed.
2271
>If there was an ETag error with the previous refreshing @PUBLISH@, calling this method with a body of @None@ will throw a @PublicationError@.
2272
  
2273
>+_route_header_+:
2274 103 Adrian Georgescu
2275 117 Adrian Georgescu
>The host where the request should be sent to in the form of a @(Frozen)RouteHeader@ object.
2276
  
2277
>+_timeout_+:
2278 103 Adrian Georgescu
2279 117 Adrian Georgescu
>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.
2280
>This is is @None@, the internal 408 is only triggered by the internal PJSIP transaction timeout.
2281
>Note that, even if the timeout is specified, the PJSIP timeout is also still valid.
2282 103 Adrian Georgescu
2283 117 Adrian Georgescu
*end*(_self_, *timeout*=@None@)
2284
>End the publication by sending a @PUBLISH@ request with an @Expires@ header of 0.
2285
>If the object is not published, this will result in a @PublicationError@ being thrown.
2286
  
2287
>+_timeout_+:
2288 103 Adrian Georgescu
2289 117 Adrian Georgescu
>The meaning of this argument is the same as it is for the @publish()@ method.
2290 103 Adrian Georgescu
2291
2292 117 Adrian Georgescu
h4. attributes
2293 103 Adrian Georgescu
2294
2295
2296 117 Adrian Georgescu
*from_header_
2297
>The @(Frozen)FromHeader@ the @Publication@ was sent with.
2298 103 Adrian Georgescu
2299 117 Adrian Georgescu
*event_
2300
>The name of the event this object is publishing for the specified SIP URI, as a string.
2301 103 Adrian Georgescu
2302 117 Adrian Georgescu
*content_type_
2303
>The @Content-Type@ of the body that will be in the @PUBLISH@ requests.
2304
>Typically this will remain the same throughout the publication session, but the attribute may be updated by the application if needed.
2305
>Note that this attribute needs to be in the typical MIME type form, containing a "/" character.
2306 103 Adrian Georgescu
2307 117 Adrian Georgescu
*credentials*
2308
>The credentials to be used when challenged for authentication by the presence agent, represented by a @(Frozen)Credentials@ object. 
2309
>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.
2310
>Note that, in contrast to most other classes mentioned in this document, the @Publication@ class does not make a copy of the @(Frozen)Credentials@ object on instantiation, but instead retains a reference to it.
2311 103 Adrian Georgescu
2312 117 Adrian Georgescu
*duration*
2313
>The amount of time in seconds that the publication should be valid for.
2314
>This attribute is set at object instantiation and can be updated for subsequent @PUBLISH@ requests.
2315 103 Adrian Georgescu
2316 117 Adrian Georgescu
*is_published*
2317
>A boolean read-only property indicating if this object is currently published.
2318 103 Adrian Georgescu
2319 117 Adrian Georgescu
*expires_in*
2320
>If published, this read-only property indicates in how many seconds from now this @Publication@ will expire.
2321
>If this is not the case, this property is 0.
2322 103 Adrian Georgescu
2323 117 Adrian Georgescu
*peer_address*
2324
>This read-only attribute contains the remote endpoint IP and port information. It can be accessed by accessing this object's @ip@ and @port@ attributes.
2325 103 Adrian Georgescu
2326 117 Adrian Georgescu
2327
h4. notifications
2328
2329
2330
2331
*SIPPublicationDidSucceed*
2332
>This notification will be sent when the @publish()@ method was called and the publication succeeded.
2333
  
2334
>+_code_+:
2335
2336
>The SIP response code as received from the SIP presence agent as an int.
2337
  
2338
>+_reason_+:
2339
2340
>The reason string received from the SIP presence agent.
2341
  
2342
>+_route_header_+:
2343
2344
>The @(Frozen)RouteHeader@ object passed as an argument to the @publish()@ method.
2345
  
2346
>+_expires_in_+:
2347
2348
>The number of seconds before this publication expires
2349
2350
*SIPPublicationDidFail*
2351
>This notification will be sent when the @publish()@ method was called and the publication failed, for whatever reason.
2352
  
2353
>+_code_+:
2354
2355
>The SIP response code as received from the presence agent as an int.
2356
>This can also be a PJSIP generated response code, or 0 if the failure was because of an internal error.
2357
  
2358
>+_reason_+:
2359
2360
>The reason string received from the presence agent or the error string.
2361
  
2362
>+_route_header_+:
2363
2364
>The @(Frozen)RouteHeader@ object passed as an argument to the @publish()@ method.
2365
2366
*SIPPublicationWillExpire*
2367
>This notification will be sent when a publication will expire soon.
2368
>It should be used as an indication to re-perform DNS lookup of the presence agent and call the @publish()@ method.
2369
  
2370
>+_expires_+:
2371
2372
>The number of seconds in which the publication will expire.
2373
2374
*SIPPublicationWillEnd*
2375
>Will be sent whenever the @end()@ method was called and an unpublishing @PUBLISH@ is sent.
2376
2377
*SIPPublicationDidNotEnd*
2378
>This notification will be sent when the unpublishing @PUBLISH@ request failed for some reason.
2379
  
2380
>+_code_+:
2381
2382
>The SIP response code as received from the presence agent as an int.
2383
>This can also be a PJSIP generated response code, or 0 if the failure was because of an internal error.
2384
  
2385
>+_reason_+:
2386
2387
>The reason string received from the presence agent or the error string.
2388
2389
*SIPPublicationDidEnd*
2390
>This notification will be sent when a @Publication@ has become unpublished.
2391
  
2392
>+_expired_+:
2393
2394
>This boolean indicates if the object is unpublished because the publication expired, in which case it will be set to @True@.
2395
>If this data attribute is @False@, it means that unpublication was explicitly requested through the @end()@ method.
2396
2397
2398
h3. Subscription
2399
2400
2401
Subscription and notifications for SIP events is an Internet standard published at "RFC 3856":http://tools.ietf.org/html/rfc3856.
2402
2403 1 Adrian Georgescu
This SIP primitive class represents a subscription to a specific event type of a particular SIP URI.
2404
This means that the application should instance this class for each combination of event and SIP URI that it wishes to subscribe to.
2405 117 Adrian Georgescu
The event type and the content types that are acceptable for it need to be registered first, either through the @init_options@ attribute of @Engine@ (before starting it), or by calling the @add_event()@ method of the @Engine@ instance.
2406
Whenever a @NOTIFY@ is received, the application will receive the @SIPSubscriptionGotNotify@ event.
2407 1 Adrian Georgescu
2408 117 Adrian Georgescu
Internally a @Subscription@ object has a state machine, which reflects the state of the subscription.
2409
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@.
2410
The last three states are directly copied from the contents of the @Subscription-State@ header of the received @NOTIFY@ request.
2411
Also, the state can be an arbitrary string if the contents of the @Subscription-State@ header are not one of the three above.
2412
The state of the object is presented in the @state@ attribute and changes of the state are indicated by means of the @SIPSubscriptionChangedState@ notification.
2413 1 Adrian Georgescu
This notification is only informational, an application using this object should take actions based on the other notifications sent by this object.
2414
2415
2416 117 Adrian Georgescu
h4. methods
2417 1 Adrian Georgescu
2418
2419
2420 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_, *request_uri*, *from_header*, *to_header*, *contact_header, *event*, *route_header*, *credentials*=@None@, *refresh*=300)
2421
>Creates a new @Subscription@ object which will be in the @NULL@ state.
2422
>The arguments for this method are documented in the attributes section above.
2423 1 Adrian Georgescu
2424 117 Adrian Georgescu
*subscribe*(_self_, *extra_headers*=@None@, *content_type*=@None@, *body*=@None@, *timeout*=@None@)
2425
>Calling this method triggers sending a @SUBSCRIBE@ request to the presence agent.
2426
>The arguments passed will be stored and used for subsequent refreshing @SUBSCRIBE@ requests.
2427
>This method may be used both to send the initial request and to update the arguments while the subscription is ongoing.
2428
>It may not be called when the object is in the @TERMINATED@ state.
2429
  
2430
>+_extra_headers_+:
2431 1 Adrian Georgescu
2432 117 Adrian Georgescu
>A dictionary of additional headers to include in the @SUBSCRIBE@ requests.
2433
  
2434
>+_content_type_+:
2435 1 Adrian Georgescu
2436 117 Adrian Georgescu
>The @Content-Type@ of the supplied @body@ argument as a string.
2437
>If this argument is supplied, the @body@ argument cannot be @None@.
2438
  
2439
>+_body_+:
2440 1 Adrian Georgescu
2441 117 Adrian Georgescu
>The optional body to include in the @SUBSCRIBE@ request as a string.
2442
>If this argument is supplied, the @content_type@ argument cannot be @None@.
2443
  
2444
>+_timeout_+:
2445 1 Adrian Georgescu
2446 117 Adrian Georgescu
>This can be either an int or a float, indicating in how many seconds the request should timeout with an internally generated 408 response.
2447
>If this is @None@, the internal 408 is only triggered by the internal PJSIP transaction timeout.
2448
>Note that, even if the timeout is specified, the PJSIP timeout is also still valid.
2449 1 Adrian Georgescu
2450 117 Adrian Georgescu
*end*(_self_, *timeout*=@None@)
2451
>This will end the subscription by sending a @SUBSCRIBE@ request with an @Expires@ value of 0.
2452
>If this object is no longer subscribed, this method will return without performing any action.
2453
>This method cannot be called when the object is in the @NULL@ state.
2454
>The @timeout@ argument has the same meaning as it does for the @subscribe()@ method.
2455 1 Adrian Georgescu
2456
2457 117 Adrian Georgescu
h4. attributes
2458 1 Adrian Georgescu
2459
2460
2461 117 Adrian Georgescu
*state*
2462
>Indicates which state the internal state machine is in.
2463
>See the previous section for a list of states the state machine can be in.
2464 1 Adrian Georgescu
2465 117 Adrian Georgescu
*from_header*
2466
>The @FrozenFromHeader@ to be put in the @From@ header of the @SUBSCRIBE@ requests.
2467
>This attribute is set on object instantiation and is read-only.
2468 1 Adrian Georgescu
2469 117 Adrian Georgescu
*to_header*
2470
>The @FrozenToHeader@ that is the target for the subscription.
2471
>This attribute is set on object instantiation and is read-only.
2472 1 Adrian Georgescu
2473 117 Adrian Georgescu
*contact_header*
2474
>The @FrozenContactHeader@ to be put in the @Contact@ header of the @SUBSCRIBE@ requests.
2475
>This attribute is set on object instantiation and is read-only.
2476 1 Adrian Georgescu
2477 117 Adrian Georgescu
*event*
2478
>The event package for which the subscription is as a string.
2479
>This attribute is set on object instantiation and is read-only.
2480 1 Adrian Georgescu
2481 117 Adrian Georgescu
*route_header*
2482
>The outbound proxy to use in the form of a @FrozenRouteHeader@ object.
2483
>This attribute is set on object instantiation and is read-only.
2484 1 Adrian Georgescu
2485 117 Adrian Georgescu
*credentials*
2486
>The SIP credentials needed to authenticate at the SIP proxy in the form of a @FrozenCredentials@ object.
2487
>If none was specified when creating the @Subscription@ object, this attribute is @None@.
2488
>This attribute is set on object instantiation and is read-only.
2489 1 Adrian Georgescu
2490 117 Adrian Georgescu
*refresh*
2491
>The refresh interval in seconds that was requested on object instantiation as an int.
2492
>This attribute is set on object instantiation and is read-only.
2493 1 Adrian Georgescu
2494 117 Adrian Georgescu
*extra_headers*
2495
>This contains the @frozenlist@ of extra headers that was last passed to a successful call to the @subscribe()@ method.
2496
>If the argument was not provided, this attribute is an empty list.
2497
>This attribute is read-only.
2498 1 Adrian Georgescu
2499 117 Adrian Georgescu
*content_type*
2500
>This attribute contains the @Content-Type@ of the body that was last passed to a successful call to the @subscribe()@ method.
2501
>If the argument was not provided, this attribute is @None@.
2502 1 Adrian Georgescu
2503 117 Adrian Georgescu
*body*
2504
>This attribute contains the @body@ string argument that was last passed to a successful call to the @subscribe()@ method.
2505
>If the argument was not provided, this attribute is @None@.
2506 1 Adrian Georgescu
2507 117 Adrian Georgescu
*peer_address*
2508
>This read-only attribute contains the remote endpoint IP and port information. It can be accessed by accessing this object's @ip@ and @port@ attributes.
2509 1 Adrian Georgescu
2510
2511 117 Adrian Georgescu
h4. notifications
2512 1 Adrian Georgescu
2513
2514
2515 117 Adrian Georgescu
*SIPSubscriptionChangedState*
2516
>This notification will be sent every time the internal state machine of a @Subscription@ object changes state.
2517
  
2518
>+_timestamp_+:
2519 1 Adrian Georgescu
2520 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2521
  
2522
>+_prev_state_+:
2523 1 Adrian Georgescu
2524 117 Adrian Georgescu
>The previous state that the sate machine was in.
2525
  
2526
>+_state_+:
2527 1 Adrian Georgescu
2528 117 Adrian Georgescu
>The new state the state machine moved into.
2529 1 Adrian Georgescu
2530 117 Adrian Georgescu
*SIPSubscriptionWillStart*
2531
>This notification will be emitted when the initial @SUBSCRIBE@ request is sent.
2532
  
2533
>+_timestamp_+:
2534 1 Adrian Georgescu
2535 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2536 1 Adrian Georgescu
2537 117 Adrian Georgescu
*SIPSubscriptionDidStart*
2538
>This notification will be sent when the initial @SUBSCRIBE@ was accepted by the presence agent.
2539
  
2540
>+_timestamp_+:
2541 1 Adrian Georgescu
2542 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2543 1 Adrian Georgescu
2544 117 Adrian Georgescu
*SIPSubscriptionGotNotify*
2545
>This notification will be sent when a @NOTIFY@ is received that corresponds to a particular @Subscription@ object.
2546
>Note that this notification could be sent when a @NOTIFY@ without a body is received.
2547
  
2548
>+_request_uri_+:
2549 1 Adrian Georgescu
2550 117 Adrian Georgescu
>The request URI of the @NOTIFY@ request as a @SIPURI@ object.
2551
  
2552
>+_from_header_+:
2553 1 Adrian Georgescu
2554 117 Adrian Georgescu
>The From header of the @NOTIFY@ request as a @FrozenFromHeader@ object.
2555
  
2556
>+_to_header_+:
2557 1 Adrian Georgescu
2558 117 Adrian Georgescu
>The To header of the @NOTIFY@ request as a @FrozenToHeader@ object.
2559
  
2560
>+_content_type_+:
2561 1 Adrian Georgescu
2562 117 Adrian Georgescu
>The Content-Type header value of the @NOTIFY@ request as a @ContentType@ object.
2563
  
2564
>+_event_+:
2565 1 Adrian Georgescu
2566 117 Adrian Georgescu
>The Event header value of the @NOTIFY@ request as a string object.
2567
  
2568
>+_headers_+:
2569 1 Adrian Georgescu
2570 117 Adrian Georgescu
>The headers of the @NOTIFY@ request as a dict.
2571
>Each SIP header is represented in its parsed for as long as PJSIP supports it.
2572
>The format of the parsed value depends on the header.
2573
  
2574
>+_body_+:
2575 1 Adrian Georgescu
2576 117 Adrian Georgescu
>The body of the @NOTIFY@ request as a string, or @None@ if no body was included.
2577
  
2578
>+_timestamp_+:
2579 1 Adrian Georgescu
2580 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.  
2581 1 Adrian Georgescu
2582 117 Adrian Georgescu
*SIPSubscriptionDidFail*
2583
>This notification will be sent whenever there is a failure, such as a rejected initial or refreshing @SUBSCRIBE@.
2584
>After this notification the @Subscription@ object is in the @TERMINATED@ state and can no longer be used.
2585
  
2586
>+_timestamp_+:
2587 1 Adrian Georgescu
2588 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2589
  
2590
>+_code_+:
2591 1 Adrian Georgescu
2592 117 Adrian Georgescu
>An integer SIP code from the fatal response that was received from the remote party of generated by PJSIP.
2593
>If the error is internal to the SIP core, this attribute will have a value of 0.
2594
  
2595
>+_reason_+:
2596 1 Adrian Georgescu
2597 117 Adrian Georgescu
>An text string describing the failure that occurred.
2598
  
2599
>+_min_expires_+:
2600 1 Adrian Georgescu
2601 117 Adrian Georgescu
>An integer containing the value from the Min-Expires header. Will be None if the response doesn't contain the header.
2602 1 Adrian Georgescu
2603 117 Adrian Georgescu
*SIPSubscriptionDidEnd*
2604
>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.
2605
>After this notification the @Subscription@ object is in the @TERMINATED@ state and can no longer be used.
2606
  
2607
>+_timestamp_+:
2608 1 Adrian Georgescu
2609 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2610 1 Adrian Georgescu
2611
2612 117 Adrian Georgescu
h3. IncomingSubscription
2613 1 Adrian Georgescu
2614
2615 117 Adrian Georgescu
Subscription and notifications for SIP events is an Internet standard published at "RFC 3856":http://tools.ietf.org/html/rfc3856.
2616 1 Adrian Georgescu
2617 117 Adrian Georgescu
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.
2618
This means that it can accept a @SUBSCRIBE@ request and subsequent refreshing @SUBSCRIBE@s and sent @NOTIFY@ requests containing event state.
2619
2620
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.
2621
This event needs to be known by the @Engine@, i.e. it should already be present in the @events@ dictionary attribute.
2622
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.
2623
This will be indicated to the application through a @SIPIncomingSubscriptionGotSubscribe@ notification.
2624
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.
2625
2626
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.
2627
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.
2628
Whenever a refreshing @SUBSCRIBE@ is received, the latest contents to be set are sent in the resulting @NOTIFY@ request.
2629
The subscription can be ended by using the @end()@ method.
2630
2631
2632
h4. methods
2633
2634
2635
2636
*<notextile>__init__</notextile>*(_self_)
2637
>An application should never create an @IncomingSubscription@ object itself.
2638
>Doing this will create a useless object in the @None@ state.
2639
2640
*reject*(_self_, *code*)
2641
>Will reply to the initial @SUBSCRIBE@ with a negative response.
2642
>This method can only be called in the @"incoming"@ state and sets the subscription to the @"terminated"@ state.
2643
  
2644
>+_code_+:
2645
2646
>The SIP response code to use.
2647
>This should be a negative response, i.e. in the 3xx, 4xx, 5xx or 6xx range.
2648
2649
*accept_pending*(_self_)
2650
>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.
2651
>The application can later decide to fully accept the subscription or terminate it.
2652
>This method can only be called in the @"incoming"@ state.
2653
2654
*accept*(_self_, *content_type*=@None@, *content*=@None@)
2655
>Accept the initial incoming @SUBSCRIBE@ and respond to it with a 200 OK, or fully accept an @IncomingSubscription@ that is in the @"pending"@ state.
2656
>In either case, a @NOTIFY@ will be sent to update the state to "active", optionally with the content specified in the arguments.
2657
>This method can only be called in the @"incoming"@ or @"pending"@ state.
2658
  
2659
>+_content_type_+:
2660
2661
>The Content-Type of the content to be set supplied as a string containing a @"/"@ character.
2662
>Note that if this argument is set, the @content@ argument should also be set.
2663
  
2664
>+_content_+:
2665
2666
>The body of the @NOTIFY@ to send when accepting the subscription, as a string.
2667
>Note that if this argument is set, the @content_type@ argument should also be set.
2668
2669
*push_content*(_self_, *content_type*, *content*)
2670
>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.
2671
>This method can only be called in the @"active"@ state.
2672
  
2673
>+_content_type_+:
2674
2675
>The Content-Type of the content to be set supplied as a string containing a @"/"@ character.
2676
  
2677
>+_content_+:
2678
2679
>The body of the @NOTIFY@ as a string.
2680
2681
2682
h4. attributes
2683
2684
2685
2686
*state*
2687
>Indicates which state the incoming subscription session is in.
2688
>This can be one of @None@, @"incoming"@, @"pending"@, @"active"@ or @"terminated"@.
2689
>This attribute is read-only.
2690
2691
*event*
2692
>The name of the event package that this @IncomingSubscription@ relates to.
2693
>This attribute is a read-only string.
2694
2695
*content_type*
2696
>The @Content-Type@ of the last set content in this subscription session.
2697
>Inititally this will be @None@.
2698
>This attribute is a read-only string.
2699
2700
*content*
2701
>The last set content in this subscription session as a read-only string.
2702
2703
*peer_address*
2704
>This read-only attribute contains the remote endpoint IP and port information. It can be accessed by accessing this object's @ip@ and @port@ attributes.
2705
2706
2707
h4. notifications
2708
2709
2710
2711
*SIPIncomingSubscriptionChangedState*
2712
>This notification will be sent every time the an @IncomingSubscription@ object changes state.
2713
>This notification is mostly indicative, an application should not let its logic depend on it.
2714
  
2715
>+_timestamp_+:
2716
2717
>A @datetime.datetime@ object indicating when the notification was sent.
2718
  
2719
>+_prev_state_+:
2720
2721
>The previous state that the subscription was in.
2722
  
2723
>+_state_+:
2724
2725
>The new state the subscription has.
2726
2727
*SIPIncomingSubscriptionGotSubscribe*
2728
>This notification will be sent when a new @IncomingSubscription@ is created as result of an incoming @SUBSCRIBE@ request.
2729
>The application should listen for this notification, retain a reference to the object that sent it and either accept or reject it.
2730
  
2731
>+_timestamp_+:
2732
2733
>A @datetime.datetime@ object indicating when the notification was sent.
2734
  
2735
>+_method_+:
2736
2737
>The method of the SIP request as a string, which will be @SUBSCRIBE@.
2738
  
2739
>+_request_uri_+:
2740
2741
>The request URI of the @SUBSCRIBE@ request as a @FrozenSIPURI@ object.
2742
  
2743
>+_headers_+:
2744
2745
>The headers of the @SUBSCRIBE@ request as a dict, the values of which are the relevant header objects.
2746
  
2747
>+_body_+:
2748
2749
>The body of the @SUBSCRIBE@ request as a string, or @None@ if no body was included.
2750
2751
*SIPIncomingSubscriptionGotRefreshingSubscribe*
2752
>This notification indicates that a refreshing @SUBSCRIBE@ request was received from the subscriber.
2753
>It is purely informative, no action needs to be taken by the application as a result of it.
2754
  
2755
>+_timestamp_+:
2756
2757
>A @datetime.datetime@ object indicating when the notification was sent.
2758
  
2759
>+_method_+:
2760
2761
>The method of the SIP request as a string, which will be @SUBSCRIBE@.
2762
  
2763
>+_request_uri_+:
2764
2765
>The request URI of the @SUBSCRIBE@ request as a @FrozenSIPURI@ object.
2766
  
2767
>+_headers_+:
2768
2769
>The headers of the @SUBSCRIBE@ request as a dict, the values of which are the relevant header objects.
2770
  
2771
>+_body_+:
2772
2773
>The body of the @SUBSCRIBE@ request as a string, or @None@ if no body was included.
2774
2775
*SIPIncomingSubscriptionGotUnsubscribe*
2776
>This notification indicates that a @SUBSCRIBE@ request with an @Expires@ header of 0 was received from the subscriber, effectively requesting to unsubscribe.
2777
>It is purely informative, no action needs to be taken by the application as a result of it.
2778
  
2779
>+_timestamp_+:
2780
2781
>A @datetime.datetime@ object indicating when the notification was sent.
2782
  
2783
>+_method_+:
2784
2785
>The method of the SIP request as a string, which will be @SUBSCRIBE@.
2786
  
2787
>+_request_uri_+:
2788
2789
>The request URI of the @SUBSCRIBE@ request as a @FrozenSIPURI@ object.
2790
  
2791
>+_headers_+:
2792
2793
>The headers of the @SUBSCRIBE@ request as a dict, the values of which are the relevant header objects.
2794
  
2795
>+_body_+:
2796
2797
>The body of the @SUBSCRIBE@ request or response as a string, or @None@ if no body was included.
2798
2799
*SIPIncomingSubscriptionAnsweredSubscribe*
2800
>This notification is sent whenever a response to a @SUBSCRIBE@ request is sent by the object, including an unsubscribing @SUBSCRIBE@.
2801
>It is purely informative, no action needs to be taken by the application as a result of it.
2802
  
2803
>+_timestamp_+:
2804
2805
>A @datetime.datetime@ object indicating when the notification was sent.
2806
  
2807
>+_code_+:
2808
2809
>The code of the SIP response as an int.
2810
  
2811
>+_reason_+:
2812
2813
>The reason text of the SIP response as an int.
2814
  
2815
>+_headers_+:
2816
2817
>The headers of the response as a dict, the values of which are the relevant header objects.
2818
  
2819
>+_body_+:
2820
2821
>This will be @None@.
2822
2823
*SIPIncomingSubscriptionSentNotify*
2824
>This notification indicates that a @NOTIFY@ request was sent to the subscriber.
2825
>It is purely informative, no action needs to be taken by the application as a result of it.
2826
  
2827
>+_timestamp_+:
2828
2829
>A @datetime.datetime@ object indicating when the notification was sent.
2830
  
2831
>+_method_+:
2832
2833
>The method of the SIP request as a string, which will be @NOTIFY@.
2834
  
2835
>+_request_uri_+:
2836
2837
>The request URI of the @NOTIFY@ request as a @FrozenSIPURI@ object.
2838
  
2839
>+_headers_+:
2840
2841
>The headers of the @NOTIFY@ request as a dict, the values of which are the relevant header objects.
2842
  
2843
>+_body_+:
2844
2845
>The body of the @NOTIFY@ request or response as a string, or @None@ if no body was included.
2846
2847
*SIPIncomingSubscriptionNotifyDidSucceed*
2848
>This indicates that a positive final response was received from the subscriber in reply to a sent @NOTIFY@ request.
2849
>The notification is purely informative, no action needs to be taken by the application as a result of it.
2850
  
2851
>+_timestamp_+:
2852
2853
>A @datetime.datetime@ object indicating when the notification was sent.
2854
  
2855
>+_code_+:
2856
2857
>The code of the SIP response as an int.
2858
  
2859
>+_reason_+:
2860
2861
>The reason text of the SIP response as a string.
2862
  
2863
>+_headers_+:
2864
2865
>The headers of the response as a dict, the values of which are the relevant header objects.
2866
  
2867
>+_body_+:
2868
2869
>This will be @None@.
2870
2871
*SIPIncomingSubscriptionNotifyDidFail*
2872
>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.
2873
  
2874
>+_timestamp_+:
2875
2876
>A @datetime.datetime@ object indicating when the notification was sent.
2877
  
2878
>+_code_+:
2879
2880
>The code of the SIP response as an int.
2881
>If this is 0, the notification was sent as a result of an internal error.
2882
  
2883
>+_reason_+:
2884
2885
>The reason text of the SIP response as a string or the internal error if the code attribute is 0.
2886
  
2887
>+_headers_+: (if the notification was caused by a negative response)
2888
2889
>The headers of the response as a dict, the values of which are the relevant header objects.
2890
  
2891
>+_body_+: (if the notification was caused by a negative response)
2892
2893
>This will be @None@.
2894
2895
*SIPIncomingSubscriptionDidEnd*
2896
>This notification is sent whenever the @IncomingSubscription@ object reaches the @"terminated"@ state and is no longer valid.
2897
>After receiving this notification, the application should not longer try to use the object.
2898
  
2899
>+_timestamp_+:
2900
2901
>A @datetime.datetime@ object indicating when the notification was sent.
2902
2903
2904
h3. Referral
2905
2906
2907
Subscription and notifications for SIP events is an Internet standard published at "RFC 3856":http://tools.ietf.org/html/rfc3856.
2908
The REFER method, defined in "RFC 3515":http://tools.ietf.org/html/rfc3515 uses the subscription mechanism to tell SIP endpoints to refer to specific resources.
2909
2910 1 Adrian Georgescu
This SIP primitive class represents a referral requested by the client to a target URI.
2911
This means that the application should instance this class for each combination of target URI and resource it wishes the target to refer to.
2912 117 Adrian Georgescu
Whenever a @NOTIFY@ is received, the application will receive the @SIPReferralGotNotify@ notification.
2913 1 Adrian Georgescu
2914 117 Adrian Georgescu
Not creating an implicit subscription is supported as per "RFC 4488":http://tools.ietf.org/html/rfc4488
2915 1 Adrian Georgescu
2916 117 Adrian Georgescu
Internally a @Referral@ object has a state machine, which reflects the state of the subscription. (The same as the @Subsription@ since it uses the same event framework)
2917
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@.
2918
The last three states are directly copied from the contents of the @Subscription-State@ header of the received @NOTIFY@ request.
2919
Also, the state can be an arbitrary string if the contents of the @Subscription-State@ header are not one of the three above.
2920
The state of the object is presented in the @state@ attribute and changes of the state are indicated by means of the @SIPReferralChangedState@ notification.
2921 1 Adrian Georgescu
This notification is only informational, an application using this object should take actions based on the other notifications sent by this object.
2922
2923
2924 117 Adrian Georgescu
h4. methods
2925 1 Adrian Georgescu
2926
2927
2928 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_, *request_uri*, *from_header*, *to_header*, *refer_to_header, *contact_header*, *route_header*, *credentials*=@None@)
2929
>Creates a new @Referral@ object which will be in the @NULL@ state.
2930
>The arguments for this method are documented in the attributes section above.
2931 1 Adrian Georgescu
2932 117 Adrian Georgescu
*send_refer*(_self_, *create_subscription*=@1@, *extra_headers*=@list()@, *timeout*=@None@)
2933
>Calling this method triggers sending a @REFER@ request to the presence agent.
2934
>The arguments passed will be stored and used for subsequent refreshing @SUBSCRIBE@ requests. The dialog may also be refreshed manually by using the @refresh@ function.
2935
>It may not be called when the object is in the @TERMINATED@ state.
2936
  
2937
>+_create_subscription_+:
2938 1 Adrian Georgescu
2939 117 Adrian Georgescu
>Boolean flag indicating if an implicit subscription should be created.
2940
  
2941
>+_extra_headers_+:
2942 1 Adrian Georgescu
2943 117 Adrian Georgescu
>A list of additional headers to include in the @REFER@ requests.
2944
  
2945
>+_timeout_+:
2946 1 Adrian Georgescu
2947 117 Adrian Georgescu
>This can be either an int or a float, indicating in how many seconds the request should timeout with an internally generated 408 response.
2948
>If this is @None@, the internal 408 is only triggered by the internal PJSIP transaction timeout.
2949
>Note that, even if the timeout is specified, the PJSIP timeout is also still valid.
2950 1 Adrian Georgescu
2951 117 Adrian Georgescu
*refresh*(_self_, *contact_header*=@None@, *extra_headers*=@list()@, *timeout*=@None@)
2952
  
2953
>+_contact_header_+:
2954 1 Adrian Georgescu
2955 117 Adrian Georgescu
>An optional @ContactHeader@ object which will replace the local contact header and will be used from this moment on.
2956
  
2957
>+_extra_headers_+:
2958 1 Adrian Georgescu
2959 117 Adrian Georgescu
>A list of additional headers to include in the refreshing @SUBSCRIBE@ request.
2960
  
2961
>+_timeout_+:
2962 1 Adrian Georgescu
2963 117 Adrian Georgescu
>The @timeout@ argument has the same meaning as it does for the @send_refer()@ method.
2964 1 Adrian Georgescu
2965 117 Adrian Georgescu
*end*(_self_, *timeout*=@None@)
2966
>This will end the referral subscription by sending a @SUBSCRIBE@ request with an @Expires@ value of 0.
2967
>If this object is no longer subscribed, this method will return without performing any action.
2968
>This method cannot be called when the object is in the @NULL@ state.
2969
>The @timeout@ argument has the same meaning as it does for the @send_refer()@ method.
2970 1 Adrian Georgescu
2971
2972 117 Adrian Georgescu
h4. attributes
2973 1 Adrian Georgescu
2974
2975
2976 117 Adrian Georgescu
*state*
2977
>Indicates which state the internal state machine is in.
2978
>See the previous section for a list of states the state machine can be in.
2979 1 Adrian Georgescu
2980 117 Adrian Georgescu
*from_header*
2981
>The @FrozenFromHeader@ to be put in the @From@ header of the @REFER@ and @SUBSCRIBE@ requests.
2982
>This attribute is set on object instantiation and is read-only.
2983 1 Adrian Georgescu
2984 117 Adrian Georgescu
*to_header*
2985
>The @FrozenToHeader@ that is the target for the referral.
2986
>This attribute is set on object instantiation and is read-only.
2987 1 Adrian Georgescu
2988 117 Adrian Georgescu
*refer_to_header*
2989
>The @FrozenReferToHeader@ that is the target resource for the referral.
2990
>This attribute is set on object instantiation and is read-only.
2991 1 Adrian Georgescu
2992 117 Adrian Georgescu
*local_contact_header*
2993
>The @FrozenContactHeader@ to be put in the @Contact@ header of the @REFER@ and @SUBSCRIBE@ requests.
2994
>This attribute is set on object instantiation and is read-only.
2995 1 Adrian Georgescu
2996 117 Adrian Georgescu
*remote_contact_header*
2997
 The @FrozenContactHeader@ received from the remote endpoint. This attribute is read-only.
2998 1 Adrian Georgescu
2999 117 Adrian Georgescu
*route_header*
3000
>The outbound proxy to use in the form of a @FrozenRouteHeader@ object.
3001
>This attribute is set on object instantiation and is read-only.
3002 1 Adrian Georgescu
3003 117 Adrian Georgescu
*credentials*
3004
>The SIP credentials needed to authenticate at the SIP proxy in the form of a @FrozenCredentials@ object.
3005
>If none was specified when creating the @Referral@ object, this attribute is @None@.
3006
>This attribute is set on object instantiation and is read-only.
3007 1 Adrian Georgescu
3008 117 Adrian Georgescu
*refresh*
3009
>The refresh interval in seconds that was requested on object instantiation as an int.
3010
>This attribute is set when a @NOTIFY@ request is received and is read-only.
3011 1 Adrian Georgescu
3012 117 Adrian Georgescu
*extra_headers*
3013
>This contains the @frozenlist@ of extra headers that was last passed to a successful call to the @subscribe()@ method.
3014
>If the argument was not provided, this attribute is an empty list.
3015
>This attribute is read-only.
3016 1 Adrian Georgescu
3017 117 Adrian Georgescu
*peer_address*
3018
>This read-only attribute contains the remote endpoint IP and port information. It can be accessed by accessing this object's @ip@ and @port@ attributes.
3019 1 Adrian Georgescu
3020
3021 117 Adrian Georgescu
h4. notifications
3022 1 Adrian Georgescu
3023
3024
3025 117 Adrian Georgescu
*SIPReferralChangedState*
3026
>This notification will be sent every time the internal state machine of a @Referral@ object changes state.
3027
  
3028
>+_timestamp_+:
3029 1 Adrian Georgescu
3030 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
3031
  
3032
>+_prev_state_+:
3033 1 Adrian Georgescu
3034 117 Adrian Georgescu
>The previous state that the sate machine was in.
3035
  
3036
>+_state_+:
3037 1 Adrian Georgescu
3038 117 Adrian Georgescu
>The new state the state machine moved into.
3039 1 Adrian Georgescu
3040 117 Adrian Georgescu
*SIPReferralWillStart*
3041
>This notification will be emitted when the initial @REFER@ request is sent.
3042
  
3043
>+_timestamp_+:
3044 1 Adrian Georgescu
3045 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
3046 1 Adrian Georgescu
3047 117 Adrian Georgescu
*SIPReferralDidStart*
3048
>This notification will be sent when the initial @REFER@ was accepted by the remote endpoint.
3049
  
3050
>+_timestamp_+:
3051 1 Adrian Georgescu
3052 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
3053 1 Adrian Georgescu
3054 117 Adrian Georgescu
*SIPReferralGotNotify*
3055
>This notification will be sent when a @NOTIFY@ is received that corresponds to a particular @Referral@ object.
3056
>Note that this notification could be sent when a @NOTIFY@ without a body is received.
3057
  
3058
>+_request_uri_+:
3059 1 Adrian Georgescu
3060 117 Adrian Georgescu
>The request URI of the @NOTIFY@ request as a @SIPURI@ object.
3061
  
3062
>+_from_header_+:
3063 1 Adrian Georgescu
3064 117 Adrian Georgescu
>The From header of the @NOTIFY@ request as a @FrozenFromHeader@ object.
3065
  
3066
>+_to_header_+:
3067 1 Adrian Georgescu
3068 117 Adrian Georgescu
>The To header of the @NOTIFY@ request as a @FrozenToHeader@ object.
3069
  
3070
>+_content_type_+:
3071 1 Adrian Georgescu
3072 117 Adrian Georgescu
>The Content-Type header value of the @NOTIFY@ request as a @ContentType@ object.
3073
  
3074
>+_event_+:
3075 1 Adrian Georgescu
3076 117 Adrian Georgescu
>The Event header value of the @NOTIFY@ request as a string object.
3077
  
3078
>+_headers_+:
3079 1 Adrian Georgescu
3080 117 Adrian Georgescu
>The headers of the @NOTIFY@ request as a dict.
3081
>Each SIP header is represented in its parsed for as long as PJSIP supports it.
3082
>The format of the parsed value depends on the header.
3083
  
3084
>+_body_+:
3085 1 Adrian Georgescu
3086 117 Adrian Georgescu
>The body of the @NOTIFY@ request as a string, or @None@ if no body was included.
3087
  
3088
>+_timestamp_+:
3089 1 Adrian Georgescu
3090 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.  
3091 1 Adrian Georgescu
3092 117 Adrian Georgescu
*SIPReferralDidFail*
3093
>This notification will be sent whenever there is a failure, such as a rejected initial @REFER@ or refreshing @SUBSCRIBE@.
3094
>After this notification the @Referral@ object is in the @TERMINATED@ state and can no longer be used.
3095
  
3096
>+_timestamp_+:
3097 1 Adrian Georgescu
3098 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
3099
  
3100
>+_code_+:
3101 1 Adrian Georgescu
3102 117 Adrian Georgescu
>An integer SIP code from the fatal response that was received from the remote party of generated by PJSIP.
3103
>If the error is internal to the SIP core, this attribute will have a value of 0.
3104
  
3105
>+_reason_+:
3106 1 Adrian Georgescu
3107 117 Adrian Georgescu
>An text string describing the failure that occurred.
3108 1 Adrian Georgescu
3109 117 Adrian Georgescu
*SIPReferralDidEnd*
3110
>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. It will also be sent when the remote endpoint sends a @NOTIFY@ request with a @noresource@ reason in the @Subscription-State@ header.
3111
>After this notification the @Referral@ object is in the @TERMINATED@ state and can no longer be used.
3112
  
3113
>+_timestamp_+:
3114 1 Adrian Georgescu
3115 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
3116 1 Adrian Georgescu
3117 117 Adrian Georgescu
3118
h3. IncomingReferral
3119
3120
3121
Subscription and notifications for SIP events is an Internet standard published at "RFC 3856":http://tools.ietf.org/html/rfc3856.
3122
The REFER method, defined in "RFC 3515":http://tools.ietf.org/html/rfc3515 uses the subscription mechanism to to tell SIP endpoints to refer to specific resources.
3123
3124
This SIP primitive class is the mirror companion to the @Referral@ class and allows the application to take on the server role in a @REFER@ dialog.
3125
This means that it can accept a @REFER@ request and subsequent refreshing @SUBSCRIBE@s and sent @NOTIFY@ requests containing event state.
3126
3127
Any incoming @REFER@ request causes the creation of a @IncomingReferral@ object.
3128
This will be indicated to the application through a @SIPIncomingReferralGotRefer@ notification.
3129
It is then up to the application to check if the @REFER@ request was valid, e.g. if it was actually directed at the correct SIP URI, and respond to it in a timely fashion.
3130
3131
The application can either reject the referral by calling the @reject()@ method or accept it through the @accept()@ method.
3132
After the @IncomingReferral@ is accepted, the application can trigger sending a @NOTIFY@ request with a body reflecting the event state through the @send_notify()@ method.
3133
Whenever a refreshing @SUBSCRIBE@ is received, the latest contents to be set are sent in the resulting @NOTIFY@ request.
3134
The subscription can be ended by using the @end()@ method.
3135
3136
3137
h4. methods
3138
3139
3140
3141
*<notextile>__init__</notextile>*(_self_)
3142
>An application should never create an @IncomingSubscription@ object itself.
3143
>Doing this will create a useless object in the @None@ state.
3144
3145
*reject*(_self_, *code*)
3146
>Will reply to the initial @REFER@ with a negative response.
3147
>This method can only be called in the @"incoming"@ state and sets the referral to the @"terminated"@ state.
3148
  
3149
>+_code_+:
3150
3151
>The SIP response code to use.
3152
>This should be a negative response, i.e. in the 3xx, 4xx, 5xx or 6xx range.
3153
3154
*accept*(_self_, *code*=@202@, *duration*=@180@)
3155
>Accept the initial incoming @REFER@ and respond to it with a 202 Accepted.
3156
>A @NOTIFY@ will be sent to update the state to "active", with a payload indicating the referral is in 100 Trying state.
3157
>This method can only be called in the @"incoming"@ state.
3158
  
3159
>+_code_+:
3160
3161
>The code to be  used for the initial reply.
3162
  
3163
>+_duration_+:
3164
3165
>The desired duration for the implicit subscription. Unlike @SUBSCRIBE@ initiated dialogs, in a referral the receiving party is the one choosing the expiration time.
3166
3167
*send_notify*(_self_, *code*, *status*=@None@)
3168
>Sets or updates the body of the @NOTIFY@s to be sent within this referral and causes a @NOTIFY@ to be sent to the subscriber.
3169
>This method can only be called in the @"active"@ state.
3170
  
3171
>+_code_+:
3172
3173
>The response code to be used to generate the sipfrag payload.
3174
  
3175
>+_status_+:
3176
3177
>Optional status reason to be used to build the sipfrag payload. If none was specified the standard reason string will be used.
3178
3179
3180
h4. attributes
3181
3182
3183
3184
*state*
3185
>Indicates which state the incoming referral dialog is in.
3186
>This can be one of @None@, @"incoming"@, @"pending"@, @"active"@ or @"terminated"@.
3187
>This attribute is read-only.
3188
3189
*local_contact_header*
3190
>The @FrozenContactHeader@ to be put in the @Contact@ header of the @REFER@ and @SUBSCRIBE@ responses and @NOTIFY@ requests.
3191
>This attribute is set on object instantiation and is read-only.
3192
3193
*remote_contact_header*
3194
 The @FrozenContactHeader@ received from the remote endpoint. This attribute is read-only.
3195
3196
*peer_address*
3197
>This read-only attribute contains the remote endpoint IP and port information. It can be accessed by accessing this object's @ip@ and @port@ attributes.
3198
3199
3200
h4. notifications
3201
3202
3203
3204
*SIPIncomingReferralChangedState*
3205
>This notification will be sent every time the an @IncomingReferral@ object changes state.
3206
>This notification is mostly indicative, an application should not let its logic depend on it.
3207
  
3208
>+_timestamp_+:
3209
3210
>A @datetime.datetime@ object indicating when the notification was sent.
3211
  
3212
>+_prev_state_+:
3213
3214
>The previous state that the subscription was in.
3215
  
3216
>+_state_+:
3217
3218
>The new state the subscription has.
3219
3220
*SIPIncomingReferralGotRefer*
3221
>This notification will be sent when a new @IncomingReferral@ is created as result of an incoming @REFER@ request.
3222
>The application should listen for this notification, retain a reference to the object that sent it and either accept or reject it.
3223
  
3224
>+_timestamp_+:
3225
3226
>A @datetime.datetime@ object indicating when the notification was sent.
3227
  
3228
>+_method_+:
3229
3230
>The method of the SIP request as a string, which will be @REFER@.
3231
  
3232
>+_request_uri_+:
3233
3234
>The request URI of the @REFER@ request as a @FrozenSIPURI@ object.
3235
  
3236
>+_refer_to_+:
3237
3238
>The Refer-To header as a @FrozenReferToHeader@ object.
3239
  
3240
>+_headers_+:
3241
3242
>The headers of the @REFER@ request as a dict, the values of which are the relevant header objects.
3243
  
3244
>+_body_+:
3245
3246
>The body of the @REFER@ request as a string, or @None@ if no body was included.
3247
3248
*SIPIncomingReferralGotRefreshingSubscribe*
3249
>This notification indicates that a refreshing @SUBSCRIBE@ request was received from the subscriber.
3250
>It is purely informative, no action needs to be taken by the application as a result of it.
3251
3252
*SIPIncomingReferralGotUnsubscribe*
3253
>This notification indicates that a @SUBSCRIBE@ request with an @Expires@ header of 0 was received from the subscriber, effectively requesting to unsubscribe.
3254
>It is purely informative, no action needs to be taken by the application as a result of it.
3255
3256
*SIPIncomingReferralAnsweredRefer*
3257
>This notification is sent whenever a response to a @REFER@ request is sent by the object.
3258
>It is purely informative, no action needs to be taken by the application as a result of it.
3259
  
3260
>+_timestamp_+:
3261
3262
>A @datetime.datetime@ object indicating when the notification was sent.
3263
  
3264
>+_code_+:
3265
3266
>The code of the SIP response as an int.
3267
  
3268
>+_reason_+:
3269
3270
>The reason text of the SIP response as an int.
3271
  
3272
>+_headers_+:
3273
3274
>The headers of the response as a dict, the values of which are the relevant header objects.
3275
  
3276
>+_body_+:
3277
3278
>This will be @None@.
3279
3280
*SIPIncomingReferralSentNotify*
3281
>This notification indicates that a @NOTIFY@ request was sent to the subscriber.
3282
>It is purely informative, no action needs to be taken by the application as a result of it.
3283
  
3284
>+_timestamp_+:
3285
3286
>A @datetime.datetime@ object indicating when the notification was sent.
3287
  
3288
>+_method_+:
3289
3290
>The method of the SIP request as a string, which will be @NOTIFY@.
3291
  
3292
>+_request_uri_+:
3293
3294
>The request URI of the @NOTIFY@ request as a @FrozenSIPURI@ object.
3295
  
3296
>+_headers_+:
3297
3298
>The headers of the @NOTIFY@ request as a dict, the values of which are the relevant header objects.
3299
  
3300
>+_body_+:
3301
3302
>The body of the @NOTIFY@ request or response as a string, or @None@ if no body was included.
3303
3304
*SIPIncomingReferralNotifyDidSucceed*
3305
>This indicates that a positive final response was received from the subscriber in reply to a sent @NOTIFY@ request.
3306
>The notification is purely informative, no action needs to be taken by the application as a result of it.
3307
  
3308
>+_timestamp_+:
3309
3310
>A @datetime.datetime@ object indicating when the notification was sent.
3311
  
3312
>+_code_+:
3313
3314
>The code of the SIP response as an int.
3315
  
3316
>+_reason_+:
3317
3318
>The reason text of the SIP response as a string.
3319
  
3320
>+_headers_+:
3321
3322
>The headers of the response as a dict, the values of which are the relevant header objects.
3323
  
3324
>+_body_+:
3325
3326
>This will be @None@.
3327
3328
*SIPIncomingReferralNotifyDidFail*
3329
>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.
3330
  
3331
>+_timestamp_+:
3332
3333
>A @datetime.datetime@ object indicating when the notification was sent.
3334
  
3335
>+_code_+:
3336
3337
>The code of the SIP response as an int.
3338
>If this is 0, the notification was sent as a result of an internal error.
3339
  
3340
>+_reason_+:
3341
3342
>The reason text of the SIP response as a string or the internal error if the code attribute is 0.
3343
  
3344
>+_headers_+: (if the notification was caused by a negative response)
3345
3346
>The headers of the response as a dict, the values of which are the relevant header objects.
3347
  
3348
>+_body_+: (if the notification was caused by a negative response)
3349
3350
>This will be @None@.
3351
3352
*SIPIncomingReferralDidEnd*
3353
>This notification is sent whenever the @IncomingReferral@ object reaches the @"terminated"@ state and is no longer valid.
3354
>After receiving this notification, the application should not longer try to use the object.
3355
  
3356
>+_timestamp_+:
3357
3358
>A @datetime.datetime@ object indicating when the notification was sent.
3359
3360
3361
h3. AudioMixer
3362
3363
3364
A @AudioMixer@ manages two audio devices, on for input and one for output, and is able to route audio data for a number of sources.
3365
It wraps a "PJSIP conference bridge":http://www.pjsip.org/pjmedia/docs/html/group+PJMEDIA+CONF.htm, the concept of which is explained in the "PJSIP documentation":http://trac.pjsip.org/repos/wiki/Python_SIP/Media.
3366
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.
3367 1 Adrian Georgescu
The sound devices, both input and output, together always occupy slot 0.
3368 117 Adrian Georgescu
It is up to the application to setup the desired routing between these components. Note that the middleware provides an abstracted API which hides the complexity of using the low-level PJSIP concepts. This is mainly provided in the [[SipMiddlewareApi#Audio|@sipsimple.audio@]] module, but also consists of other audio-enabled objects (such as the AudioStream).
3369 1 Adrian Georgescu
3370
3371 117 Adrian Georgescu
h4. methods
3372 1 Adrian Georgescu
3373
3374
3375 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_, *input_device*, *output_device*, *sample_rate*, *ec_tail_length*=200, *slot_count*=254)
3376
>Creates a new @ConferenceBridge@ object.
3377
  
3378
>+_input_device_+:
3379 1 Adrian Georgescu
3380 117 Adrian Georgescu
>The name of the audio input device to use as a string, or @None@ if no input device is to be used.
3381
>A list of known input devices can be queried through the @Engine.input_devices@ attribute.
3382
>If @"system_default"@ is used, PJSIP will select the system default output device, or @None@ if no audio input device is present.
3383
>The device that was selected can be queried afterwards through the @input_device@ attribute.
3384
  
3385
>+_output_device_+:
3386 1 Adrian Georgescu
3387 117 Adrian Georgescu
>The name of the audio output device to use as a string, or @None@ if no output device is to be used.
3388
>A list of known output devices can be queried through the @Engine.output_devices@ attribute.
3389
>If @"system_default"@ is used, PJSIP will select the system default output device, or @None@ if no audio output device is present.
3390
>The device that was selected can be queried afterwards through the @output_device@ attribute.
3391
  
3392
>+_sample_rate_+:
3393 1 Adrian Georgescu
3394 117 Adrian Georgescu
>The sample rate on which the conference bridge and sound devices should operate in Hz.
3395
>This must be a multiple of 50.
3396
  
3397
>+_ec_tail_length_+:
3398 1 Adrian Georgescu
3399 117 Adrian Georgescu
>The echo cancellation tail length in ms.
3400
>If this value is 0, no echo cancellation is used.
3401
  
3402
>+_slot_count_+:
3403 1 Adrian Georgescu
3404 117 Adrian Georgescu
>The number of slots to allocate on the conference bridge.
3405
>Not that this includes the slot that is occupied by the sound devices.
3406 1 Adrian Georgescu
3407 117 Adrian Georgescu
*set_sound_devices*(_self_, *input_device*, *output_device*, *ec_tail_length*)
3408
>Change the sound devices used (including echo cancellation) by the conference bridge.
3409
>The meaning of the parameters is that same as for @__init__()@.
3410 1 Adrian Georgescu
3411 117 Adrian Georgescu
*connect_slots*(_self_, *src_slot*, *dst_slot*)
3412
>Connect two slots on the conference bridge, making audio flow from @src_slot@ to @dst_slot@.
3413 1 Adrian Georgescu
3414 117 Adrian Georgescu
*disconnect_slots*(_self_, *src_slot*, *dst_slot*)
3415
>Break the connection between the specified slots.
3416
>Note that when an audio object is stopped or destroyed, its connections on the conference bridge will automatically be removed.
3417 1 Adrian Georgescu
3418
3419 117 Adrian Georgescu
h4. attributes
3420 1 Adrian Georgescu
3421
3422
3423 117 Adrian Georgescu
*input_device*
3424
>A string specifying the audio input device that is currently being used.
3425
>If there is no input device, this attribute will be @None@.
3426
>This attribute is read-only, but may be updated by calling the @set_sound_devices()@ method.
3427 1 Adrian Georgescu
3428 117 Adrian Georgescu
*output_device*
3429
>A string specifying the audio output device that is currently being used.
3430
>If there is no output device, this attribute will be @None@.
3431
>This attribute is read-only, but may be updated by calling the @set_sound_devices()@ method.
3432 1 Adrian Georgescu
3433 117 Adrian Georgescu
*sample_rate*
3434
>The sample rate in Hz that the conference bridge is currently operating on.
3435
>This read-only attribute is passed when the object is created.
3436 1 Adrian Georgescu
3437 117 Adrian Georgescu
*ec_tail_length*
3438
>The current echo cancellation tail length in ms.
3439
>If this value is 0, no echo cancellation is used.
3440
>This attribute is read-only, but may be updated by calling the @set_sound_devices()@ method.
3441 1 Adrian Georgescu
3442 117 Adrian Georgescu
*slot_count*
3443
>The total number of slots that is available on the conference bridge
3444
>This read-only attribute is passed when the object is created.
3445 1 Adrian Georgescu
3446 117 Adrian Georgescu
*used_slot_count*
3447
>A read-only attribute indicating the number of slots that are used by objects.
3448 1 Adrian Georgescu
3449 117 Adrian Georgescu
*input_volume*
3450
>This writable property indicates the % of volume that is read from the audio input device.
3451
>By default this value is 100.
3452 1 Adrian Georgescu
3453 117 Adrian Georgescu
*output_volume*
3454
>This writable property indicates the % of volume that is sent to the audio output device.
3455
>By default this value is 100.
3456 1 Adrian Georgescu
3457 117 Adrian Georgescu
*muted*
3458
>This writable boolean property indicates if the input audio device is muted.
3459 1 Adrian Georgescu
3460 117 Adrian Georgescu
*connected_slots*
3461
>A read-only list of tupples indicating which slot is connected to which.
3462
>Connections are directional.
3463 1 Adrian Georgescu
3464
3465 117 Adrian Georgescu
h3. MixerPort
3466 1 Adrian Georgescu
3467
3468 117 Adrian Georgescu
This a simple object which simply copies all the audio data it gets as input to it output. It's main purpose is that of facilitating the creation the of the middleware @AudioBridge@ object.
3469 1 Adrian Georgescu
3470
3471 117 Adrian Georgescu
h4. methods
3472
3473
3474
3475
*<notextile>__init__</notextile>*(_self_, _mixer_)
3476
>Create a new MixerPort which is associated with the specified AudioMixer.
3477
3478
*start*(_self_)
3479
>Activate the mixer port. This will reserve a slot on the AudioMixer and allow it to be connected to other slots.
3480
3481
*stop*(_self_)
3482
>Deactivate the mixer port. This will release the slot previously allocated on the AudioMixer and all connections which it had will be discarded.
3483
3484
3485
h4. attributes
3486
3487
3488
3489
*mixer*
3490
>The AudioMixer this MixerPort is associated with
3491
>This attribute is read-only.
3492
3493
*is_active*
3494
>Whether or not this MixerPort has a slot associated in its AudioMixer.
3495
>This attribute is read-only.
3496
3497
*slot*
3498
>The slot this MixerPort has reserved on AudioMixer or @None@ if it is not active.
3499
>This attribute is read-only.
3500
3501
3502
3503
h3. WaveFile
3504
3505
3506
This is a simple object that allows playing back of a @.wav@ file over the PJSIP conference bridge.
3507 1 Adrian Georgescu
Only 16-bit PCM and A-law/U-law formats are supported.
3508
Its main purpose is the playback of ringtones or previously recorded conversations.
3509
3510 117 Adrian Georgescu
This object is associated with a @AudioMixer@ instance and, once the @start()@ method is called, connects to it and sends the sound to all its connections.
3511
Note that the slot of the @WaveFile@ object will not start playing until it is connected to another slot on the AudioMixer.
3512
If the @stop()@ method is called or the end of the @.wav@ file is reached, a @WaveFileDidFinishPlaying@ notification is sent by the object.
3513
After this the @start()@ method may be called again in order to re-use the object.
3514 1 Adrian Georgescu
3515 117 Adrian Georgescu
It is the application's responsibility to keep a reference to the @WaveFile@ object for the duration of playback.
3516 1 Adrian Georgescu
If the reference count of the object reaches 0, playback will be stopped automatically.
3517
In this case no notification will be sent.
3518
3519
3520 117 Adrian Georgescu
h4. methods
3521 1 Adrian Georgescu
3522
3523
3524 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_, *mixer*, *filename*)
3525
>Creates a new @WaveFile@ object.
3526
  
3527
>+_mixer_+:
3528 1 Adrian Georgescu
3529 117 Adrian Georgescu
>The @AudioMixer@ object that this object is to be connected to.
3530
  
3531
>+_filename_+:
3532 1 Adrian Georgescu
3533 117 Adrian Georgescu
>The name of the @.wav@ file to be played back as a string.
3534
>This should include the full path to the file.
3535 1 Adrian Georgescu
3536 117 Adrian Georgescu
*start*(_self_)
3537
>Start playback of the @.wav@ file.
3538 1 Adrian Georgescu
3539 117 Adrian Georgescu
*stop*(_self_)
3540
>Stop playback of the file.
3541 1 Adrian Georgescu
3542
3543 117 Adrian Georgescu
h4. attributes
3544 1 Adrian Georgescu
3545
3546
3547 117 Adrian Georgescu
*mixer*
3548
>The @AudioMixer@ this object is associated with.
3549
>This attribute is read-only.
3550 1 Adrian Georgescu
3551 117 Adrian Georgescu
*filename*
3552
>The name of the @.wav@ file, as specified when the object was created.
3553
>This attribute is read-only.
3554 1 Adrian Georgescu
3555 117 Adrian Georgescu
*slot*
3556
>A read-only property indicating the slot number at which this object is attached to the associated AudioMixer.
3557
>If the @WaveFile@ is not active, this attribute will be @None@.
3558 1 Adrian Georgescu
3559 117 Adrian Georgescu
*volume*
3560
>A writable property indicating the % of volume at which this object contributes audio to the AudioMixer.
3561
>By default this is set to 100.
3562 1 Adrian Georgescu
3563 117 Adrian Georgescu
*is_active*
3564
>A boolean read-only property that indicates if the file is currently being played.
3565 1 Adrian Georgescu
3566
3567 117 Adrian Georgescu
h4. notifications
3568 1 Adrian Georgescu
3569
3570
3571 117 Adrian Georgescu
*WaveFileDidFinishPlaying*
3572
>This notification will be sent whenever playing of the @.wav@ has stopped.
3573
>After sending this event, the playback may be re-started.
3574
  
3575
>+_timestamp_+:
3576 1 Adrian Georgescu
3577 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
3578 1 Adrian Georgescu
3579
3580 117 Adrian Georgescu
h3. RecordingWaveFile
3581 1 Adrian Georgescu
3582
3583 117 Adrian Georgescu
This is a simple object that allows recording audio to a PCM @.wav@ file.
3584 1 Adrian Georgescu
3585 117 Adrian Georgescu
This object is associated with a @AudioMixer@ instance and, once the @start()@ method is called, crecords sound from its connections.
3586
Note that the @RecordingWaveFile@ will not record anything if it does not have any connections.
3587
Recording to the file can be stopped either by calling the @stop()@ method or by removing all references to the object.
3588
Once the @stop()@ method has been called, the @start()@ method may not be called again.
3589
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.
3590 1 Adrian Georgescu
3591
3592 117 Adrian Georgescu
h4. methods
3593
3594
3595
3596
*<notextile>__init__</notextile>*(_self_, *mixer*, *filename*)
3597
>Creates a new @RecordingWaveFile@ object.
3598
  
3599
>+_mixer_+:
3600
3601
>The @AudioMixer@ object that this object is to be associated with.
3602
  
3603
>+_filename_+:
3604
3605
>The name of the @.wav@ file to record to as a string.
3606
>This should include the full path to the file.
3607
3608
*start*(_self_)
3609
>Start recording the sound to the @.wav@ file.
3610
3611
*stop*(_self_)
3612
>Stop recording to the file.
3613
3614
3615
h4. attributes
3616
3617
3618
3619
*mixer*
3620
>The @AudioMixer@ this object is associated with.
3621
>This attribute is read-only.
3622
3623
*filename*
3624
>The name of the @.wav@ file, as specified when the object was created.
3625
>This attribute is read-only.
3626
3627
*slot*
3628
>A read-only property indicating the slot number at which this object is attached to the associated AudioMixer.
3629
>If the @RecordingWaveFile@ is not active, this attribute will be @None@.
3630
3631
*is_active*
3632
>A boolean read-only attribute that indicates if the file is currently being written to.
3633
3634
3635
h3. ToneGenerator
3636
3637
3638
A @ToneGenerator@ can generate a series of dual frequency tones and has a shortcut method for generating valid DTMF tones.
3639
Each instance of this object is associated with a @AudioMixer@ object, which it will connect to once started.
3640 1 Adrian Georgescu
The tones will be sent to the slots on the AudioMixer its slot is connected to.
3641 117 Adrian Georgescu
Once started, a @ToneGenerator@ can be stopped by calling the @stop()@ method and is automatically destroyed when the reference count reaches 0.
3642 1 Adrian Georgescu
3643
> Note: this object has threading issues when the application uses multiple AudioMixers. It should not be used.
3644
3645
3646 117 Adrian Georgescu
h4. methods
3647 1 Adrian Georgescu
3648
3649
3650 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_, *mixer*)
3651
>Creates a new @ToneGenerator@ object.
3652
  
3653
>+_mixer_+:
3654 1 Adrian Georgescu
3655 117 Adrian Georgescu
>The @AudioMixer@ object that this object is to be connected to.
3656 1 Adrian Georgescu
3657 117 Adrian Georgescu
*start*(_self_)
3658
>Start the tone generator and connect it to its associated @AudioMixer@.
3659 1 Adrian Georgescu
3660 117 Adrian Georgescu
*stop*(_self_)
3661
>Stop the tone generator and remove it from the conference bridge.
3662 1 Adrian Georgescu
3663 117 Adrian Georgescu
*play_tones(_self_, *tones*)
3664
>Play a sequence of single or dual frequency tones over the audio device.
3665
  
3666
>+_tones_+:
3667 1 Adrian Georgescu
3668 117 Adrian Georgescu
>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.
3669
>If @freq2@ is 0, this indicates that only @freq1@ should be used for the tone.
3670
>If @freq1@ is 0, this indicates a pause when no tone should be played for the set duration.
3671 1 Adrian Georgescu
3672 117 Adrian Georgescu
*play_dtmf(_self_, *digit*)
3673
>Play a single DTMF digit.
3674
  
3675
>+_digit_+:
3676 1 Adrian Georgescu
3677 117 Adrian Georgescu
>A string of length 1 containing a valid DTMF digit, i.e. 0 through 9, #, * or A through D.
3678 1 Adrian Georgescu
3679
3680 117 Adrian Georgescu
h4. attributes
3681 1 Adrian Georgescu
3682
3683 117 Adrian Georgescu
3684
*mixer*
3685
>The @AudioMixer@ this object is associated with.
3686
>This attribute is read-only.
3687
3688
*slot*
3689
>A read-only property indicating the slot number at which this object is attached to the associated AudioMixer.
3690
>If the @ToneGenerator@ has not been started, this attribute will be @None@.
3691
3692
*volume*
3693
>A writable property indicating the % of volume at which this object contributes audio.
3694
>By default this is set to 100.
3695
3696
*is_active*
3697
>A boolean read-only property that indicates if the object has been started.
3698
3699
*is_busy*
3700
>A boolean read-only property indicating if the @ToneGenerator@ is busy playing tones.
3701
3702
3703
h4. notifications
3704
3705
3706
*ToneGeneratorDidFinishPlaying*
3707
>This notification will be sent whenever playing of the queued tones has finished.
3708
  
3709
>+_timestamp_+:
3710
3711
>A @datetime.datetime@ object indicating when the notification was sent.