SipCoreApiDocumentation

Version 118 (Chris Maciejewski, 01/04/2014 10:13 am)

1 117 Adrian Georgescu
h1. SIP Core API
2 1 Adrian Georgescu
3 1 Adrian Georgescu
4 1 Adrian Georgescu
5 117 Adrian Georgescu
6 117 Adrian Georgescu
7 117 Adrian Georgescu
h2. Introduction
8 117 Adrian Georgescu
9 117 Adrian Georgescu
10 117 Adrian Georgescu
This chapter describes the internal architecture and API of the SIP core of the @sipsimple@ library.
11 117 Adrian Georgescu
@sipsimple@ is a Python package, the core of which wraps the PJSIP C library, which handles SIP signaling and audio media for the SIP SIMPLE client.
12 117 Adrian Georgescu
13 117 Adrian Georgescu
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 1 Adrian Georgescu
(VoIP). Media can be added to (and removed from) an existing session.
16 1 Adrian Georgescu
17 1 Adrian Georgescu
SIP transparently supports name mapping and redirection services, which
18 1 Adrian Georgescu
supports personal mobility, users can maintain a single externally visible
19 1 Adrian Georgescu
address identifier, which can be in the form of a standard email address or
20 1 Adrian Georgescu
E.164 telephone number regardless of their physical network location.
21 1 Adrian Georgescu
22 1 Adrian Georgescu
SIP allows the endpoints to negotiate and combine any type of session they
23 1 Adrian Georgescu
mutually understand like video, instant messaging (IM), file transfer,
24 1 Adrian Georgescu
desktop sharing and provides a generic event notification system with
25 1 Adrian Georgescu
real-time publications and subscriptions about state changes that can be
26 1 Adrian Georgescu
used for asynchronous services like presence, message waiting indicator and
27 1 Adrian Georgescu
busy line appearance.
28 1 Adrian Georgescu
29 1 Adrian Georgescu
For a comprehensive overview of SIP related protocols and use cases visit http://www.tech-invite.com
30 1 Adrian Georgescu
31 1 Adrian Georgescu
32 117 Adrian Georgescu
h2. PJSIP library
33 117 Adrian Georgescu
34 117 Adrian Georgescu
35 117 Adrian Georgescu
@sipsimple@ builds on PJSIP http://www.pjsip.org, a set of static libraries, written in C, which provide SIP signaling and media capabilities.
36 1 Adrian Georgescu
PJSIP is considered to be the most mature and advanced open source SIP stack available.
37 1 Adrian Georgescu
The following diagram, taken from the PJSIP documentation, illustrates the library stack of PJSIP:
38 1 Adrian Georgescu
39 117 Adrian Georgescu
!{ nolink}http://www.pjsip.org/images/diagram.jpg!
40 1 Adrian Georgescu
41 1 Adrian Georgescu
The diagram shows that there is a common base library, and two more or less independent stacks of libraries, one for SIP signaling and one for SIP media.
42 1 Adrian Georgescu
The latter also includes an abstraction layer for the sound-card.
43 1 Adrian Georgescu
Both of these stracks are integrated in the high level library, called PJSUA.
44 1 Adrian Georgescu
45 117 Adrian Georgescu
PJSIP itself provides a high-level "Python wrapper for PJSUA":http://www.pjsip.org/python/pjsua.htm.
46 117 Adrian Georgescu
Despite this, the choice was made to bypass PJSUA and write the SIP core of the @sipsimple@ package as a Python wrapper, which directly uses the PJSIP and PJMEDIA libraries.
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 117 Adrian Georgescu
* What is advertised as SIMPLE functionality, it is minimal and incomplete subset of it. Only page mode messaging using SIP MESSAGE method and basic device status presence are possible, while session mode IM and rich presence are desired.
50 117 Adrian Georgescu
* PJSUA integrates the decoding and encoding of payloads (e.g. presence related XML documents), while in the SIP SIMPLE client this should be done at a high level, not by the SIP stack.
51 1 Adrian Georgescu
52 1 Adrian Georgescu
PJSIP itself is by nature asynchronous.
53 1 Adrian Georgescu
In the case of PJSIP it means that in general there will be one thread which handles reception and transmission of SIP signaling messages by means of a polling function which is continually called by the application.
54 1 Adrian Georgescu
Whenever the application performs some action through a function, this function will return immediately.
55 1 Adrian Georgescu
If PJSIP has a result for this action, it will notify the application by means of a callback function in the context of the polling function thread.
56 1 Adrian Georgescu
57 1 Adrian Georgescu
> NOTE: Currently the core starts the media handling as a separate C thread to avoid lag caused by the GIL.
58 1 Adrian Georgescu
> The sound-card also has its own C thread.
59 1 Adrian Georgescu
60 1 Adrian Georgescu
61 117 Adrian Georgescu
h2. Architecture
62 117 Adrian Georgescu
63 117 Adrian Georgescu
64 117 Adrian Georgescu
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 90 Luci Stanescu
This in turn compiles to a Python C extension module, which links with the PJSIP static libraries.
67 90 Luci Stanescu
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 117 Adrian Georgescu
* 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 117 Adrian Georgescu
* Utility classes used throughout the core:
71 117 Adrian Georgescu
*** @frozenlist@ and @frozendict@: classes which relate respectively to @list@ and @dict@ similarly to how the standard @frozenset@ relates to @set@.
72 117 Adrian Georgescu
* Helper classes which represent a structured collection of data which is used throughout the core:
73 117 Adrian Georgescu
*** @BaseSIPURI@, @SIPURI@ and @FrozenSIPURI@
74 117 Adrian Georgescu
*** @BaseCredentials@, @Credentials@ and @FrozenCredentials@
75 117 Adrian Georgescu
* SDP manipulation classes, which directly wrap the PJSIP structures representing either the parsed or to be generated SDP:
76 117 Adrian Georgescu
*** @BaseSDPSession@, @SDPSession@ and @FrozenSDPSession@
77 117 Adrian Georgescu
*** @BaseSDPMediaStream@, @SDPMediaStream@ and @FrozenSDPMediaStream@
78 117 Adrian Georgescu
*** @BaseSDPConnection@, @SDPConnection@ and @FrozenSDPConnection@
79 117 Adrian Georgescu
*** @SDPAttributeList@ and @FrozenSDPAttributeList@
80 117 Adrian Georgescu
*** @BaseSDPAttribute@, @SDPAttribute@ and @FrozenSDPAttribute@
81 117 Adrian Georgescu
* Audio handling classes:
82 117 Adrian Georgescu
*** @AudioMixer@
83 117 Adrian Georgescu
*** @MixerPort@
84 117 Adrian Georgescu
*** @WaveFile@
85 117 Adrian Georgescu
*** @RecordingWaveFile@
86 117 Adrian Georgescu
*** @ToneGenerator@
87 117 Adrian Georgescu
* Media transport handling classes, using the functionality built into PJMEDIA:
88 117 Adrian Georgescu
*** @RTPTransport@
89 117 Adrian Georgescu
*** @AudioTransport@
90 117 Adrian Georgescu
* SIP signalling related classes:
91 117 Adrian Georgescu
*** @Request@ and @IncomingRequest@: low-level transaction support
92 117 Adrian Georgescu
*** @Invitation@: INVITE-dialog support
93 117 Adrian Georgescu
*** @Subscription@ and @IncomingSubscription@: SUBSCRIBE-dialog support (including NOTIFY handling within the SUBSCRIBE dialog)
94 117 Adrian Georgescu
*** @Referral@ and @IncomingReferral@: REFER-dialog support (including NOTIFY handling within the dialog)
95 117 Adrian Georgescu
*** @Registration@: Python object based on @Request@ for REGISTER support
96 117 Adrian Georgescu
*** @Message@: Python object based on @Request@ for MESSAGE support
97 117 Adrian Georgescu
*** @Publication@: Python object based on @Request@ for PUBLISH support
98 117 Adrian Georgescu
* Exceptions:
99 117 Adrian Georgescu
*** @SIPCoreError@: generic error used throught the core
100 117 Adrian Georgescu
*** @PJSIPError@: subclass of @SIPCoreError@ which offers more information related to errors from PJSIP
101 117 Adrian Georgescu
*** @PJSIPTLSError@: subclass of @PJSIPError@ to distinguish between TLS-related errors and the rest
102 117 Adrian Georgescu
*** @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 1 Adrian Georgescu
111 117 Adrian Georgescu
h2. Integration
112 117 Adrian Georgescu
113 117 Adrian Georgescu
114 117 Adrian Georgescu
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 117 Adrian Georgescu
It does this by creating one or more classes that act as an observer for particular messages and registering it with the @NotificationCenter@, which is a singleton class.
118 1 Adrian Georgescu
This means that any call to instance an object from this class will result in the same object.
119 1 Adrian Georgescu
As an example, this bit of code will create an observer for logging messages only:
120 1 Adrian Georgescu
121 117 Adrian Georgescu
<pre>
122 1 Adrian Georgescu
from zope.interface import implements
123 1 Adrian Georgescu
from application.notification import NotificationCenter, IObserver
124 1 Adrian Georgescu
125 1 Adrian Georgescu
class SIPEngineLogObserver(object):
126 1 Adrian Georgescu
    implements(IObserver)
127 1 Adrian Georgescu
128 1 Adrian Georgescu
    def handle_notification(self, notification):
129 1 Adrian Georgescu
        print "%(timestamp)s (%(level)d) %(sender)14s: %(message)s" % notification.data.__dict__
130 1 Adrian Georgescu
131 1 Adrian Georgescu
log_observer = SIPEngineLogObserver()
132 1 Adrian Georgescu
notification_center = NotificationCenter()
133 1 Adrian Georgescu
notification_center.add_observer(log_observer, name="SIPEngineLog")
134 117 Adrian Georgescu
</pre>
135 1 Adrian Georgescu
136 1 Adrian Georgescu
Each notification object has three attributes:
137 1 Adrian Georgescu
138 117 Adrian Georgescu
*sender*
139 117 Adrian Georgescu
>The object that sent the notification.
140 117 Adrian Georgescu
>For generic notifications the sender will be the @Engine@ instance, otherwise the relevant object.
141 1 Adrian Georgescu
142 117 Adrian Georgescu
*name*
143 117 Adrian Georgescu
>The name describing the notification.
144 117 Adrian Georgescu
>Most of the notifications in the core have the prefix "SIP".
145 1 Adrian Georgescu
146 117 Adrian Georgescu
*data*
147 117 Adrian Georgescu
>An instance of @application.notification.NotificationData@ or a subclass of it.
148 117 Adrian Georgescu
>The attributes of this object provide additional data about the notification.
149 117 Adrian Georgescu
>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 117 Adrian Georgescu
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 117 Adrian Georgescu
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 1 Adrian Georgescu
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 117 Adrian Georgescu
For example, the SIP network ports may be set through the @local_udp_port@, @local_tcp_port@ and @local_tls_port@ arguments.
158 117 Adrian Georgescu
The UDP/RTP ports are described by a range of ports through @rtp_port_range@, two of which will be randomly selected for each @RTPTransport@ object and effectively each audio stream.
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 1 Adrian Georgescu
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 1 Adrian Georgescu
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 1 Adrian Georgescu
reg = Registration(identity, credentials=cred)
175 1 Adrian Georgescu
reg.register(ContactHeader(SIPURI("127.0.0.1",port=12345)), RouteHeader(SIPURI("1.2.3.4", port=5060)))
176 117 Adrian Georgescu
</pre>
177 117 Adrian Georgescu
Note that in this example no observer for notifications from this @Registration@ object are registered, so the result of the operation cannot be seen.
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 1 Adrian Georgescu
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 1 Adrian Georgescu
185 117 Adrian Georgescu
h2. Components
186 1 Adrian Georgescu
187 1 Adrian Georgescu
188 1 Adrian Georgescu
189 117 Adrian Georgescu
h3. Engine
190 1 Adrian Georgescu
191 1 Adrian Georgescu
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 117 Adrian Georgescu
Once the @start()@ method is called, it instantiates the @core.PJSIPUA@ object and will proxy attribute and methods from it to the application.
194 1 Adrian Georgescu
195 1 Adrian Georgescu
196 117 Adrian Georgescu
h4. attributes
197 1 Adrian Georgescu
198 1 Adrian Georgescu
199 1 Adrian Georgescu
200 117 Adrian Georgescu
*default_start_options* (class attribute)
201 117 Adrian Georgescu
>This dictionary is a class attribute that describes the default values for the initialization options passed as keyword arguments to the @start()@ method.
202 117 Adrian Georgescu
>Consult this method for documentation of the contents.
203 1 Adrian Georgescu
204 117 Adrian Georgescu
*is_running*
205 117 Adrian Georgescu
>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 1 Adrian Georgescu
208 117 Adrian Georgescu
h4. methods
209 1 Adrian Georgescu
210 1 Adrian Georgescu
211 1 Adrian Georgescu
212 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_)
213 117 Adrian Georgescu
>This will either create the @Engine@ if it is called for the first time or return the one @Engine@ instance if it is called subsequently.
214 1 Adrian Georgescu
215 117 Adrian Georgescu
*start*(_self_, ***kwargs*)
216 117 Adrian Georgescu
>Initialize all PJSIP libraries based on the keyword parameters provided and start the PJSIP worker thread.
217 117 Adrian Georgescu
>If this fails an appropriate exception is raised.
218 117 Adrian Georgescu
>After the @Engine@ has been started successfully, it can never be started again after being stopped.
219 117 Adrian Georgescu
>The keyword arguments will be discussed here.
220 117 Adrian Georgescu
>Many of these values are also readable as (proxied) attributes on the Engine once the @start()@ method has been called.
221 117 Adrian Georgescu
>Many of them can also be set at runtime, either by modifying the attribute or by calling a particular method.
222 117 Adrian Georgescu
>This will also be documented for each argument in the following list of options.
223 117 Adrian Georgescu
  
224 117 Adrian Georgescu
>+_udp_port_+: (Default: @0@)
225 1 Adrian Georgescu
226 117 Adrian Georgescu
>The local UDP port to listen on for UDP datagrams.
227 117 Adrian Georgescu
>If this is 0, a random port will be chosen.
228 117 Adrian Georgescu
>If it is @None@, the UDP transport is disabled, both for incoming and outgoing traffic.
229 117 Adrian Georgescu
>As an attribute, this value is read-only, but it can be changed at runtime using the @set_udp_port()@ method.
230 117 Adrian Georgescu
  
231 117 Adrian Georgescu
>+_tcp_port_+: (Default: @0@)
232 1 Adrian Georgescu
233 117 Adrian Georgescu
>The local TCP port to listen on for new TCP connections.
234 117 Adrian Georgescu
>If this is 0, a random port will be chosen.
235 117 Adrian Georgescu
>If it is @None@, the TCP transport is disabled, both for incoming and outgoing traffic.
236 117 Adrian Georgescu
>As an attribute, this value is read-only, but it can be changed at runtime using the @set_tcp_port()@ method.
237 117 Adrian Georgescu
  
238 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
>If this is 0, a random port will be chosen.
242 117 Adrian Georgescu
>If it is @None@, the TLS transport is disabled, both for incoming and outgoing traffic.
243 117 Adrian Georgescu
>As an attribute, this value is read-only, but it can be changed at runtime using the @set_tls_options()@ method, as internally the TLS transport needs to be restarted for this operation.
244 117 Adrian Georgescu
  
245 117 Adrian Georgescu
>+_tls_protocol_+: (Default: "TLSv1")
246 117 Adrian Georgescu
 
247 117 Adrian Georgescu
>This string describes the (minimum) TLS protocol that should be used. 
248 117 Adrian Georgescu
>Its values should be either @None@, "SSLv2", "SSLv23", "SSLv3" or "TLSv1". 
249 117 Adrian Georgescu
>If @None@ is specified, the PJSIP default will be used, which is currently "TLSv1". 
250 117 Adrian Georgescu
  
251 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
>As an attribute, this value is read-only, but it can be changed at runtime using the @set_tls_options()@ method, as internally the TLS transport needs to be restarted for this operation.
255 117 Adrian Georgescu
  
256 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
>If this is set to @None@, no CA certificates will be read. 
260 117 Adrian Georgescu
>As an attribute, this value is read-only, but it can be changed at runtime using the @set_tls_options()@ method, as internally the TLS transport needs to be restarted for this operation. 
261 117 Adrian Georgescu
  
262 117 Adrian Georgescu
>+_tls_cert_file_+: (Default: @None@)
263 117 Adrian Georgescu
 
264 117 Adrian Georgescu
>This string indicates the location of a file containing the TLS certificate to be used for TLS connections. 
265 117 Adrian Georgescu
>If this is set to @None@, no certificate file will be read. 
266 117 Adrian Georgescu
>As an attribute, this value is read-only, but it can be changed at runtime using the @set_tls_options()@ method, as internally the TLS transport needs to be restarted for this operation. 
267 117 Adrian Georgescu
  
268 117 Adrian Georgescu
>+_tls_privkey_file_+: (Default: @None@)
269 117 Adrian Georgescu
 
270 117 Adrian Georgescu
>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 117 Adrian Georgescu
>If this is set to @None@, no private key file will be read. 
272 117 Adrian Georgescu
>As an attribute, this value is read-only, but it can be changed at runtime using the @set_tls_options()@ method, as internally the TLS transport needs to be restarted for this operation. 
273 117 Adrian Georgescu
  
274 117 Adrian Georgescu
>+_tls_timeout_+: (Default: 1000)
275 117 Adrian Georgescu
 
276 117 Adrian Georgescu
>The timeout value for a TLS negotiation in milliseconds. 
277 117 Adrian Georgescu
>Note that this value should be reasonably small, as a TLS negotiation blocks the whole PJSIP polling thread. 
278 117 Adrian Georgescu
>As an attribute, this value is read-only, but it can be changed at runtime using the @set_tls_options()@ method, as internally the TLS transport needs to be restarted for this operation.
279 117 Adrian Georgescu
  
280 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
>It can be read and set directly as an attribute at runtime.
284 117 Adrian Georgescu
  
285 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
>By default the maximum amount of logging information is reported.
289 117 Adrian Georgescu
>This value can be read and set directly as an attribute at runtime.
290 117 Adrian Georgescu
  
291 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
>It can be read and set directly as an attribute at runtime.
295 117 Adrian Georgescu
  
296 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
>It can be read and set directly as an attribute at runtime, but the ports of previously created @RTPTransport@ objects remain unaffected.
300 117 Adrian Georgescu
  
301 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
>It can be read and set directly as an attribute at runtime.
305 117 Adrian Georgescu
>Note that this global option can be overridden by an argument passed to @AudioTransport.__init__()@.
306 117 Adrian Georgescu
>The strings in this list is case insensitive.
307 117 Adrian Georgescu
  
308 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
>This dictionary provides some default packages and their event types.
312 117 Adrian Georgescu
>As an attribute, this value is read-only, but it can be changed at runtime using the @add_event()@ method.
313 117 Adrian Georgescu
  
314 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
>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 117 Adrian Georgescu
>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 117 Adrian Georgescu
>Note that each of the events specified here should also be a key in the @events@ dictionary argument.
320 117 Adrian Georgescu
>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 117 Adrian Georgescu
  
322 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
>Note that receiving requests using the @INVITE@, @SUBSCRIBE@, @ACK@ or @BYE@ methods in this way is not allowed.
326 117 Adrian Georgescu
>Requests using the @OPTIONS@ or @MESSAGE@ method are handled internally, but may be overridden.
327 117 Adrian Georgescu
328 117 Adrian Georgescu
*stop*(_self_)
329 117 Adrian Georgescu
>Stop the PJSIP worker thread and unload all PJSIP libraries.
330 117 Adrian Georgescu
>Note that after this all references to SIP core objects can no longer be used, these should be properly removed by the application itself before stopping the @Engine@.
331 117 Adrian Georgescu
>Also note that, once stopped the @Engine@ cannot be started again.
332 117 Adrian Georgescu
>This method is automatically called when the Python interpreter exits.
333 117 Adrian Georgescu
334 117 Adrian Georgescu
335 117 Adrian Georgescu
h4. proxied attributes
336 117 Adrian Georgescu
337 117 Adrian Georgescu
338 117 Adrian Georgescu
Besides all the proxied attributes described for the @__init__@ method above, thse other attributes are provided once the @Engine@ has been started.
339 117 Adrian Georgescu
340 117 Adrian Georgescu
341 117 Adrian Georgescu
*input_devices*
342 117 Adrian Georgescu
>This read-only attribute is a list of strings, representing all audio input devices on the system that can be used.
343 117 Adrian Georgescu
>One of these device names can be passed as the @input_device@ argument when creating a @AudioMixer@ object.
344 117 Adrian Georgescu
345 117 Adrian Georgescu
*output_devices*
346 117 Adrian Georgescu
>This read-only attribute is a list of strings, representing all audio output devices on the system that can be used.
347 117 Adrian Georgescu
>One of these device names can be passed as the @output_device@ argument when creating a @AudioMixer@ object.
348 117 Adrian Georgescu
349 117 Adrian Georgescu
*sound_devices*
350 117 Adrian Georgescu
>This read-only attribute is a list of strings, representing all audio sound devices on the system that can be used.
351 117 Adrian Georgescu
352 117 Adrian Georgescu
*available_codecs*
353 117 Adrian Georgescu
>A read-only list of codecs available in the core, regardless of the codecs configured through the @codecs@ attribute.
354 117 Adrian Georgescu
355 117 Adrian Georgescu
356 117 Adrian Georgescu
h4. proxied methods
357 117 Adrian Georgescu
358 117 Adrian Georgescu
359 117 Adrian Georgescu
360 117 Adrian Georgescu
*add_event*(_self_, *event*, *accept_types*)
361 117 Adrian Georgescu
>Couple a certain event package to a list of content types.
362 117 Adrian Georgescu
>Once added it cannot be removed or modified.
363 117 Adrian Georgescu
364 117 Adrian Georgescu
*add_incoming_event*(_self_, *event*)
365 117 Adrian Georgescu
>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 117 Adrian Georgescu
>Note that this event should be known to the @Engine@ by means of the @events@ attribute.
367 117 Adrian Georgescu
368 117 Adrian Georgescu
*remove_incoming_event*(_self_, *event*)
369 117 Adrian Georgescu
>Removes an event from the @incoming_events@ attribute.
370 117 Adrian Georgescu
>Incoming @SUBSCRIBE@ requests with this event package will automatically be replied to with a 489 "Bad Event" response.
371 117 Adrian Georgescu
372 117 Adrian Georgescu
*add_incoming_request*(_self_, *method*)
373 117 Adrian Georgescu
>Add a method to the set of methods for which incoming requests should be turned into @IncomingRequest@ objects.
374 117 Adrian Georgescu
>For the rules on which methods are allowed, see the description of the Engine attribute above.
375 117 Adrian Georgescu
376 117 Adrian Georgescu
*remove_incoming_request*(_self_, *method*)
377 117 Adrian Georgescu
>Removes a method from the set of methods that should be received.
378 117 Adrian Georgescu
379 117 Adrian Georgescu
*detect_nat_type*(_self_, *stun_server_address*, *stun_server_port*=3478, *user_data*=None)
380 117 Adrian Georgescu
>Will start a series of STUN requests which detect the type of NAT this host is behind.
381 117 Adrian Georgescu
>The @stun_server_address@ parameter indicates the IP address or hostname of the STUN server to be used and @stun_server_port@ specifies the remote UDP port to use.
382 117 Adrian Georgescu
>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 117 Adrian Georgescu
384 117 Adrian Georgescu
*set_udp_port*(_self_, *value*)
385 117 Adrian Georgescu
>Update the @local_udp_port@ attribute to the newly specified value.
386 117 Adrian Georgescu
387 117 Adrian Georgescu
*set_tcp_port*(_self_, *value*)
388 117 Adrian Georgescu
>Update the @local_tcp_port@ attribute to the newly specified value.
389 117 Adrian Georgescu
390 117 Adrian Georgescu
*set_tls_options*(_self_, *local_port*=@None@, *protocol*="TLSv1", *verify_server*=@False@, *ca_file*=@None@, *cert_file*=@None@, *privkey_file*=@None@, *timeout*=1000) 
391 117 Adrian Georgescu
>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 117 Adrian Georgescu
>The semantics of the arguments are the same as on the @start()@ method. 
393 117 Adrian Georgescu
394 117 Adrian Georgescu
395 117 Adrian Georgescu
h4. notifications
396 117 Adrian Georgescu
397 117 Adrian Georgescu
398 117 Adrian Georgescu
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 1 Adrian Georgescu
401 1 Adrian Georgescu
402 117 Adrian Georgescu
*SIPEngineWillStart*
403 117 Adrian Georgescu
>This notification is sent when the @Engine@ is about to start.
404 117 Adrian Georgescu
  
405 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
>This notification is sent when the @Engine@ is has just been started.
411 117 Adrian Georgescu
  
412 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
>This notification is sent whenever the @Engine@ has failed fatally and either cannot start or is about to stop.
418 117 Adrian Georgescu
>It is not recommended to call any methods on the @Engine@ at this point.
419 117 Adrian Georgescu
  
420 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
>This notification is sent when the @Engine@ is about to stop because the application called the @stop()@ method.
426 117 Adrian Georgescu
>Methods on the @Engine@ can be called at this point, but anything that has a delayed result will probably not return any notification.
427 117 Adrian Georgescu
  
428 117 Adrian Georgescu
>+_timestamp_+:
429 1 Adrian Georgescu
430 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
431 117 Adrian Georgescu
432 117 Adrian Georgescu
*SIPEngineDidEnd*
433 117 Adrian Georgescu
>This notification is sent when the @Engine@ was running and is now stopped, either because of failure or because the application requested it.
434 117 Adrian Georgescu
  
435 117 Adrian Georgescu
>+_timestamp_+:
436 117 Adrian Georgescu
437 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
438 117 Adrian Georgescu
439 117 Adrian Georgescu
*SIPEngineLog*
440 117 Adrian Georgescu
>This notification is a wrapper for PJSIP logging messages.
441 117 Adrian Georgescu
>It can be used by the application to output PJSIP logging to somewhere meaningful, possibly doing filtering based on log level.
442 117 Adrian Georgescu
  
443 117 Adrian Georgescu
>+_timestamp_+:
444 117 Adrian Georgescu
445 117 Adrian Georgescu
>A @datetime.datetime@ object representing the time when the log message was output by PJSIP.
446 117 Adrian Georgescu
  
447 117 Adrian Georgescu
>+_sender_+:
448 117 Adrian Georgescu
449 117 Adrian Georgescu
>The PJSIP module that originated this log message.
450 117 Adrian Georgescu
  
451 117 Adrian Georgescu
>+_level_+:
452 117 Adrian Georgescu
453 117 Adrian Georgescu
>The logging level of the message as an integer.
454 117 Adrian Georgescu
>Currently this is 1 through 5, 1 being the most critical.
455 117 Adrian Georgescu
  
456 117 Adrian Georgescu
>+_message_+:
457 117 Adrian Georgescu
458 117 Adrian Georgescu
>The actual log message.
459 117 Adrian Georgescu
460 117 Adrian Georgescu
*SIPEngineSIPTrace*
461 117 Adrian Georgescu
>Will be sent only when the @do_siptrace@ attribute of the @Engine@ instance is set to @True@.
462 117 Adrian Georgescu
>The notification data attributes will contain the SIP messages as they are sent and received on the wire.
463 117 Adrian Georgescu
  
464 117 Adrian Georgescu
>+_timestamp_+:
465 117 Adrian Georgescu
466 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
467 117 Adrian Georgescu
  
468 117 Adrian Georgescu
>+_received_+:
469 117 Adrian Georgescu
470 117 Adrian Georgescu
>A boolean indicating if this message was sent from or received by PJSIP (i.e. the direction of the message).
471 117 Adrian Georgescu
  
472 117 Adrian Georgescu
>+_source_ip_+:
473 117 Adrian Georgescu
474 117 Adrian Georgescu
>The source IP address as a string.
475 117 Adrian Georgescu
  
476 117 Adrian Georgescu
>+_source_port_+:
477 117 Adrian Georgescu
478 117 Adrian Georgescu
>The source port of the message as an integer.
479 117 Adrian Georgescu
  
480 117 Adrian Georgescu
>+_destination_ip_+:
481 117 Adrian Georgescu
482 117 Adrian Georgescu
>The destination IP address as a string.
483 117 Adrian Georgescu
  
484 117 Adrian Georgescu
>+_source_port_+:
485 117 Adrian Georgescu
486 117 Adrian Georgescu
>The source port of the message as an integer.
487 117 Adrian Georgescu
  
488 117 Adrian Georgescu
>+_data_+:
489 117 Adrian Georgescu
490 117 Adrian Georgescu
>The contents of the message as a string.
491 117 Adrian Georgescu
492 1 Adrian Georgescu
> For received message the destination_ip and for sent messages the source_ip may not be reliable.
493 1 Adrian Georgescu
494 1 Adrian Georgescu
495 117 Adrian Georgescu
*SIPEngineDetectedNATType*
496 117 Adrian Georgescu
>This notification is sent some time after the application request the NAT type this host behind to be detected using a STUN server.
497 117 Adrian Georgescu
>Note that there is no way to associate a request to do this with a notification, although every call to the @detect_nat_type()@ method will generate exactly one notification.
498 117 Adrian Georgescu
  
499 117 Adrian Georgescu
>+_timestamp_+:
500 1 Adrian Georgescu
501 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
502 117 Adrian Georgescu
  
503 117 Adrian Georgescu
>+_succeeded_+:
504 1 Adrian Georgescu
505 117 Adrian Georgescu
>A boolean indicating if the NAT detection succeeded.
506 117 Adrian Georgescu
  
507 117 Adrian Georgescu
>+_user_data_+:
508 1 Adrian Georgescu
509 117 Adrian Georgescu
>The @user_data@ argument passed while calling the @detect_nat_type()@ method.
510 117 Adrian Georgescu
>This can be any object and could be used for matching requests to responses.
511 117 Adrian Georgescu
  
512 117 Adrian Georgescu
>+_nat_type_+:
513 1 Adrian Georgescu
514 117 Adrian Georgescu
>A string describing the type of NAT found.
515 117 Adrian Georgescu
>This value is only present if NAT detection succeeded.
516 117 Adrian Georgescu
  
517 117 Adrian Georgescu
>+_error_+:
518 117 Adrian Georgescu
519 117 Adrian Georgescu
>A string indicating the error that occurred while attempting to detect the type of NAT.
520 117 Adrian Georgescu
>This value only present if NAT detection did not succeed.
521 117 Adrian Georgescu
522 117 Adrian Georgescu
*SIPEngineGotException*
523 117 Adrian Georgescu
>This notification is sent whenever there is an unexpected exception within the PJSIP working thread.
524 117 Adrian Georgescu
>The application should show the traceback to the user somehow.
525 117 Adrian Georgescu
>An exception need not be fatal, but if it is it will be followed by a *SIPEngineDidFail* notification.
526 117 Adrian Georgescu
  
527 117 Adrian Georgescu
>+_timestamp_+:
528 117 Adrian Georgescu
529 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
530 117 Adrian Georgescu
  
531 117 Adrian Georgescu
>+_traceback_+:
532 117 Adrian Georgescu
533 117 Adrian Georgescu
>A string containing the traceback of the exception.
534 117 Adrian Georgescu
>In general this should be printed on the console.
535 117 Adrian Georgescu
536 117 Adrian Georgescu
*SIPEngineGotMessage*
537 117 Adrian Georgescu
>This notification is sent whenever the Engine receives a @MESSAGE@ request.
538 117 Adrian Georgescu
  
539 117 Adrian Georgescu
>+_request_uri_+:
540 117 Adrian Georgescu
541 117 Adrian Georgescu
>The request URI of the @MESSAGE@ request as a @SIPURI@ object.
542 117 Adrian Georgescu
  
543 117 Adrian Georgescu
>+_from_header_+:
544 117 Adrian Georgescu
545 117 Adrian Georgescu
>The From header of the @MESSAGE@ request as a @FrozenFromHeader@ object.
546 117 Adrian Georgescu
  
547 117 Adrian Georgescu
>+_to_header_+:
548 117 Adrian Georgescu
549 117 Adrian Georgescu
>The To header of the @MESSAGE@ request as a @FrozenToHeader@ object.
550 117 Adrian Georgescu
  
551 117 Adrian Georgescu
>+_content_type_+:
552 117 Adrian Georgescu
553 117 Adrian Georgescu
>The Content-Type header value of the @MESSAGE@ request as a @ContentType@ object.
554 117 Adrian Georgescu
  
555 117 Adrian Georgescu
>+_headers_+:
556 117 Adrian Georgescu
557 117 Adrian Georgescu
>The headers of the @MESSAGE@ request as a dict.
558 117 Adrian Georgescu
>Each SIP header is represented in its parsed for as long as PJSIP supports it.
559 117 Adrian Georgescu
>The format of the parsed value depends on the header.
560 117 Adrian Georgescu
  
561 117 Adrian Georgescu
>+_body_+:
562 117 Adrian Georgescu
563 117 Adrian Georgescu
>The body of the @MESSAGE@ request as a string, or @None@ if no body was included.
564 117 Adrian Georgescu
  
565 117 Adrian Georgescu
>+_timestamp_+:
566 117 Adrian Georgescu
567 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
568 117 Adrian Georgescu
569 117 Adrian Georgescu
570 117 Adrian Georgescu
h3. SIPURI
571 117 Adrian Georgescu
572 117 Adrian Georgescu
573 1 Adrian Georgescu
These are helper objects for representing a SIP URI.
574 1 Adrian Georgescu
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 117 Adrian Georgescu
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 1 Adrian Georgescu
579 117 Adrian Georgescu
h4. methods
580 1 Adrian Georgescu
581 1 Adrian Georgescu
582 1 Adrian Georgescu
583 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_, *host*, *user*=@None@, *port*=@None@, *display*=@None@, *secure*=@False@, *parameters*=@None@, *headers*=@None@)
584 117 Adrian Georgescu
>Creates the SIPURI object with the specified parameters as attributes.
585 117 Adrian Georgescu
  @host@ is the only mandatory attribute.
586 117 Adrian Georgescu
  
587 117 Adrian Georgescu
>+_host_+:
588 1 Adrian Georgescu
589 117 Adrian Georgescu
>The host part of the SIP URI as a string.
590 117 Adrian Georgescu
  
591 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
  
595 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
  
599 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
  
603 117 Adrian Georgescu
>+_secure_+:
604 117 Adrian Georgescu
605 117 Adrian Georgescu
>A boolean indicating whether this is a SIP or SIPS URI, the latter being indicated by a value of @True@.
606 117 Adrian Georgescu
  
607 117 Adrian Georgescu
>+_parameters_+:
608 117 Adrian Georgescu
609 117 Adrian Georgescu
>The URI parameters. represented by a dictionary.
610 117 Adrian Georgescu
  
611 117 Adrian Georgescu
>+_headers_+:
612 117 Adrian Georgescu
613 117 Adrian Georgescu
>The URI headers, represented by a dictionary.
614 117 Adrian Georgescu
615 117 Adrian Georgescu
*<notextile>__str__</notextile>*(_self_)
616 117 Adrian Georgescu
>The special Python method to represent this object as a string, the output is the properly formatted SIP URI.
617 117 Adrian Georgescu
618 117 Adrian Georgescu
*new*(_cls_, _sipuri_)
619 117 Adrian Georgescu
>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 117 Adrian Georgescu
621 117 Adrian Georgescu
*parse*(_cls_, _uri_str_)
622 117 Adrian Georgescu
>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 117 Adrian Georgescu
624 117 Adrian Georgescu
*matches*(_self_, _address_)
625 117 Adrian Georgescu
>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 117 Adrian Georgescu
627 117 Adrian Georgescu
628 117 Adrian Georgescu
h3. Credentials
629 117 Adrian Georgescu
630 117 Adrian Georgescu
631 117 Adrian Georgescu
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 1 Adrian Georgescu
636 1 Adrian Georgescu
637 117 Adrian Georgescu
h4. methods
638 1 Adrian Georgescu
639 1 Adrian Georgescu
640 1 Adrian Georgescu
641 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_, *username*, *password*)
642 117 Adrian Georgescu
>Creates the Credentials object with the specified parameters as attributes.
643 117 Adrian Georgescu
>Each of these attributes can be accessed and changed on the object once instanced.
644 117 Adrian Georgescu
  
645 117 Adrian Georgescu
>+_username_+:
646 1 Adrian Georgescu
647 117 Adrian Georgescu
>A string representing the username of the account for which these are the credentials.
648 117 Adrian Georgescu
  
649 117 Adrian Georgescu
>+_password_+:
650 1 Adrian Georgescu
651 117 Adrian Georgescu
>The password for this SIP account as a string.
652 117 Adrian Georgescu
653 117 Adrian Georgescu
*new*(_cls_, _credentials_)
654 117 Adrian Georgescu
>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 117 Adrian Georgescu
656 117 Adrian Georgescu
657 117 Adrian Georgescu
h3. Invitation
658 117 Adrian Georgescu
659 117 Adrian Georgescu
660 117 Adrian Georgescu
The @Invitation@ class represents an @INVITE@ session, which governs a complete session of media exchange between two SIP endpoints from start to finish.
661 117 Adrian Georgescu
It is implemented to be agnostic to the media stream or streams negotiated, which is achieved by using the @SDPSession@ class and its companion classes, which directly represents the parsed SDP.
662 117 Adrian Georgescu
The @Invitation@ class represents both incoming and outgoing sessions.
663 117 Adrian Georgescu
664 117 Adrian Georgescu
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 117 Adrian Georgescu
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 1 Adrian Georgescu
State changes are triggered either by incoming or by outgoing SIP requests and responses.
668 1 Adrian Georgescu
The states and the transitions between them are shown in the following diagram:
669 1 Adrian Georgescu
670 117 Adrian Georgescu
!{ nolink}sipsimple-core-invite-state-machine.png!
671 1 Adrian Georgescu
672 1 Adrian Georgescu
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 117 Adrian Georgescu
# The application requested an outgoing session by calling the @send_invite()@ method and and initial @INVITE@ request is sent.
675 117 Adrian Georgescu
# 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 117 Adrian Georgescu
# A provisional response (1xx) is sent to the remote party, after the application called the @respond_to_invite_provisionally()@ method.
679 117 Adrian Georgescu
# A positive final response (2xx) is received from the remote party.
680 117 Adrian Georgescu
# A positive final response (2xx) is sent to the remote party, after the application called the @accept_invite()@ method.
681 117 Adrian Georgescu
# A positive final response (2xx) is sent or received, depending on the orientation of the session.
682 117 Adrian Georgescu
# An @ACK@ is sent or received, depending on the orientation of the session.
683 117 Adrian Georgescu
    If the @ACK@ is sent from the local to the remote party, it is initiated by PJSIP, not by a call from the application.
684 117 Adrian Georgescu
# The local party sent a re-@INVITE@ to the remote party by calling the @send_reinvite()@ method.
685 117 Adrian Georgescu
# The remote party has sent a final response to the re-@INVITE@.
686 117 Adrian Georgescu
# The remote party has sent a re-@INVITE@.
687 117 Adrian Georgescu
# The local party has responded to the re-@INVITE@ by calling the @respond_to_reinvite()@ method.
688 117 Adrian Georgescu
# The application requests that the session ends by calling the @end()@ method.
689 117 Adrian Georgescu
# A response is received from the remote party to whichever message was sent by the local party to end the session.
690 117 Adrian Georgescu
# 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 1 Adrian Georgescu
The application should compare the previous and current states and perform the appropriate action.
695 1 Adrian Georgescu
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 117 Adrian Georgescu
This will occur (at least) once during the initial session negotiation steps, during re-@INVITE@s in both directions and whenever an @UPDATE@ request is received.
698 117 Adrian Georgescu
In the last case, the @Invitation@ object will automatically include the current local SDP in the response.
699 1 Adrian Georgescu
700 1 Adrian Georgescu
701 117 Adrian Georgescu
h4. attributes
702 1 Adrian Georgescu
703 1 Adrian Georgescu
704 1 Adrian Georgescu
705 117 Adrian Georgescu
*state*
706 117 Adrian Georgescu
>The state the @Invitation@ state machine is currently in.
707 117 Adrian Georgescu
>See the diagram above for possible states.
708 117 Adrian Georgescu
>This attribute is read-only.
709 1 Adrian Georgescu
710 117 Adrian Georgescu
*sub_state*
711 117 Adrian Georgescu
>The sub-state the @Invitation@ state machine is currently in.
712 117 Adrian Georgescu
>See the diagram above for possible states.
713 117 Adrian Georgescu
>This attribute is read-only.
714 1 Adrian Georgescu
715 117 Adrian Georgescu
*directing*
716 117 Adrian Georgescu
>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 117 Adrian Georgescu
>The SIP credentials needed to authenticate at the SIP proxy in the form of a @FrozenCredentials@ object.
720 117 Adrian Georgescu
>If this @Invitation@ object represents an incoming @INVITE@ session this attribute will be @None@.
721 117 Adrian Georgescu
>On an outgoing session this attribute will be @None@ if it was not specified when the object was created.
722 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
723 1 Adrian Georgescu
724 117 Adrian Georgescu
*from_header*
725 117 Adrian Georgescu
>The From header of the caller represented by a @FrozenFromHeader@ object.
726 117 Adrian Georgescu
>If this is an outgoing @INVITE@ session, this is the from_header from the @send_invite()@ method.
727 117 Adrian Georgescu
>Otherwise the URI is taken from the @From:@ header of the initial @INVITE@.
728 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
729 1 Adrian Georgescu
730 117 Adrian Georgescu
*to_header*
731 117 Adrian Georgescu
>The To header of the callee represented by a @FrozenToHeader@ object.
732 117 Adrian Georgescu
>If this is an outgoing @INVITE@ session, this is the to_header from the @send_invite()@ method.
733 117 Adrian Georgescu
>Otherwise the URI is taken from the @To:@ header of the initial @INVITE@.
734 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
735 1 Adrian Georgescu
736 117 Adrian Georgescu
*local_identity*
737 117 Adrian Georgescu
>The From or To header representing the local identity used in this session.
738 117 Adrian Georgescu
>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 117 Adrian Georgescu
>The From or To header representing the remote party in this session.
742 117 Adrian Georgescu
>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 117 Adrian Georgescu
>The outbound proxy that was requested to be used in the form of a @FrozenRouteHeader@ object, including the desired transport.
746 117 Adrian Georgescu
>If this @Invitation@ object represents an incoming @INVITE@ session this attribute will always be @None@.
747 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
748 1 Adrian Georgescu
749 117 Adrian Georgescu
*call_id*
750 117 Adrian Georgescu
>The call ID of the @INVITE@ session as a read-only string.
751 117 Adrian Georgescu
>In the @NULL@ and @DISCONNECTED@ states, this attribute is @None@.
752 1 Adrian Georgescu
753 117 Adrian Georgescu
*transport*
754 117 Adrian Georgescu
>A string indicating the transport used for the application.
755 117 Adrian Georgescu
>This can be "udp", "tcp" or "tls".
756 1 Adrian Georgescu
757 117 Adrian Georgescu
*local_contact_header*
758 117 Adrian Georgescu
>The Contact header that the local side provided to the remote side within this @INVITE@ session as a @FrozenContactHeader@ object.
759 117 Adrian Georgescu
>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 117 Adrian Georgescu
>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 117 Adrian Georgescu
>A string representing the Call-Id header value of this INVITE dialog.
766 1 Adrian Georgescu
767 117 Adrian Georgescu
*remote_user_agent*
768 117 Adrian Georgescu
>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 117 Adrian Georgescu
>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 117 Adrian Georgescu
>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 117 Adrian Georgescu
>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 117 Adrian Georgescu
>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 117 Adrian Georgescu
>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 1 Adrian Georgescu
786 117 Adrian Georgescu
h4. methods
787 1 Adrian Georgescu
788 1 Adrian Georgescu
789 1 Adrian Georgescu
790 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_)
791 117 Adrian Georgescu
>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 117 Adrian Georgescu
  
795 117 Adrian Georgescu
>+_request_uri_+:
796 1 Adrian Georgescu
797 117 Adrian Georgescu
>Request URI to be set inthe outgoing INVITE request.
798 117 Adrian Georgescu
  
799 117 Adrian Georgescu
>+_from_header_+:
800 1 Adrian Georgescu
801 117 Adrian Georgescu
>The identity of the local account in the form of a @FromHeader@ object.
802 117 Adrian Georgescu
  
803 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
  
807 117 Adrian Georgescu
>+_route_header_+:
808 1 Adrian Georgescu
809 117 Adrian Georgescu
>The outbound proxy to use in the form of a @RouteHeader@ object.
810 117 Adrian Georgescu
>This includes the desired transport to use.
811 117 Adrian Georgescu
  
812 117 Adrian Georgescu
>+_contact_header_+:
813 1 Adrian Georgescu
814 117 Adrian Georgescu
>The Contact header to include in the @INVITE@ request, a @ContactHeader@ object.
815 117 Adrian Georgescu
  
816 117 Adrian Georgescu
>+_sdp_+:
817 1 Adrian Georgescu
818 117 Adrian Georgescu
>The SDP to send as offer to the remote party.
819 117 Adrian Georgescu
  
820 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
  
824 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
  
828 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
>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 117 Adrian Georgescu
>Send a response to a INVITE request. 
835 117 Adrian Georgescu
  
836 117 Adrian Georgescu
>+_code_+:
837 1 Adrian Georgescu
838 117 Adrian Georgescu
>The code of the response to use as an int.
839 117 Adrian Georgescu
  
840 117 Adrian Georgescu
>+_reason_+:
841 1 Adrian Georgescu
842 117 Adrian Georgescu
>The reason of the response as a str.
843 117 Adrian Georgescu
  
844 117 Adrian Georgescu
>+_contact_header_+:
845 1 Adrian Georgescu
846 117 Adrian Georgescu
>The Contact header to include in the response, a @ContactHeader@ object.
847 117 Adrian Georgescu
  
848 117 Adrian Georgescu
>+_sdp_+:
849 1 Adrian Georgescu
850 117 Adrian Georgescu
>The SDP to send as offer/response to the remote party.
851 117 Adrian Georgescu
  
852 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
  
858 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
  
862 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
  
866 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
>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 117 Adrian Georgescu
>This moves the @INVITE@ state machine into the @DISCONNECTING@ state by sending the necessary SIP request.
875 117 Adrian Georgescu
>When a response from the remote party is received, the state machine will go into the @DISCONNECTED@ state.
876 117 Adrian Georgescu
>Depending on the current state, this could be a CANCEL or a BYE request.
877 117 Adrian Georgescu
  
878 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
  
882 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
>If this is set to @None@, the default PJSIP timeout will be used, which currently appears to be 3.5 seconds for an established session.
886 1 Adrian Georgescu
887 1 Adrian Georgescu
888 117 Adrian Georgescu
h4. notifications
889 1 Adrian Georgescu
890 1 Adrian Georgescu
891 1 Adrian Georgescu
892 117 Adrian Georgescu
*SIPInvitationChangedState*
893 117 Adrian Georgescu
>This notification is sent by an @Invitation@ object whenever its state machine changes state.
894 117 Adrian Georgescu
  
895 117 Adrian Georgescu
>+_timestamp_+:
896 1 Adrian Georgescu
897 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
898 117 Adrian Georgescu
  
899 117 Adrian Georgescu
>+_prev_state_+:
900 1 Adrian Georgescu
901 117 Adrian Georgescu
>The previous state of the INVITE state machine.
902 117 Adrian Georgescu
  
903 117 Adrian Georgescu
>+_prev_sub_state_+:
904 1 Adrian Georgescu
905 117 Adrian Georgescu
>THe previous sub-state of the INVITE state machine.
906 117 Adrian Georgescu
  
907 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
  
911 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
  
915 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
  
919 117 Adrian Georgescu
>+_request_uri_+: (only if the state change got triggered by an incoming SIP request)
920 117 Adrian Georgescu
921 117 Adrian Georgescu
>The request URI of the SIP request as a @SIPURI@ object.
922 117 Adrian Georgescu
  
923 117 Adrian Georgescu
>+_code_+: (only if the state change got triggered by an incoming SIP response or internal timeout or error)
924 117 Adrian Georgescu
925 117 Adrian Georgescu
>The code of the SIP response or error as an int.
926 117 Adrian Georgescu
  
927 117 Adrian Georgescu
>+_reason_+: (only if the state change got triggered by an incoming SIP response or internal timeout or error)
928 117 Adrian Georgescu
929 117 Adrian Georgescu
>The reason text of the SIP response or error as a string.
930 117 Adrian Georgescu
  
931 117 Adrian Georgescu
>+_headers_+: (only if the state change got triggered by an incoming SIP request or response)
932 117 Adrian Georgescu
933 117 Adrian Georgescu
>The headers of the SIP request or response as a dict.
934 117 Adrian Georgescu
>Each SIP header is represented in its parsed for as long as PJSIP supports it.
935 117 Adrian Georgescu
>The format of the parsed value depends on the header.
936 117 Adrian Georgescu
  
937 117 Adrian Georgescu
>+_body_+: (only if the state change got triggered by an incoming SIP request or response)
938 117 Adrian Georgescu
939 117 Adrian Georgescu
>The body of the SIP request or response as a string, or @None@ if no body was included.
940 117 Adrian Georgescu
>The content type of the body can be learned from the @Content-Type:@ header in the headers argument.
941 117 Adrian Georgescu
942 117 Adrian Georgescu
*SIPInvitationGotSDPUpdate*
943 117 Adrian Georgescu
>This notification is sent by an @Invitation@ object whenever SDP negotiation has been performed.
944 117 Adrian Georgescu
>It should be used by the application as an indication to start, change or stop any associated media streams.
945 117 Adrian Georgescu
  
946 117 Adrian Georgescu
>+_timestamp_+:
947 117 Adrian Georgescu
948 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
949 117 Adrian Georgescu
  
950 117 Adrian Georgescu
>+_succeeded_+:
951 117 Adrian Georgescu
952 117 Adrian Georgescu
>A boolean indicating if the SDP negotiation has succeeded.
953 117 Adrian Georgescu
  
954 117 Adrian Georgescu
>+_error_+: (only if SDP negotiation did not succeed)
955 117 Adrian Georgescu
956 117 Adrian Georgescu
>A string indicating why SDP negotiation failed.
957 117 Adrian Georgescu
  
958 117 Adrian Georgescu
>+_local_sdp_+: (only if SDP negotiation succeeded)
959 117 Adrian Georgescu
960 117 Adrian Georgescu
>A SDPSession object indicating the local SDP that was negotiated.
961 117 Adrian Georgescu
  
962 117 Adrian Georgescu
>+_remote_sdp_+: (only if SDP negotiation succeeded)
963 117 Adrian Georgescu
964 117 Adrian Georgescu
>A SDPSession object indicating the remote SDP that was negotiated.
965 117 Adrian Georgescu
966 117 Adrian Georgescu
967 117 Adrian Georgescu
968 117 Adrian Georgescu
h3. SDPSession
969 117 Adrian Georgescu
970 117 Adrian Georgescu
971 117 Adrian Georgescu
SDP stands for Session Description Protocol. Session Description Protocol (SDP) is a format for describing streaming media initialization parameters in an ASCII string. SDP is intended for describing multimedia communication sessions for the purposes of session announcement, session invitation, and other forms of multimedia session initiation. It is an IETF standard described by "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 117 Adrian Georgescu
973 117 Adrian Georgescu
@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 117 Adrian Georgescu
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 117 Adrian Georgescu
A @(Frozen)SDPSession@ object may contain @(Frozen)SDPMediaStream@, @(Frozen)SDPConnection@ and @(Frozen)SDPAttribute@ objects.
976 117 Adrian Georgescu
It supports comparison to other @(Frozen)SDPSession@ objects using the == and != expressions.
977 117 Adrian Georgescu
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 117 Adrian Georgescu
979 117 Adrian Georgescu
980 117 Adrian Georgescu
h4. methods
981 117 Adrian Georgescu
982 117 Adrian Georgescu
983 117 Adrian Georgescu
984 117 Adrian Georgescu
*<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 117 Adrian Georgescu
>Creates the SDPSession object with the specified parameters as attributes.
986 117 Adrian Georgescu
>Each of these attributes can be accessed and changed on the object once instanced.
987 117 Adrian Georgescu
  
988 117 Adrian Georgescu
>+_address_+:
989 117 Adrian Georgescu
990 117 Adrian Georgescu
>The address that is contained in the "o" (origin) line of the SDP as a string.
991 117 Adrian Georgescu
  
992 117 Adrian Georgescu
>+_id_+:
993 117 Adrian Georgescu
994 117 Adrian Georgescu
>The session identifier contained in the "o" (origin) line of the SDP as an int.
995 117 Adrian Georgescu
>If this is set to @None@ on init, a session identifier will be generated.
996 117 Adrian Georgescu
  
997 117 Adrian Georgescu
>+_version_+:
998 117 Adrian Georgescu
999 117 Adrian Georgescu
>The version identifier contained in the "o" (origin) line of the SDP as an int.
1000 117 Adrian Georgescu
>If this is set to @None@ on init, a version identifier will be generated.
1001 117 Adrian Georgescu
  
1002 117 Adrian Georgescu
>+_user_+:
1003 117 Adrian Georgescu
1004 117 Adrian Georgescu
>The user name contained in the "o" (origin) line of the SDP as a string.
1005 117 Adrian Georgescu
  
1006 117 Adrian Georgescu
>+_net_type_+:
1007 117 Adrian Georgescu
1008 117 Adrian Georgescu
>The network type contained in the "o" (origin) line of the SDP as a string.
1009 117 Adrian Georgescu
  
1010 117 Adrian Georgescu
>+_address_type_+:
1011 117 Adrian Georgescu
1012 117 Adrian Georgescu
>The address type contained in the "o" (origin) line of the SDP as a string.
1013 117 Adrian Georgescu
  
1014 117 Adrian Georgescu
>+_name_+:
1015 117 Adrian Georgescu
1016 117 Adrian Georgescu
>The contents of the "s" (session name) line of the SDP as a string.
1017 117 Adrian Georgescu
  
1018 117 Adrian Georgescu
>+_info_+:
1019 117 Adrian Georgescu
1020 117 Adrian Georgescu
>The contents of the session level "i" (information) line of the SDP as a string.
1021 117 Adrian Georgescu
>If this is @None@ or an empty string, the SDP has no "i" line.
1022 117 Adrian Georgescu
  
1023 117 Adrian Georgescu
>+_connection_+:
1024 117 Adrian Georgescu
1025 117 Adrian Georgescu
>The contents of the "c" (connection) line of the SDP as a @(Frozen)SDPConnection@ object.
1026 117 Adrian Georgescu
>If this is set to @None@, the SDP has no session level "c" line.
1027 117 Adrian Georgescu
  
1028 117 Adrian Georgescu
>+_start_time_+:
1029 117 Adrian Georgescu
1030 117 Adrian Georgescu
>The first value of the "t" (time) line of the SDP as an int.
1031 117 Adrian Georgescu
  
1032 117 Adrian Georgescu
>+_stop_time_+:
1033 117 Adrian Georgescu
1034 117 Adrian Georgescu
>The second value of the "t" (time) line of the SDP as an int.
1035 117 Adrian Georgescu
  
1036 117 Adrian Georgescu
>+_attributes_+:
1037 117 Adrian Georgescu
1038 117 Adrian Georgescu
>The session level "a" lines (attributes) in the SDP represented by a list of @(Frozen)SDPAttribute@ objects.
1039 117 Adrian Georgescu
  
1040 117 Adrian Georgescu
>+_media_+:
1041 117 Adrian Georgescu
1042 117 Adrian Georgescu
>The media sections of the SDP represented by a list of @(Frozen)SDPMediaStream@ objects.
1043 117 Adrian Georgescu
1044 117 Adrian Georgescu
*new*(_cls_, _sdp_session_)
1045 117 Adrian Georgescu
>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 117 Adrian Georgescu
1047 117 Adrian Georgescu
1048 117 Adrian Georgescu
h4. attributes
1049 117 Adrian Georgescu
1050 117 Adrian Georgescu
1051 117 Adrian Georgescu
1052 117 Adrian Georgescu
*has_ice_proposal*
1053 117 Adrian Georgescu
>This read-only attribute returns @True@ if the SDP contains any attributes which indicate the existence of an ice proposal and @False@ otherwise.
1054 117 Adrian Georgescu
1055 117 Adrian Georgescu
1056 117 Adrian Georgescu
h3. SDPMediaStream
1057 117 Adrian Georgescu
1058 117 Adrian Georgescu
1059 117 Adrian Georgescu
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 117 Adrian Georgescu
It is a simple wrapper for the PJSIP "pjmedia_sdp_media":http://www.pjsip.org/pjmedia/docs/html/structpjmedia+sdp+media.htm structure.
1061 117 Adrian Georgescu
One or more @(Frozen)SDPMediaStream@ objects are usually contained in a @(Frozen)SDPSession@ object.
1062 117 Adrian Georgescu
It supports comparison to other @(Frozen)SDPMedia@ objects using the == and != expressions.
1063 117 Adrian Georgescu
As all the attributes of this class are set by attributes of the @__init__@ method, they will be documented along with that method.
1064 117 Adrian Georgescu
1065 117 Adrian Georgescu
1066 117 Adrian Georgescu
h4. methods
1067 117 Adrian Georgescu
1068 117 Adrian Georgescu
1069 117 Adrian Georgescu
1070 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_, *media*, *port*, *transport*, *port_count*=1, *formats*=@None@, *info*=@None@, *connection*=@None@, *attributes*=@None@)
1071 117 Adrian Georgescu
>Creates the SDPMedia object with the specified parameters as attributes.
1072 117 Adrian Georgescu
>Each of these attributes can be accessed and changed on the object once instanced.
1073 117 Adrian Georgescu
  
1074 117 Adrian Georgescu
>+_media_+:
1075 117 Adrian Georgescu
1076 117 Adrian Georgescu
>The media type contained in the "m" (media) line as a string.
1077 117 Adrian Georgescu
  
1078 117 Adrian Georgescu
>+_port_+:
1079 117 Adrian Georgescu
1080 117 Adrian Georgescu
>The transport port contained in the "m" (media) line as an int.
1081 117 Adrian Georgescu
  
1082 117 Adrian Georgescu
>+_transport_+:
1083 117 Adrian Georgescu
1084 117 Adrian Georgescu
>The transport protocol in the "m" (media) line as a string.
1085 117 Adrian Georgescu
  
1086 117 Adrian Georgescu
>+_port_count_+:
1087 117 Adrian Georgescu
1088 117 Adrian Georgescu
>The port count in the "m" (media) line as an int.
1089 117 Adrian Georgescu
>If this is set to 1, it is not included in the SDP.
1090 117 Adrian Georgescu
  
1091 117 Adrian Georgescu
>+_formats_+:
1092 117 Adrian Georgescu
1093 117 Adrian Georgescu
>The media formats in the "m" (media) line represented by a list of strings.
1094 117 Adrian Georgescu
  
1095 117 Adrian Georgescu
>+_info_+:
1096 117 Adrian Georgescu
1097 117 Adrian Georgescu
>The contents of the "i" (information) line of this media section as a string.
1098 117 Adrian Georgescu
>If this is @None@ or an empty string, the media section has no "i" line.
1099 117 Adrian Georgescu
  
1100 117 Adrian Georgescu
>+_connection_+:
1101 117 Adrian Georgescu
1102 117 Adrian Georgescu
>The contents of the "c" (connection) line that is somewhere below the "m" line of this section as a @(Frozen)SDPConnection@ object.
1103 117 Adrian Georgescu
>If this is set to @None@, this media section has no "c" line.
1104 117 Adrian Georgescu
  
1105 117 Adrian Georgescu
>+_attributes_+:
1106 117 Adrian Georgescu
1107 117 Adrian Georgescu
>The "a" lines (attributes) that are somewhere below the "m" line of this section represented by a list of @(Frozen)SDPAttribute@ objects.
1108 117 Adrian Georgescu
1109 117 Adrian Georgescu
*new*(_cls_, _sdp_media_)
1110 117 Adrian Georgescu
>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 117 Adrian Georgescu
1112 117 Adrian Georgescu
1113 117 Adrian Georgescu
h4. attributes
1114 117 Adrian Georgescu
1115 117 Adrian Georgescu
1116 117 Adrian Georgescu
1117 117 Adrian Georgescu
*direction*
1118 117 Adrian Georgescu
>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 117 Adrian Georgescu
>If none of these attributes is present, the default direction is "sendrecv".
1120 117 Adrian Georgescu
1121 117 Adrian Georgescu
1122 117 Adrian Georgescu
h3. SDPConnection
1123 117 Adrian Georgescu
1124 117 Adrian Georgescu
1125 117 Adrian Georgescu
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 117 Adrian Georgescu
It is a simple wrapper for the PJSIP "pjmedia_sdp_conn":http://www.pjsip.org/pjmedia/docs/html/structpjmedia+sdp+conn.htm structure.
1127 117 Adrian Georgescu
A @(Frozen)SDPConnection@ object can be contained in a @(Frozen)SDPSession@ object or @(Frozen)SDPMediaStream@ object.
1128 117 Adrian Georgescu
It supports comparison to other @(Frozen)SDPConnection@ objects using the == and != expressions.
1129 117 Adrian Georgescu
As all the attributes of this class are set by attributes of the @__init__@ method, they will be documented along with that method.
1130 117 Adrian Georgescu
1131 117 Adrian Georgescu
1132 117 Adrian Georgescu
h4. methods
1133 117 Adrian Georgescu
1134 117 Adrian Georgescu
1135 117 Adrian Georgescu
1136 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_, *address*, *net_type*="IN", *address_type*="IP4")
1137 117 Adrian Georgescu
>Creates the SDPConnection object with the specified parameters as attributes.
1138 117 Adrian Georgescu
>Each of these attributes can be accessed and changed on the object once instanced.
1139 117 Adrian Georgescu
  
1140 117 Adrian Georgescu
>+_address_+:
1141 117 Adrian Georgescu
1142 117 Adrian Georgescu
>The address part of the connection line as a string.
1143 117 Adrian Georgescu
  
1144 117 Adrian Georgescu
>+_net_type_+:
1145 117 Adrian Georgescu
1146 117 Adrian Georgescu
>The network type part of the connection line as a string.
1147 117 Adrian Georgescu
  
1148 117 Adrian Georgescu
>+_address_type_+:
1149 117 Adrian Georgescu
1150 117 Adrian Georgescu
>The address type part of the connection line as a string.
1151 117 Adrian Georgescu
1152 117 Adrian Georgescu
*new*(_cls_, _sdp_connection_)
1153 117 Adrian Georgescu
>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 117 Adrian Georgescu
1155 117 Adrian Georgescu
1156 117 Adrian Georgescu
h3. SDPAttributeList
1157 117 Adrian Georgescu
1158 117 Adrian Georgescu
1159 117 Adrian Georgescu
@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 117 Adrian Georgescu
1161 117 Adrian Georgescu
1162 117 Adrian Georgescu
*<notextile>__contains__</notextile>*(_self_, _item_)
1163 117 Adrian Georgescu
>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 117 Adrian Georgescu
  <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 117 Adrian Georgescu
>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 117 Adrian Georgescu
>Return the first value of the attribute with the given name, or _default_ is no such attribute exists.
1173 1 Adrian Georgescu
1174 1 Adrian Georgescu
1175 117 Adrian Georgescu
h3. SDPAttribute
1176 1 Adrian Georgescu
1177 1 Adrian Georgescu
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 117 Adrian Georgescu
It is a simple wrapper for the PJSIP "pjmedia_sdp_attr":http://www.pjsip.org/pjmedia/docs/html/structpjmedia+sdp+attr.htm structure.
1180 117 Adrian Georgescu
One or more @(Frozen)SDPAttribute@ objects can be contained in a @(Frozen)SDPSession@ object or @(Frozen)SDPMediaStream@ object.
1181 117 Adrian Georgescu
It supports comparison to other @(Frozen)SDPAttribute@ objects using the == and != expressions.
1182 117 Adrian Georgescu
As all the attributes of this class are set by attributes of the @__init__@ method, they will be documented along with that method.
1183 1 Adrian Georgescu
1184 1 Adrian Georgescu
1185 117 Adrian Georgescu
h4. methods
1186 1 Adrian Georgescu
1187 1 Adrian Georgescu
1188 1 Adrian Georgescu
1189 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_, *name*, *value*)
1190 117 Adrian Georgescu
>Creates the SDPAttribute object with the specified parameters as attributes.
1191 117 Adrian Georgescu
>Each of these attributes can be accessed and changed on the object once instanced.
1192 117 Adrian Georgescu
  
1193 117 Adrian Georgescu
>+_name_+:
1194 117 Adrian Georgescu
1195 117 Adrian Georgescu
>The name part of the attribute line as a string.
1196 117 Adrian Georgescu
  
1197 117 Adrian Georgescu
>+_value_+:
1198 117 Adrian Georgescu
1199 117 Adrian Georgescu
>The value part of the attribute line as a string.
1200 117 Adrian Georgescu
1201 117 Adrian Georgescu
*new*(_cls_, _sdp_attribute_)
1202 117 Adrian Georgescu
>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 117 Adrian Georgescu
1204 117 Adrian Georgescu
1205 117 Adrian Georgescu
1206 117 Adrian Georgescu
h3. RTPTransport
1207 117 Adrian Georgescu
1208 117 Adrian Georgescu
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 117 Adrian Georgescu
Initially this object will only be used by the @AudioTransport@ object, but in the future it can also be used for video and [[RTTProposal|Real-Time Text]].
1212 117 Adrian Georgescu
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 1 Adrian Georgescu
1219 1 Adrian Georgescu
> 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 1 Adrian Georgescu
> For these it carries media streams controlled by Session Initiation Protocol (SIP) signaling protocols, making it the technical foundation of the Voice over IP industry.
1223 1 Adrian Georgescu
1224 117 Adrian Georgescu
!{ nolink}sipsimple-rtp-transport-state-machine.png!
1225 1 Adrian Georgescu
1226 1 Adrian Georgescu
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 117 Adrian Georgescu
# The application calls the @set_INIT()@ method after object creation and ICE+STUN is used.
1229 117 Adrian Georgescu
# A successful STUN response is received from the STUN server.
1230 117 Adrian Georgescu
# The @set_LOCAL()@ method is called.
1231 117 Adrian Georgescu
# The @set_ESTABLISHED()@ method is called.
1232 117 Adrian Georgescu
# The @set_INIT()@ method is called while the object is in the @LOCAL@ or @ESTABLISHED@ state.
1233 117 Adrian Georgescu
# 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 1 Adrian Georgescu
> It would make sense to be able to use the object even if the STUN request fails (and have ICE not include a STUN candidate), but for some reason the pjmedia_transport is unusable once STUN negotiation has failed.
1238 1 Adrian Georgescu
> This means that the RTPTransport object is also unusable once it has reached the STUN_FAILED state.
1239 1 Adrian Georgescu
> A workaround would be destroy the RTPTransport object and create a new one that uses ICE without STUN.
1240 1 Adrian Georgescu
1241 1 Adrian Georgescu
These states allow for two SDP negotiation scenarios to occur, represented by two paths that can be followed through the state machine.
1242 1 Adrian Georgescu
In this example we will assume that ICE with STUN is not used, as it is independent of the SDP negotiation procedure.
1243 117 Adrian Georgescu
* The first scenario is where the local party generates the SDP offer.
1244 117 Adrian Georgescu
   For a stream that it wishes to include in this SDP offer, it instantiates a @RTPTransport@ object.
1245 117 Adrian Georgescu
   After instantiation the object is initialized by calling the @set_INIT()@ method and the local RTP address and port can be fetched from it using the @local_rtp_address@ and @local_rtp_port@ attributes respectively, which can be used to generate the local SDP in the form of a @SDPSession@ object.
1246 117 Adrian Georgescu
   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 117 Adrian Georgescu
   Depending on the options used for the @RTPTransport@ instantiation (such as ICE and SRTP), this may change the @SDPSession@ object.
1248 117 Adrian Georgescu
   This (possibly changed) @SDPSession@ object then needs to be passed to the @Invitation@ object.
1249 117 Adrian Georgescu
   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 117 Adrian Georgescu
   This will not change either of the @(Frozen)SDPSession@ objects (which is why they can also be frozen).
1251 117 Adrian Georgescu
* The second scenario is where the local party is offered a media stream in SDP and wants to accept it.
1252 117 Adrian Georgescu
   In this case a @RTPTransport@ is also instantiated and initialized using the @set_INIT()@ method, and the application can generate the local SDP in response to the remote SDP, using the @local_rtp_address@ and @local_rtp_port@ attributes.
1253 117 Adrian Georgescu
   Directly after this it should pass the generated local SDP and received remote SDP, in the form of @SDPSession@ objects, to the @set_ESTABLISHED()@ method.
1254 117 Adrian Georgescu
   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 1 Adrian Georgescu
1259 1 Adrian Georgescu
1260 117 Adrian Georgescu
h4. methods
1261 1 Adrian Georgescu
1262 1 Adrian Georgescu
1263 1 Adrian Georgescu
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 117 Adrian Georgescu
>Creates a new @RTPTransport@ object and opens the RTP and RTCP UDP sockets.
1266 117 Adrian Georgescu
>If additional features are requested, they will be initialized.
1267 117 Adrian Georgescu
>After object instantiation, it is either in the @INIT@ or the @WAIT_STUN@ state, depending on the values of the @use_ice@ and @ice_stun_address@ arguments.
1268 117 Adrian Georgescu
  
1269 117 Adrian Georgescu
>+_local_rtp_address_+:
1270 1 Adrian Georgescu
1271 117 Adrian Georgescu
>Optionally contains the local IPv4 address to listen on.
1272 117 Adrian Georgescu
>If this is not specified, PJSIP will listen on all network interfaces.
1273 117 Adrian Georgescu
  
1274 117 Adrian Georgescu
>+_use_srtp_+:
1275 1 Adrian Georgescu
1276 117 Adrian Georgescu
>A boolean indicating if SRTP should be used.
1277 117 Adrian Georgescu
>If this is set to @True@, SRTP information will be added to the SDP when it passes this object.
1278 117 Adrian Georgescu
  
1279 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
>If this is set to @True@ and the remote party does not support SRTP, the SDP negotiation for this stream will fail.
1283 117 Adrian Georgescu
>This argument is relevant only if @use_srtp@ is set to @True@.
1284 117 Adrian Georgescu
  
1285 117 Adrian Georgescu
>+_use_ice_+:
1286 1 Adrian Georgescu
1287 117 Adrian Georgescu
>A boolean indicating if ICE should be used.
1288 117 Adrian Georgescu
>If this is set to @True@, ICE candidates will be added to the SDP when it passes this object.
1289 117 Adrian Georgescu
  
1290 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
>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 117 Adrian Georgescu
>When this happens a @RTPTransportGotSTUNResponse@ notification is sent.
1295 117 Adrian Georgescu
>This argument is relevant only if @use_ice@ is set to @True@.
1296 117 Adrian Georgescu
  
1297 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
>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 117 Adrian Georgescu
>This moves the internal state machine into the @INIT@ state.
1304 117 Adrian Georgescu
>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 117 Adrian Georgescu
>This moves the the internal state machine into the @LOCAL@ state.
1308 117 Adrian Georgescu
  
1309 117 Adrian Georgescu
>+_local_sdp_+:
1310 1 Adrian Georgescu
1311 117 Adrian Georgescu
>The local SDP to be proposed in the form of a @SDPSession@ object.
1312 117 Adrian Georgescu
>Note that this object may be modified by this method.
1313 117 Adrian Georgescu
  
1314 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
>This moves the the internal state machine into the @ESTABLISHED@ state.
1320 117 Adrian Georgescu
  
1321 117 Adrian Georgescu
>+_local_sdp_+:
1322 1 Adrian Georgescu
1323 117 Adrian Georgescu
>The local SDP to be proposed in the form of a @SDPSession@ object.
1324 117 Adrian Georgescu
>Note that this object may be modified by this method, but only when moving from the @LOCAL@ to the @ESTABLISHED@ state.
1325 117 Adrian Georgescu
  
1326 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
  
1330 117 Adrian Georgescu
>+_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 1 Adrian Georgescu
1335 117 Adrian Georgescu
h4. attributes
1336 1 Adrian Georgescu
1337 1 Adrian Georgescu
1338 1 Adrian Georgescu
1339 117 Adrian Georgescu
*state*
1340 117 Adrian Georgescu
>Indicates which state the internal state machine is in.
1341 117 Adrian Georgescu
>See the previous section for a list of states the state machine can be in.
1342 117 Adrian Georgescu
>This attribute is read-only.
1343 1 Adrian Georgescu
1344 117 Adrian Georgescu
*local_rtp_address*
1345 117 Adrian Georgescu
>The local IPv4 address of the interface the @RTPTransport@ object is listening on and the address that should be included in the SDP.
1346 117 Adrian Georgescu
>If no address was specified during object instantiation, PJSIP will take guess out of the IP addresses of all interfaces.
1347 117 Adrian Georgescu
>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 117 Adrian Georgescu
>The UDP port PJSIP is listening on for RTP traffic.
1351 117 Adrian Georgescu
>RTCP traffic will always be this port plus one.
1352 117 Adrian Georgescu
>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 117 Adrian Georgescu
>The remote IP address that was seen in the SDP.
1356 117 Adrian Georgescu
>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 117 Adrian Georgescu
>The remote UDP port for RTP that was seen in the SDP.
1360 117 Adrian Georgescu
>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 117 Adrian Georgescu
>The remote IP address that was selected by the ICE negotation.
1364 117 Adrian Georgescu
>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 117 Adrian Georgescu
>The remote port that was selected by the ICE negotation.
1368 117 Adrian Georgescu
>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 117 Adrian Georgescu
>The remote IP address from which RTP data was received.
1372 117 Adrian Georgescu
>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 117 Adrian Georgescu
>The remote UDP port from which RTP data was received.
1376 117 Adrian Georgescu
>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 117 Adrian Georgescu
>A boolean indicating if the use of SRTP was requested when the object was instantiated.
1380 117 Adrian Georgescu
>This attribute is read-only.
1381 1 Adrian Georgescu
1382 117 Adrian Georgescu
*force_srtp*
1383 117 Adrian Georgescu
>A boolean indicating if SRTP being mandatory for this transport if it is enabled was requested when the object was instantiated.
1384 117 Adrian Georgescu
>This attribute is read-only.
1385 1 Adrian Georgescu
1386 117 Adrian Georgescu
*srtp_active*
1387 117 Adrian Georgescu
>A boolean indicating if SRTP encryption and decryption is running.
1388 117 Adrian Georgescu
>Querying this attribute only makes sense once the object is in the @ESTABLISHED@ state and use of SRTP was requested.
1389 117 Adrian Georgescu
>This attribute is read-only.
1390 117 Adrian Georgescu
1391 117 Adrian Georgescu
*use_ice*
1392 117 Adrian Georgescu
>A boolean indicating if the use of ICE was requested when the object was instantiated.
1393 117 Adrian Georgescu
>This attribute is read-only.
1394 117 Adrian Georgescu
1395 117 Adrian Georgescu
*ice_active_
1396 117 Adrian Georgescu
>A boolean indicating if ICE is being used.
1397 117 Adrian Georgescu
>This attribute is read-only.
1398 117 Adrian Georgescu
1399 117 Adrian Georgescu
*ice_stun_address*
1400 117 Adrian Georgescu
>A string indicating the IP address of the STUN server that was requested to be used.
1401 117 Adrian Georgescu
>This attribute is read-only.
1402 117 Adrian Georgescu
1403 117 Adrian Georgescu
*ice_stun_port*
1404 117 Adrian Georgescu
>A string indicating the UDP port of the STUN server that was requested to be used.
1405 117 Adrian Georgescu
>This attribute is read-only.
1406 117 Adrian Georgescu
1407 117 Adrian Georgescu
*local_rtp_candidate_type*
1408 117 Adrian Georgescu
>Returns the ICE candidate type which has been selected for the local endpoint.
1409 117 Adrian Georgescu
1410 117 Adrian Georgescu
*remote_rtp_candidate_type*
1411 117 Adrian Georgescu
>Returns the ICE candidate type which has been selected for the remote endpoint.
1412 117 Adrian Georgescu
1413 117 Adrian Georgescu
1414 117 Adrian Georgescu
h4. notifications
1415 117 Adrian Georgescu
1416 117 Adrian Georgescu
1417 117 Adrian Georgescu
1418 117 Adrian Georgescu
*RTPTransportDidInitialize*
1419 117 Adrian Georgescu
>This notification is sent when a @RTPTransport@ object has successfully initialized.
1420 117 Adrian Georgescu
>If STUN+ICE is not requested, this is sent immediately on @set_INIT()@, otherwise it is sent after the STUN query has succeeded.
1421 117 Adrian Georgescu
  
1422 117 Adrian Georgescu
>+_timestamp_+:
1423 117 Adrian Georgescu
1424 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
1425 117 Adrian Georgescu
1426 117 Adrian Georgescu
*RTPTransportDidFail*
1427 117 Adrian Georgescu
>This notification is sent by a @RTPTransport@ object that fails to retrieve ICE candidates from the STUN server after @set_INIT()@ is called.
1428 117 Adrian Georgescu
  
1429 117 Adrian Georgescu
>+_timestamp_+:
1430 117 Adrian Georgescu
1431 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
1432 117 Adrian Georgescu
  
1433 117 Adrian Georgescu
>+_reason_+:
1434 117 Adrian Georgescu
1435 117 Adrian Georgescu
>A string describing the failure reason.
1436 117 Adrian Georgescu
1437 117 Adrian Georgescu
*RTPTransportICENegotiationStateDidChange*
1438 117 Adrian Georgescu
>This notification is sent to indicate the progress of the ICE negotiation.
1439 117 Adrian Georgescu
  
1440 117 Adrian Georgescu
>+_state_+:
1441 117 Adrian Georgescu
1442 117 Adrian Georgescu
>A string describing the current ICE negotiation state.
1443 117 Adrian Georgescu
1444 117 Adrian Georgescu
*RTPTransportICENegotiationDidFail*
1445 117 Adrian Georgescu
>This notification is sent when the ICE negotiation fails.
1446 117 Adrian Georgescu
  
1447 117 Adrian Georgescu
>+_reason_+:
1448 117 Adrian Georgescu
1449 117 Adrian Georgescu
>A string describing the failure reason of ICE negotation.
1450 117 Adrian Georgescu
1451 117 Adrian Georgescu
*RTPTransportICENegotiationDidSucceed*
1452 117 Adrian Georgescu
>This notification is sent when the ICE negotation succeeds.
1453 117 Adrian Georgescu
  
1454 117 Adrian Georgescu
>+_chosen_local_candidates_ and _chosen_remote_candidates_+:
1455 117 Adrian Georgescu
1456 117 Adrian Georgescu
>Dictionaries with the following keys:
1457 117 Adrian Georgescu
*** rtp_cand_type: the type of the RTP candidate
1458 117 Adrian Georgescu
*** rtp_cand_ip: the IP address of the RTP candidate
1459 117 Adrian Georgescu
*** rtcp_cand_type: the type of the RTCP candidate
1460 117 Adrian Georgescu
*** rtcp_cand_ip: the IP address of teh RTCP candidate
1461 117 Adrian Georgescu
  
1462 117 Adrian Georgescu
>+_duration_+:
1463 117 Adrian Georgescu
1464 117 Adrian Georgescu
>The amount of time the ICE negotiation took.
1465 117 Adrian Georgescu
  
1466 117 Adrian Georgescu
>+_local_candidates_ and _remote_candidates_+:
1467 117 Adrian Georgescu
1468 117 Adrian Georgescu
>Lists of tuples with the following elements:
1469 117 Adrian Georgescu
*** Item ID
1470 117 Adrian Georgescu
*** Component ID
1471 117 Adrian Georgescu
*** Address
1472 117 Adrian Georgescu
*** Component Type
1473 117 Adrian Georgescu
  
1474 117 Adrian Georgescu
>+_connectivity_checks_results_+:
1475 117 Adrian Georgescu
1476 117 Adrian Georgescu
>A list of tuples with the following elements:
1477 117 Adrian Georgescu
*** Item ID
1478 117 Adrian Georgescu
*** Component ID
1479 117 Adrian Georgescu
*** Source
1480 117 Adrian Georgescu
*** Destination
1481 117 Adrian Georgescu
*** Nomination
1482 117 Adrian Georgescu
*** State
1483 117 Adrian Georgescu
1484 117 Adrian Georgescu
1485 117 Adrian Georgescu
h3. AudioTransport
1486 117 Adrian Georgescu
1487 117 Adrian Georgescu
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 117 Adrian Georgescu
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 117 Adrian Georgescu
* In the first scenario, only the @RTPTransport@ instance to be used is passed to the AudioTransport object.
1496 117 Adrian Georgescu
   The application can then generate the @SDPMediaStream@ object by calling the @get_local_media()@ method and should include it in the SDP offer.
1497 117 Adrian Georgescu
   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 117 Adrian Georgescu
   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 1 Adrian Georgescu
1503 117 Adrian Georgescu
Unlike the @RTPTransport@ object, this object cannot be reused.
1504 1 Adrian Georgescu
1505 1 Adrian Georgescu
1506 117 Adrian Georgescu
h4. methods
1507 1 Adrian Georgescu
1508 1 Adrian Georgescu
1509 1 Adrian Georgescu
1510 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_, *mixer*, *transport*, *remote_sdp*=@None@, *sdp_index*=0, *enable_silence_detection*=True, *codecs*=@None@)
1511 117 Adrian Georgescu
>Creates a new @AudioTransport@ object and start the underlying stream if the remote SDP is already known.
1512 117 Adrian Georgescu
  
1513 117 Adrian Georgescu
>+_mixer_+:
1514 1 Adrian Georgescu
1515 117 Adrian Georgescu
>The @AudioMixer@ object that this object is to be connected to.
1516 117 Adrian Georgescu
  
1517 117 Adrian Georgescu
>+_transport_+:
1518 1 Adrian Georgescu
1519 117 Adrian Georgescu
>The transport to use in the form of a @RTPTransport@ object.
1520 117 Adrian Georgescu
  
1521 117 Adrian Georgescu
>+_remote_sdp_+:
1522 1 Adrian Georgescu
1523 117 Adrian Georgescu
>The remote SDP that was received in the form of a @SDPSession@ object.
1524 117 Adrian Georgescu
  
1525 117 Adrian Georgescu
>+_sdp_index_+:
1526 1 Adrian Georgescu
1527 117 Adrian Georgescu
>The index within the SDP of the audio stream that should be created.
1528 117 Adrian Georgescu
  
1529 117 Adrian Georgescu
_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 117 Adrian Georgescu
>When enabled, this @AudioTransport@ object will stop sending audio to the remote party if the input volume is below a certain threshold.
1533 117 Adrian Georgescu
  
1534 117 Adrian Georgescu
_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 117 Adrian Georgescu
>This overrides the global codecs list set on the @Engine@.
1538 117 Adrian Georgescu
>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 117 Adrian Georgescu
>Generates a @SDPMediaStream@ object which describes the audio stream.
1542 117 Adrian Georgescu
>This object should be included in a @SDPSession@ object that gets passed to the @Invitation@ object.
1543 117 Adrian Georgescu
>This method should also be used to obtain the SDP to include in re-INVITEs and replies to re-INVITEs.
1544 117 Adrian Georgescu
  
1545 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
>If this is @False@ it is to be included in an answer.
1549 117 Adrian Georgescu
  
1550 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
>This method should only be called once, when the application has previously sent an SDP offer and the answer has been received.
1556 117 Adrian Georgescu
  
1557 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
  
1561 117 Adrian Georgescu
>+_remote_sdp_+:
1562 1 Adrian Georgescu
1563 117 Adrian Georgescu
>The remote SDP that was received in the form of a @SDPSession@ object.
1564 117 Adrian Georgescu
  
1565 117 Adrian Georgescu
>+_sdp_index_+:
1566 1 Adrian Georgescu
1567 117 Adrian Georgescu
>The index within the SDP of the audio stream.
1568 117 Adrian Georgescu
  
1569 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
>Setting this to 0 disables this an all subsequent RTP checks.
1573 117 Adrian Georgescu
  
1574 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
>It means that if between two of these interval checks no RTP has been received, a @RTPAudioTransportDidNotGetRTP@ notification will be sent.
1578 117 Adrian Georgescu
>Setting this to 0 will disable checking the RTP at intervals.
1579 117 Adrian Georgescu
>The initial check may still be performed if its timeout is non-zero.
1580 84 Ruud Klaver
1581 117 Adrian Georgescu
*stop*(_self_)
1582 117 Adrian Georgescu
>This method stops and destroys the audio stream encapsulated by this object.
1583 117 Adrian Georgescu
>After this it can no longer be used and should be deleted, while the @RTPTransport@ object used by it can be re-used for something else.
1584 117 Adrian Georgescu
>This method will be called automatically when the object is deleted after it was started, but this should not be relied on because of possible reference counting issues.
1585 84 Ruud Klaver
1586 117 Adrian Georgescu
*send_dtmf*(_self_, *digit*)
1587 117 Adrian Georgescu
>For a negotiated audio transport this sends one DTMF digit to the other party
1588 117 Adrian Georgescu
  
1589 117 Adrian Georgescu
>+_digit_+:
1590 84 Ruud Klaver
1591 117 Adrian Georgescu
>A string of length one indicating the DTMF digit to send.
1592 117 Adrian Georgescu
>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 117 Adrian Georgescu
>This method should be called after SDP negotiation has completed to update the direction of the media stream.
1596 117 Adrian Georgescu
  
1597 117 Adrian Georgescu
>+_direction_+:
1598 1 Adrian Georgescu
1599 117 Adrian Georgescu
>The direction that has been negotiated.
1600 1 Adrian Georgescu
1601 117 Adrian Georgescu
1602 117 Adrian Georgescu
h4. attributes
1603 117 Adrian Georgescu
1604 117 Adrian Georgescu
1605 117 Adrian Georgescu
1606 117 Adrian Georgescu
*mixer*
1607 117 Adrian Georgescu
>The @AudioMixer@ object that was passed when the object got instantiated.
1608 117 Adrian Georgescu
>This attribute is read-only.
1609 117 Adrian Georgescu
1610 117 Adrian Georgescu
*transport*
1611 117 Adrian Georgescu
>The @RTPTransport@ object that was passed when the object got instantiated.
1612 117 Adrian Georgescu
>This attribute is read-only.
1613 117 Adrian Georgescu
1614 117 Adrian Georgescu
*slot*
1615 117 Adrian Georgescu
>A read-only property indicating the slot number at which this object is attached to the associated conference bridge.
1616 117 Adrian Georgescu
>If the @AudioTransport@ is not active (i.e. has not been started), this attribute will be @None@.
1617 117 Adrian Georgescu
1618 117 Adrian Georgescu
*volume*
1619 117 Adrian Georgescu
>A writable property indicating the % of volume at which this object contributes audio to the conference bridge.
1620 117 Adrian Georgescu
>By default this is set to 100.
1621 117 Adrian Georgescu
1622 117 Adrian Georgescu
*is_active*
1623 117 Adrian Georgescu
>A boolean indicating if the object is currently sending and receiving audio.
1624 117 Adrian Georgescu
>This attribute is read-only.
1625 117 Adrian Georgescu
1626 117 Adrian Georgescu
*is_started*
1627 117 Adrian Georgescu
>A boolean indicating if the object has been started.
1628 117 Adrian Georgescu
>Both this attribute and the @is_active@ attribute get set to @True@ once the @start()@ method is called, but unlike the @is_active@ attribute this attribute does not get set to @False@ once @stop()@ is called.
1629 117 Adrian Georgescu
>This is to prevent the object from being re-used.
1630 117 Adrian Georgescu
>This attribute is read-only.
1631 117 Adrian Georgescu
1632 117 Adrian Georgescu
*codec*
1633 117 Adrian Georgescu
>Once the SDP negotiation is complete, this attribute indicates the audio codec that was negotiated, otherwise it will be @None@.
1634 117 Adrian Georgescu
>This attribute is read-only.
1635 117 Adrian Georgescu
1636 117 Adrian Georgescu
*sample_rate*
1637 117 Adrian Georgescu
>Once the SDP negotiation is complete, this attribute indicates the sample rate of the audio codec that was negotiated, otherwise it will be @None@.
1638 117 Adrian Georgescu
>This attribute is read-only.
1639 117 Adrian Georgescu
1640 117 Adrian Georgescu
*direction*
1641 117 Adrian Georgescu
>The current direction of the audio transport, which is one of "sendrecv", "sendonly", "recvonly" or "inactive".
1642 117 Adrian Georgescu
>This attribute is read-only, although it can be set using the @update_direction()@ method.
1643 117 Adrian Georgescu
1644 117 Adrian Georgescu
1645 117 Adrian Georgescu
h4. notifications
1646 117 Adrian Georgescu
1647 117 Adrian Georgescu
1648 117 Adrian Georgescu
1649 117 Adrian Georgescu
*RTPAudioTransportGotDTMF*
1650 117 Adrian Georgescu
>This notification will be sent when an incoming DTMF digit is received from the remote party.
1651 117 Adrian Georgescu
  
1652 117 Adrian Georgescu
>+_timestamp_+:
1653 117 Adrian Georgescu
1654 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
1655 117 Adrian Georgescu
  
1656 117 Adrian Georgescu
>+_digit_+:
1657 117 Adrian Georgescu
1658 117 Adrian Georgescu
>The DTMF digit that was received, in the form of a string of length one.
1659 117 Adrian Georgescu
>This can be either a number or letters A through D.
1660 117 Adrian Georgescu
1661 117 Adrian Georgescu
*RTPAudioTransportDidNotGetRTP*
1662 117 Adrian Georgescu
>This notification will be sent when no RTP packets have been received from the remote party for some time.
1663 117 Adrian Georgescu
>See the @start()@ method for a more exact description.
1664 117 Adrian Georgescu
  
1665 117 Adrian Georgescu
>+_timestamp_+:
1666 117 Adrian Georgescu
1667 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
1668 117 Adrian Georgescu
  
1669 117 Adrian Georgescu
>+_got_any_+:
1670 117 Adrian Georgescu
1671 117 Adrian Georgescu
>A boolean data attribute indicating if the @AudioTransport@ every saw any RTP packets from the remote party.
1672 117 Adrian Georgescu
>In effect, if no RTP was received after @no_media_timeout@ seconds, its value will be @False@.
1673 117 Adrian Georgescu
1674 117 Adrian Georgescu
1675 117 Adrian Georgescu
h3. Request
1676 117 Adrian Georgescu
1677 117 Adrian Georgescu
1678 117 Adrian Georgescu
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 117 Adrian Georgescu
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 117 Adrian Georgescu
1681 1 Adrian Georgescu
The lifetime of this object is linear and is described by the following diagram:
1682 1 Adrian Georgescu
1683 117 Adrian Georgescu
!{ nolink}sipsimple-request-lifetime.png!
1684 1 Adrian Georgescu
1685 1 Adrian Georgescu
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 117 Adrian Georgescu
The request will be sent over the network once its @send()@ method is called, moving the object into the @IN_PROGRESS@ state.
1688 117 Adrian Georgescu
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 117 Adrian Georgescu
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 117 Adrian Georgescu
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 117 Adrian Georgescu
This should usually trigger whomever is using this @Request@ object to construct a new @Request@ for a refreshing operation.
1696 117 Adrian Georgescu
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 17 Ruud Klaver
1699 117 Adrian Georgescu
h4. methods
1700 99 Adrian Georgescu
1701 17 Ruud Klaver
1702 117 Adrian Georgescu
1703 117 Adrian Georgescu
*<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 117 Adrian Georgescu
>Creates a new @Request@ object in the @INIT@ state.
1705 117 Adrian Georgescu
>The arguments to this method are documented in the attributes section.
1706 117 Adrian Georgescu
1707 117 Adrian Georgescu
*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 117 Adrian Georgescu
  
1711 117 Adrian Georgescu
>+_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 117 Adrian Georgescu
>This is is @None@, the internal 408 is only triggered by the internal PJSIP transaction timeout.
1715 117 Adrian Georgescu
>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 117 Adrian Georgescu
>Terminate the transaction, whichever state it is in, sending the appropriate notifications.
1719 117 Adrian Georgescu
>Note that calling this method while in the @INIT@ state does nothing.
1720 1 Adrian Georgescu
1721 1 Adrian Georgescu
1722 117 Adrian Georgescu
h4. attributes
1723 1 Adrian Georgescu
1724 112 Adrian Georgescu
1725 112 Adrian Georgescu
1726 117 Adrian Georgescu
*expire_warning_time* (class attribute)
1727 117 Adrian Georgescu
>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 117 Adrian Georgescu
>The default value is 30 seconds.
1729 112 Adrian Georgescu
1730 117 Adrian Georgescu
*state*
1731 117 Adrian Georgescu
>Indicates the state the @Request@ object is in, in the form of a string.
1732 117 Adrian Georgescu
>Refer to the diagram above for possible states.
1733 117 Adrian Georgescu
>This attribute is read-only.
1734 112 Adrian Georgescu
1735 117 Adrian Georgescu
*method*
1736 117 Adrian Georgescu
>The method of the SIP request as a string.
1737 117 Adrian Georgescu
>This attribute is set on instantiation and is read-only.
1738 112 Adrian Georgescu
1739 117 Adrian Georgescu
*from_header*
1740 117 Adrian Georgescu
>The @FrozenFromHeader@ object to put in the @From@ header of the request.
1741 117 Adrian Georgescu
>This attribute is set on instantiation and is read-only.
1742 112 Adrian Georgescu
1743 117 Adrian Georgescu
*to_header*
1744 117 Adrian Georgescu
>The @FrozenToHeader@ object to put in the @To@ header of the request.
1745 117 Adrian Georgescu
>This attribute is set on instantiation and is read-only.
1746 112 Adrian Georgescu
1747 117 Adrian Georgescu
*request_uri*
1748 117 Adrian Georgescu
>The SIP URI to put as request URI in the request, in the form of a @FrozenSIPURI@ object.
1749 117 Adrian Georgescu
>This attribute is set on instantiation and is read-only.
1750 112 Adrian Georgescu
1751 117 Adrian Georgescu
*route_header*
1752 117 Adrian Georgescu
>Where to send the SIP request to, including IP, port and transport, in the form of a @FrozenRouteHeader@ object.
1753 117 Adrian Georgescu
>This will also be included in the @Route@ header of the request.
1754 117 Adrian Georgescu
>This attribute is set on instantiation and is read-only.
1755 112 Adrian Georgescu
1756 117 Adrian Georgescu
*credentials*
1757 117 Adrian Georgescu
>The credentials to be used when challenged for authentication, represented by a @FrozenCredentials@ object.
1758 117 Adrian Georgescu
>If no credentials were supplied when the object was created this attribute is @None@.
1759 117 Adrian Georgescu
>This attribute is set on instantiation and is read-only.
1760 112 Adrian Georgescu
1761 117 Adrian Georgescu
*contact_header*
1762 117 Adrian Georgescu
>The @FrozenContactHeader@ object to put in the @Contact@ header of the request.
1763 117 Adrian Georgescu
>If this was not specified, this attribute is @None@.
1764 117 Adrian Georgescu
>It is set on instantiation and is read-only.
1765 112 Adrian Georgescu
1766 117 Adrian Georgescu
*call_id*
1767 117 Adrian Georgescu
>The @Call-ID@ to be used for this transaction as a string.
1768 117 Adrian Georgescu
>If no call id was specified on instantiation, this attribute contains the generated id.
1769 117 Adrian Georgescu
>This attribute is set on instantiation and is read-only.
1770 112 Adrian Georgescu
1771 117 Adrian Georgescu
*cseq*
1772 117 Adrian Georgescu
>The sequence number to use in the request as an int.
1773 117 Adrian Georgescu
>If no sequence number was specified on instantiation, this attribute contains the generated sequence number.
1774 117 Adrian Georgescu
>Note that this number may be increased by one if an authentication challenge is received and a @Credentials@ object is given.
1775 117 Adrian Georgescu
>This attribute is read-only.
1776 112 Adrian Georgescu
1777 117 Adrian Georgescu
*extra_headers*
1778 117 Adrian Georgescu
>Extra headers to include in the request as a frozenlist of header objects.
1779 117 Adrian Georgescu
>This attribute is set on instantiation and is read-only.
1780 112 Adrian Georgescu
1781 117 Adrian Georgescu
*content_type*
1782 117 Adrian Georgescu
>What string to put as content type in the @Content-Type@ headers, if the request contains a body.
1783 117 Adrian Georgescu
>If no body was specified, this attribute is @None@
1784 117 Adrian Georgescu
>It is set on instantiation and is read-only.
1785 112 Adrian Georgescu
1786 117 Adrian Georgescu
*body*
1787 117 Adrian Georgescu
>The body of the request as a string.
1788 117 Adrian Georgescu
>If no body was specified, this attribute is @None@
1789 117 Adrian Georgescu
>It is set on instantiation and is read-only.
1790 112 Adrian Georgescu
1791 117 Adrian Georgescu
*expires_in*
1792 117 Adrian Georgescu
>This read-only property indicates in how many seconds from now this @Request@ will expire, if it is in the @EXPIRING@ state.
1793 117 Adrian Georgescu
>If this is not the case, this property is 0.
1794 112 Adrian Georgescu
1795 117 Adrian Georgescu
*peer_address*
1796 117 Adrian Georgescu
>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 112 Adrian Georgescu
1799 117 Adrian Georgescu
h4. notifications
1800 112 Adrian Georgescu
1801 112 Adrian Georgescu
1802 112 Adrian Georgescu
1803 117 Adrian Georgescu
*SIPRequestGotProvisionalResponse*
1804 117 Adrian Georgescu
>This notification will be sent on every provisional response received in reply to the sent request.
1805 117 Adrian Georgescu
  
1806 117 Adrian Georgescu
>+_timestamp_+:
1807 112 Adrian Georgescu
1808 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
1809 117 Adrian Georgescu
  
1810 117 Adrian Georgescu
>+_code_+:
1811 117 Adrian Georgescu
1812 117 Adrian Georgescu
>The SIP response code of the received provisional response as an int, which will be in the 1xx range.
1813 117 Adrian Georgescu
  
1814 117 Adrian Georgescu
>+_reason_+:
1815 117 Adrian Georgescu
1816 117 Adrian Georgescu
>The reason text string included with the SIP response code.
1817 117 Adrian Georgescu
  
1818 117 Adrian Georgescu
>+_headers_+:
1819 117 Adrian Georgescu
1820 117 Adrian Georgescu
>The headers included in the provisional response as a dict, the values of which are header objects.
1821 117 Adrian Georgescu
  
1822 117 Adrian Georgescu
>+_body_+:
1823 117 Adrian Georgescu
1824 117 Adrian Georgescu
>The body of the provisional response as a string, or @None@ if there was no body.
1825 117 Adrian Georgescu
1826 117 Adrian Georgescu
*SIPRequestDidSucceed*
1827 117 Adrian Georgescu
>This notification will be sent when a positive final response was received in reply to the request.
1828 117 Adrian Georgescu
  
1829 117 Adrian Georgescu
>+_timestamp_+:
1830 117 Adrian Georgescu
1831 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
1832 117 Adrian Georgescu
  
1833 117 Adrian Georgescu
>+_code_+:
1834 117 Adrian Georgescu
1835 117 Adrian Georgescu
>The SIP response code of the received positive final response as an int, which will be in the 2xx range.
1836 117 Adrian Georgescu
  
1837 117 Adrian Georgescu
>+_reason_+:
1838 117 Adrian Georgescu
1839 117 Adrian Georgescu
>The reason text string included with the SIP response code.
1840 117 Adrian Georgescu
  
1841 117 Adrian Georgescu
>+_headers_+:
1842 117 Adrian Georgescu
1843 117 Adrian Georgescu
>The headers included in the positive final response as a dict, the values of which are header objects.
1844 117 Adrian Georgescu
  
1845 117 Adrian Georgescu
>+_body_+:
1846 117 Adrian Georgescu
1847 117 Adrian Georgescu
>The body of the positive final response as a string, or @None@ if there was no body.
1848 117 Adrian Georgescu
  
1849 117 Adrian Georgescu
>+_expires_+:
1850 117 Adrian Georgescu
1851 117 Adrian Georgescu
>Indicates in how many seconds the @Request@ will expire as an int.
1852 117 Adrian Georgescu
>If it does not expire and the @EXPIRING@ state is skipped, this attribute is 0.
1853 117 Adrian Georgescu
1854 117 Adrian Georgescu
*SIPRequestDidFail*
1855 117 Adrian Georgescu
>This notification will be sent when a negative final response is received in reply to the request or if an internal error occurs.
1856 117 Adrian Georgescu
  
1857 117 Adrian Georgescu
>+_timestamp_+:
1858 117 Adrian Georgescu
1859 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
1860 117 Adrian Georgescu
  
1861 117 Adrian Georgescu
>+_code_+:
1862 117 Adrian Georgescu
1863 117 Adrian Georgescu
>The SIP response code of the received negative final response as an int.
1864 117 Adrian Georgescu
>This could also be a response code generated by PJSIP internally, or 0 when an internal error occurs.
1865 117 Adrian Georgescu
  
1866 117 Adrian Georgescu
>+_reason_+:
1867 117 Adrian Georgescu
1868 117 Adrian Georgescu
>The reason text string included with the SIP response code or error.
1869 117 Adrian Georgescu
  
1870 117 Adrian Georgescu
>+_headers_+: (only if a negative final response was received)
1871 117 Adrian Georgescu
1872 117 Adrian Georgescu
>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 117 Adrian Georgescu
  
1874 117 Adrian Georgescu
>+_body_+: (only if a negative final response was received)
1875 117 Adrian Georgescu
1876 117 Adrian Georgescu
>The body of the negative final response as a string, or @None@ if there was no body.
1877 117 Adrian Georgescu
>This attribute is absent if no response was received.
1878 117 Adrian Georgescu
1879 117 Adrian Georgescu
*SIPRequestWillExpire*
1880 117 Adrian Georgescu
>This notification will be sent when a @Request@ in the @EXPIRING@ state will expire soon.
1881 117 Adrian Georgescu
  
1882 117 Adrian Georgescu
>+_timestamp_+:
1883 117 Adrian Georgescu
1884 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
1885 117 Adrian Georgescu
  
1886 117 Adrian Georgescu
>+_expires_+:
1887 117 Adrian Georgescu
1888 117 Adrian Georgescu
>An int indicating in how many seconds from now the @Request@ will actually expire.
1889 117 Adrian Georgescu
1890 117 Adrian Georgescu
*SIPRequestDidEnd*
1891 117 Adrian Georgescu
>This notification will be sent when a @Request@ object enters the @TERMINATED@ state and can no longer be used.
1892 117 Adrian Georgescu
  
1893 117 Adrian Georgescu
>+_timestamp_+:
1894 117 Adrian Georgescu
1895 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
1896 117 Adrian Georgescu
1897 117 Adrian Georgescu
1898 117 Adrian Georgescu
h3. IncomingRequest
1899 117 Adrian Georgescu
1900 117 Adrian Georgescu
1901 113 Adrian Georgescu
This is a relatively simple object that can manage responding to incoming requests in a single transaction.
1902 113 Adrian Georgescu
For this reason it does not handle requests that create a dialog.
1903 117 Adrian Georgescu
To register methods for which requests should be formed into an @IncomingRequest@ object, the application should set the @incoming_requests@ set attribute on the @Engine@.
1904 117 Adrian Georgescu
Receiving @INVITE@, @SUBSCRIBE@, @ACK@ and @BYE@ through this object is not supported.
1905 113 Adrian Georgescu
1906 117 Adrian Georgescu
The application is notified of an incoming request through the @SIPIncomingRequestGotRequest@ notification.
1907 117 Adrian Georgescu
It can answer this request by calling the @answer@ method on the sender of this notification.
1908 117 Adrian Georgescu
Note that if the @IncomingRequest@ object gets destroyed before it is answered, a 500 response is automatically sent.
1909 113 Adrian Georgescu
1910 113 Adrian Georgescu
1911 117 Adrian Georgescu
h4. attributes
1912 113 Adrian Georgescu
1913 113 Adrian Georgescu
1914 113 Adrian Georgescu
1915 117 Adrian Georgescu
*state*
1916 117 Adrian Georgescu
>This read-only attribute indicates the state the object is in.
1917 117 Adrian Georgescu
>This can be @None@ if the object was created by the application, essentially meaning the object is inert, @"incoming"@ or @"answered"@.
1918 113 Adrian Georgescu
1919 113 Adrian Georgescu
1920 117 Adrian Georgescu
h4. methods
1921 113 Adrian Georgescu
1922 113 Adrian Georgescu
1923 113 Adrian Georgescu
1924 117 Adrian Georgescu
*answer*(_self_, *code*, *reason*=@None@, *extra_headers*=@None@)
1925 117 Adrian Georgescu
>Reply to the received request with a final response.
1926 117 Adrian Georgescu
  
1927 117 Adrian Georgescu
>+_code_+:
1928 113 Adrian Georgescu
1929 117 Adrian Georgescu
>The SIP response code to send.
1930 117 Adrian Georgescu
>This should be 200 or higher.
1931 117 Adrian Georgescu
  
1932 117 Adrian Georgescu
>+_reason_+:
1933 113 Adrian Georgescu
1934 117 Adrian Georgescu
>The reason text to include in the response.
1935 117 Adrian Georgescu
>If this is @None@, the default text for the given response code is used.
1936 117 Adrian Georgescu
  
1937 117 Adrian Georgescu
>+_extra_headers_+:
1938 113 Adrian Georgescu
1939 117 Adrian Georgescu
>The extra headers to include in the response as an iterable of header objects.
1940 113 Adrian Georgescu
1941 113 Adrian Georgescu
1942 117 Adrian Georgescu
h4. notifications
1943 113 Adrian Georgescu
1944 113 Adrian Georgescu
1945 113 Adrian Georgescu
1946 117 Adrian Georgescu
*SIPIncomingRequestGotRequest*
1947 117 Adrian Georgescu
>This notification will be sent when a new @IncomingRequest@ is created as result of a received request.
1948 117 Adrian Georgescu
>The application should listen for this notification, retain a reference to the object that sent it and answer it.
1949 117 Adrian Georgescu
  
1950 117 Adrian Georgescu
>+_timestamp_+:
1951 113 Adrian Georgescu
1952 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
1953 117 Adrian Georgescu
  
1954 117 Adrian Georgescu
>+_method_+:
1955 113 Adrian Georgescu
1956 117 Adrian Georgescu
>The method of the SIP request as a string.
1957 117 Adrian Georgescu
  
1958 117 Adrian Georgescu
>+_request_uri_+:
1959 113 Adrian Georgescu
1960 117 Adrian Georgescu
>The request URI of the request as a @FrozenSIPURI@ object.
1961 117 Adrian Georgescu
  
1962 117 Adrian Georgescu
>+_headers_+:
1963 113 Adrian Georgescu
1964 117 Adrian Georgescu
>The headers of the request as a dict, the values of which are the relevant header objects.
1965 117 Adrian Georgescu
  
1966 117 Adrian Georgescu
>+_body_+:
1967 113 Adrian Georgescu
1968 117 Adrian Georgescu
>The body of the request as a string, or @None@ if no body was included.
1969 113 Adrian Georgescu
1970 117 Adrian Georgescu
*SIPIncomingRequestSentResponse*
1971 117 Adrian Georgescu
>This notification is sent when a response to the request is sent by the object.
1972 117 Adrian Georgescu
  
1973 117 Adrian Georgescu
>+_timestamp_+:
1974 113 Adrian Georgescu
1975 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
1976 117 Adrian Georgescu
  
1977 117 Adrian Georgescu
>+_code_+:
1978 113 Adrian Georgescu
1979 117 Adrian Georgescu
>The code of the SIP response as an int.
1980 117 Adrian Georgescu
  
1981 117 Adrian Georgescu
>+_reason_+:
1982 113 Adrian Georgescu
1983 117 Adrian Georgescu
>The reason text of the SIP response as an int.
1984 117 Adrian Georgescu
  
1985 117 Adrian Georgescu
>+_headers_+:
1986 113 Adrian Georgescu
1987 117 Adrian Georgescu
>The headers of the response as a dict, the values of which are the relevant header objects.
1988 117 Adrian Georgescu
  
1989 117 Adrian Georgescu
>+_body_+:
1990 113 Adrian Georgescu
1991 117 Adrian Georgescu
>This will be @None@.
1992 113 Adrian Georgescu
1993 113 Adrian Georgescu
1994 117 Adrian Georgescu
h3. Message
1995 113 Adrian Georgescu
1996 113 Adrian Georgescu
1997 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.
1998 117 Adrian Georgescu
It is a one-shot object that manages only one @Request@ object.
1999 113 Adrian Georgescu
2000 113 Adrian Georgescu
2001 117 Adrian Georgescu
h4. methods
2002 113 Adrian Georgescu
2003 113 Adrian Georgescu
2004 113 Adrian Georgescu
2005 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_, *from_header*, *to_header*, *route_header*, *content_type*, *body*, *credentials*=@None@, *extra_headers*=@[]@)
2006 117 Adrian Georgescu
>Creates a new @Message@ object with the specified arguments.
2007 117 Adrian Georgescu
>These arguments are documented in the attributes section for this class.
2008 113 Adrian Georgescu
2009 117 Adrian Georgescu
*send*(_self_, *timeout*=@None@)
2010 117 Adrian Georgescu
>Send the @MESSAGE@ request to the remote party.
2011 117 Adrian Georgescu
  
2012 117 Adrian Georgescu
>+_timeout_+:
2013 113 Adrian Georgescu
2014 117 Adrian Georgescu
>This argument as the same meaning as it does for @Request.send()@.
2015 113 Adrian Georgescu
2016 117 Adrian Georgescu
*end*(_self_)
2017 117 Adrian Georgescu
>Stop trying to send the @MESSAGE@ request.
2018 117 Adrian Georgescu
>If it was not sent yet, calling this method does nothing.
2019 113 Adrian Georgescu
2020 113 Adrian Georgescu
2021 117 Adrian Georgescu
h4. attributes
2022 113 Adrian Georgescu
2023 113 Adrian Georgescu
2024 113 Adrian Georgescu
2025 117 Adrian Georgescu
*from_header*
2026 117 Adrian Georgescu
>The @FrozenFromHeader@ to put in the @From@ header of the @MESSAGE@ request.
2027 117 Adrian Georgescu
>This attribute is set on instantiation and is read-only.
2028 113 Adrian Georgescu
2029 117 Adrian Georgescu
*to_header*
2030 117 Adrian Georgescu
>The @FrozenToHeader@ to put in the @To@ header of the @MESSAGE@ request.
2031 117 Adrian Georgescu
>This attribute is set on instantiation and is read-only.
2032 113 Adrian Georgescu
2033 117 Adrian Georgescu
*route_header*
2034 117 Adrian Georgescu
>Where to send the @MESSAGE@ request to, including IP, port and transport, in the form of a @FrozenRouteHeader@ object.
2035 117 Adrian Georgescu
>This will also be included in the @Route@ header of the request.
2036 117 Adrian Georgescu
>This attribute is set on instantiation and is read-only.
2037 113 Adrian Georgescu
2038 117 Adrian Georgescu
*content_type*
2039 117 Adrian Georgescu
>What string to put as content type in the @Content-Type@ headers.
2040 117 Adrian Georgescu
>It is set on instantiation and is read-only.
2041 113 Adrian Georgescu
2042 117 Adrian Georgescu
*body*
2043 117 Adrian Georgescu
>The body of the @MESSAGE@ request as a string.
2044 117 Adrian Georgescu
>If no body was specified, this attribute is @None@
2045 117 Adrian Georgescu
>It is set on instantiation and is read-only.
2046 113 Adrian Georgescu
2047 117 Adrian Georgescu
*credentials*
2048 117 Adrian Georgescu
>The credentials to be used when challenged for authentication, represented by a @FrozenCredentials@ object.
2049 117 Adrian Georgescu
>If no credentials were specified, this attribute is @None@.
2050 117 Adrian Georgescu
>This attribute is set on instantiation and is read-only.
2051 103 Adrian Georgescu
2052 117 Adrian Georgescu
*is_sent*
2053 117 Adrian Georgescu
>A boolean read-only property indicating if the @MESSAGE@ request was sent.
2054 103 Adrian Georgescu
2055 117 Adrian Georgescu
*in_progress*
2056 117 Adrian Georgescu
>A boolean read-only property indicating if the object is waiting for the response from the remote party.
2057 103 Adrian Georgescu
2058 117 Adrian Georgescu
*peer_address*
2059 117 Adrian Georgescu
>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.
2060 103 Adrian Georgescu
2061 103 Adrian Georgescu
2062 117 Adrian Georgescu
h4. notifications
2063 103 Adrian Georgescu
2064 103 Adrian Georgescu
2065 117 Adrian Georgescu
2066 117 Adrian Georgescu
*SIPMessageDidSucceed*
2067 117 Adrian Georgescu
>This notification will be sent when the remote party acknowledged the reception of the @MESSAGE@ request.
2068 117 Adrian Georgescu
>It has not data attributes.
2069 117 Adrian Georgescu
2070 117 Adrian Georgescu
*SIPMessageDidFail*
2071 117 Adrian Georgescu
>This notification will be sent when transmission of the @MESSAGE@ request fails for whatever reason.
2072 117 Adrian Georgescu
  
2073 117 Adrian Georgescu
>+_code_+:
2074 117 Adrian Georgescu
2075 117 Adrian Georgescu
>An int indicating the SIP or internal PJSIP code that was given in response to the @MESSAGE@ request.
2076 117 Adrian Georgescu
>This is 0 if the failure is caused by an internal error.
2077 117 Adrian Georgescu
  
2078 117 Adrian Georgescu
>+_reason_+:
2079 117 Adrian Georgescu
2080 117 Adrian Georgescu
>A status string describing the failure, either taken from the SIP response or the internal error.
2081 117 Adrian Georgescu
2082 117 Adrian Georgescu
2083 117 Adrian Georgescu
h3. Registration
2084 117 Adrian Georgescu
2085 117 Adrian Georgescu
2086 117 Adrian Georgescu
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.
2087 117 Adrian Georgescu
For details, see "RFC 3261":http://tools.ietf.org/html/rfc3261.
2088 117 Adrian Georgescu
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.
2089 117 Adrian Georgescu
The application should then perform a DNS lookup to find the relevant SIP registrar and call the @register()@ method on this object.
2090 117 Adrian Georgescu
2091 117 Adrian Georgescu
2092 117 Adrian Georgescu
h4. methods
2093 117 Adrian Georgescu
2094 117 Adrian Georgescu
2095 117 Adrian Georgescu
2096 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_, *from_header*, *credentials*=@None@, *duration*=300)
2097 117 Adrian Georgescu
>Creates a new @Registration@ object with the specified arguments.
2098 117 Adrian Georgescu
>These arguments are documented in the attributes section for this class.
2099 117 Adrian Georgescu
2100 117 Adrian Georgescu
*register*(_self_, *contact_header*, *route_header*, *timeout*=@None@)
2101 117 Adrian Georgescu
>Calling this method will attempt to send a new @REGISTER@ request to the registrar provided, whatever state the object is in.
2102 117 Adrian Georgescu
>If the object is currently busy sending a @REGISTER@, this request will be preempted for the new one.
2103 117 Adrian Georgescu
>Once sent, the @Registration@ object will send either a @SIPRegistrationDidSucceed@ or a @SIPRegistrationDidFail@ notification.
2104 117 Adrian Georgescu
>The @contact_header@ argument is mentioned in the attributes section of this class.
2105 117 Adrian Georgescu
>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()@.
2106 117 Adrian Georgescu
2107 117 Adrian Georgescu
*end*(_self_, *timeout*=@None@)
2108 117 Adrian Georgescu
>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.
2109 117 Adrian Georgescu
>The @RouteHeader@ used for this will be the same as the last successfully sent @REGISTER@ request.
2110 117 Adrian Georgescu
>If another @REGISTER@ is currently being sent, it will be preempted.
2111 117 Adrian Georgescu
>When the unregistering @REGISTER@ request is sent, a @SIPRegistrationWillEnd@ notification is sent.
2112 117 Adrian Georgescu
>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.
2113 117 Adrian Georgescu
>Calling this method when the object is not registered will do nothing.
2114 117 Adrian Georgescu
>The @timeout@ argument has the same meaning as for the @register()@ method.
2115 117 Adrian Georgescu
2116 117 Adrian Georgescu
2117 117 Adrian Georgescu
h4. attributes
2118 117 Adrian Georgescu
2119 117 Adrian Georgescu
2120 117 Adrian Georgescu
2121 117 Adrian Georgescu
*from_header_
2122 117 Adrian Georgescu
>The @(Frozen)FromHeader@ the @Registration@ was sent with.
2123 117 Adrian Georgescu
2124 117 Adrian Georgescu
*credentials*
2125 117 Adrian Georgescu
>The credentials to be used when challenged for authentication by the registrar, represented by a @(Frozen)Credentials@ object. 
2126 117 Adrian Georgescu
>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.
2127 117 Adrian Georgescu
>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.
2128 117 Adrian Georgescu
2129 117 Adrian Georgescu
*duration*
2130 117 Adrian Georgescu
>The amount of time in seconds to request the registration for at the registrar.
2131 117 Adrian Georgescu
>This attribute is set at object instantiation and can be updated for subsequent @REGISTER@ requests.
2132 117 Adrian Georgescu
2133 117 Adrian Georgescu
*is_registered*
2134 117 Adrian Georgescu
>A boolean read-only property indicating if this object is currently registered.
2135 117 Adrian Georgescu
2136 117 Adrian Georgescu
*contact_header*
2137 117 Adrian Georgescu
>If the @Registration@ object is registered, this attribute contains the latest contact header that was sent to the registrar as a @FrozenContactHeader@ object.
2138 117 Adrian Georgescu
>Otherwise, this attribute is @None@
2139 117 Adrian Georgescu
2140 117 Adrian Georgescu
*expires_in*
2141 117 Adrian Georgescu
>If registered, this read-only property indicates in how many seconds from now this @Registration@ will expire.
2142 117 Adrian Georgescu
>If this is not the case, this property is 0.
2143 117 Adrian Georgescu
2144 117 Adrian Georgescu
*peer_address*
2145 117 Adrian Georgescu
>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.
2146 117 Adrian Georgescu
2147 117 Adrian Georgescu
2148 117 Adrian Georgescu
h4. notifications
2149 117 Adrian Georgescu
2150 117 Adrian Georgescu
2151 117 Adrian Georgescu
2152 117 Adrian Georgescu
*SIPRegistrationDidSucceed*
2153 117 Adrian Georgescu
>This notification will be sent when the @register()@ method was called and the registration succeeded.
2154 117 Adrian Georgescu
  
2155 117 Adrian Georgescu
>+_code_+:
2156 117 Adrian Georgescu
2157 117 Adrian Georgescu
>The SIP response code as received from the registrar as an int.
2158 117 Adrian Georgescu
  
2159 117 Adrian Georgescu
>+_reason_+:
2160 117 Adrian Georgescu
2161 117 Adrian Georgescu
>The reason string received from the SIP registrar.
2162 117 Adrian Georgescu
  
2163 117 Adrian Georgescu
>+_route_header_+:
2164 117 Adrian Georgescu
2165 117 Adrian Georgescu
>The @(Frozen)RouteHeader@ object passed as an argument to the @register()@ method.
2166 117 Adrian Georgescu
  
2167 117 Adrian Georgescu
>+_contact_header_+:
2168 117 Adrian Georgescu
2169 117 Adrian Georgescu
>The contact header that was sent to the registrar as a @FrozenContactHeader@ object.
2170 117 Adrian Georgescu
  
2171 117 Adrian Georgescu
>+_contact_header_list_+:
2172 117 Adrian Georgescu
2173 117 Adrian Georgescu
>A full list of contact headers that are registered for this SIP account, including the one used for this registration.
2174 117 Adrian Georgescu
>The format of this data attribute is a list of FrozenContactHeader objects.
2175 117 Adrian Georgescu
  
2176 117 Adrian Georgescu
>+_expires_in_+:
2177 117 Adrian Georgescu
2178 117 Adrian Georgescu
>The number of seconds before this registration expires
2179 117 Adrian Georgescu
2180 117 Adrian Georgescu
*SIPRegistrationDidFail*
2181 117 Adrian Georgescu
>This notification will be sent when the @register()@ method was called and the registration failed, for whatever reason.
2182 117 Adrian Georgescu
  
2183 117 Adrian Georgescu
>+_code_+:
2184 117 Adrian Georgescu
2185 117 Adrian Georgescu
>The SIP response code as received from the registrar as an int.
2186 117 Adrian Georgescu
>This can also be a PJSIP generated response code, or 0 if the failure was because of an internal error.
2187 117 Adrian Georgescu
  
2188 117 Adrian Georgescu
>+_reason_+:
2189 117 Adrian Georgescu
2190 117 Adrian Georgescu
>The reason string received from the SIP registrar or the error string.
2191 117 Adrian Georgescu
  
2192 117 Adrian Georgescu
>+_route_header_+:
2193 117 Adrian Georgescu
2194 117 Adrian Georgescu
>The @(Frozen)RouteHeader@ object passed as an argument to the @register()@ method.
2195 117 Adrian Georgescu
2196 117 Adrian Georgescu
*SIPRegistrationWillExpire*
2197 117 Adrian Georgescu
>This notification will be sent when a registration will expire soon.
2198 117 Adrian Georgescu
>It should be used as an indication to re-perform DNS lookup of the registrar and call the @register()@ method.
2199 117 Adrian Georgescu
  
2200 117 Adrian Georgescu
>+_expires_+:
2201 117 Adrian Georgescu
2202 117 Adrian Georgescu
>The number of seconds in which the registration will expire.
2203 117 Adrian Georgescu
2204 117 Adrian Georgescu
*SIPRegistrationWillEnd*
2205 117 Adrian Georgescu
>Will be sent whenever the @end()@ method was called and an unregistering @REGISTER@ is sent.
2206 117 Adrian Georgescu
2207 117 Adrian Georgescu
*SIPRegistrationDidNotEnd*
2208 117 Adrian Georgescu
>This notification will be sent when the unregistering @REGISTER@ request failed for some reason.
2209 117 Adrian Georgescu
  
2210 117 Adrian Georgescu
>+_code_+:
2211 117 Adrian Georgescu
2212 117 Adrian Georgescu
>The SIP response code as received from the registrar as an int.
2213 117 Adrian Georgescu
>This can also be a PJSIP generated response code, or 0 if the failure was because of an internal error.
2214 117 Adrian Georgescu
  
2215 117 Adrian Georgescu
>+_reason_+:
2216 117 Adrian Georgescu
2217 117 Adrian Georgescu
>The reason string received from the SIP registrar or the error string.
2218 117 Adrian Georgescu
2219 117 Adrian Georgescu
*SIPRegistrationDidEnd*
2220 117 Adrian Georgescu
>This notification will be sent when a @Registration@ has become unregistered.
2221 117 Adrian Georgescu
  
2222 117 Adrian Georgescu
>+_expired_+:
2223 117 Adrian Georgescu
2224 117 Adrian Georgescu
>This boolean indicates if the object is unregistered because the registration expired, in which case it will be set to @True@.
2225 117 Adrian Georgescu
>If this data attribute is @False@, it means that unregistration was explicitly requested through the @end()@ method.
2226 117 Adrian Georgescu
2227 117 Adrian Georgescu
2228 117 Adrian Georgescu
h4. example code
2229 117 Adrian Georgescu
2230 117 Adrian Georgescu
2231 99 Adrian Georgescu
For an example on how to use this object, see the Integration section.
2232 103 Adrian Georgescu
2233 103 Adrian Georgescu
2234 117 Adrian Georgescu
h3. Publication
2235 103 Adrian Georgescu
2236 103 Adrian Georgescu
2237 117 Adrian Georgescu
Publication of SIP events is an Internet standard published at "RFC 3903":http://tools.ietf.org/html/rfc3903. 
2238 117 Adrian Georgescu
@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.
2239 103 Adrian Georgescu
2240 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.
2241 117 Adrian Georgescu
This object is similar in behaviour to the @Registration@ object, as it is also based on a sequence of @Request@ objects.
2242 117 Adrian Georgescu
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.
2243 103 Adrian Georgescu
2244 103 Adrian Georgescu
2245 117 Adrian Georgescu
h4. methods
2246 103 Adrian Georgescu
2247 103 Adrian Georgescu
2248 103 Adrian Georgescu
2249 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_, *from_header*, *event*, *content_type*, *credentials*=@None@, *duration*=300)
2250 117 Adrian Georgescu
>Creates a new @Publication@ object with the specified arguments.
2251 117 Adrian Georgescu
>These arguments are documented in the attributes section for this class.
2252 103 Adrian Georgescu
2253 117 Adrian Georgescu
*publish*(_self_, *body*, *route_header*, *timeout*=@None@)
2254 117 Adrian Georgescu
>Send an actual @PUBLISH@ request to the specified presence agent.
2255 117 Adrian Georgescu
  
2256 117 Adrian Georgescu
>+_body_+:
2257 103 Adrian Georgescu
2258 117 Adrian Georgescu
>The body to place in the @PUBLISH@ request as a string.
2259 117 Adrian Georgescu
>This body needs to be of the content type specified at object creation.
2260 117 Adrian Georgescu
>For the initial request, a body will need to be specified.
2261 117 Adrian Georgescu
>For subsequent refreshing @PUBLISH@ requests, the body can be @None@ to indicate that the last published body should be refreshed.
2262 117 Adrian Georgescu
>If there was an ETag error with the previous refreshing @PUBLISH@, calling this method with a body of @None@ will throw a @PublicationError@.
2263 117 Adrian Georgescu
  
2264 117 Adrian Georgescu
>+_route_header_+:
2265 103 Adrian Georgescu
2266 117 Adrian Georgescu
>The host where the request should be sent to in the form of a @(Frozen)RouteHeader@ object.
2267 117 Adrian Georgescu
  
2268 117 Adrian Georgescu
>+_timeout_+:
2269 103 Adrian Georgescu
2270 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.
2271 117 Adrian Georgescu
>This is is @None@, the internal 408 is only triggered by the internal PJSIP transaction timeout.
2272 117 Adrian Georgescu
>Note that, even if the timeout is specified, the PJSIP timeout is also still valid.
2273 103 Adrian Georgescu
2274 117 Adrian Georgescu
*end*(_self_, *timeout*=@None@)
2275 117 Adrian Georgescu
>End the publication by sending a @PUBLISH@ request with an @Expires@ header of 0.
2276 117 Adrian Georgescu
>If the object is not published, this will result in a @PublicationError@ being thrown.
2277 117 Adrian Georgescu
  
2278 117 Adrian Georgescu
>+_timeout_+:
2279 103 Adrian Georgescu
2280 117 Adrian Georgescu
>The meaning of this argument is the same as it is for the @publish()@ method.
2281 103 Adrian Georgescu
2282 103 Adrian Georgescu
2283 117 Adrian Georgescu
h4. attributes
2284 103 Adrian Georgescu
2285 103 Adrian Georgescu
2286 103 Adrian Georgescu
2287 117 Adrian Georgescu
*from_header_
2288 117 Adrian Georgescu
>The @(Frozen)FromHeader@ the @Publication@ was sent with.
2289 103 Adrian Georgescu
2290 117 Adrian Georgescu
*event_
2291 117 Adrian Georgescu
>The name of the event this object is publishing for the specified SIP URI, as a string.
2292 103 Adrian Georgescu
2293 117 Adrian Georgescu
*content_type_
2294 117 Adrian Georgescu
>The @Content-Type@ of the body that will be in the @PUBLISH@ requests.
2295 117 Adrian Georgescu
>Typically this will remain the same throughout the publication session, but the attribute may be updated by the application if needed.
2296 117 Adrian Georgescu
>Note that this attribute needs to be in the typical MIME type form, containing a "/" character.
2297 103 Adrian Georgescu
2298 117 Adrian Georgescu
*credentials*
2299 117 Adrian Georgescu
>The credentials to be used when challenged for authentication by the presence agent, represented by a @(Frozen)Credentials@ object. 
2300 117 Adrian Georgescu
>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.
2301 117 Adrian Georgescu
>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.
2302 103 Adrian Georgescu
2303 117 Adrian Georgescu
*duration*
2304 117 Adrian Georgescu
>The amount of time in seconds that the publication should be valid for.
2305 117 Adrian Georgescu
>This attribute is set at object instantiation and can be updated for subsequent @PUBLISH@ requests.
2306 103 Adrian Georgescu
2307 117 Adrian Georgescu
*is_published*
2308 117 Adrian Georgescu
>A boolean read-only property indicating if this object is currently published.
2309 103 Adrian Georgescu
2310 117 Adrian Georgescu
*expires_in*
2311 117 Adrian Georgescu
>If published, this read-only property indicates in how many seconds from now this @Publication@ will expire.
2312 117 Adrian Georgescu
>If this is not the case, this property is 0.
2313 103 Adrian Georgescu
2314 117 Adrian Georgescu
*peer_address*
2315 117 Adrian Georgescu
>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.
2316 103 Adrian Georgescu
2317 117 Adrian Georgescu
2318 117 Adrian Georgescu
h4. notifications
2319 117 Adrian Georgescu
2320 117 Adrian Georgescu
2321 117 Adrian Georgescu
2322 117 Adrian Georgescu
*SIPPublicationDidSucceed*
2323 117 Adrian Georgescu
>This notification will be sent when the @publish()@ method was called and the publication succeeded.
2324 117 Adrian Georgescu
  
2325 117 Adrian Georgescu
>+_code_+:
2326 117 Adrian Georgescu
2327 117 Adrian Georgescu
>The SIP response code as received from the SIP presence agent as an int.
2328 117 Adrian Georgescu
  
2329 117 Adrian Georgescu
>+_reason_+:
2330 117 Adrian Georgescu
2331 117 Adrian Georgescu
>The reason string received from the SIP presence agent.
2332 117 Adrian Georgescu
  
2333 117 Adrian Georgescu
>+_route_header_+:
2334 117 Adrian Georgescu
2335 117 Adrian Georgescu
>The @(Frozen)RouteHeader@ object passed as an argument to the @publish()@ method.
2336 117 Adrian Georgescu
  
2337 117 Adrian Georgescu
>+_expires_in_+:
2338 117 Adrian Georgescu
2339 117 Adrian Georgescu
>The number of seconds before this publication expires
2340 117 Adrian Georgescu
2341 117 Adrian Georgescu
*SIPPublicationDidFail*
2342 117 Adrian Georgescu
>This notification will be sent when the @publish()@ method was called and the publication failed, for whatever reason.
2343 117 Adrian Georgescu
  
2344 117 Adrian Georgescu
>+_code_+:
2345 117 Adrian Georgescu
2346 117 Adrian Georgescu
>The SIP response code as received from the presence agent as an int.
2347 117 Adrian Georgescu
>This can also be a PJSIP generated response code, or 0 if the failure was because of an internal error.
2348 117 Adrian Georgescu
  
2349 117 Adrian Georgescu
>+_reason_+:
2350 117 Adrian Georgescu
2351 117 Adrian Georgescu
>The reason string received from the presence agent or the error string.
2352 117 Adrian Georgescu
  
2353 117 Adrian Georgescu
>+_route_header_+:
2354 117 Adrian Georgescu
2355 117 Adrian Georgescu
>The @(Frozen)RouteHeader@ object passed as an argument to the @publish()@ method.
2356 117 Adrian Georgescu
2357 117 Adrian Georgescu
*SIPPublicationWillExpire*
2358 117 Adrian Georgescu
>This notification will be sent when a publication will expire soon.
2359 117 Adrian Georgescu
>It should be used as an indication to re-perform DNS lookup of the presence agent and call the @publish()@ method.
2360 117 Adrian Georgescu
  
2361 117 Adrian Georgescu
>+_expires_+:
2362 117 Adrian Georgescu
2363 117 Adrian Georgescu
>The number of seconds in which the publication will expire.
2364 117 Adrian Georgescu
2365 117 Adrian Georgescu
*SIPPublicationWillEnd*
2366 117 Adrian Georgescu
>Will be sent whenever the @end()@ method was called and an unpublishing @PUBLISH@ is sent.
2367 117 Adrian Georgescu
2368 117 Adrian Georgescu
*SIPPublicationDidNotEnd*
2369 117 Adrian Georgescu
>This notification will be sent when the unpublishing @PUBLISH@ request failed for some reason.
2370 117 Adrian Georgescu
  
2371 117 Adrian Georgescu
>+_code_+:
2372 117 Adrian Georgescu
2373 117 Adrian Georgescu
>The SIP response code as received from the presence agent as an int.
2374 117 Adrian Georgescu
>This can also be a PJSIP generated response code, or 0 if the failure was because of an internal error.
2375 117 Adrian Georgescu
  
2376 117 Adrian Georgescu
>+_reason_+:
2377 117 Adrian Georgescu
2378 117 Adrian Georgescu
>The reason string received from the presence agent or the error string.
2379 117 Adrian Georgescu
2380 117 Adrian Georgescu
*SIPPublicationDidEnd*
2381 117 Adrian Georgescu
>This notification will be sent when a @Publication@ has become unpublished.
2382 117 Adrian Georgescu
  
2383 117 Adrian Georgescu
>+_expired_+:
2384 117 Adrian Georgescu
2385 117 Adrian Georgescu
>This boolean indicates if the object is unpublished because the publication expired, in which case it will be set to @True@.
2386 117 Adrian Georgescu
>If this data attribute is @False@, it means that unpublication was explicitly requested through the @end()@ method.
2387 117 Adrian Georgescu
2388 117 Adrian Georgescu
2389 117 Adrian Georgescu
h3. Subscription
2390 117 Adrian Georgescu
2391 117 Adrian Georgescu
2392 117 Adrian Georgescu
Subscription and notifications for SIP events is an Internet standard published at "RFC 3856":http://tools.ietf.org/html/rfc3856.
2393 117 Adrian Georgescu
2394 1 Adrian Georgescu
This SIP primitive class represents a subscription to a specific event type of a particular SIP URI.
2395 1 Adrian Georgescu
This means that the application should instance this class for each combination of event and SIP URI that it wishes to subscribe to.
2396 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.
2397 117 Adrian Georgescu
Whenever a @NOTIFY@ is received, the application will receive the @SIPSubscriptionGotNotify@ event.
2398 1 Adrian Georgescu
2399 117 Adrian Georgescu
Internally a @Subscription@ object has a state machine, which reflects the state of the subscription.
2400 117 Adrian Georgescu
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@.
2401 117 Adrian Georgescu
The last three states are directly copied from the contents of the @Subscription-State@ header of the received @NOTIFY@ request.
2402 117 Adrian Georgescu
Also, the state can be an arbitrary string if the contents of the @Subscription-State@ header are not one of the three above.
2403 117 Adrian Georgescu
The state of the object is presented in the @state@ attribute and changes of the state are indicated by means of the @SIPSubscriptionChangedState@ notification.
2404 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.
2405 1 Adrian Georgescu
2406 1 Adrian Georgescu
2407 117 Adrian Georgescu
h4. methods
2408 1 Adrian Georgescu
2409 1 Adrian Georgescu
2410 1 Adrian Georgescu
2411 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_, *request_uri*, *from_header*, *to_header*, *contact_header, *event*, *route_header*, *credentials*=@None@, *refresh*=300)
2412 117 Adrian Georgescu
>Creates a new @Subscription@ object which will be in the @NULL@ state.
2413 117 Adrian Georgescu
>The arguments for this method are documented in the attributes section above.
2414 1 Adrian Georgescu
2415 117 Adrian Georgescu
*subscribe*(_self_, *extra_headers*=@None@, *content_type*=@None@, *body*=@None@, *timeout*=@None@)
2416 117 Adrian Georgescu
>Calling this method triggers sending a @SUBSCRIBE@ request to the presence agent.
2417 117 Adrian Georgescu
>The arguments passed will be stored and used for subsequent refreshing @SUBSCRIBE@ requests.
2418 117 Adrian Georgescu
>This method may be used both to send the initial request and to update the arguments while the subscription is ongoing.
2419 117 Adrian Georgescu
>It may not be called when the object is in the @TERMINATED@ state.
2420 117 Adrian Georgescu
  
2421 117 Adrian Georgescu
>+_extra_headers_+:
2422 1 Adrian Georgescu
2423 117 Adrian Georgescu
>A dictionary of additional headers to include in the @SUBSCRIBE@ requests.
2424 117 Adrian Georgescu
  
2425 117 Adrian Georgescu
>+_content_type_+:
2426 1 Adrian Georgescu
2427 117 Adrian Georgescu
>The @Content-Type@ of the supplied @body@ argument as a string.
2428 117 Adrian Georgescu
>If this argument is supplied, the @body@ argument cannot be @None@.
2429 117 Adrian Georgescu
  
2430 117 Adrian Georgescu
>+_body_+:
2431 1 Adrian Georgescu
2432 117 Adrian Georgescu
>The optional body to include in the @SUBSCRIBE@ request as a string.
2433 117 Adrian Georgescu
>If this argument is supplied, the @content_type@ argument cannot be @None@.
2434 117 Adrian Georgescu
  
2435 117 Adrian Georgescu
>+_timeout_+:
2436 1 Adrian Georgescu
2437 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.
2438 117 Adrian Georgescu
>If this is @None@, the internal 408 is only triggered by the internal PJSIP transaction timeout.
2439 117 Adrian Georgescu
>Note that, even if the timeout is specified, the PJSIP timeout is also still valid.
2440 1 Adrian Georgescu
2441 117 Adrian Georgescu
*end*(_self_, *timeout*=@None@)
2442 117 Adrian Georgescu
>This will end the subscription by sending a @SUBSCRIBE@ request with an @Expires@ value of 0.
2443 117 Adrian Georgescu
>If this object is no longer subscribed, this method will return without performing any action.
2444 117 Adrian Georgescu
>This method cannot be called when the object is in the @NULL@ state.
2445 117 Adrian Georgescu
>The @timeout@ argument has the same meaning as it does for the @subscribe()@ method.
2446 1 Adrian Georgescu
2447 1 Adrian Georgescu
2448 117 Adrian Georgescu
h4. attributes
2449 1 Adrian Georgescu
2450 1 Adrian Georgescu
2451 1 Adrian Georgescu
2452 117 Adrian Georgescu
*state*
2453 117 Adrian Georgescu
>Indicates which state the internal state machine is in.
2454 117 Adrian Georgescu
>See the previous section for a list of states the state machine can be in.
2455 1 Adrian Georgescu
2456 117 Adrian Georgescu
*from_header*
2457 117 Adrian Georgescu
>The @FrozenFromHeader@ to be put in the @From@ header of the @SUBSCRIBE@ requests.
2458 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
2459 1 Adrian Georgescu
2460 117 Adrian Georgescu
*to_header*
2461 117 Adrian Georgescu
>The @FrozenToHeader@ that is the target for the subscription.
2462 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
2463 1 Adrian Georgescu
2464 117 Adrian Georgescu
*contact_header*
2465 117 Adrian Georgescu
>The @FrozenContactHeader@ to be put in the @Contact@ header of the @SUBSCRIBE@ requests.
2466 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
2467 1 Adrian Georgescu
2468 117 Adrian Georgescu
*event*
2469 117 Adrian Georgescu
>The event package for which the subscription is as a string.
2470 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
2471 1 Adrian Georgescu
2472 117 Adrian Georgescu
*route_header*
2473 117 Adrian Georgescu
>The outbound proxy to use in the form of a @FrozenRouteHeader@ object.
2474 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
2475 1 Adrian Georgescu
2476 117 Adrian Georgescu
*credentials*
2477 117 Adrian Georgescu
>The SIP credentials needed to authenticate at the SIP proxy in the form of a @FrozenCredentials@ object.
2478 117 Adrian Georgescu
>If none was specified when creating the @Subscription@ object, this attribute is @None@.
2479 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
2480 1 Adrian Georgescu
2481 117 Adrian Georgescu
*refresh*
2482 117 Adrian Georgescu
>The refresh interval in seconds that was requested on object instantiation as an int.
2483 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
2484 1 Adrian Georgescu
2485 117 Adrian Georgescu
*extra_headers*
2486 117 Adrian Georgescu
>This contains the @frozenlist@ of extra headers that was last passed to a successful call to the @subscribe()@ method.
2487 117 Adrian Georgescu
>If the argument was not provided, this attribute is an empty list.
2488 117 Adrian Georgescu
>This attribute is read-only.
2489 1 Adrian Georgescu
2490 117 Adrian Georgescu
*content_type*
2491 117 Adrian Georgescu
>This attribute contains the @Content-Type@ of the body that was last passed to a successful call to the @subscribe()@ method.
2492 117 Adrian Georgescu
>If the argument was not provided, this attribute is @None@.
2493 1 Adrian Georgescu
2494 117 Adrian Georgescu
*body*
2495 117 Adrian Georgescu
>This attribute contains the @body@ string argument that was last passed to a successful call to the @subscribe()@ method.
2496 117 Adrian Georgescu
>If the argument was not provided, this attribute is @None@.
2497 1 Adrian Georgescu
2498 117 Adrian Georgescu
*peer_address*
2499 117 Adrian Georgescu
>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.
2500 1 Adrian Georgescu
2501 1 Adrian Georgescu
2502 117 Adrian Georgescu
h4. notifications
2503 1 Adrian Georgescu
2504 1 Adrian Georgescu
2505 1 Adrian Georgescu
2506 117 Adrian Georgescu
*SIPSubscriptionChangedState*
2507 117 Adrian Georgescu
>This notification will be sent every time the internal state machine of a @Subscription@ object changes state.
2508 117 Adrian Georgescu
  
2509 117 Adrian Georgescu
>+_timestamp_+:
2510 1 Adrian Georgescu
2511 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2512 117 Adrian Georgescu
  
2513 117 Adrian Georgescu
>+_prev_state_+:
2514 1 Adrian Georgescu
2515 117 Adrian Georgescu
>The previous state that the sate machine was in.
2516 117 Adrian Georgescu
  
2517 117 Adrian Georgescu
>+_state_+:
2518 1 Adrian Georgescu
2519 117 Adrian Georgescu
>The new state the state machine moved into.
2520 1 Adrian Georgescu
2521 117 Adrian Georgescu
*SIPSubscriptionWillStart*
2522 117 Adrian Georgescu
>This notification will be emitted when the initial @SUBSCRIBE@ request is sent.
2523 117 Adrian Georgescu
  
2524 117 Adrian Georgescu
>+_timestamp_+:
2525 1 Adrian Georgescu
2526 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2527 1 Adrian Georgescu
2528 117 Adrian Georgescu
*SIPSubscriptionDidStart*
2529 117 Adrian Georgescu
>This notification will be sent when the initial @SUBSCRIBE@ was accepted by the presence agent.
2530 117 Adrian Georgescu
  
2531 117 Adrian Georgescu
>+_timestamp_+:
2532 1 Adrian Georgescu
2533 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2534 1 Adrian Georgescu
2535 117 Adrian Georgescu
*SIPSubscriptionGotNotify*
2536 117 Adrian Georgescu
>This notification will be sent when a @NOTIFY@ is received that corresponds to a particular @Subscription@ object.
2537 117 Adrian Georgescu
>Note that this notification could be sent when a @NOTIFY@ without a body is received.
2538 117 Adrian Georgescu
  
2539 117 Adrian Georgescu
>+_request_uri_+:
2540 1 Adrian Georgescu
2541 117 Adrian Georgescu
>The request URI of the @NOTIFY@ request as a @SIPURI@ object.
2542 117 Adrian Georgescu
  
2543 117 Adrian Georgescu
>+_from_header_+:
2544 1 Adrian Georgescu
2545 117 Adrian Georgescu
>The From header of the @NOTIFY@ request as a @FrozenFromHeader@ object.
2546 117 Adrian Georgescu
  
2547 117 Adrian Georgescu
>+_to_header_+:
2548 1 Adrian Georgescu
2549 117 Adrian Georgescu
>The To header of the @NOTIFY@ request as a @FrozenToHeader@ object.
2550 117 Adrian Georgescu
  
2551 117 Adrian Georgescu
>+_content_type_+:
2552 1 Adrian Georgescu
2553 117 Adrian Georgescu
>The Content-Type header value of the @NOTIFY@ request as a @ContentType@ object.
2554 117 Adrian Georgescu
  
2555 117 Adrian Georgescu
>+_event_+:
2556 1 Adrian Georgescu
2557 117 Adrian Georgescu
>The Event header value of the @NOTIFY@ request as a string object.
2558 117 Adrian Georgescu
  
2559 117 Adrian Georgescu
>+_headers_+:
2560 1 Adrian Georgescu
2561 117 Adrian Georgescu
>The headers of the @NOTIFY@ request as a dict.
2562 117 Adrian Georgescu
>Each SIP header is represented in its parsed for as long as PJSIP supports it.
2563 117 Adrian Georgescu
>The format of the parsed value depends on the header.
2564 117 Adrian Georgescu
  
2565 117 Adrian Georgescu
>+_body_+:
2566 1 Adrian Georgescu
2567 117 Adrian Georgescu
>The body of the @NOTIFY@ request as a string, or @None@ if no body was included.
2568 117 Adrian Georgescu
  
2569 117 Adrian Georgescu
>+_timestamp_+:
2570 1 Adrian Georgescu
2571 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.  
2572 1 Adrian Georgescu
2573 117 Adrian Georgescu
*SIPSubscriptionDidFail*
2574 117 Adrian Georgescu
>This notification will be sent whenever there is a failure, such as a rejected initial or refreshing @SUBSCRIBE@.
2575 117 Adrian Georgescu
>After this notification the @Subscription@ object is in the @TERMINATED@ state and can no longer be used.
2576 117 Adrian Georgescu
  
2577 117 Adrian Georgescu
>+_timestamp_+:
2578 1 Adrian Georgescu
2579 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2580 117 Adrian Georgescu
  
2581 117 Adrian Georgescu
>+_code_+:
2582 1 Adrian Georgescu
2583 117 Adrian Georgescu
>An integer SIP code from the fatal response that was received from the remote party of generated by PJSIP.
2584 117 Adrian Georgescu
>If the error is internal to the SIP core, this attribute will have a value of 0.
2585 117 Adrian Georgescu
  
2586 117 Adrian Georgescu
>+_reason_+:
2587 1 Adrian Georgescu
2588 117 Adrian Georgescu
>An text string describing the failure that occurred.
2589 117 Adrian Georgescu
  
2590 117 Adrian Georgescu
>+_min_expires_+:
2591 1 Adrian Georgescu
2592 117 Adrian Georgescu
>An integer containing the value from the Min-Expires header. Will be None if the response doesn't contain the header.
2593 1 Adrian Georgescu
2594 117 Adrian Georgescu
*SIPSubscriptionDidEnd*
2595 117 Adrian Georgescu
>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.
2596 117 Adrian Georgescu
>After this notification the @Subscription@ object is in the @TERMINATED@ state and can no longer be used.
2597 117 Adrian Georgescu
  
2598 117 Adrian Georgescu
>+_timestamp_+:
2599 1 Adrian Georgescu
2600 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2601 1 Adrian Georgescu
2602 1 Adrian Georgescu
2603 117 Adrian Georgescu
h3. IncomingSubscription
2604 1 Adrian Georgescu
2605 1 Adrian Georgescu
2606 117 Adrian Georgescu
Subscription and notifications for SIP events is an Internet standard published at "RFC 3856":http://tools.ietf.org/html/rfc3856.
2607 1 Adrian Georgescu
2608 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.
2609 117 Adrian Georgescu
This means that it can accept a @SUBSCRIBE@ request and subsequent refreshing @SUBSCRIBE@s and sent @NOTIFY@ requests containing event state.
2610 117 Adrian Georgescu
2611 117 Adrian Georgescu
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.
2612 117 Adrian Georgescu
This event needs to be known by the @Engine@, i.e. it should already be present in the @events@ dictionary attribute.
2613 117 Adrian Georgescu
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.
2614 117 Adrian Georgescu
This will be indicated to the application through a @SIPIncomingSubscriptionGotSubscribe@ notification.
2615 117 Adrian Georgescu
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.
2616 117 Adrian Georgescu
2617 117 Adrian Georgescu
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.
2618 117 Adrian Georgescu
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.
2619 117 Adrian Georgescu
Whenever a refreshing @SUBSCRIBE@ is received, the latest contents to be set are sent in the resulting @NOTIFY@ request.
2620 117 Adrian Georgescu
The subscription can be ended by using the @end()@ method.
2621 117 Adrian Georgescu
2622 117 Adrian Georgescu
2623 117 Adrian Georgescu
h4. methods
2624 117 Adrian Georgescu
2625 117 Adrian Georgescu
2626 117 Adrian Georgescu
2627 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_)
2628 117 Adrian Georgescu
>An application should never create an @IncomingSubscription@ object itself.
2629 117 Adrian Georgescu
>Doing this will create a useless object in the @None@ state.
2630 117 Adrian Georgescu
2631 117 Adrian Georgescu
*reject*(_self_, *code*)
2632 117 Adrian Georgescu
>Will reply to the initial @SUBSCRIBE@ with a negative response.
2633 117 Adrian Georgescu
>This method can only be called in the @"incoming"@ state and sets the subscription to the @"terminated"@ state.
2634 117 Adrian Georgescu
  
2635 117 Adrian Georgescu
>+_code_+:
2636 117 Adrian Georgescu
2637 117 Adrian Georgescu
>The SIP response code to use.
2638 117 Adrian Georgescu
>This should be a negative response, i.e. in the 3xx, 4xx, 5xx or 6xx range.
2639 117 Adrian Georgescu
2640 117 Adrian Georgescu
*accept_pending*(_self_)
2641 117 Adrian Georgescu
>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.
2642 117 Adrian Georgescu
>The application can later decide to fully accept the subscription or terminate it.
2643 117 Adrian Georgescu
>This method can only be called in the @"incoming"@ state.
2644 117 Adrian Georgescu
2645 117 Adrian Georgescu
*accept*(_self_, *content_type*=@None@, *content*=@None@)
2646 117 Adrian Georgescu
>Accept the initial incoming @SUBSCRIBE@ and respond to it with a 200 OK, or fully accept an @IncomingSubscription@ that is in the @"pending"@ state.
2647 117 Adrian Georgescu
>In either case, a @NOTIFY@ will be sent to update the state to "active", optionally with the content specified in the arguments.
2648 117 Adrian Georgescu
>This method can only be called in the @"incoming"@ or @"pending"@ state.
2649 117 Adrian Georgescu
  
2650 117 Adrian Georgescu
>+_content_type_+:
2651 117 Adrian Georgescu
2652 117 Adrian Georgescu
>The Content-Type of the content to be set supplied as a string containing a @"/"@ character.
2653 117 Adrian Georgescu
>Note that if this argument is set, the @content@ argument should also be set.
2654 117 Adrian Georgescu
  
2655 117 Adrian Georgescu
>+_content_+:
2656 117 Adrian Georgescu
2657 117 Adrian Georgescu
>The body of the @NOTIFY@ to send when accepting the subscription, as a string.
2658 117 Adrian Georgescu
>Note that if this argument is set, the @content_type@ argument should also be set.
2659 117 Adrian Georgescu
2660 117 Adrian Georgescu
*push_content*(_self_, *content_type*, *content*)
2661 117 Adrian Georgescu
>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.
2662 117 Adrian Georgescu
>This method can only be called in the @"active"@ state.
2663 117 Adrian Georgescu
  
2664 117 Adrian Georgescu
>+_content_type_+:
2665 117 Adrian Georgescu
2666 117 Adrian Georgescu
>The Content-Type of the content to be set supplied as a string containing a @"/"@ character.
2667 117 Adrian Georgescu
  
2668 117 Adrian Georgescu
>+_content_+:
2669 117 Adrian Georgescu
2670 117 Adrian Georgescu
>The body of the @NOTIFY@ as a string.
2671 117 Adrian Georgescu
2672 117 Adrian Georgescu
2673 117 Adrian Georgescu
h4. attributes
2674 117 Adrian Georgescu
2675 117 Adrian Georgescu
2676 117 Adrian Georgescu
2677 117 Adrian Georgescu
*state*
2678 117 Adrian Georgescu
>Indicates which state the incoming subscription session is in.
2679 117 Adrian Georgescu
>This can be one of @None@, @"incoming"@, @"pending"@, @"active"@ or @"terminated"@.
2680 117 Adrian Georgescu
>This attribute is read-only.
2681 117 Adrian Georgescu
2682 117 Adrian Georgescu
*event*
2683 117 Adrian Georgescu
>The name of the event package that this @IncomingSubscription@ relates to.
2684 117 Adrian Georgescu
>This attribute is a read-only string.
2685 117 Adrian Georgescu
2686 117 Adrian Georgescu
*content_type*
2687 117 Adrian Georgescu
>The @Content-Type@ of the last set content in this subscription session.
2688 117 Adrian Georgescu
>Inititally this will be @None@.
2689 117 Adrian Georgescu
>This attribute is a read-only string.
2690 117 Adrian Georgescu
2691 117 Adrian Georgescu
*content*
2692 117 Adrian Georgescu
>The last set content in this subscription session as a read-only string.
2693 117 Adrian Georgescu
2694 117 Adrian Georgescu
*peer_address*
2695 117 Adrian Georgescu
>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.
2696 117 Adrian Georgescu
2697 117 Adrian Georgescu
2698 117 Adrian Georgescu
h4. notifications
2699 117 Adrian Georgescu
2700 117 Adrian Georgescu
2701 117 Adrian Georgescu
2702 117 Adrian Georgescu
*SIPIncomingSubscriptionChangedState*
2703 117 Adrian Georgescu
>This notification will be sent every time the an @IncomingSubscription@ object changes state.
2704 117 Adrian Georgescu
>This notification is mostly indicative, an application should not let its logic depend on it.
2705 117 Adrian Georgescu
  
2706 117 Adrian Georgescu
>+_timestamp_+:
2707 117 Adrian Georgescu
2708 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2709 117 Adrian Georgescu
  
2710 117 Adrian Georgescu
>+_prev_state_+:
2711 117 Adrian Georgescu
2712 117 Adrian Georgescu
>The previous state that the subscription was in.
2713 117 Adrian Georgescu
  
2714 117 Adrian Georgescu
>+_state_+:
2715 117 Adrian Georgescu
2716 117 Adrian Georgescu
>The new state the subscription has.
2717 117 Adrian Georgescu
2718 117 Adrian Georgescu
*SIPIncomingSubscriptionGotSubscribe*
2719 117 Adrian Georgescu
>This notification will be sent when a new @IncomingSubscription@ is created as result of an incoming @SUBSCRIBE@ request.
2720 117 Adrian Georgescu
>The application should listen for this notification, retain a reference to the object that sent it and either accept or reject it.
2721 117 Adrian Georgescu
  
2722 117 Adrian Georgescu
>+_timestamp_+:
2723 117 Adrian Georgescu
2724 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2725 117 Adrian Georgescu
  
2726 117 Adrian Georgescu
>+_method_+:
2727 117 Adrian Georgescu
2728 117 Adrian Georgescu
>The method of the SIP request as a string, which will be @SUBSCRIBE@.
2729 117 Adrian Georgescu
  
2730 117 Adrian Georgescu
>+_request_uri_+:
2731 117 Adrian Georgescu
2732 117 Adrian Georgescu
>The request URI of the @SUBSCRIBE@ request as a @FrozenSIPURI@ object.
2733 117 Adrian Georgescu
  
2734 117 Adrian Georgescu
>+_headers_+:
2735 117 Adrian Georgescu
2736 117 Adrian Georgescu
>The headers of the @SUBSCRIBE@ request as a dict, the values of which are the relevant header objects.
2737 117 Adrian Georgescu
  
2738 117 Adrian Georgescu
>+_body_+:
2739 117 Adrian Georgescu
2740 117 Adrian Georgescu
>The body of the @SUBSCRIBE@ request as a string, or @None@ if no body was included.
2741 117 Adrian Georgescu
2742 117 Adrian Georgescu
*SIPIncomingSubscriptionGotRefreshingSubscribe*
2743 117 Adrian Georgescu
>This notification indicates that a refreshing @SUBSCRIBE@ request was received from the subscriber.
2744 117 Adrian Georgescu
>It is purely informative, no action needs to be taken by the application as a result of it.
2745 117 Adrian Georgescu
  
2746 117 Adrian Georgescu
>+_timestamp_+:
2747 117 Adrian Georgescu
2748 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2749 117 Adrian Georgescu
  
2750 117 Adrian Georgescu
>+_method_+:
2751 117 Adrian Georgescu
2752 117 Adrian Georgescu
>The method of the SIP request as a string, which will be @SUBSCRIBE@.
2753 117 Adrian Georgescu
  
2754 117 Adrian Georgescu
>+_request_uri_+:
2755 117 Adrian Georgescu
2756 117 Adrian Georgescu
>The request URI of the @SUBSCRIBE@ request as a @FrozenSIPURI@ object.
2757 117 Adrian Georgescu
  
2758 117 Adrian Georgescu
>+_headers_+:
2759 117 Adrian Georgescu
2760 117 Adrian Georgescu
>The headers of the @SUBSCRIBE@ request as a dict, the values of which are the relevant header objects.
2761 117 Adrian Georgescu
  
2762 117 Adrian Georgescu
>+_body_+:
2763 117 Adrian Georgescu
2764 117 Adrian Georgescu
>The body of the @SUBSCRIBE@ request as a string, or @None@ if no body was included.
2765 117 Adrian Georgescu
2766 117 Adrian Georgescu
*SIPIncomingSubscriptionGotUnsubscribe*
2767 117 Adrian Georgescu
>This notification indicates that a @SUBSCRIBE@ request with an @Expires@ header of 0 was received from the subscriber, effectively requesting to unsubscribe.
2768 117 Adrian Georgescu
>It is purely informative, no action needs to be taken by the application as a result of it.
2769 117 Adrian Georgescu
  
2770 117 Adrian Georgescu
>+_timestamp_+:
2771 117 Adrian Georgescu
2772 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2773 117 Adrian Georgescu
  
2774 117 Adrian Georgescu
>+_method_+:
2775 117 Adrian Georgescu
2776 117 Adrian Georgescu
>The method of the SIP request as a string, which will be @SUBSCRIBE@.
2777 117 Adrian Georgescu
  
2778 117 Adrian Georgescu
>+_request_uri_+:
2779 117 Adrian Georgescu
2780 117 Adrian Georgescu
>The request URI of the @SUBSCRIBE@ request as a @FrozenSIPURI@ object.
2781 117 Adrian Georgescu
  
2782 117 Adrian Georgescu
>+_headers_+:
2783 117 Adrian Georgescu
2784 117 Adrian Georgescu
>The headers of the @SUBSCRIBE@ request as a dict, the values of which are the relevant header objects.
2785 117 Adrian Georgescu
  
2786 117 Adrian Georgescu
>+_body_+:
2787 117 Adrian Georgescu
2788 117 Adrian Georgescu
>The body of the @SUBSCRIBE@ request or response as a string, or @None@ if no body was included.
2789 117 Adrian Georgescu
2790 117 Adrian Georgescu
*SIPIncomingSubscriptionAnsweredSubscribe*
2791 117 Adrian Georgescu
>This notification is sent whenever a response to a @SUBSCRIBE@ request is sent by the object, including an unsubscribing @SUBSCRIBE@.
2792 117 Adrian Georgescu
>It is purely informative, no action needs to be taken by the application as a result of it.
2793 117 Adrian Georgescu
  
2794 117 Adrian Georgescu
>+_timestamp_+:
2795 117 Adrian Georgescu
2796 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2797 117 Adrian Georgescu
  
2798 117 Adrian Georgescu
>+_code_+:
2799 117 Adrian Georgescu
2800 117 Adrian Georgescu
>The code of the SIP response as an int.
2801 117 Adrian Georgescu
  
2802 117 Adrian Georgescu
>+_reason_+:
2803 117 Adrian Georgescu
2804 117 Adrian Georgescu
>The reason text of the SIP response as an int.
2805 117 Adrian Georgescu
  
2806 117 Adrian Georgescu
>+_headers_+:
2807 117 Adrian Georgescu
2808 117 Adrian Georgescu
>The headers of the response as a dict, the values of which are the relevant header objects.
2809 117 Adrian Georgescu
  
2810 117 Adrian Georgescu
>+_body_+:
2811 117 Adrian Georgescu
2812 117 Adrian Georgescu
>This will be @None@.
2813 117 Adrian Georgescu
2814 117 Adrian Georgescu
*SIPIncomingSubscriptionSentNotify*
2815 117 Adrian Georgescu
>This notification indicates that a @NOTIFY@ request was sent to the subscriber.
2816 117 Adrian Georgescu
>It is purely informative, no action needs to be taken by the application as a result of it.
2817 117 Adrian Georgescu
  
2818 117 Adrian Georgescu
>+_timestamp_+:
2819 117 Adrian Georgescu
2820 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2821 117 Adrian Georgescu
  
2822 117 Adrian Georgescu
>+_method_+:
2823 117 Adrian Georgescu
2824 117 Adrian Georgescu
>The method of the SIP request as a string, which will be @NOTIFY@.
2825 117 Adrian Georgescu
  
2826 117 Adrian Georgescu
>+_request_uri_+:
2827 117 Adrian Georgescu
2828 117 Adrian Georgescu
>The request URI of the @NOTIFY@ request as a @FrozenSIPURI@ object.
2829 117 Adrian Georgescu
  
2830 117 Adrian Georgescu
>+_headers_+:
2831 117 Adrian Georgescu
2832 117 Adrian Georgescu
>The headers of the @NOTIFY@ request as a dict, the values of which are the relevant header objects.
2833 117 Adrian Georgescu
  
2834 117 Adrian Georgescu
>+_body_+:
2835 117 Adrian Georgescu
2836 117 Adrian Georgescu
>The body of the @NOTIFY@ request or response as a string, or @None@ if no body was included.
2837 117 Adrian Georgescu
2838 117 Adrian Georgescu
*SIPIncomingSubscriptionNotifyDidSucceed*
2839 117 Adrian Georgescu
>This indicates that a positive final response was received from the subscriber in reply to a sent @NOTIFY@ request.
2840 117 Adrian Georgescu
>The notification is purely informative, no action needs to be taken by the application as a result of it.
2841 117 Adrian Georgescu
  
2842 117 Adrian Georgescu
>+_timestamp_+:
2843 117 Adrian Georgescu
2844 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2845 117 Adrian Georgescu
  
2846 117 Adrian Georgescu
>+_code_+:
2847 117 Adrian Georgescu
2848 117 Adrian Georgescu
>The code of the SIP response as an int.
2849 117 Adrian Georgescu
  
2850 117 Adrian Georgescu
>+_reason_+:
2851 117 Adrian Georgescu
2852 117 Adrian Georgescu
>The reason text of the SIP response as a string.
2853 117 Adrian Georgescu
  
2854 117 Adrian Georgescu
>+_headers_+:
2855 117 Adrian Georgescu
2856 117 Adrian Georgescu
>The headers of the response as a dict, the values of which are the relevant header objects.
2857 117 Adrian Georgescu
  
2858 117 Adrian Georgescu
>+_body_+:
2859 117 Adrian Georgescu
2860 117 Adrian Georgescu
>This will be @None@.
2861 117 Adrian Georgescu
2862 117 Adrian Georgescu
*SIPIncomingSubscriptionNotifyDidFail*
2863 117 Adrian Georgescu
>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.
2864 117 Adrian Georgescu
  
2865 117 Adrian Georgescu
>+_timestamp_+:
2866 117 Adrian Georgescu
2867 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2868 117 Adrian Georgescu
  
2869 117 Adrian Georgescu
>+_code_+:
2870 117 Adrian Georgescu
2871 117 Adrian Georgescu
>The code of the SIP response as an int.
2872 117 Adrian Georgescu
>If this is 0, the notification was sent as a result of an internal error.
2873 117 Adrian Georgescu
  
2874 117 Adrian Georgescu
>+_reason_+:
2875 117 Adrian Georgescu
2876 117 Adrian Georgescu
>The reason text of the SIP response as a string or the internal error if the code attribute is 0.
2877 117 Adrian Georgescu
  
2878 117 Adrian Georgescu
>+_headers_+: (if the notification was caused by a negative response)
2879 117 Adrian Georgescu
2880 117 Adrian Georgescu
>The headers of the response as a dict, the values of which are the relevant header objects.
2881 117 Adrian Georgescu
  
2882 117 Adrian Georgescu
>+_body_+: (if the notification was caused by a negative response)
2883 117 Adrian Georgescu
2884 117 Adrian Georgescu
>This will be @None@.
2885 117 Adrian Georgescu
2886 117 Adrian Georgescu
*SIPIncomingSubscriptionDidEnd*
2887 117 Adrian Georgescu
>This notification is sent whenever the @IncomingSubscription@ object reaches the @"terminated"@ state and is no longer valid.
2888 117 Adrian Georgescu
>After receiving this notification, the application should not longer try to use the object.
2889 117 Adrian Georgescu
  
2890 117 Adrian Georgescu
>+_timestamp_+:
2891 117 Adrian Georgescu
2892 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2893 117 Adrian Georgescu
2894 117 Adrian Georgescu
2895 117 Adrian Georgescu
h3. Referral
2896 117 Adrian Georgescu
2897 117 Adrian Georgescu
2898 117 Adrian Georgescu
Subscription and notifications for SIP events is an Internet standard published at "RFC 3856":http://tools.ietf.org/html/rfc3856.
2899 117 Adrian Georgescu
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.
2900 117 Adrian Georgescu
2901 1 Adrian Georgescu
This SIP primitive class represents a referral requested by the client to a target URI.
2902 1 Adrian Georgescu
This means that the application should instance this class for each combination of target URI and resource it wishes the target to refer to.
2903 117 Adrian Georgescu
Whenever a @NOTIFY@ is received, the application will receive the @SIPReferralGotNotify@ notification.
2904 1 Adrian Georgescu
2905 117 Adrian Georgescu
Not creating an implicit subscription is supported as per "RFC 4488":http://tools.ietf.org/html/rfc4488
2906 1 Adrian Georgescu
2907 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)
2908 117 Adrian Georgescu
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@.
2909 117 Adrian Georgescu
The last three states are directly copied from the contents of the @Subscription-State@ header of the received @NOTIFY@ request.
2910 117 Adrian Georgescu
Also, the state can be an arbitrary string if the contents of the @Subscription-State@ header are not one of the three above.
2911 117 Adrian Georgescu
The state of the object is presented in the @state@ attribute and changes of the state are indicated by means of the @SIPReferralChangedState@ notification.
2912 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.
2913 1 Adrian Georgescu
2914 1 Adrian Georgescu
2915 117 Adrian Georgescu
h4. methods
2916 1 Adrian Georgescu
2917 1 Adrian Georgescu
2918 1 Adrian Georgescu
2919 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_, *request_uri*, *from_header*, *to_header*, *refer_to_header, *contact_header*, *route_header*, *credentials*=@None@)
2920 117 Adrian Georgescu
>Creates a new @Referral@ object which will be in the @NULL@ state.
2921 117 Adrian Georgescu
>The arguments for this method are documented in the attributes section above.
2922 1 Adrian Georgescu
2923 117 Adrian Georgescu
*send_refer*(_self_, *create_subscription*=@1@, *extra_headers*=@list()@, *timeout*=@None@)
2924 117 Adrian Georgescu
>Calling this method triggers sending a @REFER@ request to the presence agent.
2925 117 Adrian Georgescu
>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.
2926 117 Adrian Georgescu
>It may not be called when the object is in the @TERMINATED@ state.
2927 117 Adrian Georgescu
  
2928 117 Adrian Georgescu
>+_create_subscription_+:
2929 1 Adrian Georgescu
2930 117 Adrian Georgescu
>Boolean flag indicating if an implicit subscription should be created.
2931 117 Adrian Georgescu
  
2932 117 Adrian Georgescu
>+_extra_headers_+:
2933 1 Adrian Georgescu
2934 117 Adrian Georgescu
>A list of additional headers to include in the @REFER@ requests.
2935 117 Adrian Georgescu
  
2936 117 Adrian Georgescu
>+_timeout_+:
2937 1 Adrian Georgescu
2938 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.
2939 117 Adrian Georgescu
>If this is @None@, the internal 408 is only triggered by the internal PJSIP transaction timeout.
2940 117 Adrian Georgescu
>Note that, even if the timeout is specified, the PJSIP timeout is also still valid.
2941 1 Adrian Georgescu
2942 117 Adrian Georgescu
*refresh*(_self_, *contact_header*=@None@, *extra_headers*=@list()@, *timeout*=@None@)
2943 117 Adrian Georgescu
  
2944 117 Adrian Georgescu
>+_contact_header_+:
2945 1 Adrian Georgescu
2946 117 Adrian Georgescu
>An optional @ContactHeader@ object which will replace the local contact header and will be used from this moment on.
2947 117 Adrian Georgescu
  
2948 117 Adrian Georgescu
>+_extra_headers_+:
2949 1 Adrian Georgescu
2950 117 Adrian Georgescu
>A list of additional headers to include in the refreshing @SUBSCRIBE@ request.
2951 117 Adrian Georgescu
  
2952 117 Adrian Georgescu
>+_timeout_+:
2953 1 Adrian Georgescu
2954 117 Adrian Georgescu
>The @timeout@ argument has the same meaning as it does for the @send_refer()@ method.
2955 1 Adrian Georgescu
2956 117 Adrian Georgescu
*end*(_self_, *timeout*=@None@)
2957 117 Adrian Georgescu
>This will end the referral subscription by sending a @SUBSCRIBE@ request with an @Expires@ value of 0.
2958 117 Adrian Georgescu
>If this object is no longer subscribed, this method will return without performing any action.
2959 117 Adrian Georgescu
>This method cannot be called when the object is in the @NULL@ state.
2960 117 Adrian Georgescu
>The @timeout@ argument has the same meaning as it does for the @send_refer()@ method.
2961 1 Adrian Georgescu
2962 1 Adrian Georgescu
2963 117 Adrian Georgescu
h4. attributes
2964 1 Adrian Georgescu
2965 1 Adrian Georgescu
2966 1 Adrian Georgescu
2967 117 Adrian Georgescu
*state*
2968 117 Adrian Georgescu
>Indicates which state the internal state machine is in.
2969 117 Adrian Georgescu
>See the previous section for a list of states the state machine can be in.
2970 1 Adrian Georgescu
2971 117 Adrian Georgescu
*from_header*
2972 117 Adrian Georgescu
>The @FrozenFromHeader@ to be put in the @From@ header of the @REFER@ and @SUBSCRIBE@ requests.
2973 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
2974 1 Adrian Georgescu
2975 117 Adrian Georgescu
*to_header*
2976 117 Adrian Georgescu
>The @FrozenToHeader@ that is the target for the referral.
2977 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
2978 1 Adrian Georgescu
2979 117 Adrian Georgescu
*refer_to_header*
2980 117 Adrian Georgescu
>The @FrozenReferToHeader@ that is the target resource for the referral.
2981 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
2982 1 Adrian Georgescu
2983 117 Adrian Georgescu
*local_contact_header*
2984 117 Adrian Georgescu
>The @FrozenContactHeader@ to be put in the @Contact@ header of the @REFER@ and @SUBSCRIBE@ requests.
2985 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
2986 1 Adrian Georgescu
2987 117 Adrian Georgescu
*remote_contact_header*
2988 117 Adrian Georgescu
 The @FrozenContactHeader@ received from the remote endpoint. This attribute is read-only.
2989 1 Adrian Georgescu
2990 117 Adrian Georgescu
*route_header*
2991 117 Adrian Georgescu
>The outbound proxy to use in the form of a @FrozenRouteHeader@ object.
2992 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
2993 1 Adrian Georgescu
2994 117 Adrian Georgescu
*credentials*
2995 117 Adrian Georgescu
>The SIP credentials needed to authenticate at the SIP proxy in the form of a @FrozenCredentials@ object.
2996 117 Adrian Georgescu
>If none was specified when creating the @Referral@ object, this attribute is @None@.
2997 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
2998 1 Adrian Georgescu
2999 117 Adrian Georgescu
*refresh*
3000 117 Adrian Georgescu
>The refresh interval in seconds that was requested on object instantiation as an int.
3001 117 Adrian Georgescu
>This attribute is set when a @NOTIFY@ request is received and is read-only.
3002 1 Adrian Georgescu
3003 117 Adrian Georgescu
*extra_headers*
3004 117 Adrian Georgescu
>This contains the @frozenlist@ of extra headers that was last passed to a successful call to the @subscribe()@ method.
3005 117 Adrian Georgescu
>If the argument was not provided, this attribute is an empty list.
3006 117 Adrian Georgescu
>This attribute is read-only.
3007 1 Adrian Georgescu
3008 117 Adrian Georgescu
*peer_address*
3009 117 Adrian Georgescu
>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.
3010 1 Adrian Georgescu
3011 1 Adrian Georgescu
3012 117 Adrian Georgescu
h4. notifications
3013 1 Adrian Georgescu
3014 1 Adrian Georgescu
3015 1 Adrian Georgescu
3016 117 Adrian Georgescu
*SIPReferralChangedState*
3017 117 Adrian Georgescu
>This notification will be sent every time the internal state machine of a @Referral@ object changes state.
3018 117 Adrian Georgescu
  
3019 117 Adrian Georgescu
>+_timestamp_+:
3020 1 Adrian Georgescu
3021 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
3022 117 Adrian Georgescu
  
3023 117 Adrian Georgescu
>+_prev_state_+:
3024 1 Adrian Georgescu
3025 117 Adrian Georgescu
>The previous state that the sate machine was in.
3026 117 Adrian Georgescu
  
3027 117 Adrian Georgescu
>+_state_+:
3028 1 Adrian Georgescu
3029 117 Adrian Georgescu
>The new state the state machine moved into.
3030 1 Adrian Georgescu
3031 117 Adrian Georgescu
*SIPReferralWillStart*
3032 117 Adrian Georgescu
>This notification will be emitted when the initial @REFER@ request is sent.
3033 117 Adrian Georgescu
  
3034 117 Adrian Georgescu
>+_timestamp_+:
3035 1 Adrian Georgescu
3036 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
3037 1 Adrian Georgescu
3038 117 Adrian Georgescu
*SIPReferralDidStart*
3039 117 Adrian Georgescu
>This notification will be sent when the initial @REFER@ was accepted by the remote endpoint.
3040 117 Adrian Georgescu
  
3041 117 Adrian Georgescu
>+_timestamp_+:
3042 1 Adrian Georgescu
3043 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
3044 1 Adrian Georgescu
3045 117 Adrian Georgescu
*SIPReferralGotNotify*
3046 117 Adrian Georgescu
>This notification will be sent when a @NOTIFY@ is received that corresponds to a particular @Referral@ object.
3047 117 Adrian Georgescu
>Note that this notification could be sent when a @NOTIFY@ without a body is received.
3048 117 Adrian Georgescu
  
3049 117 Adrian Georgescu
>+_request_uri_+:
3050 1 Adrian Georgescu
3051 117 Adrian Georgescu
>The request URI of the @NOTIFY@ request as a @SIPURI@ object.
3052 117 Adrian Georgescu
  
3053 117 Adrian Georgescu
>+_from_header_+:
3054 1 Adrian Georgescu
3055 117 Adrian Georgescu
>The From header of the @NOTIFY@ request as a @FrozenFromHeader@ object.
3056 117 Adrian Georgescu
  
3057 117 Adrian Georgescu
>+_to_header_+:
3058 1 Adrian Georgescu
3059 117 Adrian Georgescu
>The To header of the @NOTIFY@ request as a @FrozenToHeader@ object.
3060 117 Adrian Georgescu
  
3061 117 Adrian Georgescu
>+_content_type_+:
3062 1 Adrian Georgescu
3063 117 Adrian Georgescu
>The Content-Type header value of the @NOTIFY@ request as a @ContentType@ object.
3064 117 Adrian Georgescu
  
3065 117 Adrian Georgescu
>+_event_+:
3066 1 Adrian Georgescu
3067 117 Adrian Georgescu
>The Event header value of the @NOTIFY@ request as a string object.
3068 117 Adrian Georgescu
  
3069 117 Adrian Georgescu
>+_headers_+:
3070 1 Adrian Georgescu
3071 117 Adrian Georgescu
>The headers of the @NOTIFY@ request as a dict.
3072 117 Adrian Georgescu
>Each SIP header is represented in its parsed for as long as PJSIP supports it.
3073 117 Adrian Georgescu
>The format of the parsed value depends on the header.
3074 117 Adrian Georgescu
  
3075 117 Adrian Georgescu
>+_body_+:
3076 1 Adrian Georgescu
3077 117 Adrian Georgescu
>The body of the @NOTIFY@ request as a string, or @None@ if no body was included.
3078 117 Adrian Georgescu
  
3079 117 Adrian Georgescu
>+_timestamp_+:
3080 1 Adrian Georgescu
3081 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.  
3082 1 Adrian Georgescu
3083 117 Adrian Georgescu
*SIPReferralDidFail*
3084 117 Adrian Georgescu
>This notification will be sent whenever there is a failure, such as a rejected initial @REFER@ or refreshing @SUBSCRIBE@.
3085 117 Adrian Georgescu
>After this notification the @Referral@ object is in the @TERMINATED@ state and can no longer be used.
3086 117 Adrian Georgescu
  
3087 117 Adrian Georgescu
>+_timestamp_+:
3088 1 Adrian Georgescu
3089 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
3090 117 Adrian Georgescu
  
3091 117 Adrian Georgescu
>+_code_+:
3092 1 Adrian Georgescu
3093 117 Adrian Georgescu
>An integer SIP code from the fatal response that was received from the remote party of generated by PJSIP.
3094 117 Adrian Georgescu
>If the error is internal to the SIP core, this attribute will have a value of 0.
3095 117 Adrian Georgescu
  
3096 117 Adrian Georgescu
>+_reason_+:
3097 1 Adrian Georgescu
3098 117 Adrian Georgescu
>An text string describing the failure that occurred.
3099 1 Adrian Georgescu
3100 117 Adrian Georgescu
*SIPReferralDidEnd*
3101 117 Adrian Georgescu
>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.
3102 117 Adrian Georgescu
>After this notification the @Referral@ object is in the @TERMINATED@ state and can no longer be used.
3103 117 Adrian Georgescu
  
3104 117 Adrian Georgescu
>+_timestamp_+:
3105 1 Adrian Georgescu
3106 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
3107 1 Adrian Georgescu
3108 117 Adrian Georgescu
3109 117 Adrian Georgescu
h3. IncomingReferral
3110 117 Adrian Georgescu
3111 117 Adrian Georgescu
3112 117 Adrian Georgescu
Subscription and notifications for SIP events is an Internet standard published at "RFC 3856":http://tools.ietf.org/html/rfc3856.
3113 117 Adrian Georgescu
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.
3114 117 Adrian Georgescu
3115 117 Adrian Georgescu
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.
3116 117 Adrian Georgescu
This means that it can accept a @REFER@ request and subsequent refreshing @SUBSCRIBE@s and sent @NOTIFY@ requests containing event state.
3117 117 Adrian Georgescu
3118 117 Adrian Georgescu
Any incoming @REFER@ request causes the creation of a @IncomingReferral@ object.
3119 117 Adrian Georgescu
This will be indicated to the application through a @SIPIncomingReferralGotRefer@ notification.
3120 117 Adrian Georgescu
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.
3121 117 Adrian Georgescu
3122 117 Adrian Georgescu
The application can either reject the referral by calling the @reject()@ method or accept it through the @accept()@ method.
3123 117 Adrian Georgescu
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.
3124 117 Adrian Georgescu
Whenever a refreshing @SUBSCRIBE@ is received, the latest contents to be set are sent in the resulting @NOTIFY@ request.
3125 117 Adrian Georgescu
The subscription can be ended by using the @end()@ method.
3126 117 Adrian Georgescu
3127 117 Adrian Georgescu
3128 117 Adrian Georgescu
h4. methods
3129 117 Adrian Georgescu
3130 117 Adrian Georgescu
3131 117 Adrian Georgescu
3132 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_)
3133 117 Adrian Georgescu
>An application should never create an @IncomingSubscription@ object itself.
3134 117 Adrian Georgescu
>Doing this will create a useless object in the @None@ state.
3135 117 Adrian Georgescu
3136 117 Adrian Georgescu
*reject*(_self_, *code*)
3137 117 Adrian Georgescu
>Will reply to the initial @REFER@ with a negative response.
3138 117 Adrian Georgescu
>This method can only be called in the @"incoming"@ state and sets the referral to the @"terminated"@ state.
3139 117 Adrian Georgescu
  
3140 117 Adrian Georgescu
>+_code_+:
3141 117 Adrian Georgescu
3142 117 Adrian Georgescu
>The SIP response code to use.
3143 117 Adrian Georgescu
>This should be a negative response, i.e. in the 3xx, 4xx, 5xx or 6xx range.
3144 117 Adrian Georgescu
3145 117 Adrian Georgescu
*accept*(_self_, *code*=@202@, *duration*=@180@)
3146 117 Adrian Georgescu
>Accept the initial incoming @REFER@ and respond to it with a 202 Accepted.
3147 117 Adrian Georgescu
>A @NOTIFY@ will be sent to update the state to "active", with a payload indicating the referral is in 100 Trying state.
3148 117 Adrian Georgescu
>This method can only be called in the @"incoming"@ state.
3149 117 Adrian Georgescu
  
3150 117 Adrian Georgescu
>+_code_+:
3151 117 Adrian Georgescu
3152 117 Adrian Georgescu
>The code to be  used for the initial reply.
3153 117 Adrian Georgescu
  
3154 117 Adrian Georgescu
>+_duration_+:
3155 117 Adrian Georgescu
3156 117 Adrian Georgescu
>The desired duration for the implicit subscription. Unlike @SUBSCRIBE@ initiated dialogs, in a referral the receiving party is the one choosing the expiration time.
3157 117 Adrian Georgescu
3158 117 Adrian Georgescu
*send_notify*(_self_, *code*, *status*=@None@)
3159 117 Adrian Georgescu
>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.
3160 117 Adrian Georgescu
>This method can only be called in the @"active"@ state.
3161 117 Adrian Georgescu
  
3162 117 Adrian Georgescu
>+_code_+:
3163 117 Adrian Georgescu
3164 117 Adrian Georgescu
>The response code to be used to generate the sipfrag payload.
3165 117 Adrian Georgescu
  
3166 117 Adrian Georgescu
>+_status_+:
3167 117 Adrian Georgescu
3168 117 Adrian Georgescu
>Optional status reason to be used to build the sipfrag payload. If none was specified the standard reason string will be used.
3169 117 Adrian Georgescu
3170 117 Adrian Georgescu
3171 117 Adrian Georgescu
h4. attributes
3172 117 Adrian Georgescu
3173 117 Adrian Georgescu
3174 117 Adrian Georgescu
3175 117 Adrian Georgescu
*state*
3176 117 Adrian Georgescu
>Indicates which state the incoming referral dialog is in.
3177 117 Adrian Georgescu
>This can be one of @None@, @"incoming"@, @"pending"@, @"active"@ or @"terminated"@.
3178 117 Adrian Georgescu
>This attribute is read-only.
3179 117 Adrian Georgescu
3180 117 Adrian Georgescu
*local_contact_header*
3181 117 Adrian Georgescu
>The @FrozenContactHeader@ to be put in the @Contact@ header of the @REFER@ and @SUBSCRIBE@ responses and @NOTIFY@ requests.
3182 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
3183 117 Adrian Georgescu
3184 117 Adrian Georgescu
*remote_contact_header*
3185 117 Adrian Georgescu
 The @FrozenContactHeader@ received from the remote endpoint. This attribute is read-only.
3186 117 Adrian Georgescu
3187 117 Adrian Georgescu
*peer_address*
3188 117 Adrian Georgescu
>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.
3189 117 Adrian Georgescu
3190 117 Adrian Georgescu
3191 117 Adrian Georgescu
h4. notifications
3192 117 Adrian Georgescu
3193 117 Adrian Georgescu
3194 117 Adrian Georgescu
3195 117 Adrian Georgescu
*SIPIncomingReferralChangedState*
3196 117 Adrian Georgescu
>This notification will be sent every time the an @IncomingReferral@ object changes state.
3197 117 Adrian Georgescu
>This notification is mostly indicative, an application should not let its logic depend on it.
3198 117 Adrian Georgescu
  
3199 117 Adrian Georgescu
>+_timestamp_+:
3200 117 Adrian Georgescu
3201 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
3202 117 Adrian Georgescu
  
3203 117 Adrian Georgescu
>+_prev_state_+:
3204 117 Adrian Georgescu
3205 117 Adrian Georgescu
>The previous state that the subscription was in.
3206 117 Adrian Georgescu
  
3207 117 Adrian Georgescu
>+_state_+:
3208 117 Adrian Georgescu
3209 117 Adrian Georgescu
>The new state the subscription has.
3210 117 Adrian Georgescu
3211 117 Adrian Georgescu
*SIPIncomingReferralGotRefer*
3212 117 Adrian Georgescu
>This notification will be sent when a new @IncomingReferral@ is created as result of an incoming @REFER@ request.
3213 117 Adrian Georgescu
>The application should listen for this notification, retain a reference to the object that sent it and either accept or reject it.
3214 117 Adrian Georgescu
  
3215 117 Adrian Georgescu
>+_timestamp_+:
3216 117 Adrian Georgescu
3217 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
3218 117 Adrian Georgescu
  
3219 117 Adrian Georgescu
>+_method_+:
3220 117 Adrian Georgescu
3221 117 Adrian Georgescu
>The method of the SIP request as a string, which will be @REFER@.
3222 117 Adrian Georgescu
  
3223 117 Adrian Georgescu
>+_request_uri_+:
3224 117 Adrian Georgescu
3225 117 Adrian Georgescu
>The request URI of the @REFER@ request as a @FrozenSIPURI@ object.
3226 117 Adrian Georgescu
  
3227 117 Adrian Georgescu
>+_refer_to_+:
3228 117 Adrian Georgescu
3229 117 Adrian Georgescu
>The Refer-To header as a @FrozenReferToHeader@ object.
3230 117 Adrian Georgescu
  
3231 117 Adrian Georgescu
>+_headers_+:
3232 117 Adrian Georgescu
3233 117 Adrian Georgescu
>The headers of the @REFER@ request as a dict, the values of which are the relevant header objects.
3234 117 Adrian Georgescu
  
3235 117 Adrian Georgescu
>+_body_+:
3236 117 Adrian Georgescu
3237 117 Adrian Georgescu
>The body of the @REFER@ request as a string, or @None@ if no body was included.
3238 117 Adrian Georgescu
3239 117 Adrian Georgescu
*SIPIncomingReferralGotRefreshingSubscribe*
3240 117 Adrian Georgescu
>This notification indicates that a refreshing @SUBSCRIBE@ request was received from the subscriber.
3241 117 Adrian Georgescu
>It is purely informative, no action needs to be taken by the application as a result of it.
3242 117 Adrian Georgescu
3243 117 Adrian Georgescu
*SIPIncomingReferralGotUnsubscribe*
3244 117 Adrian Georgescu
>This notification indicates that a @SUBSCRIBE@ request with an @Expires@ header of 0 was received from the subscriber, effectively requesting to unsubscribe.
3245 117 Adrian Georgescu
>It is purely informative, no action needs to be taken by the application as a result of it.
3246 117 Adrian Georgescu
3247 117 Adrian Georgescu
*SIPIncomingReferralAnsweredRefer*
3248 117 Adrian Georgescu
>This notification is sent whenever a response to a @REFER@ request is sent by the object.
3249 117 Adrian Georgescu
>It is purely informative, no action needs to be taken by the application as a result of it.
3250 117 Adrian Georgescu
  
3251 117 Adrian Georgescu
>+_timestamp_+:
3252 117 Adrian Georgescu
3253 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
3254 117 Adrian Georgescu
  
3255 117 Adrian Georgescu
>+_code_+:
3256 117 Adrian Georgescu
3257 117 Adrian Georgescu
>The code of the SIP response as an int.
3258 117 Adrian Georgescu
  
3259 117 Adrian Georgescu
>+_reason_+:
3260 117 Adrian Georgescu
3261 117 Adrian Georgescu
>The reason text of the SIP response as an int.
3262 117 Adrian Georgescu
  
3263 117 Adrian Georgescu
>+_headers_+:
3264 117 Adrian Georgescu
3265 117 Adrian Georgescu
>The headers of the response as a dict, the values of which are the relevant header objects.
3266 117 Adrian Georgescu
  
3267 117 Adrian Georgescu
>+_body_+:
3268 117 Adrian Georgescu
3269 117 Adrian Georgescu
>This will be @None@.
3270 117 Adrian Georgescu
3271 117 Adrian Georgescu
*SIPIncomingReferralSentNotify*
3272 117 Adrian Georgescu
>This notification indicates that a @NOTIFY@ request was sent to the subscriber.
3273 117 Adrian Georgescu
>It is purely informative, no action needs to be taken by the application as a result of it.
3274 117 Adrian Georgescu
  
3275 117 Adrian Georgescu
>+_timestamp_+:
3276 117 Adrian Georgescu
3277 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
3278 117 Adrian Georgescu
  
3279 117 Adrian Georgescu
>+_method_+:
3280 117 Adrian Georgescu
3281 117 Adrian Georgescu
>The method of the SIP request as a string, which will be @NOTIFY@.
3282 117 Adrian Georgescu
  
3283 117 Adrian Georgescu
>+_request_uri_+:
3284 117 Adrian Georgescu
3285 117 Adrian Georgescu
>The request URI of the @NOTIFY@ request as a @FrozenSIPURI@ object.
3286 117 Adrian Georgescu
  
3287 117 Adrian Georgescu
>+_headers_+:
3288 117 Adrian Georgescu
3289 117 Adrian Georgescu
>The headers of the @NOTIFY@ request as a dict, the values of which are the relevant header objects.
3290 117 Adrian Georgescu
  
3291 117 Adrian Georgescu
>+_body_+:
3292 117 Adrian Georgescu
3293 117 Adrian Georgescu
>The body of the @NOTIFY@ request or response as a string, or @None@ if no body was included.
3294 117 Adrian Georgescu
3295 117 Adrian Georgescu
*SIPIncomingReferralNotifyDidSucceed*
3296 117 Adrian Georgescu
>This indicates that a positive final response was received from the subscriber in reply to a sent @NOTIFY@ request.
3297 117 Adrian Georgescu
>The notification is purely informative, no action needs to be taken by the application as a result of it.
3298 117 Adrian Georgescu
  
3299 117 Adrian Georgescu
>+_timestamp_+:
3300 117 Adrian Georgescu
3301 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
3302 117 Adrian Georgescu
  
3303 117 Adrian Georgescu
>+_code_+:
3304 117 Adrian Georgescu
3305 117 Adrian Georgescu
>The code of the SIP response as an int.
3306 117 Adrian Georgescu
  
3307 117 Adrian Georgescu
>+_reason_+:
3308 117 Adrian Georgescu
3309 117 Adrian Georgescu
>The reason text of the SIP response as a string.
3310 117 Adrian Georgescu
  
3311 117 Adrian Georgescu
>+_headers_+:
3312 117 Adrian Georgescu
3313 117 Adrian Georgescu
>The headers of the response as a dict, the values of which are the relevant header objects.
3314 117 Adrian Georgescu
  
3315 117 Adrian Georgescu
>+_body_+:
3316 117 Adrian Georgescu
3317 117 Adrian Georgescu
>This will be @None@.
3318 117 Adrian Georgescu
3319 117 Adrian Georgescu
*SIPIncomingReferralNotifyDidFail*
3320 117 Adrian Georgescu
>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.
3321 117 Adrian Georgescu
  
3322 117 Adrian Georgescu
>+_timestamp_+:
3323 117 Adrian Georgescu
3324 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
3325 117 Adrian Georgescu
  
3326 117 Adrian Georgescu
>+_code_+:
3327 117 Adrian Georgescu
3328 117 Adrian Georgescu
>The code of the SIP response as an int.
3329 117 Adrian Georgescu
>If this is 0, the notification was sent as a result of an internal error.
3330 117 Adrian Georgescu
  
3331 117 Adrian Georgescu
>+_reason_+:
3332 117 Adrian Georgescu
3333 117 Adrian Georgescu
>The reason text of the SIP response as a string or the internal error if the code attribute is 0.
3334 117 Adrian Georgescu
  
3335 117 Adrian Georgescu
>+_headers_+: (if the notification was caused by a negative response)
3336 117 Adrian Georgescu
3337 117 Adrian Georgescu
>The headers of the response as a dict, the values of which are the relevant header objects.
3338 117 Adrian Georgescu
  
3339 117 Adrian Georgescu
>+_body_+: (if the notification was caused by a negative response)
3340 117 Adrian Georgescu
3341 117 Adrian Georgescu
>This will be @None@.
3342 117 Adrian Georgescu
3343 117 Adrian Georgescu
*SIPIncomingReferralDidEnd*
3344 117 Adrian Georgescu
>This notification is sent whenever the @IncomingReferral@ object reaches the @"terminated"@ state and is no longer valid.
3345 117 Adrian Georgescu
>After receiving this notification, the application should not longer try to use the object.
3346 117 Adrian Georgescu
  
3347 117 Adrian Georgescu
>+_timestamp_+:
3348 117 Adrian Georgescu
3349 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
3350 117 Adrian Georgescu
3351 117 Adrian Georgescu
3352 117 Adrian Georgescu
h3. AudioMixer
3353 117 Adrian Georgescu
3354 117 Adrian Georgescu
3355 117 Adrian Georgescu
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.
3356 117 Adrian Georgescu
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.
3357 117 Adrian Georgescu
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.
3358 1 Adrian Georgescu
The sound devices, both input and output, together always occupy slot 0.
3359 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).
3360 1 Adrian Georgescu
3361 1 Adrian Georgescu
3362 117 Adrian Georgescu
h4. methods
3363 1 Adrian Georgescu
3364 1 Adrian Georgescu
3365 1 Adrian Georgescu
3366 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_, *input_device*, *output_device*, *sample_rate*, *ec_tail_length*=200, *slot_count*=254)
3367 117 Adrian Georgescu
>Creates a new @ConferenceBridge@ object.
3368 117 Adrian Georgescu
  
3369 117 Adrian Georgescu
>+_input_device_+:
3370 1 Adrian Georgescu
3371 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.
3372 117 Adrian Georgescu
>A list of known input devices can be queried through the @Engine.input_devices@ attribute.
3373 117 Adrian Georgescu
>If @"system_default"@ is used, PJSIP will select the system default output device, or @None@ if no audio input device is present.
3374 117 Adrian Georgescu
>The device that was selected can be queried afterwards through the @input_device@ attribute.
3375 117 Adrian Georgescu
  
3376 117 Adrian Georgescu
>+_output_device_+:
3377 1 Adrian Georgescu
3378 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.
3379 117 Adrian Georgescu
>A list of known output devices can be queried through the @Engine.output_devices@ attribute.
3380 117 Adrian Georgescu
>If @"system_default"@ is used, PJSIP will select the system default output device, or @None@ if no audio output device is present.
3381 117 Adrian Georgescu
>The device that was selected can be queried afterwards through the @output_device@ attribute.
3382 117 Adrian Georgescu
  
3383 117 Adrian Georgescu
>+_sample_rate_+:
3384 1 Adrian Georgescu
3385 117 Adrian Georgescu
>The sample rate on which the conference bridge and sound devices should operate in Hz.
3386 117 Adrian Georgescu
>This must be a multiple of 50.
3387 117 Adrian Georgescu
  
3388 117 Adrian Georgescu
>+_ec_tail_length_+:
3389 1 Adrian Georgescu
3390 117 Adrian Georgescu
>The echo cancellation tail length in ms.
3391 117 Adrian Georgescu
>If this value is 0, no echo cancellation is used.
3392 117 Adrian Georgescu
  
3393 117 Adrian Georgescu
>+_slot_count_+:
3394 1 Adrian Georgescu
3395 117 Adrian Georgescu
>The number of slots to allocate on the conference bridge.
3396