SipCoreApiDocumentation

Version 119 (Dan Pascu, 03/14/2019 10:51 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 119 Dan Pascu
This is a relatively simple object that can manage responding to incoming requests in a single transaction. For this reason it does not handle requests that create a dialog.
1902 119 Dan Pascu
To register methods for which requests should be formed into an @IncomingRequest@ object, the application should either start the @Engine@ with the *incoming_requests*=[list_of_method_names] argument, or use the *add_incoming_request/remove_incoming_request methods* on the @Engine@ after it's started to modify the list of methods for which the @Engine@ will create @IncomingRequest@ instances.
1903 119 Dan Pascu
1904 119 Dan Pascu
Example:
1905 119 Dan Pascu
1906 119 Dan Pascu
engine = Engine()
1907 119 Dan Pascu
engine.start(incoming_requests=['OPTIONS'])
1908 119 Dan Pascu
1909 119 Dan Pascu
or after the @Engine@ was started
1910 119 Dan Pascu
1911 119 Dan Pascu
engine.add_incoming_request('OPTIONS')
1912 119 Dan Pascu
1913 119 Dan Pascu
Note: Receiving @INVITE@, @SUBSCRIBE@, @ACK@ and @BYE@ through this object is not supported.
1914 113 Adrian Georgescu
1915 117 Adrian Georgescu
The application is notified of an incoming request through the @SIPIncomingRequestGotRequest@ notification.
1916 117 Adrian Georgescu
It can answer this request by calling the @answer@ method on the sender of this notification.
1917 117 Adrian Georgescu
Note that if the @IncomingRequest@ object gets destroyed before it is answered, a 500 response is automatically sent.
1918 113 Adrian Georgescu
1919 113 Adrian Georgescu
1920 117 Adrian Georgescu
h4. attributes
1921 113 Adrian Georgescu
1922 113 Adrian Georgescu
1923 113 Adrian Georgescu
1924 117 Adrian Georgescu
*state*
1925 117 Adrian Georgescu
>This read-only attribute indicates the state the object is in.
1926 117 Adrian Georgescu
>This can be @None@ if the object was created by the application, essentially meaning the object is inert, @"incoming"@ or @"answered"@.
1927 113 Adrian Georgescu
1928 113 Adrian Georgescu
1929 117 Adrian Georgescu
h4. methods
1930 113 Adrian Georgescu
1931 113 Adrian Georgescu
1932 113 Adrian Georgescu
1933 117 Adrian Georgescu
*answer*(_self_, *code*, *reason*=@None@, *extra_headers*=@None@)
1934 117 Adrian Georgescu
>Reply to the received request with a final response.
1935 117 Adrian Georgescu
  
1936 117 Adrian Georgescu
>+_code_+:
1937 113 Adrian Georgescu
1938 117 Adrian Georgescu
>The SIP response code to send.
1939 117 Adrian Georgescu
>This should be 200 or higher.
1940 117 Adrian Georgescu
  
1941 117 Adrian Georgescu
>+_reason_+:
1942 113 Adrian Georgescu
1943 117 Adrian Georgescu
>The reason text to include in the response.
1944 117 Adrian Georgescu
>If this is @None@, the default text for the given response code is used.
1945 117 Adrian Georgescu
  
1946 117 Adrian Georgescu
>+_extra_headers_+:
1947 113 Adrian Georgescu
1948 117 Adrian Georgescu
>The extra headers to include in the response as an iterable of header objects.
1949 113 Adrian Georgescu
1950 113 Adrian Georgescu
1951 117 Adrian Georgescu
h4. notifications
1952 113 Adrian Georgescu
1953 113 Adrian Georgescu
1954 113 Adrian Georgescu
1955 117 Adrian Georgescu
*SIPIncomingRequestGotRequest*
1956 117 Adrian Georgescu
>This notification will be sent when a new @IncomingRequest@ is created as result of a received request.
1957 117 Adrian Georgescu
>The application should listen for this notification, retain a reference to the object that sent it and answer it.
1958 117 Adrian Georgescu
  
1959 117 Adrian Georgescu
>+_timestamp_+:
1960 113 Adrian Georgescu
1961 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
1962 117 Adrian Georgescu
  
1963 117 Adrian Georgescu
>+_method_+:
1964 113 Adrian Georgescu
1965 117 Adrian Georgescu
>The method of the SIP request as a string.
1966 117 Adrian Georgescu
  
1967 117 Adrian Georgescu
>+_request_uri_+:
1968 113 Adrian Georgescu
1969 117 Adrian Georgescu
>The request URI of the request as a @FrozenSIPURI@ object.
1970 117 Adrian Georgescu
  
1971 117 Adrian Georgescu
>+_headers_+:
1972 113 Adrian Georgescu
1973 117 Adrian Georgescu
>The headers of the request as a dict, the values of which are the relevant header objects.
1974 117 Adrian Georgescu
  
1975 117 Adrian Georgescu
>+_body_+:
1976 113 Adrian Georgescu
1977 117 Adrian Georgescu
>The body of the request as a string, or @None@ if no body was included.
1978 113 Adrian Georgescu
1979 117 Adrian Georgescu
*SIPIncomingRequestSentResponse*
1980 117 Adrian Georgescu
>This notification is sent when a response to the request is sent by the object.
1981 117 Adrian Georgescu
  
1982 117 Adrian Georgescu
>+_timestamp_+:
1983 113 Adrian Georgescu
1984 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
1985 117 Adrian Georgescu
  
1986 117 Adrian Georgescu
>+_code_+:
1987 113 Adrian Georgescu
1988 117 Adrian Georgescu
>The code of the SIP response as an int.
1989 117 Adrian Georgescu
  
1990 117 Adrian Georgescu
>+_reason_+:
1991 113 Adrian Georgescu
1992 117 Adrian Georgescu
>The reason text of the SIP response as an int.
1993 117 Adrian Georgescu
  
1994 117 Adrian Georgescu
>+_headers_+:
1995 113 Adrian Georgescu
1996 117 Adrian Georgescu
>The headers of the response as a dict, the values of which are the relevant header objects.
1997 117 Adrian Georgescu
  
1998 117 Adrian Georgescu
>+_body_+:
1999 113 Adrian Georgescu
2000 117 Adrian Georgescu
>This will be @None@.
2001 113 Adrian Georgescu
2002 113 Adrian Georgescu
2003 117 Adrian Georgescu
h3. Message
2004 113 Adrian Georgescu
2005 113 Adrian Georgescu
2006 117 Adrian Georgescu
The @Message@ class is a simple wrapper for the @Request@ class, with the purpose of sending @MESSAGE@ requests, as described in "RFC 3428":http://tools.ietf.org/html/rfc3428.
2007 117 Adrian Georgescu
It is a one-shot object that manages only one @Request@ object.
2008 113 Adrian Georgescu
2009 113 Adrian Georgescu
2010 117 Adrian Georgescu
h4. methods
2011 113 Adrian Georgescu
2012 113 Adrian Georgescu
2013 113 Adrian Georgescu
2014 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_, *from_header*, *to_header*, *route_header*, *content_type*, *body*, *credentials*=@None@, *extra_headers*=@[]@)
2015 117 Adrian Georgescu
>Creates a new @Message@ object with the specified arguments.
2016 117 Adrian Georgescu
>These arguments are documented in the attributes section for this class.
2017 113 Adrian Georgescu
2018 117 Adrian Georgescu
*send*(_self_, *timeout*=@None@)
2019 117 Adrian Georgescu
>Send the @MESSAGE@ request to the remote party.
2020 117 Adrian Georgescu
  
2021 117 Adrian Georgescu
>+_timeout_+:
2022 113 Adrian Georgescu
2023 117 Adrian Georgescu
>This argument as the same meaning as it does for @Request.send()@.
2024 113 Adrian Georgescu
2025 117 Adrian Georgescu
*end*(_self_)
2026 117 Adrian Georgescu
>Stop trying to send the @MESSAGE@ request.
2027 117 Adrian Georgescu
>If it was not sent yet, calling this method does nothing.
2028 113 Adrian Georgescu
2029 113 Adrian Georgescu
2030 117 Adrian Georgescu
h4. attributes
2031 113 Adrian Georgescu
2032 113 Adrian Georgescu
2033 113 Adrian Georgescu
2034 117 Adrian Georgescu
*from_header*
2035 117 Adrian Georgescu
>The @FrozenFromHeader@ to put in the @From@ header of the @MESSAGE@ request.
2036 117 Adrian Georgescu
>This attribute is set on instantiation and is read-only.
2037 113 Adrian Georgescu
2038 117 Adrian Georgescu
*to_header*
2039 117 Adrian Georgescu
>The @FrozenToHeader@ to put in the @To@ header of the @MESSAGE@ request.
2040 117 Adrian Georgescu
>This attribute is set on instantiation and is read-only.
2041 113 Adrian Georgescu
2042 117 Adrian Georgescu
*route_header*
2043 117 Adrian Georgescu
>Where to send the @MESSAGE@ request to, including IP, port and transport, in the form of a @FrozenRouteHeader@ object.
2044 117 Adrian Georgescu
>This will also be included in the @Route@ header of the request.
2045 117 Adrian Georgescu
>This attribute is set on instantiation and is read-only.
2046 113 Adrian Georgescu
2047 117 Adrian Georgescu
*content_type*
2048 117 Adrian Georgescu
>What string to put as content type in the @Content-Type@ headers.
2049 117 Adrian Georgescu
>It is set on instantiation and is read-only.
2050 113 Adrian Georgescu
2051 117 Adrian Georgescu
*body*
2052 117 Adrian Georgescu
>The body of the @MESSAGE@ request as a string.
2053 117 Adrian Georgescu
>If no body was specified, this attribute is @None@
2054 117 Adrian Georgescu
>It is set on instantiation and is read-only.
2055 113 Adrian Georgescu
2056 117 Adrian Georgescu
*credentials*
2057 117 Adrian Georgescu
>The credentials to be used when challenged for authentication, represented by a @FrozenCredentials@ object.
2058 117 Adrian Georgescu
>If no credentials were specified, this attribute is @None@.
2059 117 Adrian Georgescu
>This attribute is set on instantiation and is read-only.
2060 103 Adrian Georgescu
2061 117 Adrian Georgescu
*is_sent*
2062 117 Adrian Georgescu
>A boolean read-only property indicating if the @MESSAGE@ request was sent.
2063 103 Adrian Georgescu
2064 117 Adrian Georgescu
*in_progress*
2065 117 Adrian Georgescu
>A boolean read-only property indicating if the object is waiting for the response from the remote party.
2066 103 Adrian Georgescu
2067 117 Adrian Georgescu
*peer_address*
2068 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.
2069 103 Adrian Georgescu
2070 103 Adrian Georgescu
2071 117 Adrian Georgescu
h4. notifications
2072 103 Adrian Georgescu
2073 103 Adrian Georgescu
2074 117 Adrian Georgescu
2075 117 Adrian Georgescu
*SIPMessageDidSucceed*
2076 117 Adrian Georgescu
>This notification will be sent when the remote party acknowledged the reception of the @MESSAGE@ request.
2077 117 Adrian Georgescu
>It has not data attributes.
2078 117 Adrian Georgescu
2079 117 Adrian Georgescu
*SIPMessageDidFail*
2080 117 Adrian Georgescu
>This notification will be sent when transmission of the @MESSAGE@ request fails for whatever reason.
2081 117 Adrian Georgescu
  
2082 117 Adrian Georgescu
>+_code_+:
2083 117 Adrian Georgescu
2084 117 Adrian Georgescu
>An int indicating the SIP or internal PJSIP code that was given in response to the @MESSAGE@ request.
2085 117 Adrian Georgescu
>This is 0 if the failure is caused by an internal error.
2086 117 Adrian Georgescu
  
2087 117 Adrian Georgescu
>+_reason_+:
2088 117 Adrian Georgescu
2089 117 Adrian Georgescu
>A status string describing the failure, either taken from the SIP response or the internal error.
2090 117 Adrian Georgescu
2091 117 Adrian Georgescu
2092 117 Adrian Georgescu
h3. Registration
2093 117 Adrian Georgescu
2094 117 Adrian Georgescu
2095 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.
2096 117 Adrian Georgescu
For details, see "RFC 3261":http://tools.ietf.org/html/rfc3261.
2097 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.
2098 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.
2099 117 Adrian Georgescu
2100 117 Adrian Georgescu
2101 117 Adrian Georgescu
h4. methods
2102 117 Adrian Georgescu
2103 117 Adrian Georgescu
2104 117 Adrian Georgescu
2105 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_, *from_header*, *credentials*=@None@, *duration*=300)
2106 117 Adrian Georgescu
>Creates a new @Registration@ object with the specified arguments.
2107 117 Adrian Georgescu
>These arguments are documented in the attributes section for this class.
2108 117 Adrian Georgescu
2109 117 Adrian Georgescu
*register*(_self_, *contact_header*, *route_header*, *timeout*=@None@)
2110 117 Adrian Georgescu
>Calling this method will attempt to send a new @REGISTER@ request to the registrar provided, whatever state the object is in.
2111 117 Adrian Georgescu
>If the object is currently busy sending a @REGISTER@, this request will be preempted for the new one.
2112 117 Adrian Georgescu
>Once sent, the @Registration@ object will send either a @SIPRegistrationDidSucceed@ or a @SIPRegistrationDidFail@ notification.
2113 117 Adrian Georgescu
>The @contact_header@ argument is mentioned in the attributes section of this class.
2114 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()@.
2115 117 Adrian Georgescu
2116 117 Adrian Georgescu
*end*(_self_, *timeout*=@None@)
2117 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.
2118 117 Adrian Georgescu
>The @RouteHeader@ used for this will be the same as the last successfully sent @REGISTER@ request.
2119 117 Adrian Georgescu
>If another @REGISTER@ is currently being sent, it will be preempted.
2120 117 Adrian Georgescu
>When the unregistering @REGISTER@ request is sent, a @SIPRegistrationWillEnd@ notification is sent.
2121 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.
2122 117 Adrian Georgescu
>Calling this method when the object is not registered will do nothing.
2123 117 Adrian Georgescu
>The @timeout@ argument has the same meaning as for the @register()@ method.
2124 117 Adrian Georgescu
2125 117 Adrian Georgescu
2126 117 Adrian Georgescu
h4. attributes
2127 117 Adrian Georgescu
2128 117 Adrian Georgescu
2129 117 Adrian Georgescu
2130 117 Adrian Georgescu
*from_header_
2131 117 Adrian Georgescu
>The @(Frozen)FromHeader@ the @Registration@ was sent with.
2132 117 Adrian Georgescu
2133 117 Adrian Georgescu
*credentials*
2134 117 Adrian Georgescu
>The credentials to be used when challenged for authentication by the registrar, represented by a @(Frozen)Credentials@ object. 
2135 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.
2136 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.
2137 117 Adrian Georgescu
2138 117 Adrian Georgescu
*duration*
2139 117 Adrian Georgescu
>The amount of time in seconds to request the registration for at the registrar.
2140 117 Adrian Georgescu
>This attribute is set at object instantiation and can be updated for subsequent @REGISTER@ requests.
2141 117 Adrian Georgescu
2142 117 Adrian Georgescu
*is_registered*
2143 117 Adrian Georgescu
>A boolean read-only property indicating if this object is currently registered.
2144 117 Adrian Georgescu
2145 117 Adrian Georgescu
*contact_header*
2146 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.
2147 117 Adrian Georgescu
>Otherwise, this attribute is @None@
2148 117 Adrian Georgescu
2149 117 Adrian Georgescu
*expires_in*
2150 117 Adrian Georgescu
>If registered, this read-only property indicates in how many seconds from now this @Registration@ will expire.
2151 117 Adrian Georgescu
>If this is not the case, this property is 0.
2152 117 Adrian Georgescu
2153 117 Adrian Georgescu
*peer_address*
2154 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.
2155 117 Adrian Georgescu
2156 117 Adrian Georgescu
2157 117 Adrian Georgescu
h4. notifications
2158 117 Adrian Georgescu
2159 117 Adrian Georgescu
2160 117 Adrian Georgescu
2161 117 Adrian Georgescu
*SIPRegistrationDidSucceed*
2162 117 Adrian Georgescu
>This notification will be sent when the @register()@ method was called and the registration succeeded.
2163 117 Adrian Georgescu
  
2164 117 Adrian Georgescu
>+_code_+:
2165 117 Adrian Georgescu
2166 117 Adrian Georgescu
>The SIP response code as received from the registrar as an int.
2167 117 Adrian Georgescu
  
2168 117 Adrian Georgescu
>+_reason_+:
2169 117 Adrian Georgescu
2170 117 Adrian Georgescu
>The reason string received from the SIP registrar.
2171 117 Adrian Georgescu
  
2172 117 Adrian Georgescu
>+_route_header_+:
2173 117 Adrian Georgescu
2174 117 Adrian Georgescu
>The @(Frozen)RouteHeader@ object passed as an argument to the @register()@ method.
2175 117 Adrian Georgescu
  
2176 117 Adrian Georgescu
>+_contact_header_+:
2177 117 Adrian Georgescu
2178 117 Adrian Georgescu
>The contact header that was sent to the registrar as a @FrozenContactHeader@ object.
2179 117 Adrian Georgescu
  
2180 117 Adrian Georgescu
>+_contact_header_list_+:
2181 117 Adrian Georgescu
2182 117 Adrian Georgescu
>A full list of contact headers that are registered for this SIP account, including the one used for this registration.
2183 117 Adrian Georgescu
>The format of this data attribute is a list of FrozenContactHeader objects.
2184 117 Adrian Georgescu
  
2185 117 Adrian Georgescu
>+_expires_in_+:
2186 117 Adrian Georgescu
2187 117 Adrian Georgescu
>The number of seconds before this registration expires
2188 117 Adrian Georgescu
2189 117 Adrian Georgescu
*SIPRegistrationDidFail*
2190 117 Adrian Georgescu
>This notification will be sent when the @register()@ method was called and the registration failed, for whatever reason.
2191 117 Adrian Georgescu
  
2192 117 Adrian Georgescu
>+_code_+:
2193 117 Adrian Georgescu
2194 117 Adrian Georgescu
>The SIP response code as received from the registrar as an int.
2195 117 Adrian Georgescu
>This can also be a PJSIP generated response code, or 0 if the failure was because of an internal error.
2196 117 Adrian Georgescu
  
2197 117 Adrian Georgescu
>+_reason_+:
2198 117 Adrian Georgescu
2199 117 Adrian Georgescu
>The reason string received from the SIP registrar or the error string.
2200 117 Adrian Georgescu
  
2201 117 Adrian Georgescu
>+_route_header_+:
2202 117 Adrian Georgescu
2203 117 Adrian Georgescu
>The @(Frozen)RouteHeader@ object passed as an argument to the @register()@ method.
2204 117 Adrian Georgescu
2205 117 Adrian Georgescu
*SIPRegistrationWillExpire*
2206 117 Adrian Georgescu
>This notification will be sent when a registration will expire soon.
2207 117 Adrian Georgescu
>It should be used as an indication to re-perform DNS lookup of the registrar and call the @register()@ method.
2208 117 Adrian Georgescu
  
2209 117 Adrian Georgescu
>+_expires_+:
2210 117 Adrian Georgescu
2211 117 Adrian Georgescu
>The number of seconds in which the registration will expire.
2212 117 Adrian Georgescu
2213 117 Adrian Georgescu
*SIPRegistrationWillEnd*
2214 117 Adrian Georgescu
>Will be sent whenever the @end()@ method was called and an unregistering @REGISTER@ is sent.
2215 117 Adrian Georgescu
2216 117 Adrian Georgescu
*SIPRegistrationDidNotEnd*
2217 117 Adrian Georgescu
>This notification will be sent when the unregistering @REGISTER@ request failed for some reason.
2218 117 Adrian Georgescu
  
2219 117 Adrian Georgescu
>+_code_+:
2220 117 Adrian Georgescu
2221 117 Adrian Georgescu
>The SIP response code as received from the registrar as an int.
2222 117 Adrian Georgescu
>This can also be a PJSIP generated response code, or 0 if the failure was because of an internal error.
2223 117 Adrian Georgescu
  
2224 117 Adrian Georgescu
>+_reason_+:
2225 117 Adrian Georgescu
2226 117 Adrian Georgescu
>The reason string received from the SIP registrar or the error string.
2227 117 Adrian Georgescu
2228 117 Adrian Georgescu
*SIPRegistrationDidEnd*
2229 117 Adrian Georgescu
>This notification will be sent when a @Registration@ has become unregistered.
2230 117 Adrian Georgescu
  
2231 117 Adrian Georgescu
>+_expired_+:
2232 117 Adrian Georgescu
2233 117 Adrian Georgescu
>This boolean indicates if the object is unregistered because the registration expired, in which case it will be set to @True@.
2234 117 Adrian Georgescu
>If this data attribute is @False@, it means that unregistration was explicitly requested through the @end()@ method.
2235 117 Adrian Georgescu
2236 117 Adrian Georgescu
2237 117 Adrian Georgescu
h4. example code
2238 117 Adrian Georgescu
2239 117 Adrian Georgescu
2240 99 Adrian Georgescu
For an example on how to use this object, see the Integration section.
2241 103 Adrian Georgescu
2242 103 Adrian Georgescu
2243 117 Adrian Georgescu
h3. Publication
2244 103 Adrian Georgescu
2245 103 Adrian Georgescu
2246 117 Adrian Georgescu
Publication of SIP events is an Internet standard published at "RFC 3903":http://tools.ietf.org/html/rfc3903. 
2247 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.
2248 103 Adrian Georgescu
2249 117 Adrian Georgescu
A @Publication@ object represents publishing some content for a particular SIP account and a particular event type at the SIP presence agent through a series of @PUBLISH@ request.
2250 117 Adrian Georgescu
This object is similar in behaviour to the @Registration@ object, as it is also based on a sequence of @Request@ objects.
2251 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.
2252 103 Adrian Georgescu
2253 103 Adrian Georgescu
2254 117 Adrian Georgescu
h4. methods
2255 103 Adrian Georgescu
2256 103 Adrian Georgescu
2257 103 Adrian Georgescu
2258 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_, *from_header*, *event*, *content_type*, *credentials*=@None@, *duration*=300)
2259 117 Adrian Georgescu
>Creates a new @Publication@ object with the specified arguments.
2260 117 Adrian Georgescu
>These arguments are documented in the attributes section for this class.
2261 103 Adrian Georgescu
2262 117 Adrian Georgescu
*publish*(_self_, *body*, *route_header*, *timeout*=@None@)
2263 117 Adrian Georgescu
>Send an actual @PUBLISH@ request to the specified presence agent.
2264 117 Adrian Georgescu
  
2265 117 Adrian Georgescu
>+_body_+:
2266 103 Adrian Georgescu
2267 117 Adrian Georgescu
>The body to place in the @PUBLISH@ request as a string.
2268 117 Adrian Georgescu
>This body needs to be of the content type specified at object creation.
2269 117 Adrian Georgescu
>For the initial request, a body will need to be specified.
2270 117 Adrian Georgescu
>For subsequent refreshing @PUBLISH@ requests, the body can be @None@ to indicate that the last published body should be refreshed.
2271 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@.
2272 117 Adrian Georgescu
  
2273 117 Adrian Georgescu
>+_route_header_+:
2274 103 Adrian Georgescu
2275 117 Adrian Georgescu
>The host where the request should be sent to in the form of a @(Frozen)RouteHeader@ object.
2276 117 Adrian Georgescu
  
2277 117 Adrian Georgescu
>+_timeout_+:
2278 103 Adrian Georgescu
2279 117 Adrian Georgescu
>This can be either an int or a float, indicating in how many seconds the @SUBSCRIBE@ request should timeout with an internally generated 408 response.
2280 117 Adrian Georgescu
>This is is @None@, the internal 408 is only triggered by the internal PJSIP transaction timeout.
2281 117 Adrian Georgescu
>Note that, even if the timeout is specified, the PJSIP timeout is also still valid.
2282 103 Adrian Georgescu
2283 117 Adrian Georgescu
*end*(_self_, *timeout*=@None@)
2284 117 Adrian Georgescu
>End the publication by sending a @PUBLISH@ request with an @Expires@ header of 0.
2285 117 Adrian Georgescu
>If the object is not published, this will result in a @PublicationError@ being thrown.
2286 117 Adrian Georgescu
  
2287 117 Adrian Georgescu
>+_timeout_+:
2288 103 Adrian Georgescu
2289 117 Adrian Georgescu
>The meaning of this argument is the same as it is for the @publish()@ method.
2290 103 Adrian Georgescu
2291 103 Adrian Georgescu
2292 117 Adrian Georgescu
h4. attributes
2293 103 Adrian Georgescu
2294 103 Adrian Georgescu
2295 103 Adrian Georgescu
2296 117 Adrian Georgescu
*from_header_
2297 117 Adrian Georgescu
>The @(Frozen)FromHeader@ the @Publication@ was sent with.
2298 103 Adrian Georgescu
2299 117 Adrian Georgescu
*event_
2300 117 Adrian Georgescu
>The name of the event this object is publishing for the specified SIP URI, as a string.
2301 103 Adrian Georgescu
2302 117 Adrian Georgescu
*content_type_
2303 117 Adrian Georgescu
>The @Content-Type@ of the body that will be in the @PUBLISH@ requests.
2304 117 Adrian Georgescu
>Typically this will remain the same throughout the publication session, but the attribute may be updated by the application if needed.
2305 117 Adrian Georgescu
>Note that this attribute needs to be in the typical MIME type form, containing a "/" character.
2306 103 Adrian Georgescu
2307 117 Adrian Georgescu
*credentials*
2308 117 Adrian Georgescu
>The credentials to be used when challenged for authentication by the presence agent, represented by a @(Frozen)Credentials@ object. 
2309 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.
2310 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.
2311 103 Adrian Georgescu
2312 117 Adrian Georgescu
*duration*
2313 117 Adrian Georgescu
>The amount of time in seconds that the publication should be valid for.
2314 117 Adrian Georgescu
>This attribute is set at object instantiation and can be updated for subsequent @PUBLISH@ requests.
2315 103 Adrian Georgescu
2316 117 Adrian Georgescu
*is_published*
2317 117 Adrian Georgescu
>A boolean read-only property indicating if this object is currently published.
2318 103 Adrian Georgescu
2319 117 Adrian Georgescu
*expires_in*
2320 117 Adrian Georgescu
>If published, this read-only property indicates in how many seconds from now this @Publication@ will expire.
2321 117 Adrian Georgescu
>If this is not the case, this property is 0.
2322 103 Adrian Georgescu
2323 117 Adrian Georgescu
*peer_address*
2324 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.
2325 103 Adrian Georgescu
2326 117 Adrian Georgescu
2327 117 Adrian Georgescu
h4. notifications
2328 117 Adrian Georgescu
2329 117 Adrian Georgescu
2330 117 Adrian Georgescu
2331 117 Adrian Georgescu
*SIPPublicationDidSucceed*
2332 117 Adrian Georgescu
>This notification will be sent when the @publish()@ method was called and the publication succeeded.
2333 117 Adrian Georgescu
  
2334 117 Adrian Georgescu
>+_code_+:
2335 117 Adrian Georgescu
2336 117 Adrian Georgescu
>The SIP response code as received from the SIP presence agent as an int.
2337 117 Adrian Georgescu
  
2338 117 Adrian Georgescu
>+_reason_+:
2339 117 Adrian Georgescu
2340 117 Adrian Georgescu
>The reason string received from the SIP presence agent.
2341 117 Adrian Georgescu
  
2342 117 Adrian Georgescu
>+_route_header_+:
2343 117 Adrian Georgescu
2344 117 Adrian Georgescu
>The @(Frozen)RouteHeader@ object passed as an argument to the @publish()@ method.
2345 117 Adrian Georgescu
  
2346 117 Adrian Georgescu
>+_expires_in_+:
2347 117 Adrian Georgescu
2348 117 Adrian Georgescu
>The number of seconds before this publication expires
2349 117 Adrian Georgescu
2350 117 Adrian Georgescu
*SIPPublicationDidFail*
2351 117 Adrian Georgescu
>This notification will be sent when the @publish()@ method was called and the publication failed, for whatever reason.
2352 117 Adrian Georgescu
  
2353 117 Adrian Georgescu
>+_code_+:
2354 117 Adrian Georgescu
2355 117 Adrian Georgescu
>The SIP response code as received from the presence agent as an int.
2356 117 Adrian Georgescu
>This can also be a PJSIP generated response code, or 0 if the failure was because of an internal error.
2357 117 Adrian Georgescu
  
2358 117 Adrian Georgescu
>+_reason_+:
2359 117 Adrian Georgescu
2360 117 Adrian Georgescu
>The reason string received from the presence agent or the error string.
2361 117 Adrian Georgescu
  
2362 117 Adrian Georgescu
>+_route_header_+:
2363 117 Adrian Georgescu
2364 117 Adrian Georgescu
>The @(Frozen)RouteHeader@ object passed as an argument to the @publish()@ method.
2365 117 Adrian Georgescu
2366 117 Adrian Georgescu
*SIPPublicationWillExpire*
2367 117 Adrian Georgescu
>This notification will be sent when a publication will expire soon.
2368 117 Adrian Georgescu
>It should be used as an indication to re-perform DNS lookup of the presence agent and call the @publish()@ method.
2369 117 Adrian Georgescu
  
2370 117 Adrian Georgescu
>+_expires_+:
2371 117 Adrian Georgescu
2372 117 Adrian Georgescu
>The number of seconds in which the publication will expire.
2373 117 Adrian Georgescu
2374 117 Adrian Georgescu
*SIPPublicationWillEnd*
2375 117 Adrian Georgescu
>Will be sent whenever the @end()@ method was called and an unpublishing @PUBLISH@ is sent.
2376 117 Adrian Georgescu
2377 117 Adrian Georgescu
*SIPPublicationDidNotEnd*
2378 117 Adrian Georgescu
>This notification will be sent when the unpublishing @PUBLISH@ request failed for some reason.
2379 117 Adrian Georgescu
  
2380 117 Adrian Georgescu
>+_code_+:
2381 117 Adrian Georgescu
2382 117 Adrian Georgescu
>The SIP response code as received from the presence agent as an int.
2383 117 Adrian Georgescu
>This can also be a PJSIP generated response code, or 0 if the failure was because of an internal error.
2384 117 Adrian Georgescu
  
2385 117 Adrian Georgescu
>+_reason_+:
2386 117 Adrian Georgescu
2387 117 Adrian Georgescu
>The reason string received from the presence agent or the error string.
2388 117 Adrian Georgescu
2389 117 Adrian Georgescu
*SIPPublicationDidEnd*
2390 117 Adrian Georgescu
>This notification will be sent when a @Publication@ has become unpublished.
2391 117 Adrian Georgescu
  
2392 117 Adrian Georgescu
>+_expired_+:
2393 117 Adrian Georgescu
2394 117 Adrian Georgescu
>This boolean indicates if the object is unpublished because the publication expired, in which case it will be set to @True@.
2395 117 Adrian Georgescu
>If this data attribute is @False@, it means that unpublication was explicitly requested through the @end()@ method.
2396 117 Adrian Georgescu
2397 117 Adrian Georgescu
2398 117 Adrian Georgescu
h3. Subscription
2399 117 Adrian Georgescu
2400 117 Adrian Georgescu
2401 117 Adrian Georgescu
Subscription and notifications for SIP events is an Internet standard published at "RFC 3856":http://tools.ietf.org/html/rfc3856.
2402 117 Adrian Georgescu
2403 1 Adrian Georgescu
This SIP primitive class represents a subscription to a specific event type of a particular SIP URI.
2404 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.
2405 117 Adrian Georgescu
The event type and the content types that are acceptable for it need to be registered first, either through the @init_options@ attribute of @Engine@ (before starting it), or by calling the @add_event()@ method of the @Engine@ instance.
2406 117 Adrian Georgescu
Whenever a @NOTIFY@ is received, the application will receive the @SIPSubscriptionGotNotify@ event.
2407 1 Adrian Georgescu
2408 117 Adrian Georgescu
Internally a @Subscription@ object has a state machine, which reflects the state of the subscription.
2409 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@.
2410 117 Adrian Georgescu
The last three states are directly copied from the contents of the @Subscription-State@ header of the received @NOTIFY@ request.
2411 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.
2412 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.
2413 1 Adrian Georgescu
This notification is only informational, an application using this object should take actions based on the other notifications sent by this object.
2414 1 Adrian Georgescu
2415 1 Adrian Georgescu
2416 117 Adrian Georgescu
h4. methods
2417 1 Adrian Georgescu
2418 1 Adrian Georgescu
2419 1 Adrian Georgescu
2420 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_, *request_uri*, *from_header*, *to_header*, *contact_header, *event*, *route_header*, *credentials*=@None@, *refresh*=300)
2421 117 Adrian Georgescu
>Creates a new @Subscription@ object which will be in the @NULL@ state.
2422 117 Adrian Georgescu
>The arguments for this method are documented in the attributes section above.
2423 1 Adrian Georgescu
2424 117 Adrian Georgescu
*subscribe*(_self_, *extra_headers*=@None@, *content_type*=@None@, *body*=@None@, *timeout*=@None@)
2425 117 Adrian Georgescu
>Calling this method triggers sending a @SUBSCRIBE@ request to the presence agent.
2426 117 Adrian Georgescu
>The arguments passed will be stored and used for subsequent refreshing @SUBSCRIBE@ requests.
2427 117 Adrian Georgescu
>This method may be used both to send the initial request and to update the arguments while the subscription is ongoing.
2428 117 Adrian Georgescu
>It may not be called when the object is in the @TERMINATED@ state.
2429 117 Adrian Georgescu
  
2430 117 Adrian Georgescu
>+_extra_headers_+:
2431 1 Adrian Georgescu
2432 117 Adrian Georgescu
>A dictionary of additional headers to include in the @SUBSCRIBE@ requests.
2433 117 Adrian Georgescu
  
2434 117 Adrian Georgescu
>+_content_type_+:
2435 1 Adrian Georgescu
2436 117 Adrian Georgescu
>The @Content-Type@ of the supplied @body@ argument as a string.
2437 117 Adrian Georgescu
>If this argument is supplied, the @body@ argument cannot be @None@.
2438 117 Adrian Georgescu
  
2439 117 Adrian Georgescu
>+_body_+:
2440 1 Adrian Georgescu
2441 117 Adrian Georgescu
>The optional body to include in the @SUBSCRIBE@ request as a string.
2442 117 Adrian Georgescu
>If this argument is supplied, the @content_type@ argument cannot be @None@.
2443 117 Adrian Georgescu
  
2444 117 Adrian Georgescu
>+_timeout_+:
2445 1 Adrian Georgescu
2446 117 Adrian Georgescu
>This can be either an int or a float, indicating in how many seconds the request should timeout with an internally generated 408 response.
2447 117 Adrian Georgescu
>If this is @None@, the internal 408 is only triggered by the internal PJSIP transaction timeout.
2448 117 Adrian Georgescu
>Note that, even if the timeout is specified, the PJSIP timeout is also still valid.
2449 1 Adrian Georgescu
2450 117 Adrian Georgescu
*end*(_self_, *timeout*=@None@)
2451 117 Adrian Georgescu
>This will end the subscription by sending a @SUBSCRIBE@ request with an @Expires@ value of 0.
2452 117 Adrian Georgescu
>If this object is no longer subscribed, this method will return without performing any action.
2453 117 Adrian Georgescu
>This method cannot be called when the object is in the @NULL@ state.
2454 117 Adrian Georgescu
>The @timeout@ argument has the same meaning as it does for the @subscribe()@ method.
2455 1 Adrian Georgescu
2456 1 Adrian Georgescu
2457 117 Adrian Georgescu
h4. attributes
2458 1 Adrian Georgescu
2459 1 Adrian Georgescu
2460 1 Adrian Georgescu
2461 117 Adrian Georgescu
*state*
2462 117 Adrian Georgescu
>Indicates which state the internal state machine is in.
2463 117 Adrian Georgescu
>See the previous section for a list of states the state machine can be in.
2464 1 Adrian Georgescu
2465 117 Adrian Georgescu
*from_header*
2466 117 Adrian Georgescu
>The @FrozenFromHeader@ to be put in the @From@ header of the @SUBSCRIBE@ requests.
2467 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
2468 1 Adrian Georgescu
2469 117 Adrian Georgescu
*to_header*
2470 117 Adrian Georgescu
>The @FrozenToHeader@ that is the target for the subscription.
2471 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
2472 1 Adrian Georgescu
2473 117 Adrian Georgescu
*contact_header*
2474 117 Adrian Georgescu
>The @FrozenContactHeader@ to be put in the @Contact@ header of the @SUBSCRIBE@ requests.
2475 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
2476 1 Adrian Georgescu
2477 117 Adrian Georgescu
*event*
2478 117 Adrian Georgescu
>The event package for which the subscription is as a string.
2479 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
2480 1 Adrian Georgescu
2481 117 Adrian Georgescu
*route_header*
2482 117 Adrian Georgescu
>The outbound proxy to use in the form of a @FrozenRouteHeader@ object.
2483 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
2484 1 Adrian Georgescu
2485 117 Adrian Georgescu
*credentials*
2486 117 Adrian Georgescu
>The SIP credentials needed to authenticate at the SIP proxy in the form of a @FrozenCredentials@ object.
2487 117 Adrian Georgescu
>If none was specified when creating the @Subscription@ object, this attribute is @None@.
2488 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
2489 1 Adrian Georgescu
2490 117 Adrian Georgescu
*refresh*
2491 117 Adrian Georgescu
>The refresh interval in seconds that was requested on object instantiation as an int.
2492 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
2493 1 Adrian Georgescu
2494 117 Adrian Georgescu
*extra_headers*
2495 117 Adrian Georgescu
>This contains the @frozenlist@ of extra headers 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 an empty list.
2497 117 Adrian Georgescu
>This attribute is read-only.
2498 1 Adrian Georgescu
2499 117 Adrian Georgescu
*content_type*
2500 117 Adrian Georgescu
>This attribute contains the @Content-Type@ of the body that was last passed to a successful call to the @subscribe()@ method.
2501 117 Adrian Georgescu
>If the argument was not provided, this attribute is @None@.
2502 1 Adrian Georgescu
2503 117 Adrian Georgescu
*body*
2504 117 Adrian Georgescu
>This attribute contains the @body@ string argument that was last passed to a successful call to the @subscribe()@ method.
2505 117 Adrian Georgescu
>If the argument was not provided, this attribute is @None@.
2506 1 Adrian Georgescu
2507 117 Adrian Georgescu
*peer_address*
2508 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.
2509 1 Adrian Georgescu
2510 1 Adrian Georgescu
2511 117 Adrian Georgescu
h4. notifications
2512 1 Adrian Georgescu
2513 1 Adrian Georgescu
2514 1 Adrian Georgescu
2515 117 Adrian Georgescu
*SIPSubscriptionChangedState*
2516 117 Adrian Georgescu
>This notification will be sent every time the internal state machine of a @Subscription@ object changes state.
2517 117 Adrian Georgescu
  
2518 117 Adrian Georgescu
>+_timestamp_+:
2519 1 Adrian Georgescu
2520 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2521 117 Adrian Georgescu
  
2522 117 Adrian Georgescu
>+_prev_state_+:
2523 1 Adrian Georgescu
2524 117 Adrian Georgescu
>The previous state that the sate machine was in.
2525 117 Adrian Georgescu
  
2526 117 Adrian Georgescu
>+_state_+:
2527 1 Adrian Georgescu
2528 117 Adrian Georgescu
>The new state the state machine moved into.
2529 1 Adrian Georgescu
2530 117 Adrian Georgescu
*SIPSubscriptionWillStart*
2531 117 Adrian Georgescu
>This notification will be emitted when the initial @SUBSCRIBE@ request is sent.
2532 117 Adrian Georgescu
  
2533 117 Adrian Georgescu
>+_timestamp_+:
2534 1 Adrian Georgescu
2535 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2536 1 Adrian Georgescu
2537 117 Adrian Georgescu
*SIPSubscriptionDidStart*
2538 117 Adrian Georgescu
>This notification will be sent when the initial @SUBSCRIBE@ was accepted by the presence agent.
2539 117 Adrian Georgescu
  
2540 117 Adrian Georgescu
>+_timestamp_+:
2541 1 Adrian Georgescu
2542 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2543 1 Adrian Georgescu
2544 117 Adrian Georgescu
*SIPSubscriptionGotNotify*
2545 117 Adrian Georgescu
>This notification will be sent when a @NOTIFY@ is received that corresponds to a particular @Subscription@ object.
2546 117 Adrian Georgescu
>Note that this notification could be sent when a @NOTIFY@ without a body is received.
2547 117 Adrian Georgescu
  
2548 117 Adrian Georgescu
>+_request_uri_+:
2549 1 Adrian Georgescu
2550 117 Adrian Georgescu
>The request URI of the @NOTIFY@ request as a @SIPURI@ object.
2551 117 Adrian Georgescu
  
2552 117 Adrian Georgescu
>+_from_header_+:
2553 1 Adrian Georgescu
2554 117 Adrian Georgescu
>The From header of the @NOTIFY@ request as a @FrozenFromHeader@ object.
2555 117 Adrian Georgescu
  
2556 117 Adrian Georgescu
>+_to_header_+:
2557 1 Adrian Georgescu
2558 117 Adrian Georgescu
>The To header of the @NOTIFY@ request as a @FrozenToHeader@ object.
2559 117 Adrian Georgescu
  
2560 117 Adrian Georgescu
>+_content_type_+:
2561 1 Adrian Georgescu
2562 117 Adrian Georgescu
>The Content-Type header value of the @NOTIFY@ request as a @ContentType@ object.
2563 117 Adrian Georgescu
  
2564 117 Adrian Georgescu
>+_event_+:
2565 1 Adrian Georgescu
2566 117 Adrian Georgescu
>The Event header value of the @NOTIFY@ request as a string object.
2567 117 Adrian Georgescu
  
2568 117 Adrian Georgescu
>+_headers_+:
2569 1 Adrian Georgescu
2570 117 Adrian Georgescu
>The headers of the @NOTIFY@ request as a dict.
2571 117 Adrian Georgescu
>Each SIP header is represented in its parsed for as long as PJSIP supports it.
2572 117 Adrian Georgescu
>The format of the parsed value depends on the header.
2573 117 Adrian Georgescu
  
2574 117 Adrian Georgescu
>+_body_+:
2575 1 Adrian Georgescu
2576 117 Adrian Georgescu
>The body of the @NOTIFY@ request as a string, or @None@ if no body was included.
2577 117 Adrian Georgescu
  
2578 117 Adrian Georgescu
>+_timestamp_+:
2579 1 Adrian Georgescu
2580 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.  
2581 1 Adrian Georgescu
2582 117 Adrian Georgescu
*SIPSubscriptionDidFail*
2583 117 Adrian Georgescu
>This notification will be sent whenever there is a failure, such as a rejected initial or refreshing @SUBSCRIBE@.
2584 117 Adrian Georgescu
>After this notification the @Subscription@ object is in the @TERMINATED@ state and can no longer be used.
2585 117 Adrian Georgescu
  
2586 117 Adrian Georgescu
>+_timestamp_+:
2587 1 Adrian Georgescu
2588 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2589 117 Adrian Georgescu
  
2590 117 Adrian Georgescu
>+_code_+:
2591 1 Adrian Georgescu
2592 117 Adrian Georgescu
>An integer SIP code from the fatal response that was received from the remote party of generated by PJSIP.
2593 117 Adrian Georgescu
>If the error is internal to the SIP core, this attribute will have a value of 0.
2594 117 Adrian Georgescu
  
2595 117 Adrian Georgescu
>+_reason_+:
2596 1 Adrian Georgescu
2597 117 Adrian Georgescu
>An text string describing the failure that occurred.
2598 117 Adrian Georgescu
  
2599 117 Adrian Georgescu
>+_min_expires_+:
2600 1 Adrian Georgescu
2601 117 Adrian Georgescu
>An integer containing the value from the Min-Expires header. Will be None if the response doesn't contain the header.
2602 1 Adrian Georgescu
2603 117 Adrian Georgescu
*SIPSubscriptionDidEnd*
2604 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.
2605 117 Adrian Georgescu
>After this notification the @Subscription@ object is in the @TERMINATED@ state and can no longer be used.
2606 117 Adrian Georgescu
  
2607 117 Adrian Georgescu
>+_timestamp_+:
2608 1 Adrian Georgescu
2609 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2610 1 Adrian Georgescu
2611 1 Adrian Georgescu
2612 117 Adrian Georgescu
h3. IncomingSubscription
2613 1 Adrian Georgescu
2614 1 Adrian Georgescu
2615 117 Adrian Georgescu
Subscription and notifications for SIP events is an Internet standard published at "RFC 3856":http://tools.ietf.org/html/rfc3856.
2616 1 Adrian Georgescu
2617 117 Adrian Georgescu
This SIP primitive class is the mirror companion to the @Subscription@ class and allows the application to take on the server role in a @SUBSCRIBE@ session.
2618 117 Adrian Georgescu
This means that it can accept a @SUBSCRIBE@ request and subsequent refreshing @SUBSCRIBE@s and sent @NOTIFY@ requests containing event state.
2619 117 Adrian Georgescu
2620 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.
2621 117 Adrian Georgescu
This event needs to be known by the @Engine@, i.e. it should already be present in the @events@ dictionary attribute.
2622 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.
2623 117 Adrian Georgescu
This will be indicated to the application through a @SIPIncomingSubscriptionGotSubscribe@ notification.
2624 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.
2625 117 Adrian Georgescu
2626 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.
2627 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.
2628 117 Adrian Georgescu
Whenever a refreshing @SUBSCRIBE@ is received, the latest contents to be set are sent in the resulting @NOTIFY@ request.
2629 117 Adrian Georgescu
The subscription can be ended by using the @end()@ method.
2630 117 Adrian Georgescu
2631 117 Adrian Georgescu
2632 117 Adrian Georgescu
h4. methods
2633 117 Adrian Georgescu
2634 117 Adrian Georgescu
2635 117 Adrian Georgescu
2636 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_)
2637 117 Adrian Georgescu
>An application should never create an @IncomingSubscription@ object itself.
2638 117 Adrian Georgescu
>Doing this will create a useless object in the @None@ state.
2639 117 Adrian Georgescu
2640 117 Adrian Georgescu
*reject*(_self_, *code*)
2641 117 Adrian Georgescu
>Will reply to the initial @SUBSCRIBE@ with a negative response.
2642 117 Adrian Georgescu
>This method can only be called in the @"incoming"@ state and sets the subscription to the @"terminated"@ state.
2643 117 Adrian Georgescu
  
2644 117 Adrian Georgescu
>+_code_+:
2645 117 Adrian Georgescu
2646 117 Adrian Georgescu
>The SIP response code to use.
2647 117 Adrian Georgescu
>This should be a negative response, i.e. in the 3xx, 4xx, 5xx or 6xx range.
2648 117 Adrian Georgescu
2649 117 Adrian Georgescu
*accept_pending*(_self_)
2650 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.
2651 117 Adrian Georgescu
>The application can later decide to fully accept the subscription or terminate it.
2652 117 Adrian Georgescu
>This method can only be called in the @"incoming"@ state.
2653 117 Adrian Georgescu
2654 117 Adrian Georgescu
*accept*(_self_, *content_type*=@None@, *content*=@None@)
2655 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.
2656 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.
2657 117 Adrian Georgescu
>This method can only be called in the @"incoming"@ or @"pending"@ state.
2658 117 Adrian Georgescu
  
2659 117 Adrian Georgescu
>+_content_type_+:
2660 117 Adrian Georgescu
2661 117 Adrian Georgescu
>The Content-Type of the content to be set supplied as a string containing a @"/"@ character.
2662 117 Adrian Georgescu
>Note that if this argument is set, the @content@ argument should also be set.
2663 117 Adrian Georgescu
  
2664 117 Adrian Georgescu
>+_content_+:
2665 117 Adrian Georgescu
2666 117 Adrian Georgescu
>The body of the @NOTIFY@ to send when accepting the subscription, as a string.
2667 117 Adrian Georgescu
>Note that if this argument is set, the @content_type@ argument should also be set.
2668 117 Adrian Georgescu
2669 117 Adrian Georgescu
*push_content*(_self_, *content_type*, *content*)
2670 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.
2671 117 Adrian Georgescu
>This method can only be called in the @"active"@ state.
2672 117 Adrian Georgescu
  
2673 117 Adrian Georgescu
>+_content_type_+:
2674 117 Adrian Georgescu
2675 117 Adrian Georgescu
>The Content-Type of the content to be set supplied as a string containing a @"/"@ character.
2676 117 Adrian Georgescu
  
2677 117 Adrian Georgescu
>+_content_+:
2678 117 Adrian Georgescu
2679 117 Adrian Georgescu
>The body of the @NOTIFY@ as a string.
2680 117 Adrian Georgescu
2681 117 Adrian Georgescu
2682 117 Adrian Georgescu
h4. attributes
2683 117 Adrian Georgescu
2684 117 Adrian Georgescu
2685 117 Adrian Georgescu
2686 117 Adrian Georgescu
*state*
2687 117 Adrian Georgescu
>Indicates which state the incoming subscription session is in.
2688 117 Adrian Georgescu
>This can be one of @None@, @"incoming"@, @"pending"@, @"active"@ or @"terminated"@.
2689 117 Adrian Georgescu
>This attribute is read-only.
2690 117 Adrian Georgescu
2691 117 Adrian Georgescu
*event*
2692 117 Adrian Georgescu
>The name of the event package that this @IncomingSubscription@ relates to.
2693 117 Adrian Georgescu
>This attribute is a read-only string.
2694 117 Adrian Georgescu
2695 117 Adrian Georgescu
*content_type*
2696 117 Adrian Georgescu
>The @Content-Type@ of the last set content in this subscription session.
2697 117 Adrian Georgescu
>Inititally this will be @None@.
2698 117 Adrian Georgescu
>This attribute is a read-only string.
2699 117 Adrian Georgescu
2700 117 Adrian Georgescu
*content*
2701 117 Adrian Georgescu
>The last set content in this subscription session as a read-only string.
2702 117 Adrian Georgescu
2703 117 Adrian Georgescu
*peer_address*
2704 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.
2705 117 Adrian Georgescu
2706 117 Adrian Georgescu
2707 117 Adrian Georgescu
h4. notifications
2708 117 Adrian Georgescu
2709 117 Adrian Georgescu
2710 117 Adrian Georgescu
2711 117 Adrian Georgescu
*SIPIncomingSubscriptionChangedState*
2712 117 Adrian Georgescu
>This notification will be sent every time the an @IncomingSubscription@ object changes state.
2713 117 Adrian Georgescu
>This notification is mostly indicative, an application should not let its logic depend on it.
2714 117 Adrian Georgescu
  
2715 117 Adrian Georgescu
>+_timestamp_+:
2716 117 Adrian Georgescu
2717 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2718 117 Adrian Georgescu
  
2719 117 Adrian Georgescu
>+_prev_state_+:
2720 117 Adrian Georgescu
2721 117 Adrian Georgescu
>The previous state that the subscription was in.
2722 117 Adrian Georgescu
  
2723 117 Adrian Georgescu
>+_state_+:
2724 117 Adrian Georgescu
2725 117 Adrian Georgescu
>The new state the subscription has.
2726 117 Adrian Georgescu
2727 117 Adrian Georgescu
*SIPIncomingSubscriptionGotSubscribe*
2728 117 Adrian Georgescu
>This notification will be sent when a new @IncomingSubscription@ is created as result of an incoming @SUBSCRIBE@ request.
2729 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.
2730 117 Adrian Georgescu
  
2731 117 Adrian Georgescu
>+_timestamp_+:
2732 117 Adrian Georgescu
2733 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2734 117 Adrian Georgescu
  
2735 117 Adrian Georgescu
>+_method_+:
2736 117 Adrian Georgescu
2737 117 Adrian Georgescu
>The method of the SIP request as a string, which will be @SUBSCRIBE@.
2738 117 Adrian Georgescu
  
2739 117 Adrian Georgescu
>+_request_uri_+:
2740 117 Adrian Georgescu
2741 117 Adrian Georgescu
>The request URI of the @SUBSCRIBE@ request as a @FrozenSIPURI@ object.
2742 117 Adrian Georgescu
  
2743 117 Adrian Georgescu
>+_headers_+:
2744 117 Adrian Georgescu
2745 117 Adrian Georgescu
>The headers of the @SUBSCRIBE@ request as a dict, the values of which are the relevant header objects.
2746 117 Adrian Georgescu
  
2747 117 Adrian Georgescu
>+_body_+:
2748 117 Adrian Georgescu
2749 117 Adrian Georgescu
>The body of the @SUBSCRIBE@ request as a string, or @None@ if no body was included.
2750 117 Adrian Georgescu
2751 117 Adrian Georgescu
*SIPIncomingSubscriptionGotRefreshingSubscribe*
2752 117 Adrian Georgescu
>This notification indicates that a refreshing @SUBSCRIBE@ request was received from the subscriber.
2753 117 Adrian Georgescu
>It is purely informative, no action needs to be taken by the application as a result of it.
2754 117 Adrian Georgescu
  
2755 117 Adrian Georgescu
>+_timestamp_+:
2756 117 Adrian Georgescu
2757 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2758 117 Adrian Georgescu
  
2759 117 Adrian Georgescu
>+_method_+:
2760 117 Adrian Georgescu
2761 117 Adrian Georgescu
>The method of the SIP request as a string, which will be @SUBSCRIBE@.
2762 117 Adrian Georgescu
  
2763 117 Adrian Georgescu
>+_request_uri_+:
2764 117 Adrian Georgescu
2765 117 Adrian Georgescu
>The request URI of the @SUBSCRIBE@ request as a @FrozenSIPURI@ object.
2766 117 Adrian Georgescu
  
2767 117 Adrian Georgescu
>+_headers_+:
2768 117 Adrian Georgescu
2769 117 Adrian Georgescu
>The headers of the @SUBSCRIBE@ request as a dict, the values of which are the relevant header objects.
2770 117 Adrian Georgescu
  
2771 117 Adrian Georgescu
>+_body_+:
2772 117 Adrian Georgescu
2773 117 Adrian Georgescu
>The body of the @SUBSCRIBE@ request as a string, or @None@ if no body was included.
2774 117 Adrian Georgescu
2775 117 Adrian Georgescu
*SIPIncomingSubscriptionGotUnsubscribe*
2776 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.
2777 117 Adrian Georgescu
>It is purely informative, no action needs to be taken by the application as a result of it.
2778 117 Adrian Georgescu
  
2779 117 Adrian Georgescu
>+_timestamp_+:
2780 117 Adrian Georgescu
2781 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2782 117 Adrian Georgescu
  
2783 117 Adrian Georgescu
>+_method_+:
2784 117 Adrian Georgescu
2785 117 Adrian Georgescu
>The method of the SIP request as a string, which will be @SUBSCRIBE@.
2786 117 Adrian Georgescu
  
2787 117 Adrian Georgescu
>+_request_uri_+:
2788 117 Adrian Georgescu
2789 117 Adrian Georgescu
>The request URI of the @SUBSCRIBE@ request as a @FrozenSIPURI@ object.
2790 117 Adrian Georgescu
  
2791 117 Adrian Georgescu
>+_headers_+:
2792 117 Adrian Georgescu
2793 117 Adrian Georgescu
>The headers of the @SUBSCRIBE@ request as a dict, the values of which are the relevant header objects.
2794 117 Adrian Georgescu
  
2795 117 Adrian Georgescu
>+_body_+:
2796 117 Adrian Georgescu
2797 117 Adrian Georgescu
>The body of the @SUBSCRIBE@ request or response as a string, or @None@ if no body was included.
2798 117 Adrian Georgescu
2799 117 Adrian Georgescu
*SIPIncomingSubscriptionAnsweredSubscribe*
2800 117 Adrian Georgescu
>This notification is sent whenever a response to a @SUBSCRIBE@ request is sent by the object, including an unsubscribing @SUBSCRIBE@.
2801 117 Adrian Georgescu
>It is purely informative, no action needs to be taken by the application as a result of it.
2802 117 Adrian Georgescu
  
2803 117 Adrian Georgescu
>+_timestamp_+:
2804 117 Adrian Georgescu
2805 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2806 117 Adrian Georgescu
  
2807 117 Adrian Georgescu
>+_code_+:
2808 117 Adrian Georgescu
2809 117 Adrian Georgescu
>The code of the SIP response as an int.
2810 117 Adrian Georgescu
  
2811 117 Adrian Georgescu
>+_reason_+:
2812 117 Adrian Georgescu
2813 117 Adrian Georgescu
>The reason text of the SIP response as an int.
2814 117 Adrian Georgescu
  
2815 117 Adrian Georgescu
>+_headers_+:
2816 117 Adrian Georgescu
2817 117 Adrian Georgescu
>The headers of the response as a dict, the values of which are the relevant header objects.
2818 117 Adrian Georgescu
  
2819 117 Adrian Georgescu
>+_body_+:
2820 117 Adrian Georgescu
2821 117 Adrian Georgescu
>This will be @None@.
2822 117 Adrian Georgescu
2823 117 Adrian Georgescu
*SIPIncomingSubscriptionSentNotify*
2824 117 Adrian Georgescu
>This notification indicates that a @NOTIFY@ request was sent to the subscriber.
2825 117 Adrian Georgescu
>It is purely informative, no action needs to be taken by the application as a result of it.
2826 117 Adrian Georgescu
  
2827 117 Adrian Georgescu
>+_timestamp_+:
2828 117 Adrian Georgescu
2829 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2830 117 Adrian Georgescu
  
2831 117 Adrian Georgescu
>+_method_+:
2832 117 Adrian Georgescu
2833 117 Adrian Georgescu
>The method of the SIP request as a string, which will be @NOTIFY@.
2834 117 Adrian Georgescu
  
2835 117 Adrian Georgescu
>+_request_uri_+:
2836 117 Adrian Georgescu
2837 117 Adrian Georgescu
>The request URI of the @NOTIFY@ request as a @FrozenSIPURI@ object.
2838 117 Adrian Georgescu
  
2839 117 Adrian Georgescu
>+_headers_+:
2840 117 Adrian Georgescu
2841 117 Adrian Georgescu
>The headers of the @NOTIFY@ request as a dict, the values of which are the relevant header objects.
2842 117 Adrian Georgescu
  
2843 117 Adrian Georgescu
>+_body_+:
2844 117 Adrian Georgescu
2845 117 Adrian Georgescu
>The body of the @NOTIFY@ request or response as a string, or @None@ if no body was included.
2846 117 Adrian Georgescu
2847 117 Adrian Georgescu
*SIPIncomingSubscriptionNotifyDidSucceed*
2848 117 Adrian Georgescu
>This indicates that a positive final response was received from the subscriber in reply to a sent @NOTIFY@ request.
2849 117 Adrian Georgescu
>The notification is purely informative, no action needs to be taken by the application as a result of it.
2850 117 Adrian Georgescu
  
2851 117 Adrian Georgescu
>+_timestamp_+:
2852 117 Adrian Georgescu
2853 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2854 117 Adrian Georgescu
  
2855 117 Adrian Georgescu
>+_code_+:
2856 117 Adrian Georgescu
2857 117 Adrian Georgescu
>The code of the SIP response as an int.
2858 117 Adrian Georgescu
  
2859 117 Adrian Georgescu
>+_reason_+:
2860 117 Adrian Georgescu
2861 117 Adrian Georgescu
>The reason text of the SIP response as a string.
2862 117 Adrian Georgescu
  
2863 117 Adrian Georgescu
>+_headers_+:
2864 117 Adrian Georgescu
2865 117 Adrian Georgescu
>The headers of the response as a dict, the values of which are the relevant header objects.
2866 117 Adrian Georgescu
  
2867 117 Adrian Georgescu
>+_body_+:
2868 117 Adrian Georgescu
2869 117 Adrian Georgescu
>This will be @None@.
2870 117 Adrian Georgescu
2871 117 Adrian Georgescu
*SIPIncomingSubscriptionNotifyDidFail*
2872 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.
2873 117 Adrian Georgescu
  
2874 117 Adrian Georgescu
>+_timestamp_+:
2875 117 Adrian Georgescu
2876 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2877 117 Adrian Georgescu
  
2878 117 Adrian Georgescu
>+_code_+:
2879 117 Adrian Georgescu
2880 117 Adrian Georgescu
>The code of the SIP response as an int.
2881 117 Adrian Georgescu
>If this is 0, the notification was sent as a result of an internal error.
2882 117 Adrian Georgescu
  
2883 117 Adrian Georgescu
>+_reason_+:
2884 117 Adrian Georgescu
2885 117 Adrian Georgescu
>The reason text of the SIP response as a string or the internal error if the code attribute is 0.
2886 117 Adrian Georgescu
  
2887 117 Adrian Georgescu
>+_headers_+: (if the notification was caused by a negative response)
2888 117 Adrian Georgescu
2889 117 Adrian Georgescu
>The headers of the response as a dict, the values of which are the relevant header objects.
2890 117 Adrian Georgescu
  
2891 117 Adrian Georgescu
>+_body_+: (if the notification was caused by a negative response)
2892 117 Adrian Georgescu
2893 117 Adrian Georgescu
>This will be @None@.
2894 117 Adrian Georgescu
2895 117 Adrian Georgescu
*SIPIncomingSubscriptionDidEnd*
2896 117 Adrian Georgescu
>This notification is sent whenever the @IncomingSubscription@ object reaches the @"terminated"@ state and is no longer valid.
2897 117 Adrian Georgescu
>After receiving this notification, the application should not longer try to use the object.
2898 117 Adrian Georgescu
  
2899 117 Adrian Georgescu
>+_timestamp_+:
2900 117 Adrian Georgescu
2901 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
2902 117 Adrian Georgescu
2903 117 Adrian Georgescu
2904 117 Adrian Georgescu
h3. Referral
2905 117 Adrian Georgescu
2906 117 Adrian Georgescu
2907 117 Adrian Georgescu
Subscription and notifications for SIP events is an Internet standard published at "RFC 3856":http://tools.ietf.org/html/rfc3856.
2908 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.
2909 117 Adrian Georgescu
2910 1 Adrian Georgescu
This SIP primitive class represents a referral requested by the client to a target URI.
2911 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.
2912 117 Adrian Georgescu
Whenever a @NOTIFY@ is received, the application will receive the @SIPReferralGotNotify@ notification.
2913 1 Adrian Georgescu
2914 117 Adrian Georgescu
Not creating an implicit subscription is supported as per "RFC 4488":http://tools.ietf.org/html/rfc4488
2915 1 Adrian Georgescu
2916 117 Adrian Georgescu
Internally a @Referral@ object has a state machine, which reflects the state of the subscription. (The same as the @Subsription@ since it uses the same event framework)
2917 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@.
2918 117 Adrian Georgescu
The last three states are directly copied from the contents of the @Subscription-State@ header of the received @NOTIFY@ request.
2919 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.
2920 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.
2921 1 Adrian Georgescu
This notification is only informational, an application using this object should take actions based on the other notifications sent by this object.
2922 1 Adrian Georgescu
2923 1 Adrian Georgescu
2924 117 Adrian Georgescu
h4. methods
2925 1 Adrian Georgescu
2926 1 Adrian Georgescu
2927 1 Adrian Georgescu
2928 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_, *request_uri*, *from_header*, *to_header*, *refer_to_header, *contact_header*, *route_header*, *credentials*=@None@)
2929 117 Adrian Georgescu
>Creates a new @Referral@ object which will be in the @NULL@ state.
2930 117 Adrian Georgescu
>The arguments for this method are documented in the attributes section above.
2931 1 Adrian Georgescu
2932 117 Adrian Georgescu
*send_refer*(_self_, *create_subscription*=@1@, *extra_headers*=@list()@, *timeout*=@None@)
2933 117 Adrian Georgescu
>Calling this method triggers sending a @REFER@ request to the presence agent.
2934 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.
2935 117 Adrian Georgescu
>It may not be called when the object is in the @TERMINATED@ state.
2936 117 Adrian Georgescu
  
2937 117 Adrian Georgescu
>+_create_subscription_+:
2938 1 Adrian Georgescu
2939 117 Adrian Georgescu
>Boolean flag indicating if an implicit subscription should be created.
2940 117 Adrian Georgescu
  
2941 117 Adrian Georgescu
>+_extra_headers_+:
2942 1 Adrian Georgescu
2943 117 Adrian Georgescu
>A list of additional headers to include in the @REFER@ requests.
2944 117 Adrian Georgescu
  
2945 117 Adrian Georgescu
>+_timeout_+:
2946 1 Adrian Georgescu
2947 117 Adrian Georgescu
>This can be either an int or a float, indicating in how many seconds the request should timeout with an internally generated 408 response.
2948 117 Adrian Georgescu
>If this is @None@, the internal 408 is only triggered by the internal PJSIP transaction timeout.
2949 117 Adrian Georgescu
>Note that, even if the timeout is specified, the PJSIP timeout is also still valid.
2950 1 Adrian Georgescu
2951 117 Adrian Georgescu
*refresh*(_self_, *contact_header*=@None@, *extra_headers*=@list()@, *timeout*=@None@)
2952 117 Adrian Georgescu
  
2953 117 Adrian Georgescu
>+_contact_header_+:
2954 1 Adrian Georgescu
2955 117 Adrian Georgescu
>An optional @ContactHeader@ object which will replace the local contact header and will be used from this moment on.
2956 117 Adrian Georgescu
  
2957 117 Adrian Georgescu
>+_extra_headers_+:
2958 1 Adrian Georgescu
2959 117 Adrian Georgescu
>A list of additional headers to include in the refreshing @SUBSCRIBE@ request.
2960 117 Adrian Georgescu
  
2961 117 Adrian Georgescu
>+_timeout_+:
2962 1 Adrian Georgescu
2963 117 Adrian Georgescu
>The @timeout@ argument has the same meaning as it does for the @send_refer()@ method.
2964 1 Adrian Georgescu
2965 117 Adrian Georgescu
*end*(_self_, *timeout*=@None@)
2966 117 Adrian Georgescu
>This will end the referral subscription by sending a @SUBSCRIBE@ request with an @Expires@ value of 0.
2967 117 Adrian Georgescu
>If this object is no longer subscribed, this method will return without performing any action.
2968 117 Adrian Georgescu
>This method cannot be called when the object is in the @NULL@ state.
2969 117 Adrian Georgescu
>The @timeout@ argument has the same meaning as it does for the @send_refer()@ method.
2970 1 Adrian Georgescu
2971 1 Adrian Georgescu
2972 117 Adrian Georgescu
h4. attributes
2973 1 Adrian Georgescu
2974 1 Adrian Georgescu
2975 1 Adrian Georgescu
2976 117 Adrian Georgescu
*state*
2977 117 Adrian Georgescu
>Indicates which state the internal state machine is in.
2978 117 Adrian Georgescu
>See the previous section for a list of states the state machine can be in.
2979 1 Adrian Georgescu
2980 117 Adrian Georgescu
*from_header*
2981 117 Adrian Georgescu
>The @FrozenFromHeader@ to be put in the @From@ header of the @REFER@ and @SUBSCRIBE@ requests.
2982 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
2983 1 Adrian Georgescu
2984 117 Adrian Georgescu
*to_header*
2985 117 Adrian Georgescu
>The @FrozenToHeader@ that is the target for the referral.
2986 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
2987 1 Adrian Georgescu
2988 117 Adrian Georgescu
*refer_to_header*
2989 117 Adrian Georgescu
>The @FrozenReferToHeader@ that is the target resource for the referral.
2990 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
2991 1 Adrian Georgescu
2992 117 Adrian Georgescu
*local_contact_header*
2993 117 Adrian Georgescu
>The @FrozenContactHeader@ to be put in the @Contact@ header of the @REFER@ and @SUBSCRIBE@ requests.
2994 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
2995 1 Adrian Georgescu
2996 117 Adrian Georgescu
*remote_contact_header*
2997 117 Adrian Georgescu
 The @FrozenContactHeader@ received from the remote endpoint. This attribute is read-only.
2998 1 Adrian Georgescu
2999 117 Adrian Georgescu
*route_header*
3000 117 Adrian Georgescu
>The outbound proxy to use in the form of a @FrozenRouteHeader@ object.
3001 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
3002 1 Adrian Georgescu
3003 117 Adrian Georgescu
*credentials*
3004 117 Adrian Georgescu
>The SIP credentials needed to authenticate at the SIP proxy in the form of a @FrozenCredentials@ object.
3005 117 Adrian Georgescu
>If none was specified when creating the @Referral@ object, this attribute is @None@.
3006 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
3007 1 Adrian Georgescu
3008 117 Adrian Georgescu
*refresh*
3009 117 Adrian Georgescu
>The refresh interval in seconds that was requested on object instantiation as an int.
3010 117 Adrian Georgescu
>This attribute is set when a @NOTIFY@ request is received and is read-only.
3011 1 Adrian Georgescu
3012 117 Adrian Georgescu
*extra_headers*
3013 117 Adrian Georgescu
>This contains the @frozenlist@ of extra headers that was last passed to a successful call to the @subscribe()@ method.
3014 117 Adrian Georgescu
>If the argument was not provided, this attribute is an empty list.
3015 117 Adrian Georgescu
>This attribute is read-only.
3016 1 Adrian Georgescu
3017 117 Adrian Georgescu
*peer_address*
3018 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.
3019 1 Adrian Georgescu
3020 1 Adrian Georgescu
3021 117 Adrian Georgescu
h4. notifications
3022 1 Adrian Georgescu
3023 1 Adrian Georgescu
3024 1 Adrian Georgescu
3025 117 Adrian Georgescu
*SIPReferralChangedState*
3026 117 Adrian Georgescu
>This notification will be sent every time the internal state machine of a @Referral@ object changes state.
3027 117 Adrian Georgescu
  
3028 117 Adrian Georgescu
>+_timestamp_+:
3029 1 Adrian Georgescu
3030 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
3031 117 Adrian Georgescu
  
3032 117 Adrian Georgescu
>+_prev_state_+:
3033 1 Adrian Georgescu
3034 117 Adrian Georgescu
>The previous state that the sate machine was in.
3035 117 Adrian Georgescu
  
3036 117 Adrian Georgescu
>+_state_+:
3037 1 Adrian Georgescu
3038 117 Adrian Georgescu
>The new state the state machine moved into.
3039 1 Adrian Georgescu
3040 117 Adrian Georgescu
*SIPReferralWillStart*
3041 117 Adrian Georgescu
>This notification will be emitted when the initial @REFER@ request is sent.
3042 117 Adrian Georgescu
  
3043 117 Adrian Georgescu
>+_timestamp_+:
3044 1 Adrian Georgescu
3045 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
3046 1 Adrian Georgescu
3047 117 Adrian Georgescu
*SIPReferralDidStart*
3048 117 Adrian Georgescu
>This notification will be sent when the initial @REFER@ was accepted by the remote endpoint.
3049 117 Adrian Georgescu
  
3050 117 Adrian Georgescu
>+_timestamp_+:
3051 1 Adrian Georgescu
3052 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
3053 1 Adrian Georgescu
3054 117 Adrian Georgescu
*SIPReferralGotNotify*
3055 117 Adrian Georgescu
>This notification will be sent when a @NOTIFY@ is received that corresponds to a particular @Referral@ object.
3056 117 Adrian Georgescu
>Note that this notification could be sent when a @NOTIFY@ without a body is received.
3057 117 Adrian Georgescu
  
3058 117 Adrian Georgescu
>+_request_uri_+:
3059 1 Adrian Georgescu
3060 117 Adrian Georgescu
>The request URI of the @NOTIFY@ request as a @SIPURI@ object.
3061 117 Adrian Georgescu
  
3062 117 Adrian Georgescu
>+_from_header_+:
3063 1 Adrian Georgescu
3064 117 Adrian Georgescu
>The From header of the @NOTIFY@ request as a @FrozenFromHeader@ object.
3065 117 Adrian Georgescu
  
3066 117 Adrian Georgescu
>+_to_header_+:
3067 1 Adrian Georgescu
3068 117 Adrian Georgescu
>The To header of the @NOTIFY@ request as a @FrozenToHeader@ object.
3069 117 Adrian Georgescu
  
3070 117 Adrian Georgescu
>+_content_type_+:
3071 1 Adrian Georgescu
3072 117 Adrian Georgescu
>The Content-Type header value of the @NOTIFY@ request as a @ContentType@ object.
3073 117 Adrian Georgescu
  
3074 117 Adrian Georgescu
>+_event_+:
3075 1 Adrian Georgescu
3076 117 Adrian Georgescu
>The Event header value of the @NOTIFY@ request as a string object.
3077 117 Adrian Georgescu
  
3078 117 Adrian Georgescu
>+_headers_+:
3079 1 Adrian Georgescu
3080 117 Adrian Georgescu
>The headers of the @NOTIFY@ request as a dict.
3081 117 Adrian Georgescu
>Each SIP header is represented in its parsed for as long as PJSIP supports it.
3082 117 Adrian Georgescu
>The format of the parsed value depends on the header.
3083 117 Adrian Georgescu
  
3084 117 Adrian Georgescu
>+_body_+:
3085 1 Adrian Georgescu
3086 117 Adrian Georgescu
>The body of the @NOTIFY@ request as a string, or @None@ if no body was included.
3087 117 Adrian Georgescu
  
3088 117 Adrian Georgescu
>+_timestamp_+:
3089 1 Adrian Georgescu
3090 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.  
3091 1 Adrian Georgescu
3092 117 Adrian Georgescu
*SIPReferralDidFail*
3093 117 Adrian Georgescu
>This notification will be sent whenever there is a failure, such as a rejected initial @REFER@ or refreshing @SUBSCRIBE@.
3094 117 Adrian Georgescu
>After this notification the @Referral@ object is in the @TERMINATED@ state and can no longer be used.
3095 117 Adrian Georgescu
  
3096 117 Adrian Georgescu
>+_timestamp_+:
3097 1 Adrian Georgescu
3098 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
3099 117 Adrian Georgescu
  
3100 117 Adrian Georgescu
>+_code_+:
3101 1 Adrian Georgescu
3102 117 Adrian Georgescu
>An integer SIP code from the fatal response that was received from the remote party of generated by PJSIP.
3103 117 Adrian Georgescu
>If the error is internal to the SIP core, this attribute will have a value of 0.
3104 117 Adrian Georgescu
  
3105 117 Adrian Georgescu
>+_reason_+:
3106 1 Adrian Georgescu
3107 117 Adrian Georgescu
>An text string describing the failure that occurred.
3108 1 Adrian Georgescu
3109 117 Adrian Georgescu
*SIPReferralDidEnd*
3110 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.
3111 117 Adrian Georgescu
>After this notification the @Referral@ object is in the @TERMINATED@ state and can no longer be used.
3112 117 Adrian Georgescu
  
3113 117 Adrian Georgescu
>+_timestamp_+:
3114 1 Adrian Georgescu
3115 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
3116 1 Adrian Georgescu
3117 117 Adrian Georgescu
3118 117 Adrian Georgescu
h3. IncomingReferral
3119 117 Adrian Georgescu
3120 117 Adrian Georgescu
3121 117 Adrian Georgescu
Subscription and notifications for SIP events is an Internet standard published at "RFC 3856":http://tools.ietf.org/html/rfc3856.
3122 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.
3123 117 Adrian Georgescu
3124 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.
3125 117 Adrian Georgescu
This means that it can accept a @REFER@ request and subsequent refreshing @SUBSCRIBE@s and sent @NOTIFY@ requests containing event state.
3126 117 Adrian Georgescu
3127 117 Adrian Georgescu
Any incoming @REFER@ request causes the creation of a @IncomingReferral@ object.
3128 117 Adrian Georgescu
This will be indicated to the application through a @SIPIncomingReferralGotRefer@ notification.
3129 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.
3130 117 Adrian Georgescu
3131 117 Adrian Georgescu
The application can either reject the referral by calling the @reject()@ method or accept it through the @accept()@ method.
3132 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.
3133 117 Adrian Georgescu
Whenever a refreshing @SUBSCRIBE@ is received, the latest contents to be set are sent in the resulting @NOTIFY@ request.
3134 117 Adrian Georgescu
The subscription can be ended by using the @end()@ method.
3135 117 Adrian Georgescu
3136 117 Adrian Georgescu
3137 117 Adrian Georgescu
h4. methods
3138 117 Adrian Georgescu
3139 117 Adrian Georgescu
3140 117 Adrian Georgescu
3141 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_)
3142 117 Adrian Georgescu
>An application should never create an @IncomingSubscription@ object itself.
3143 117 Adrian Georgescu
>Doing this will create a useless object in the @None@ state.
3144 117 Adrian Georgescu
3145 117 Adrian Georgescu
*reject*(_self_, *code*)
3146 117 Adrian Georgescu
>Will reply to the initial @REFER@ with a negative response.
3147 117 Adrian Georgescu
>This method can only be called in the @"incoming"@ state and sets the referral to the @"terminated"@ state.
3148 117 Adrian Georgescu
  
3149 117 Adrian Georgescu
>+_code_+:
3150 117 Adrian Georgescu
3151 117 Adrian Georgescu
>The SIP response code to use.
3152 117 Adrian Georgescu
>This should be a negative response, i.e. in the 3xx, 4xx, 5xx or 6xx range.
3153 117 Adrian Georgescu
3154 117 Adrian Georgescu
*accept*(_self_, *code*=@202@, *duration*=@180@)
3155 117 Adrian Georgescu
>Accept the initial incoming @REFER@ and respond to it with a 202 Accepted.
3156 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.
3157 117 Adrian Georgescu
>This method can only be called in the @"incoming"@ state.
3158 117 Adrian Georgescu
  
3159 117 Adrian Georgescu
>+_code_+:
3160 117 Adrian Georgescu
3161 117 Adrian Georgescu
>The code to be  used for the initial reply.
3162 117 Adrian Georgescu
  
3163 117 Adrian Georgescu
>+_duration_+:
3164 117 Adrian Georgescu
3165 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.
3166 117 Adrian Georgescu
3167 117 Adrian Georgescu
*send_notify*(_self_, *code*, *status*=@None@)
3168 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.
3169 117 Adrian Georgescu
>This method can only be called in the @"active"@ state.
3170 117 Adrian Georgescu
  
3171 117 Adrian Georgescu
>+_code_+:
3172 117 Adrian Georgescu
3173 117 Adrian Georgescu
>The response code to be used to generate the sipfrag payload.
3174 117 Adrian Georgescu
  
3175 117 Adrian Georgescu
>+_status_+:
3176 117 Adrian Georgescu
3177 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.
3178 117 Adrian Georgescu
3179 117 Adrian Georgescu
3180 117 Adrian Georgescu
h4. attributes
3181 117 Adrian Georgescu
3182 117 Adrian Georgescu
3183 117 Adrian Georgescu
3184 117 Adrian Georgescu
*state*
3185 117 Adrian Georgescu
>Indicates which state the incoming referral dialog is in.
3186 117 Adrian Georgescu
>This can be one of @None@, @"incoming"@, @"pending"@, @"active"@ or @"terminated"@.
3187 117 Adrian Georgescu
>This attribute is read-only.
3188 117 Adrian Georgescu
3189 117 Adrian Georgescu
*local_contact_header*
3190 117 Adrian Georgescu
>The @FrozenContactHeader@ to be put in the @Contact@ header of the @REFER@ and @SUBSCRIBE@ responses and @NOTIFY@ requests.
3191 117 Adrian Georgescu
>This attribute is set on object instantiation and is read-only.
3192 117 Adrian Georgescu
3193 117 Adrian Georgescu
*remote_contact_header*
3194 117 Adrian Georgescu
 The @FrozenContactHeader@ received from the remote endpoint. This attribute is read-only.
3195 117 Adrian Georgescu
3196 117 Adrian Georgescu
*peer_address*
3197 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.
3198 117 Adrian Georgescu
3199 117 Adrian Georgescu
3200 117 Adrian Georgescu
h4. notifications
3201 117 Adrian Georgescu
3202 117 Adrian Georgescu
3203 117 Adrian Georgescu
3204 117 Adrian Georgescu
*SIPIncomingReferralChangedState*
3205 117 Adrian Georgescu
>This notification will be sent every time the an @IncomingReferral@ object changes state.
3206 117 Adrian Georgescu
>This notification is mostly indicative, an application should not let its logic depend on it.
3207 117 Adrian Georgescu
  
3208 117 Adrian Georgescu
>+_timestamp_+:
3209 117 Adrian Georgescu
3210 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
3211 117 Adrian Georgescu
  
3212 117 Adrian Georgescu
>+_prev_state_+:
3213 117 Adrian Georgescu
3214 117 Adrian Georgescu
>The previous state that the subscription was in.
3215 117 Adrian Georgescu
  
3216 117 Adrian Georgescu
>+_state_+:
3217 117 Adrian Georgescu
3218 117 Adrian Georgescu
>The new state the subscription has.
3219 117 Adrian Georgescu
3220 117 Adrian Georgescu
*SIPIncomingReferralGotRefer*
3221 117 Adrian Georgescu
>This notification will be sent when a new @IncomingReferral@ is created as result of an incoming @REFER@ request.
3222 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.
3223 117 Adrian Georgescu
  
3224 117 Adrian Georgescu
>+_timestamp_+:
3225 117 Adrian Georgescu
3226 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
3227 117 Adrian Georgescu
  
3228 117 Adrian Georgescu
>+_method_+:
3229 117 Adrian Georgescu
3230 117 Adrian Georgescu
>The method of the SIP request as a string, which will be @REFER@.
3231 117 Adrian Georgescu
  
3232 117 Adrian Georgescu
>+_request_uri_+:
3233 117 Adrian Georgescu
3234 117 Adrian Georgescu
>The request URI of the @REFER@ request as a @FrozenSIPURI@ object.
3235 117 Adrian Georgescu
  
3236 117 Adrian Georgescu
>+_refer_to_+:
3237 117 Adrian Georgescu
3238 117 Adrian Georgescu
>The Refer-To header as a @FrozenReferToHeader@ object.
3239 117 Adrian Georgescu
  
3240 117 Adrian Georgescu
>+_headers_+:
3241 117 Adrian Georgescu
3242 117 Adrian Georgescu
>The headers of the @REFER@ request as a dict, the values of which are the relevant header objects.
3243 117 Adrian Georgescu
  
3244 117 Adrian Georgescu
>+_body_+:
3245 117 Adrian Georgescu
3246 117 Adrian Georgescu
>The body of the @REFER@ request as a string, or @None@ if no body was included.
3247 117 Adrian Georgescu
3248 117 Adrian Georgescu
*SIPIncomingReferralGotRefreshingSubscribe*
3249 117 Adrian Georgescu
>This notification indicates that a refreshing @SUBSCRIBE@ request was received from the subscriber.
3250 117 Adrian Georgescu
>It is purely informative, no action needs to be taken by the application as a result of it.
3251 117 Adrian Georgescu
3252 117 Adrian Georgescu
*SIPIncomingReferralGotUnsubscribe*
3253 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.
3254 117 Adrian Georgescu
>It is purely informative, no action needs to be taken by the application as a result of it.
3255 117 Adrian Georgescu
3256 117 Adrian Georgescu
*SIPIncomingReferralAnsweredRefer*
3257 117 Adrian Georgescu
>This notification is sent whenever a response to a @REFER@ request is sent by the object.
3258 117 Adrian Georgescu
>It is purely informative, no action needs to be taken by the application as a result of it.
3259 117 Adrian Georgescu
  
3260 117 Adrian Georgescu
>+_timestamp_+:
3261 117 Adrian Georgescu
3262 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
3263 117 Adrian Georgescu
  
3264 117 Adrian Georgescu
>+_code_+:
3265 117 Adrian Georgescu
3266 117 Adrian Georgescu
>The code of the SIP response as an int.
3267 117 Adrian Georgescu
  
3268 117 Adrian Georgescu
>+_reason_+:
3269 117 Adrian Georgescu
3270 117 Adrian Georgescu
>The reason text of the SIP response as an int.
3271 117 Adrian Georgescu
  
3272 117 Adrian Georgescu
>+_headers_+:
3273 117 Adrian Georgescu
3274 117 Adrian Georgescu
>The headers of the response as a dict, the values of which are the relevant header objects.
3275 117 Adrian Georgescu
  
3276 117 Adrian Georgescu
>+_body_+:
3277 117 Adrian Georgescu
3278 117 Adrian Georgescu
>This will be @None@.
3279 117 Adrian Georgescu
3280 117 Adrian Georgescu
*SIPIncomingReferralSentNotify*
3281 117 Adrian Georgescu
>This notification indicates that a @NOTIFY@ request was sent to the subscriber.
3282 117 Adrian Georgescu
>It is purely informative, no action needs to be taken by the application as a result of it.
3283 117 Adrian Georgescu
  
3284 117 Adrian Georgescu
>+_timestamp_+:
3285 117 Adrian Georgescu
3286 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
3287 117 Adrian Georgescu
  
3288 117 Adrian Georgescu
>+_method_+:
3289 117 Adrian Georgescu
3290 117 Adrian Georgescu
>The method of the SIP request as a string, which will be @NOTIFY@.
3291 117 Adrian Georgescu
  
3292 117 Adrian Georgescu
>+_request_uri_+:
3293 117 Adrian Georgescu
3294 117 Adrian Georgescu
>The request URI of the @NOTIFY@ request as a @FrozenSIPURI@ object.
3295 117 Adrian Georgescu
  
3296 117 Adrian Georgescu
>+_headers_+:
3297 117 Adrian Georgescu
3298 117 Adrian Georgescu
>The headers of the @NOTIFY@ request as a dict, the values of which are the relevant header objects.
3299 117 Adrian Georgescu
  
3300 117 Adrian Georgescu
>+_body_+:
3301 117 Adrian Georgescu
3302 117 Adrian Georgescu
>The body of the @NOTIFY@ request or response as a string, or @None@ if no body was included.
3303 117 Adrian Georgescu
3304 117 Adrian Georgescu
*SIPIncomingReferralNotifyDidSucceed*
3305 117 Adrian Georgescu
>This indicates that a positive final response was received from the subscriber in reply to a sent @NOTIFY@ request.
3306 117 Adrian Georgescu
>The notification is purely informative, no action needs to be taken by the application as a result of it.
3307 117 Adrian Georgescu
  
3308 117 Adrian Georgescu
>+_timestamp_+:
3309 117 Adrian Georgescu
3310 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
3311 117 Adrian Georgescu
  
3312 117 Adrian Georgescu
>+_code_+:
3313 117 Adrian Georgescu
3314 117 Adrian Georgescu
>The code of the SIP response as an int.
3315 117 Adrian Georgescu
  
3316 117 Adrian Georgescu
>+_reason_+:
3317 117 Adrian Georgescu
3318 117 Adrian Georgescu
>The reason text of the SIP response as a string.
3319 117 Adrian Georgescu
  
3320 117 Adrian Georgescu
>+_headers_+:
3321 117 Adrian Georgescu
3322 117 Adrian Georgescu
>The headers of the response as a dict, the values of which are the relevant header objects.
3323 117 Adrian Georgescu
  
3324 117 Adrian Georgescu
>+_body_+:
3325 117 Adrian Georgescu
3326 117 Adrian Georgescu
>This will be @None@.
3327 117 Adrian Georgescu
3328 117 Adrian Georgescu
*SIPIncomingReferralNotifyDidFail*
3329 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.
3330 117 Adrian Georgescu
  
3331 117 Adrian Georgescu
>+_timestamp_+:
3332 117 Adrian Georgescu
3333 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
3334 117 Adrian Georgescu
  
3335 117 Adrian Georgescu
>+_code_+:
3336 117 Adrian Georgescu
3337 117 Adrian Georgescu
>The code of the SIP response as an int.
3338 117 Adrian Georgescu
>If this is 0, the notification was sent as a result of an internal error.
3339 117 Adrian Georgescu
  
3340 117 Adrian Georgescu
>+_reason_+:
3341 117 Adrian Georgescu
3342 117 Adrian Georgescu
>The reason text of the SIP response as a string or the internal error if the code attribute is 0.
3343 117 Adrian Georgescu
  
3344 117 Adrian Georgescu
>+_headers_+: (if the notification was caused by a negative response)
3345 117 Adrian Georgescu
3346 117 Adrian Georgescu
>The headers of the response as a dict, the values of which are the relevant header objects.
3347 117 Adrian Georgescu
  
3348 117 Adrian Georgescu
>+_body_+: (if the notification was caused by a negative response)
3349 117 Adrian Georgescu
3350 117 Adrian Georgescu
>This will be @None@.
3351 117 Adrian Georgescu
3352 117 Adrian Georgescu
*SIPIncomingReferralDidEnd*
3353 117 Adrian Georgescu
>This notification is sent whenever the @IncomingReferral@ object reaches the @"terminated"@ state and is no longer valid.
3354 117 Adrian Georgescu
>After receiving this notification, the application should not longer try to use the object.
3355 117 Adrian Georgescu
  
3356 117 Adrian Georgescu
>+_timestamp_+:
3357 117 Adrian Georgescu
3358 117 Adrian Georgescu
>A @datetime.datetime@ object indicating when the notification was sent.
3359 117 Adrian Georgescu
3360 117 Adrian Georgescu
3361 117 Adrian Georgescu
h3. AudioMixer
3362 117 Adrian Georgescu
3363 117 Adrian Georgescu
3364 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.
3365 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.
3366 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.
3367 1 Adrian Georgescu
The sound devices, both input and output, together always occupy slot 0.
3368 117 Adrian Georgescu
It is up to the application to setup the desired routing between these components. Note that the middleware provides an abstracted API which hides the complexity of using the low-level PJSIP concepts. This is mainly provided in the [[SipMiddlewareApi#Audio|@sipsimple.audio@]] module, but also consists of other audio-enabled objects (such as the AudioStream).
3369 1 Adrian Georgescu
3370 1 Adrian Georgescu
3371 117 Adrian Georgescu
h4. methods
3372 1 Adrian Georgescu
3373 1 Adrian Georgescu
3374 1 Adrian Georgescu
3375 117 Adrian Georgescu
*<notextile>__init__</notextile>*(_self_, *input_device*, *output_device*, *sample_rate*, *ec_tail_length*=200, *slot_count*=254)
3376 117 Adrian Georgescu
>Creates a new @ConferenceBridge@ object.
3377 117 Adrian Georgescu
  
3378 117 Adrian Georgescu
>+_input_device_+:
3379 1 Adrian Georgescu
3380 117 Adrian Georgescu
>The name of the audio input device to use as a string, or @None@ if no input device is to be used.
3381 117 Adrian Georgescu
>A list of known input devices can be queried through the @Engine.input_devices@ attribute.
3382 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.
3383 117 Adrian Georgescu
>The device that was selected can be queried afterwards through the @input_device@ attribute.
3384 117 Adrian Georgescu
  
3385 117 Adrian Georgescu
>+_output_device_+:
3386 1 Adrian Georgescu
3387 117 Adrian Georgescu
>The name of the audio output device to use as a string, or @None@ if no output device is to be used.
3388 117 Adrian Georgescu
>A list of known output devices can be queried through the @Engine.output_devices@ attribute.
3389 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.
3390 117 Adrian Georgescu
>The device that was selected can be queried afterwards through the @output_device@ attribute.
3391 117 Adrian Georgescu
  
3392 117 Adrian Georgescu
>+_sample_rate_+:
3393 1 Adrian Georgescu
3394 117 Adrian Georgescu
>The sample rate on which the conference bridge and sound devices should operate in Hz.
3395 117 Adrian Georgescu
>This must be a multiple of 50.