SipCoreApiDocumentation

Version 114 (Anonymous, 04/21/2011 10:21 am)

1 89 Adrian Georgescu
= SIP Core API =
2 1 Adrian Georgescu
3 101 Adrian Georgescu
[[TOC(SipMiddlewareApi, SipConfigurationAPI, SipCoreApiDocumentation, depth=3)]]
4 5 Adrian Georgescu
5 1 Adrian Georgescu
== Introduction ==
6 1 Adrian Georgescu
7 13 Adrian Georgescu
This chapter describes the internal architecture and API of the SIP core of the {{{sipsimple}}} library.
8 71 Adrian Georgescu
{{{sipsimple}}} is a Python package, the core of which wraps the PJSIP C library, which handles SIP signaling and audio media for the SIP SIMPLE client.
9 1 Adrian Georgescu
10 1 Adrian Georgescu
SIP stands for 'Sessions Initiation Protocol', an IETF standard described by [http://tools.ietf.org/html/rfc3261 RFC 3261]. SIP is an application-layer control protocol that can establish,
11 1 Adrian Georgescu
modify and terminate multimedia sessions such as Internet telephony calls
12 1 Adrian Georgescu
(VoIP). Media can be added to (and removed from) an existing session.
13 1 Adrian Georgescu
14 1 Adrian Georgescu
SIP transparently supports name mapping and redirection services, which
15 1 Adrian Georgescu
supports personal mobility, users can maintain a single externally visible
16 1 Adrian Georgescu
address identifier, which can be in the form of a standard email address or
17 1 Adrian Georgescu
E.164 telephone number regardless of their physical network location.
18 1 Adrian Georgescu
19 1 Adrian Georgescu
SIP allows the endpoints to negotiate and combine any type of session they
20 1 Adrian Georgescu
mutually understand like video, instant messaging (IM), file transfer,
21 1 Adrian Georgescu
desktop sharing and provides a generic event notification system with
22 1 Adrian Georgescu
real-time publications and subscriptions about state changes that can be
23 1 Adrian Georgescu
used for asynchronous services like presence, message waiting indicator and
24 1 Adrian Georgescu
busy line appearance.
25 1 Adrian Georgescu
26 1 Adrian Georgescu
For a comprehensive overview of SIP related protocols and use cases visit http://www.tech-invite.com
27 1 Adrian Georgescu
28 30 Adrian Georgescu
== PJSIP library ==
29 1 Adrian Georgescu
30 1 Adrian Georgescu
{{{sipsimple}}} builds on PJSIP [http://www.pjsip.org], a set of static libraries, written in C, which provide SIP signaling and media capabilities.
31 1 Adrian Georgescu
PJSIP is considered to be the most mature and advanced open source SIP stack available.
32 1 Adrian Georgescu
The following diagram, taken from the PJSIP documentation, illustrates the library stack of PJSIP:
33 1 Adrian Georgescu
34 1 Adrian Georgescu
[[Image(http://www.pjsip.org/images/diagram.jpg, nolink)]]
35 1 Adrian Georgescu
36 1 Adrian Georgescu
The diagram shows that there is a common base library, and two more or less independent stacks of libraries, one for SIP signaling and one for SIP media.
37 71 Adrian Georgescu
The latter also includes an abstraction layer for the sound-card.
38 1 Adrian Georgescu
Both of these stracks are integrated in the high level library, called PJSUA.
39 1 Adrian Georgescu
40 1 Adrian Georgescu
PJSIP itself provides a high-level [http://www.pjsip.org/python/pjsua.htm Python wrapper for PJSUA].
41 1 Adrian Georgescu
Despite this, the choice was made to bypass PJSUA and write the SIP core of the {{{sipsimple}}} package as a Python wrapper, which directly uses the PJSIP and PJMEDIA libraries.
42 1 Adrian Georgescu
The main reasons for this are the following:
43 1 Adrian Georgescu
 * PJSUA assumes a session with exactly one audio stream, whilst for the SIP SIMPLE client more advanced (i.e. low-level) manipulation of the SDP is needed.
44 1 Adrian Georgescu
 * What is advertised as SIMPLE functionality, it is minimal and incomplete subset of it. Only page mode messaging using SIP MESSAGE method and basic device status presence are possible, while session mode IM and rich presence are desired.
45 1 Adrian Georgescu
 * PJSUA integrates the decoding and encoding of payloads (e.g. presence related XML documents), while in the SIP SIMPLE client this should be done at a high level, not by the SIP stack.
46 1 Adrian Georgescu
47 1 Adrian Georgescu
PJSIP itself is by nature asynchronous.
48 1 Adrian Georgescu
In the case of PJSIP it means that in general there will be one thread which handles reception and transmission of SIP signaling messages by means of a polling function which is continually called by the application.
49 1 Adrian Georgescu
Whenever the application performs some action through a function, this function will return immediately.
50 1 Adrian Georgescu
If PJSIP has a result for this action, it will notify the application by means of a callback function in the context of the polling function thread.
51 1 Adrian Georgescu
52 1 Adrian Georgescu
> NOTE: Currently the core starts the media handling as a separate C thread to avoid lag caused by the GIL.
53 71 Adrian Georgescu
> The sound-card also has its own C thread.
54 1 Adrian Georgescu
55 1 Adrian Georgescu
== Architecture ==
56 1 Adrian Georgescu
57 1 Adrian Georgescu
The {{{sipsimple}}} core wrapper itself is mostly written using [http://cython.org/ Cython] (formerly [http://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/ Pyrex]).
58 1 Adrian Georgescu
It allows a Python-like file with some added C manipulation statements to be compiled to C.
59 1 Adrian Georgescu
This in turn compiles to a Python C extension module, which links with the PJSIP static libraries.
60 1 Adrian Georgescu
61 90 Luci Stanescu
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:
62 90 Luci Stanescu
 * 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.
63 90 Luci Stanescu
 * Utility classes used throughout the core:
64 90 Luci Stanescu
   * {{{frozenlist}}} and {{{frozendict}}}: classes which relate respectively to {{{list}}} and {{{dict}}} similarly to how the standard {{{frozenset}}} relates to {{{set}}}.
65 90 Luci Stanescu
 * Helper classes which represent a structured collection of data which is used throughout the core:
66 90 Luci Stanescu
   * {{{BaseSIPURI}}}, {{{SIPURI}}} and {{{FrozenSIPURI}}}
67 90 Luci Stanescu
   * {{{BaseCredentials}}}, {{{Credentials}}} and {{{FrozenCredentials}}}
68 90 Luci Stanescu
 * SDP manipulation classes, which directly wrap the PJSIP structures representing either the parsed or to be generated SDP:
69 90 Luci Stanescu
   * {{{BaseSDPSession}}}, {{{SDPSession}}} and {{{FrozenSDPSession}}}
70 90 Luci Stanescu
   * {{{BaseSDPMediaStream}}}, {{{SDPMediaStream}}} and {{{FrozenSDPMediaStream}}}
71 90 Luci Stanescu
   * {{{BaseSDPConnection}}}, {{{SDPConnection}}} and {{{FrozenSDPConnection}}}
72 90 Luci Stanescu
   * {{{SDPAttributeList}}} and {{{FrozenSDPAttributeList}}}
73 90 Luci Stanescu
   * {{{BaseSDPAttribute}}}, {{{SDPAttribute}}} and {{{FrozenSDPAttribute}}}
74 90 Luci Stanescu
 * Audio handling classes:
75 90 Luci Stanescu
   * {{{AudioMixer}}}
76 90 Luci Stanescu
   * {{{MixerPort}}}
77 90 Luci Stanescu
   * {{{WaveFile}}}
78 90 Luci Stanescu
   * {{{RecordingWaveFile}}}
79 90 Luci Stanescu
   * {{{ToneGenerator}}}
80 90 Luci Stanescu
 * Media transport handling classes, using the functionality built into PJMEDIA:
81 90 Luci Stanescu
   * {{{RTPTransport}}}
82 90 Luci Stanescu
   * {{{AudioTransport}}}
83 90 Luci Stanescu
 * SIP signalling related classes:
84 90 Luci Stanescu
   * {{{Request}}} and {{{IncomingRequest}}}: low-level transaction support
85 90 Luci Stanescu
   * {{{Invitation}}}: INVITE-dialog support
86 90 Luci Stanescu
   * {{{Subscription}}} and {{{IncomingSubscription}}}: SUBSCRIBE-dialog support (including NOTIFY handling within the SUBSCRIBE dialog)
87 114 Adrian Georgescu
   * {{{Referral}}} and {{{IncomingReferral}}}: REFER-dialog support (including NOTIFY handling within the dialog)
88 90 Luci Stanescu
   * {{{Registration}}}: Python object based on {{{Request}}} for REGISTER support
89 90 Luci Stanescu
   * {{{Message}}}: Python object based on {{{Request}}} for MESSAGE support
90 90 Luci Stanescu
   * {{{Publication}}}: Python object based on {{{Request}}} for PUBLISH support
91 90 Luci Stanescu
 * Exceptions:
92 90 Luci Stanescu
   * {{{SIPCoreError}}}: generic error used throught the core
93 90 Luci Stanescu
   * {{{PJSIPError}}}: subclass of {{{SIPCoreError}}} which offers more information related to errors from PJSIP
94 90 Luci Stanescu
   * {{{PJSIPTLSError}}}: subclass of {{{PJSIPError}}} to distinguish between TLS-related errors and the rest
95 90 Luci Stanescu
   * {{{SIPCoreInvalidStateError}}}: subclass of {{{SIPCoreError}}} used by objects which are based on a state-machine
96 1 Adrian Georgescu
97 90 Luci Stanescu
Most of the objects cannot be used until the {{{Engine}}} has been started. The following diagram illustrates these classes:
98 1 Adrian Georgescu
99 1 Adrian Georgescu
[[Image(sipsimple-core-classes.png, nolink)]]
100 90 Luci Stanescu
101 90 Luci Stanescu
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.
102 67 Ruud Klaver
103 11 Adrian Georgescu
== Integration ==
104 1 Adrian Georgescu
105 1 Adrian Georgescu
The core itself has one Python dependency, the [http://pypi.python.org/pypi/python-application application] module, which in turn depends on the [http://pypi.python.org/pypi/zope.interface zope.interface] module.
106 1 Adrian Georgescu
These modules should be present on the system before the core can be used.
107 1 Adrian Georgescu
An application that uses the SIP core must use the notification system provided by the {{{application}}} module in order to receive notifications from it.
108 1 Adrian Georgescu
It does this by creating one or more classes that act as an observer for particular messages and registering it with the {{{NotificationCenter}}}, which is a singleton class.
109 1 Adrian Georgescu
This means that any call to instance an object from this class will result in the same object.
110 1 Adrian Georgescu
As an example, this bit of code will create an observer for logging messages only:
111 1 Adrian Georgescu
112 1 Adrian Georgescu
{{{
113 1 Adrian Georgescu
from zope.interface import implements
114 1 Adrian Georgescu
from application.notification import NotificationCenter, IObserver
115 1 Adrian Georgescu
116 29 Luci Stanescu
class SIPEngineLogObserver(object):
117 1 Adrian Georgescu
    implements(IObserver)
118 1 Adrian Georgescu
119 1 Adrian Georgescu
    def handle_notification(self, notification):
120 1 Adrian Georgescu
        print "%(timestamp)s (%(level)d) %(sender)14s: %(message)s" % notification.data.__dict__
121 1 Adrian Georgescu
122 102 Luci Stanescu
log_observer = SIPEngineLogObserver()
123 1 Adrian Georgescu
notification_center = NotificationCenter()
124 102 Luci Stanescu
notification_center.add_observer(log_observer, name="SIPEngineLog")
125 1 Adrian Georgescu
}}}
126 1 Adrian Georgescu
127 1 Adrian Georgescu
Each notification object has three attributes:
128 99 Adrian Georgescu
129 1 Adrian Georgescu
 '''sender'''::
130 1 Adrian Georgescu
  The object that sent the notification.
131 1 Adrian Georgescu
  For generic notifications the sender will be the {{{Engine}}} instance, otherwise the relevant object.
132 99 Adrian Georgescu
133 1 Adrian Georgescu
 '''name'''::
134 1 Adrian Georgescu
  The name describing the notification.
135 91 Luci Stanescu
  Most of the notifications in the core have the prefix "SIP".
136 99 Adrian Georgescu
137 1 Adrian Georgescu
 '''data'''::
138 1 Adrian Georgescu
  An instance of {{{application.notification.NotificationData}}} or a subclass of it.
139 1 Adrian Georgescu
  The attributes of this object provide additional data about the notification.
140 1 Adrian Georgescu
  Notifications described in this document will also have the data attributes described.
141 1 Adrian Georgescu
142 91 Luci Stanescu
Besides setting up the notification observers, the application should import the relevant objects from the {{{sipsimple.core}}} module.
143 91 Luci Stanescu
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.
144 1 Adrian Georgescu
Most of these options can later be changed at runtime, by setting attributes of the same name on the {{{Engine}}} object.
145 91 Luci Stanescu
The application may then instantiate one of the SIP primitive classes and perform operations on it.
146 1 Adrian Georgescu
147 1 Adrian Georgescu
When starting the {{{Engine}}} class, the application can pass a number of keyword arguments that influence the behaviour of the SIP endpoint.
148 1 Adrian Georgescu
For example, the SIP network ports may be set through the {{{local_udp_port}}}, {{{local_tcp_port}}} and {{{local_tls_port}}} arguments.
149 1 Adrian Georgescu
The UDP/RTP ports are described by a range of ports through {{{rtp_port_range}}}, two of which will be randomly selected for each {{{RTPTransport}}} object and effectively each audio stream.
150 1 Adrian Georgescu
151 1 Adrian Georgescu
The methods called on the SIP primitive objects and the {{{Engine}}} object (proxied to the {{{PJSIPUA}}} instance) may be called from any thread.
152 31 Ruud Klaver
They will return immediately and any delayed result, such as results depending on network traffic, will be returned later using a notification.
153 31 Ruud Klaver
In this manner the SIP core continues the asynchronous pattern of PJSIP.
154 1 Adrian Georgescu
If there is an error in processing the request, an instance of {{{SIPCoreError}}}, or its subclass {{{PJSIPError}}} will be raised.
155 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.
156 1 Adrian Georgescu
The {{{PJSIPError}}} object also contains a status attribute, which is the PJSIP errno as an integer.
157 43 Ruud Klaver
158 1 Adrian Georgescu
As a very basic example, one can {{{REGISTER}}} for a sip account by typing the following lines on a Python console:
159 43 Ruud Klaver
{{{
160 91 Luci Stanescu
from sipsimple.core import ContactHeader, Credentials, Engine, Registration, RouteHeader, SIPURI
161 1 Adrian Georgescu
e = Engine()
162 1 Adrian Georgescu
e.start()
163 91 Luci Stanescu
identity = FromHeader(SIPURI(user="alice", host="example.com"), display_name="Alice")
164 43 Ruud Klaver
cred = Credentials("alice", "mypassword")
165 91 Luci Stanescu
reg = Registration(identity, credentials=cred)
166 91 Luci Stanescu
reg.register(ContactHeader(SIPURI("127.0.0.1",port=12345)), RouteHeader(SIPURI("1.2.3.4", port=5060)))
167 1 Adrian Georgescu
}}}
168 1 Adrian Georgescu
Note that in this example no observer for notifications from this {{{Registration}}} object are registered, so the result of the operation cannot be seen.
169 43 Ruud Klaver
Also note that this will not keep the registration registered when it is about to expire, as it is the application's responsibility.
170 43 Ruud Klaver
See the {{{Registration}}} documentation for more details.
171 43 Ruud Klaver
172 43 Ruud Klaver
Another convention that is worth mentioning at this point is that the SIP core will never perform DNS lookups.
173 91 Luci Stanescu
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 [wiki:SipMiddlewareApi#Lookup {{{sipsimple.lookup}}}] module of the middleware can be used to perform DNS lookups according to RFC3263.
174 32 Ruud Klaver
175 1 Adrian Georgescu
== Components ==
176 1 Adrian Georgescu
177 1 Adrian Georgescu
=== Engine ===
178 1 Adrian Georgescu
179 1 Adrian Georgescu
As explained above, this singleton class needs to be instantiated by the application using the SIP core of {{{sipsimple}}} and represents the whole SIP core stack.
180 1 Adrian Georgescu
Once the {{{start()}}} method is called, it instantiates the {{{core.PJSIPUA}}} object and will proxy attribute and methods from it to the application.
181 1 Adrian Georgescu
182 1 Adrian Georgescu
==== attributes ====
183 1 Adrian Georgescu
184 99 Adrian Georgescu
185 1 Adrian Georgescu
 '''default_start_options''' (class attribute)::
186 1 Adrian Georgescu
  This dictionary is a class attribute that describes the default values for the initialization options passed as keyword arguments to the {{{start()}}} method.
187 1 Adrian Georgescu
  Consult this method for documentation of the contents.
188 99 Adrian Georgescu
189 32 Ruud Klaver
 '''is_running'''::
190 32 Ruud Klaver
  A boolean property indicating if the {{{Engine}}} is running and if it is safe to try calling any proxied methods or attributes on it.
191 1 Adrian Georgescu
192 1 Adrian Georgescu
==== methods ====
193 1 Adrian Georgescu
194 99 Adrian Georgescu
195 1 Adrian Georgescu
 '''!__init!__'''(''self'')::
196 71 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.
197 99 Adrian Georgescu
198 1 Adrian Georgescu
 '''start'''(''self'', '''**kwargs''')::
199 1 Adrian Georgescu
  Initialize all PJSIP libraries based on the keyword parameters provided and start the PJSIP worker thread.
200 1 Adrian Georgescu
  If this fails an appropriate exception is raised.
201 1 Adrian Georgescu
  After the {{{Engine}}} has been started successfully, it can never be started again after being stopped.
202 1 Adrian Georgescu
  The keyword arguments will be discussed here.
203 87 Adrian Georgescu
  Many of these values are also readable as (proxied) attributes on the Engine once the {{{start()}}} method has been called.
204 44 Ruud Klaver
  Many of them can also be set at runtime, either by modifying the attribute or by calling a particular method.
205 1 Adrian Georgescu
  This will also be documented for each argument in the following list of options.
206 87 Adrian Georgescu
  [[BR]]''udp_port'': (Default: {{{0}}})[[BR]]
207 1 Adrian Georgescu
  The local UDP port to listen on for UDP datagrams.
208 1 Adrian Georgescu
  If this is 0, a random port will be chosen.
209 1 Adrian Georgescu
  If it is {{{None}}}, the UDP transport is disabled, both for incoming and outgoing traffic.
210 91 Luci Stanescu
  As an attribute, this value is read-only, but it can be changed at runtime using the {{{set_udp_port()}}} method.
211 87 Adrian Georgescu
  [[BR]]''tcp_port'': (Default: {{{0}}})[[BR]]
212 1 Adrian Georgescu
  The local TCP port to listen on for new TCP connections.
213 1 Adrian Georgescu
  If this is 0, a random port will be chosen.
214 1 Adrian Georgescu
  If it is {{{None}}}, the TCP transport is disabled, both for incoming and outgoing traffic.
215 91 Luci Stanescu
  As an attribute, this value is read-only, but it can be changed at runtime using the {{{set_tcp_port()}}} method.
216 87 Adrian Georgescu
  [[BR]]''tls_port'': (Default: {{{0}}})[[BR]]
217 1 Adrian Georgescu
  The local TCP port to listen on for new TLS over TCP connections.
218 1 Adrian Georgescu
  If this is 0, a random port will be chosen.
219 28 Adrian Georgescu
  If it is {{{None}}}, the TLS transport is disabled, both for incoming and outgoing traffic.
220 87 Adrian Georgescu
  As an attribute, this value is read-only, but it can be changed at runtime using the {{{set_tls_options()}}} method, as internally the TLS transport needs to be restarted for this operation.
221 1 Adrian Georgescu
  [[BR]]''tls_protocol'': (Default: "TLSv1")[[BR]] 
222 35 Ruud Klaver
  This string describes the (minimum) TLS protocol that should be used. 
223 32 Ruud Klaver
  Its values should be either {{{None}}}, "SSLv2", "SSLv23", "SSLv3" or "TLSv1". 
224 32 Ruud Klaver
  If {{{None}}} is specified, the PJSIP default will be used, which is currently "TLSv1". 
225 1 Adrian Georgescu
  [[BR]]''tls_verify_server'': (Default: {{{False}}})[[BR]]
226 32 Ruud Klaver
  This boolean indicates whether PJSIP should verify the certificate of the server against the local CA list when making an outgoing TLS connection.
227 1 Adrian Georgescu
  As an attribute, this value is read-only, but it can be changed at runtime using the {{{set_tls_options()}}} method, as internally the TLS transport needs to be restarted for this operation.
228 28 Adrian Georgescu
  [[BR]]''tls_ca_file'': (Default: {{{None}}})[[BR]]
229 32 Ruud Klaver
  This string indicates the location of the file containing the local list of CA certificates, to be used for TLS connections.
230 1 Adrian Georgescu
  If this is set to {{{None}}}, no CA certificates will be read. 
231 1 Adrian Georgescu
  As an attribute, this value is read-only, but it can be changed at runtime using the {{{set_tls_options()}}} method, as internally the TLS transport needs to be restarted for this operation. 
232 32 Ruud Klaver
  [[BR]]''tls_cert_file'': (Default: {{{None}}})[[BR]] 
233 32 Ruud Klaver
  This string indicates the location of a file containing the TLS certificate to be used for TLS connections. 
234 32 Ruud Klaver
  If this is set to {{{None}}}, no certificate file will be read. 
235 32 Ruud Klaver
  As an attribute, this value is read-only, but it can be changed at runtime using the {{{set_tls_options()}}} method, as internally the TLS transport needs to be restarted for this operation. 
236 32 Ruud Klaver
  [[BR]]''tls_privkey_file'': (Default: {{{None}}})[[BR]] 
237 32 Ruud Klaver
  This string indicates the location of a file containing the TLS private key associated with the above mentioned certificated to be used for TLS connections. 
238 32 Ruud Klaver
  If this is set to {{{None}}}, no private key file will be read. 
239 32 Ruud Klaver
  As an attribute, this value is read-only, but it can be changed at runtime using the {{{set_tls_options()}}} method, as internally the TLS transport needs to be restarted for this operation. 
240 32 Ruud Klaver
  [[BR]]''tls_timeout'': (Default: 1000)[[BR]] 
241 1 Adrian Georgescu
  The timeout value for a TLS negotiation in milliseconds. 
242 32 Ruud Klaver
  Note that this value should be reasonably small, as a TLS negotiation blocks the whole PJSIP polling thread. 
243 32 Ruud Klaver
  As an attribute, this value is read-only, but it can be changed at runtime using the {{{set_tls_options()}}} method, as internally the TLS transport needs to be restarted for this operation.
244 91 Luci Stanescu
  [[BR]]''user_agent'': (Default: {{{"sipsimple-%version-pjsip-%pjsip_version-r%pjsip_svn_revision"}}})[[BR]]
245 32 Ruud Klaver
  This value indicates what should be set in the {{{User-Agent}}} header, which is included in each request or response sent.
246 71 Adrian Georgescu
  It can be read and set directly as an attribute at runtime.
247 1 Adrian Georgescu
  [[BR]]''log_level'': (Default: 5)[[BR]]
248 1 Adrian Georgescu
  This integer dictates the maximum log level that may be reported to the application by PJSIP through the {{{SIPEngineLog}}} notification.
249 1 Adrian Georgescu
  By default the maximum amount of logging information is reported.
250 29 Luci Stanescu
  This value can be read and set directly as an attribute at runtime.
251 1 Adrian Georgescu
  [[BR]]''trace_sip'': (Default: {{{False}}})[[BR]]
252 1 Adrian Georgescu
  This boolean indicates if the SIP core should send the application SIP messages as seen on the wire through the {{{SIPEngineSIPTrace}}} notification.
253 1 Adrian Georgescu
  It can be read and set directly as an attribute at runtime.
254 1 Adrian Georgescu
  [[BR]]''rtp_port_range'': (Default: (40000, 40100))[[BR]]
255 1 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.
256 1 Adrian Georgescu
  It can be read and set directly as an attribute at runtime, but the ports of previously created {{{RTPTransport}}} objects remain unaffected.
257 1 Adrian Georgescu
  [[BR]]''codecs'': (Default: {{{["speex", "G722", "PCMU", "PCMA", "iLBC", "GSM"]}}})[[BR]]
258 71 Adrian Georgescu
  This list specifies the codecs to use for audio sessions and their preferred order.
259 1 Adrian Georgescu
  It can be read and set directly as an attribute at runtime.
260 1 Adrian Georgescu
  Note that this global option can be overridden by an argument passed to {{{AudioTransport.__init__()}}}.
261 40 Ruud Klaver
  The strings in this list is case insensitive.
262 1 Adrian Georgescu
  [[BR]]''events'': (Default: <some sensible events>)[[BR]]
263 1 Adrian Georgescu
  PJSIP needs a mapping between SIP SIMPLE event packages and content types.
264 1 Adrian Georgescu
  This dictionary provides some default packages and their event types.
265 91 Luci Stanescu
  As an attribute, this value is read-only, but it can be changed at runtime using the {{{add_event()}}} method.
266 1 Adrian Georgescu
  [[BR]]''incoming_events'': (Default: {{{set()}}})[[BR]]
267 1 Adrian Georgescu
  A list that specifies for which SIP SIMPLE event packages the application wishes to receive {{{IncomingSubscribe}}} objects.
268 82 Ruud Klaver
  When a {{{SUBSCRIBE}}} request is received containing an event name that is not in this list, a 489 "Bad event" response is internally generated.
269 1 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.
270 82 Ruud Klaver
  Note that each of the events specified here should also be a key in the {{{events}}} dictionary argument.
271 82 Ruud Klaver
  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.
272 82 Ruud Klaver
  [[BR]]''incoming_requests'': (Default: {{{set()}}})[[BR]]
273 82 Ruud Klaver
  A set of methods for which {{{IncomingRequest}}} objects are created and sent to the application if they are received.
274 85 Ruud Klaver
  Note that receiving requests using the {{{INVITE}}}, {{{SUBSCRIBE}}}, {{{ACK}}} or {{{BYE}}} methods in this way is not allowed.
275 74 Ruud Klaver
  Requests using the {{{OPTIONS}}} or {{{MESSAGE}}} method are handled internally, but may be overridden.
276 99 Adrian Georgescu
277 40 Ruud Klaver
 '''stop'''(''self'')::
278 1 Adrian Georgescu
  Stop the PJSIP worker thread and unload all PJSIP libraries.
279 36 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}}}.
280 32 Ruud Klaver
  Also note that, once stopped the {{{Engine}}} cannot be started again.
281 32 Ruud Klaver
  This method is automatically called when the Python interpreter exits.
282 35 Ruud Klaver
283 1 Adrian Georgescu
==== proxied attributes ====
284 39 Ruud Klaver
285 91 Luci Stanescu
Besides all the proxied attributes described for the {{{__init__}}} method above, thse other attributes are provided once the {{{Engine}}} has been started.
286 1 Adrian Georgescu
287 99 Adrian Georgescu
288 20 Ruud Klaver
 '''input_devices'''::
289 1 Adrian Georgescu
  This read-only attribute is a list of strings, representing all audio input devices on the system that can be used.
290 91 Luci Stanescu
  One of these device names can be passed as the {{{input_device}}} argument when creating a {{{AudioMixer}}} object.
291 99 Adrian Georgescu
292 74 Ruud Klaver
 '''output_devices'''::
293 91 Luci Stanescu
  This read-only attribute is a list of strings, representing all audio output devices on the system that can be used.
294 91 Luci Stanescu
  One of these device names can be passed as the {{{output_device}}} argument when creating a {{{AudioMixer}}} object.
295 99 Adrian Georgescu
296 91 Luci Stanescu
 '''sound_devices'''::
297 91 Luci Stanescu
  This read-only attribute is a list of strings, representing all audio sound devices on the system that can be used.
298 99 Adrian Georgescu
299 1 Adrian Georgescu
 '''available_codecs'''::
300 1 Adrian Georgescu
  A read-only list of codecs available in the core, regardless of the codecs configured through the {{{codecs}}} attribute.
301 1 Adrian Georgescu
302 29 Luci Stanescu
==== proxied methods ====
303 1 Adrian Georgescu
304 99 Adrian Georgescu
305 1 Adrian Georgescu
 '''add_event'''(''self'', '''event''', '''accept_types''')::
306 82 Ruud Klaver
  Couple a certain event package to a list of content types.
307 82 Ruud Klaver
  Once added it cannot be removed or modified.
308 99 Adrian Georgescu
309 82 Ruud Klaver
 '''add_incoming_event'''(''self'', '''event''')::
310 82 Ruud Klaver
  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.
311 82 Ruud Klaver
  Note that this event should be known to the {{{Engine}}} by means of the {{{events}}} attribute.
312 99 Adrian Georgescu
313 85 Ruud Klaver
 '''remove_incoming_event'''(''self'', '''event''')::
314 85 Ruud Klaver
  Removes an event from the {{{incoming_events}}} attribute.
315 85 Ruud Klaver
  Incoming {{{SUBSCRIBE}}} requests with this event package will automatically be replied to with a 489 "Bad Event" response.
316 99 Adrian Georgescu
317 85 Ruud Klaver
 '''add_incoming_request'''(''self'', '''method''')::
318 1 Adrian Georgescu
  Add a method to the set of methods for which incoming requests should be turned into {{{IncomingRequest}}} objects.
319 1 Adrian Georgescu
  For the rules on which methods are allowed, see the description of the Engine attribute above.
320 99 Adrian Georgescu
321 38 Ruud Klaver
 '''remove_incoming_request'''(''self'', '''method''')::
322 1 Adrian Georgescu
  Removes a method from the set of methods that should be received.
323 99 Adrian Georgescu
324 1 Adrian Georgescu
 '''detect_nat_type'''(''self'', '''stun_server_address''', '''stun_server_port'''=3478, '''user_data'''=None)::
325 38 Ruud Klaver
  Will start a series of STUN requests which detect the type of NAT this host is behind.
326 87 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.
327 1 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.
328 99 Adrian Georgescu
329 87 Adrian Georgescu
 '''set_udp_port'''(''self'', '''value''')::
330 1 Adrian Georgescu
  Update the {{{local_udp_port}}} attribute to the newly specified value.
331 99 Adrian Georgescu
332 44 Ruud Klaver
 '''set_tcp_port'''(''self'', '''value''')::
333 44 Ruud Klaver
  Update the {{{local_tcp_port}}} attribute to the newly specified value.
334 99 Adrian Georgescu
335 44 Ruud Klaver
 '''set_tls_options'''(''self'', '''local_port'''={{{None}}}, '''protocol'''="TLSv1", '''verify_server'''={{{False}}}, '''ca_file'''={{{None}}}, '''cert_file'''={{{None}}}, '''privkey_file'''={{{None}}}, '''timeout'''=1000):: 
336 83 Ruud Klaver
  Calling this method will (re)start the TLS transport with the specified arguments, or stop it in the case that the '''local_port''' argument is set to {{{None}}}. 
337 44 Ruud Klaver
  The semantics of the arguments are the same as on the {{{start()}}} method. 
338 1 Adrian Georgescu
339 1 Adrian Georgescu
==== notifications ====
340 1 Adrian Georgescu
341 1 Adrian Georgescu
Notifications sent by the {{{Engine}}} are notifications that are related to the {{{Engine}}} itself or unrelated to any SIP primitive object.
342 1 Adrian Georgescu
They are described here including the data attributes that is included with them.
343 16 Ruud Klaver
344 99 Adrian Georgescu
345 1 Adrian Georgescu
 '''SIPEngineWillStart'''::
346 1 Adrian Georgescu
  This notification is sent when the {{{Engine}}} is about to start.
347 29 Luci Stanescu
  [[BR]]''timestamp'':[[BR]]
348 1 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
349 99 Adrian Georgescu
350 16 Ruud Klaver
 '''SIPEngineDidStart'''::
351 16 Ruud Klaver
  This notification is sent when the {{{Engine}}} is has just been started.
352 29 Luci Stanescu
  [[BR]]''timestamp'':[[BR]]
353 16 Ruud Klaver
  A {{{datetime.datetime}}} object indicating when the notification was sent.
354 99 Adrian Georgescu
355 16 Ruud Klaver
 '''SIPEngineDidFail'''::
356 16 Ruud Klaver
  This notification is sent whenever the {{{Engine}}} has failed fatally and either cannot start or is about to stop.
357 29 Luci Stanescu
  It is not recommended to call any methods on the {{{Engine}}} at this point.
358 16 Ruud Klaver
  [[BR]]''timestamp'':[[BR]]
359 16 Ruud Klaver
  A {{{datetime.datetime}}} object indicating when the notification was sent.
360 99 Adrian Georgescu
361 16 Ruud Klaver
 '''SIPEngineWillEnd'''::
362 16 Ruud Klaver
  This notification is sent when the {{{Engine}}} is about to stop because the application called the {{{stop()}}} method.
363 1 Adrian Georgescu
  Methods on the {{{Engine}}} can be called at this point, but anything that has a delayed result will probably not return any notification.
364 16 Ruud Klaver
  [[BR]]''timestamp'':[[BR]]
365 1 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
366 99 Adrian Georgescu
367 16 Ruud Klaver
 '''SIPEngineDidEnd'''::
368 16 Ruud Klaver
  This notification is sent when the {{{Engine}}} was running and is now stopped, either because of failure or because the application requested it.
369 29 Luci Stanescu
  [[BR]]''timestamp'':[[BR]]
370 16 Ruud Klaver
  A {{{datetime.datetime}}} object indicating when the notification was sent.
371 99 Adrian Georgescu
372 16 Ruud Klaver
 '''SIPEngineLog'''::
373 16 Ruud Klaver
  This notification is a wrapper for PJSIP logging messages.
374 1 Adrian Georgescu
  It can be used by the application to output PJSIP logging to somewhere meaningful, possibly doing filtering based on log level.
375 1 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
376 1 Adrian Georgescu
  A {{{datetime.datetime}}} object representing the time when the log message was output by PJSIP.
377 1 Adrian Georgescu
  [[BR]]''sender'':[[BR]]
378 1 Adrian Georgescu
  The PJSIP module that originated this log message.
379 1 Adrian Georgescu
  [[BR]]''level'':[[BR]]
380 1 Adrian Georgescu
  The logging level of the message as an integer.
381 1 Adrian Georgescu
  Currently this is 1 through 5, 1 being the most critical.
382 1 Adrian Georgescu
  [[BR]]''message'':[[BR]]
383 1 Adrian Georgescu
  The actual log message.
384 99 Adrian Georgescu
385 1 Adrian Georgescu
 '''SIPEngineSIPTrace'''::
386 1 Adrian Georgescu
  Will be sent only when the {{{do_siptrace}}} attribute of the {{{Engine}}} instance is set to {{{True}}}.
387 1 Adrian Georgescu
  The notification data attributes will contain the SIP messages as they are sent and received on the wire.
388 1 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
389 1 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
390 1 Adrian Georgescu
  [[BR]]''received'':[[BR]]
391 1 Adrian Georgescu
  A boolean indicating if this message was sent from or received by PJSIP (i.e. the direction of the message).
392 1 Adrian Georgescu
  [[BR]]''source_ip'':[[BR]]
393 1 Adrian Georgescu
  The source IP address as a string.
394 1 Adrian Georgescu
  [[BR]]''source_port'':[[BR]]
395 1 Adrian Georgescu
  The source port of the message as an integer.
396 1 Adrian Georgescu
  [[BR]]''destination_ip'':[[BR]]
397 1 Adrian Georgescu
  The destination IP address as a string.
398 1 Adrian Georgescu
  [[BR]]''source_port'':[[BR]]
399 1 Adrian Georgescu
  The source port of the message as an integer.
400 1 Adrian Georgescu
  [[BR]]''data'':[[BR]]
401 1 Adrian Georgescu
  The contents of the message as a string.
402 1 Adrian Georgescu
403 1 Adrian Georgescu
> For received message the destination_ip and for sent messages the source_ip may not be reliable.
404 1 Adrian Georgescu
405 99 Adrian Georgescu
406 1 Adrian Georgescu
 '''SIPEngineDetectedNATType'''::
407 1 Adrian Georgescu
  This notification is sent some time after the application request the NAT type this host behind to be detected using a STUN server.
408 1 Adrian Georgescu
  Note that there is no way to associate a request to do this with a notification, although every call to the {{{detect_nat_type()}}} method will generate exactly one notification.
409 1 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
410 1 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
411 1 Adrian Georgescu
  [[BR]]''succeeded'':[[BR]]
412 1 Adrian Georgescu
  A boolean indicating if the NAT detection succeeded.
413 1 Adrian Georgescu
  [[BR]]''user_data'':[[BR]]
414 1 Adrian Georgescu
  The {{{user_data}}} argument passed while calling the {{{detect_nat_type()}}} method.
415 1 Adrian Georgescu
  This can be any object and could be used for matching requests to responses.
416 1 Adrian Georgescu
  [[BR]]''nat_type'':[[BR]]
417 1 Adrian Georgescu
  A string describing the type of NAT found.
418 1 Adrian Georgescu
  This value is only present if NAT detection succeeded.
419 1 Adrian Georgescu
  [[BR]]''error'':[[BR]]
420 1 Adrian Georgescu
  A string indicating the error that occurred while attempting to detect the type of NAT.
421 1 Adrian Georgescu
  This value only present if NAT detection did not succeed.
422 99 Adrian Georgescu
423 1 Adrian Georgescu
 '''SIPEngineGotException'''::
424 1 Adrian Georgescu
  This notification is sent whenever there is an unexpected exception within the PJSIP working thread.
425 1 Adrian Georgescu
  The application should show the traceback to the user somehow.
426 1 Adrian Georgescu
  An exception need not be fatal, but if it is it will be followed by a '''SIPEngineDidFail''' notification.
427 1 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
428 1 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
429 1 Adrian Georgescu
  [[BR]]''traceback'':[[BR]]
430 1 Adrian Georgescu
  A string containing the traceback of the exception.
431 1 Adrian Georgescu
  In general this should be printed on the console.
432 1 Adrian Georgescu
433 108 Adrian Georgescu
 '''SIPEngineGotMessage'''::
434 108 Adrian Georgescu
  This notification is sent whenever the Engine receives a {{{MESSAGE}}} request.
435 108 Adrian Georgescu
  [[BR]]''request_uri'':[[BR]]
436 108 Adrian Georgescu
  The request URI of the {{{MESSAGE}}} request as a {{{SIPURI}}} object.
437 108 Adrian Georgescu
  [[BR]]''from_header'':[[BR]]
438 108 Adrian Georgescu
  The From header of the {{{MESSAGE}}} request as a {{{FrozenFromHeader}}} object.
439 108 Adrian Georgescu
  [[BR]]''to_header'':[[BR]]
440 108 Adrian Georgescu
  The To header of the {{{MESSAGE}}} request as a {{{FrozenToHeader}}} object.
441 108 Adrian Georgescu
  [[BR]]''content_type'':[[BR]]
442 108 Adrian Georgescu
  The Content-Type header value of the {{{MESSAGE}}} request as a {{{ContentType}}} object.
443 108 Adrian Georgescu
  [[BR]]''headers'':[[BR]]
444 108 Adrian Georgescu
  The headers of the {{{MESSAGE}}} request as a dict.
445 108 Adrian Georgescu
  Each SIP header is represented in its parsed for as long as PJSIP supports it.
446 108 Adrian Georgescu
  The format of the parsed value depends on the header.
447 108 Adrian Georgescu
  [[BR]]''body'':[[BR]]
448 108 Adrian Georgescu
  The body of the {{{MESSAGE}}} request as a string, or {{{None}}} if no body was included.
449 108 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
450 108 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
451 108 Adrian Georgescu
452 98 Adrian Georgescu
=== SIPURI ===
453 1 Adrian Georgescu
454 91 Luci Stanescu
These are helper objects for representing a SIP URI.
455 91 Luci Stanescu
This object needs to be used whenever a SIP URI should be specified to the SIP core.
456 91 Luci Stanescu
It supports comparison to other {{{SIPURI}}} objects using the == and != expressions.
457 91 Luci Stanescu
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.
458 91 Luci Stanescu
459 91 Luci Stanescu
==== methods ====
460 91 Luci Stanescu
461 99 Adrian Georgescu
462 91 Luci Stanescu
 '''!__init!__'''(''self'', '''host''', '''user'''={{{None}}}, '''port'''={{{None}}}, '''display'''={{{None}}}, '''secure'''={{{False}}}, '''parameters'''={{{None}}}, '''headers'''={{{None}}})::
463 91 Luci Stanescu
  Creates the SIPURI object with the specified parameters as attributes.
464 91 Luci Stanescu
  {{{host}}} is the only mandatory attribute.
465 91 Luci Stanescu
  [[BR]]''host'':[[BR]]
466 91 Luci Stanescu
  The host part of the SIP URI as a string.
467 91 Luci Stanescu
  [[BR]]''user'':[[BR]]
468 91 Luci Stanescu
  The username part of the SIP URI as a string, or None if not set.
469 91 Luci Stanescu
  [[BR]]''port'':[[BR]]
470 91 Luci Stanescu
  The port part of the SIP URI as an int, or None or 0 if not set.
471 91 Luci Stanescu
  [[BR]]''display'':[[BR]]
472 91 Luci Stanescu
  The optional display name of the SIP URI as a string, or None if not set.
473 91 Luci Stanescu
  [[BR]]''secure'':[[BR]]
474 91 Luci Stanescu
  A boolean indicating whether this is a SIP or SIPS URI, the latter being indicated by a value of {{{True}}}.
475 91 Luci Stanescu
  [[BR]]''parameters'':[[BR]]
476 91 Luci Stanescu
  The URI parameters. represented by a dictionary.
477 91 Luci Stanescu
  [[BR]]''headers'':[[BR]]
478 91 Luci Stanescu
  The URI headers, represented by a dictionary.
479 99 Adrian Georgescu
480 91 Luci Stanescu
 '''!__str!__'''(''self'')::
481 91 Luci Stanescu
  The special Python method to represent this object as a string, the output is the properly formatted SIP URI.
482 99 Adrian Georgescu
483 91 Luci Stanescu
 '''new'''(''cls'', ''sipuri'')::
484 91 Luci Stanescu
  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).
485 99 Adrian Georgescu
486 91 Luci Stanescu
 '''parse'''(''cls'', ''uri_str'')::
487 91 Luci Stanescu
  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.
488 91 Luci Stanescu
489 104 Luci Stanescu
 '''matches'''(''self'', ''address'')::
490 104 Luci Stanescu
  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}}}.
491 104 Luci Stanescu
492 96 Luci Stanescu
=== Credentials ===
493 91 Luci Stanescu
494 96 Luci Stanescu
The {{{Credentials}}} and {{{FrozenCredentails}}} simple objects represent authentication credentials for a particular SIP account.
495 91 Luci Stanescu
These can be included whenever creating a SIP primitive object that originates SIP requests.
496 96 Luci Stanescu
The attributes of this object are the same as the arguments to the {{{__init__}}} method.
497 91 Luci Stanescu
Note that the domain name of the SIP account is not stored on this object.
498 91 Luci Stanescu
499 91 Luci Stanescu
==== methods ====
500 91 Luci Stanescu
501 99 Adrian Georgescu
502 91 Luci Stanescu
 '''!__init!__'''(''self'', '''username''', '''password''')::
503 91 Luci Stanescu
  Creates the Credentials object with the specified parameters as attributes.
504 91 Luci Stanescu
  Each of these attributes can be accessed and changed on the object once instanced.
505 91 Luci Stanescu
  [[BR]]''username'':[[BR]]
506 91 Luci Stanescu
  A string representing the username of the account for which these are the credentials.
507 91 Luci Stanescu
  [[BR]]''password'':[[BR]]
508 91 Luci Stanescu
  The password for this SIP account as a string.
509 99 Adrian Georgescu
510 91 Luci Stanescu
 '''new'''(''cls'', ''credentials'')::
511 91 Luci Stanescu
  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).
512 91 Luci Stanescu
513 103 Adrian Georgescu
=== Invitation ===
514 103 Adrian Georgescu
515 103 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.
516 103 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.
517 103 Adrian Georgescu
The {{{Invitation}}} class represents both incoming and outgoing sessions.
518 103 Adrian Georgescu
519 103 Adrian Georgescu
The state machine contained in each {{{Invitation}}} object is based on the one used by the underlying PJSIP [http://www.pjsip.org/pjsip/docs/html/group__PJSIP__INV.htm pjsip_inv_session] object.
520 103 Adrian Georgescu
In order to represent re-{{{INVITE}}}s and user-requested disconnections, three more states have been added to this state machine.
521 103 Adrian Georgescu
The progression through this state machine is fairly linear and is dependent on whether this is an incoming or an outgoing session.
522 103 Adrian Georgescu
State changes are triggered either by incoming or by outgoing SIP requests and responses.
523 103 Adrian Georgescu
The states and the transitions between them are shown in the following diagram:
524 103 Adrian Georgescu
525 103 Adrian Georgescu
[[Image(sipsimple-core-invite-state-machine.png, nolink)]]
526 103 Adrian Georgescu
527 103 Adrian Georgescu
The state changes of this machine are triggered by the following:
528 103 Adrian Georgescu
 1. An {{{Invitation}}} object is newly created, either by the application for an outgoing session, or by the core for an incoming session.
529 103 Adrian Georgescu
 2. The application requested an outgoing session by calling the {{{send_invite()}}} method and and initial {{{INVITE}}} request is sent.
530 103 Adrian Georgescu
 3. A new incoming session is received by the core.
531 103 Adrian Georgescu
    The application should look out for state change to this state in order to be notified of new incoming sessions.
532 103 Adrian Georgescu
 4. A provisional response (1xx) is received from the remove party.
533 103 Adrian Georgescu
 5. A provisional response (1xx) is sent to the remote party, after the application called the {{{respond_to_invite_provisionally()}}} method.
534 103 Adrian Georgescu
 6. A positive final response (2xx) is received from the remote party.
535 103 Adrian Georgescu
 7. A positive final response (2xx) is sent to the remote party, after the application called the {{{accept_invite()}}} method.
536 103 Adrian Georgescu
 8. A positive final response (2xx) is sent or received, depending on the orientation of the session.
537 103 Adrian Georgescu
 9. An {{{ACK}}} is sent or received, depending on the orientation of the session.
538 103 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.
539 103 Adrian Georgescu
 10. The local party sent a re-{{{INVITE}}} to the remote party by calling the {{{send_reinvite()}}} method.
540 103 Adrian Georgescu
 11. The remote party has sent a final response to the re-{{{INVITE}}}.
541 103 Adrian Georgescu
 12. The remote party has sent a re-{{{INVITE}}}.
542 103 Adrian Georgescu
 13. The local party has responded to the re-{{{INVITE}}} by calling the {{{respond_to_reinvite()}}} method.
543 103 Adrian Georgescu
 14. The application requests that the session ends by calling the {{{end()}}} method.
544 103 Adrian Georgescu
 15. A response is received from the remote party to whichever message was sent by the local party to end the session.
545 103 Adrian Georgescu
 16. A message is received from the remote party which ends the session.
546 103 Adrian Georgescu
547 103 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.
548 103 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.
549 103 Adrian Georgescu
The application should compare the previous and current states and perform the appropriate action.
550 103 Adrian Georgescu
551 103 Adrian Georgescu
An {{{Invitiation}}} object also emits the {{{SIPInvitationGotSDPUpdate}}} notification, which indicates that SDP negotiation between the two parties has been completed.
552 103 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.
553 103 Adrian Georgescu
In the last case, the {{{Invitation}}} object will automatically include the current local SDP in the response.
554 103 Adrian Georgescu
555 103 Adrian Georgescu
==== attributes ====
556 103 Adrian Georgescu
557 103 Adrian Georgescu
558 103 Adrian Georgescu
 '''state'''::
559 103 Adrian Georgescu
  The state the {{{Invitation}}} state machine is currently in.
560 103 Adrian Georgescu
  See the diagram above for possible states.
561 103 Adrian Georgescu
  This attribute is read-only.
562 103 Adrian Georgescu
563 103 Adrian Georgescu
 '''sub_state'''::
564 103 Adrian Georgescu
  The sub-state the {{{Invitation}}} state machine is currently in.
565 103 Adrian Georgescu
  See the diagram above for possible states.
566 103 Adrian Georgescu
  This attribute is read-only.
567 103 Adrian Georgescu
568 103 Adrian Georgescu
 '''directing'''::
569 103 Adrian Georgescu
  A string with the values {{{"incoming"}}} or {{{"outgoing"}}} depending on the direction of the original INVITE request.
570 103 Adrian Georgescu
571 103 Adrian Georgescu
 '''credentials'''::
572 103 Adrian Georgescu
  The SIP credentials needed to authenticate at the SIP proxy in the form of a {{{FrozenCredentials}}} object.
573 103 Adrian Georgescu
  If this {{{Invitation}}} object represents an incoming {{{INVITE}}} session this attribute will be {{{None}}}.
574 103 Adrian Georgescu
  On an outgoing session this attribute will be {{{None}}} if it was not specified when the object was created.
575 103 Adrian Georgescu
  This attribute is set on object instantiation and is read-only.
576 103 Adrian Georgescu
577 103 Adrian Georgescu
 '''from_header'''::
578 103 Adrian Georgescu
  The From header of the caller represented by a {{{FrozenFromHeader}}} object.
579 103 Adrian Georgescu
  If this is an outgoing {{{INVITE}}} session, this is the from_header from the {{{send_invite()}}} method.
580 103 Adrian Georgescu
  Otherwise the URI is taken from the {{{From:}}} header of the initial {{{INVITE}}}.
581 103 Adrian Georgescu
  This attribute is set on object instantiation and is read-only.
582 103 Adrian Georgescu
583 103 Adrian Georgescu
 '''to_header'''::
584 103 Adrian Georgescu
  The To header of the callee represented by a {{{FrozenToHeader}}} object.
585 103 Adrian Georgescu
  If this is an outgoing {{{INVITE}}} session, this is the to_header from the {{{send_invite()}}} method.
586 103 Adrian Georgescu
  Otherwise the URI is taken from the {{{To:}}} header of the initial {{{INVITE}}}.
587 103 Adrian Georgescu
  This attribute is set on object instantiation and is read-only.
588 103 Adrian Georgescu
589 103 Adrian Georgescu
 '''local_identity'''::
590 103 Adrian Georgescu
  The From or To header representing the local identity used in this session.
591 103 Adrian Georgescu
  If the original {{{INVITE}}} was incoming, this is the same as {{{to_header}}}, otherwise it will be the same as {{{from_header}}}.
592 103 Adrian Georgescu
593 103 Adrian Georgescu
 '''remote_identity'''::
594 103 Adrian Georgescu
  The From or To header representing the remote party in this session.
595 103 Adrian Georgescu
  If the original {{{INVITE}}} was incoming, this is the same as {{{from_header}}}, otherwise it will be the same as {{{to_header}}}.
596 103 Adrian Georgescu
597 103 Adrian Georgescu
 '''route_header'''::
598 103 Adrian Georgescu
  The outbound proxy that was requested to be used in the form of a {{{FrozenRouteHeader}}} object, including the desired transport.
599 103 Adrian Georgescu
  If this {{{Invitation}}} object represents an incoming {{{INVITE}}} session this attribute will always be {{{None}}}.
600 103 Adrian Georgescu
  This attribute is set on object instantiation and is read-only.
601 103 Adrian Georgescu
602 103 Adrian Georgescu
 '''call_id'''::
603 103 Adrian Georgescu
  The call ID of the {{{INVITE}}} session as a read-only string.
604 103 Adrian Georgescu
  In the {{{NULL}}} and {{{DISCONNECTED}}} states, this attribute is {{{None}}}.
605 103 Adrian Georgescu
606 103 Adrian Georgescu
 '''transport'''::
607 103 Adrian Georgescu
  A string indicating the transport used for the application.
608 103 Adrian Georgescu
  This can be "udp", "tcp" or "tls".
609 103 Adrian Georgescu
610 103 Adrian Georgescu
 '''local_contact_header'''::
611 103 Adrian Georgescu
  The Contact header that the local side provided to the remote side within this {{{INVITE}}} session as a {{{FrozenContactHeader}}} object.
612 103 Adrian Georgescu
  Note that this can either be set on object creation or updated using the {{{send_reinvite()}}} method.
613 103 Adrian Georgescu
614 111 Adrian Georgescu
 '''remote_contact_header'''::
615 111 Adrian Georgescu
  The Contact header that the remote side provided to us within this {{{INVITE}}} session as a {{{FrozenContactHeader}}} object.
616 111 Adrian Georgescu
617 103 Adrian Georgescu
 '''call_id'''::
618 103 Adrian Georgescu
  A string representing the Call-Id header value of this INVITE dialog.
619 103 Adrian Georgescu
620 103 Adrian Georgescu
 '''remote_user_agent'''::
621 103 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).
622 103 Adrian Georgescu
623 103 Adrian Georgescu
 '''sdp.proposed_local'''::
624 103 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.
625 103 Adrian Georgescu
626 103 Adrian Georgescu
 '''sdp.proposed_remote'''::
627 103 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.
628 103 Adrian Georgescu
629 103 Adrian Georgescu
 '''sdp.active_local'''::
630 103 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.
631 103 Adrian Georgescu
632 103 Adrian Georgescu
 '''sdp.active_remote'''::
633 103 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.
634 103 Adrian Georgescu
635 109 Adrian Georgescu
 '''peer_address'''::
636 109 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.
637 109 Adrian Georgescu
638 103 Adrian Georgescu
==== methods ====
639 103 Adrian Georgescu
640 103 Adrian Georgescu
641 103 Adrian Georgescu
 '''!__init!__'''(''self'')::
642 103 Adrian Georgescu
  Creates a new {{{Invitation}}} object.
643 103 Adrian Georgescu
644 110 Adrian Georgescu
 '''send_invite'''(''self'', '''request_uri''','''from_header''', '''to_header''', '''route_header''', '''contact_header''', '''sdp''', '''credentials'''={{{None}}}, '''extra_headers'''={{{[]}}}, '''timeout'''=None)::
645 110 Adrian Georgescu
  [[BR]]''request_uri'':[[BR]]
646 110 Adrian Georgescu
  Request URI to be set inthe outgoing INVITE request.
647 103 Adrian Georgescu
  [[BR]]''from_header'':[[BR]]
648 103 Adrian Georgescu
  The identity of the local account in the form of a {{{FromHeader}}} object.
649 103 Adrian Georgescu
  [[BR]]''to_header'':[[BR]]
650 103 Adrian Georgescu
  The identity we want to send the {{{INVITE}}} to, represented as a {{{ToHeader}}} object.
651 103 Adrian Georgescu
  [[BR]]''route_header'':[[BR]]
652 103 Adrian Georgescu
  The outbound proxy to use in the form of a {{{RouteHeader}}} object.
653 103 Adrian Georgescu
  This includes the desired transport to use.
654 103 Adrian Georgescu
  [[BR]]''contact_header'':[[BR]]
655 103 Adrian Georgescu
  The Contact header to include in the {{{INVITE}}} request, a {{{ContactHeader}}} object.
656 103 Adrian Georgescu
  [[BR]]''sdp'':[[BR]]
657 103 Adrian Georgescu
  The SDP to send as offer to the remote party.
658 103 Adrian Georgescu
  [[BR]]''credentials'':[[BR]]
659 103 Adrian Georgescu
  The optional SIP credentials needed to authenticate at the SIP proxy in the form of a {{{Credentials}}} object.
660 103 Adrian Georgescu
  [[BR]]''extra_headers'':[[BR]]
661 103 Adrian Georgescu
  Any extra headers that should be included in the {{{INVITE}}} request in the form of a list of header objects.
662 103 Adrian Georgescu
  [[BR]]''timeout'':[[BR]]
663 103 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.
664 103 Adrian Georgescu
  If this is set to {{{None}}}, the default PJSIP timeout will be used, which appears to be slightly longer than 30 seconds.
665 103 Adrian Georgescu
666 103 Adrian Georgescu
 '''send_response'''(''self'', '''code''', '''reason''', '''contact_header''', '''sdp''', '''extra_headers''')::
667 103 Adrian Georgescu
  Send a response to a INVITE request. 
668 103 Adrian Georgescu
  [[BR]]''code'':[[BR]]
669 103 Adrian Georgescu
  The code of the response to use as an int.
670 103 Adrian Georgescu
  [[BR]]''reason'':[[BR]]
671 103 Adrian Georgescu
  The reason of the response as a str.
672 103 Adrian Georgescu
  [[BR]]''contact_header'':[[BR]]
673 103 Adrian Georgescu
  The Contact header to include in the response, a {{{ContactHeader}}} object.
674 103 Adrian Georgescu
  [[BR]]''sdp'':[[BR]]
675 103 Adrian Georgescu
  The SDP to send as offer/response to the remote party.
676 103 Adrian Georgescu
  [[BR]]''extra_headers'':[[BR]]
677 103 Adrian Georgescu
  Any extra headers that should be included in the response in the form of a list of header objects.
678 103 Adrian Georgescu
679 103 Adrian Georgescu
 '''send_reinvite'''(''self'', '''contact_header'''={{{None}}}, '''sdp'''={{{None}}}, '''extra_header'''={{{[]}}})::
680 103 Adrian Georgescu
  [[BR]]''contact_header'':[[BR]]
681 103 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.
682 103 Adrian Georgescu
  [[BR]]''sdp'':[[BR]]
683 103 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.
684 103 Adrian Georgescu
  [[BR]]''extra_headers'':[[BR]]
685 103 Adrian Georgescu
  Any extra headers that should be included in the response in the form of a list of header objects.
686 103 Adrian Georgescu
687 103 Adrian Georgescu
 '''cancel_reinvite'''(''self'')::
688 103 Adrian Georgescu
  Send a CANCEL after a re-INVITE has been sent to cancel the action of the re-INVITE.
689 103 Adrian Georgescu
690 103 Adrian Georgescu
 '''end'''(''self'', '''extra_headers'''={{{[]}}}, '''timeout'''={{{None}}})::
691 103 Adrian Georgescu
  This moves the {{{INVITE}}} state machine into the {{{DISCONNECTING}}} state by sending the necessary SIP request.
692 103 Adrian Georgescu
  When a response from the remote party is received, the state machine will go into the {{{DISCONNECTED}}} state.
693 103 Adrian Georgescu
  Depending on the current state, this could be a CANCEL or a BYE request.
694 103 Adrian Georgescu
  [[BR]]''extra_headers'':[[BR]]
695 103 Adrian Georgescu
  Any extra headers that should be included in the request or response in the form of a dict.
696 103 Adrian Georgescu
  [[BR]]''timeout'':[[BR]]
697 103 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.
698 103 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.
699 103 Adrian Georgescu
700 103 Adrian Georgescu
==== notifications ====
701 103 Adrian Georgescu
702 103 Adrian Georgescu
703 103 Adrian Georgescu
 '''SIPInvitationChangedState'''::
704 103 Adrian Georgescu
  This notification is sent by an {{{Invitation}}} object whenever its state machine changes state.
705 103 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
706 103 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
707 103 Adrian Georgescu
  [[BR]]''prev_state'':[[BR]]
708 103 Adrian Georgescu
  The previous state of the INVITE state machine.
709 103 Adrian Georgescu
  [[BR]]''prev_sub_state'':[[BR]]
710 103 Adrian Georgescu
  THe previous sub-state of the INVITE state machine.
711 103 Adrian Georgescu
  [[BR]]''state'':[[BR]]
712 103 Adrian Georgescu
  The new state of the INVITE state machine, which may be the same as the previous state.
713 103 Adrian Georgescu
  [[BR]]''sub_state'':[[BR]]
714 103 Adrian Georgescu
  The new sub-state of teh INVITE state machine, which may be the same as the previous sub-state.
715 103 Adrian Georgescu
  [[BR]]''method'': (only if the state change got triggered by an incoming SIP request)[[BR]]
716 103 Adrian Georgescu
  The method of the SIP request as a string.
717 103 Adrian Georgescu
  [[BR]]''request_uri'': (only if the state change got triggered by an incoming SIP request)[[BR]]
718 103 Adrian Georgescu
  The request URI of the SIP request as a {{{SIPURI}}} object.
719 103 Adrian Georgescu
  [[BR]]''code'': (only if the state change got triggered by an incoming SIP response or internal timeout or error)[[BR]]
720 103 Adrian Georgescu
  The code of the SIP response or error as an int.
721 103 Adrian Georgescu
  [[BR]]''reason'': (only if the state change got triggered by an incoming SIP response or internal timeout or error)[[BR]]
722 103 Adrian Georgescu
  The reason text of the SIP response or error as a string.
723 103 Adrian Georgescu
  [[BR]]''headers'': (only if the state change got triggered by an incoming SIP request or response)[[BR]]
724 103 Adrian Georgescu
  The headers of the SIP request or response as a dict.
725 103 Adrian Georgescu
  Each SIP header is represented in its parsed for as long as PJSIP supports it.
726 103 Adrian Georgescu
  The format of the parsed value depends on the header.
727 103 Adrian Georgescu
  [[BR]]''body'': (only if the state change got triggered by an incoming SIP request or response)[[BR]]
728 103 Adrian Georgescu
  The body of the SIP request or response as a string, or {{{None}}} if no body was included.
729 103 Adrian Georgescu
  The content type of the body can be learned from the {{{Content-Type:}}} header in the headers argument.
730 103 Adrian Georgescu
731 103 Adrian Georgescu
 '''SIPInvitationGotSDPUpdate'''::
732 103 Adrian Georgescu
  This notification is sent by an {{{Invitation}}} object whenever SDP negotiation has been performed.
733 103 Adrian Georgescu
  It should be used by the application as an indication to start, change or stop any associated media streams.
734 103 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
735 103 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
736 103 Adrian Georgescu
  [[BR]]''succeeded'':[[BR]]
737 103 Adrian Georgescu
  A boolean indicating if the SDP negotiation has succeeded.
738 103 Adrian Georgescu
  [[BR]]''error'': (only if SDP negotiation did not succeed)[[BR]]
739 103 Adrian Georgescu
  A string indicating why SDP negotiation failed.
740 103 Adrian Georgescu
  [[BR]]''local_sdp'': (only if SDP negotiation succeeded)[[BR]]
741 103 Adrian Georgescu
  A SDPSession object indicating the local SDP that was negotiated.
742 103 Adrian Georgescu
  [[BR]]''remote_sdp'': (only if SDP negotiation succeeded)[[BR]]
743 103 Adrian Georgescu
  A SDPSession object indicating the remote SDP that was negotiated.
744 103 Adrian Georgescu
745 103 Adrian Georgescu
746 92 Luci Stanescu
=== SDPSession ===
747 92 Luci Stanescu
748 92 Luci Stanescu
SDP stands for Session Description Protocol. Session Description Protocol (SDP) is a format for describing streaming media initialization parameters in an ASCII string. SDP is intended for describing multimedia communication sessions for the purposes of session announcement, session invitation, and other forms of multimedia session initiation. It is an IETF standard described by [http://tools.ietf.org/html/rfc4566 RFC 4566]. [http://tools.ietf.org/html/rfc3264 RFC 3264] defines an Offer/Answer Model with the Session Description Protocol (SDP), a mechanism by which two entities can make use of the Session Description Protocol (SDP) to arrive at a common view of a multimedia session between them. 
749 92 Luci Stanescu
750 92 Luci Stanescu
{{{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 [http://www.pjsip.org/pjmedia/docs/html/structpjmedia__sdp__session.htm pjmedia_sdp_session] structure.
751 92 Luci Stanescu
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.
752 92 Luci Stanescu
A {{{(Frozen)SDPSession}}} object may contain {{{(Frozen)SDPMediaStream}}}, {{{(Frozen)SDPConnection}}} and {{{(Frozen)SDPAttribute}}} objects.
753 92 Luci Stanescu
It supports comparison to other {{{(Frozen)SDPSession}}} objects using the == and != expressions.
754 92 Luci Stanescu
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.
755 99 Adrian Georgescu
756 92 Luci Stanescu
==== methods ====
757 92 Luci Stanescu
758 92 Luci Stanescu
759 92 Luci Stanescu
 '''!__init!__'''(''self'', '''address''', '''id'''={{{None}}}, '''version'''={{{None}}}, '''user='''"-", net_type="IN", '''address_type'''="IP4", '''name'''=" ", '''info'''={{{None}}}, '''connection'''={{{None}}}, '''start_time'''=0, '''stop_time'''=0, '''attributes'''={{{None}}}, '''media'''={{{None}}})::
760 92 Luci Stanescu
  Creates the SDPSession object with the specified parameters as attributes.
761 92 Luci Stanescu
  Each of these attributes can be accessed and changed on the object once instanced.
762 92 Luci Stanescu
  [[BR]]''address'':[[BR]]
763 99 Adrian Georgescu
  The address that is contained in the "o" (origin) line of the SDP as a string.
764 92 Luci Stanescu
  [[BR]]''id'':[[BR]]
765 92 Luci Stanescu
  The session identifier contained in the "o" (origin) line of the SDP as an int.
766 99 Adrian Georgescu
  If this is set to {{{None}}} on init, a session identifier will be generated.
767 92 Luci Stanescu
  [[BR]]''version'':[[BR]]
768 92 Luci Stanescu
  The version identifier contained in the "o" (origin) line of the SDP as an int.
769 92 Luci Stanescu
  If this is set to {{{None}}} on init, a version identifier will be generated.
770 92 Luci Stanescu
  [[BR]]''user'':[[BR]]
771 92 Luci Stanescu
  The user name contained in the "o" (origin) line of the SDP as a string.
772 99 Adrian Georgescu
  [[BR]]''net_type'':[[BR]]
773 92 Luci Stanescu
  The network type contained in the "o" (origin) line of the SDP as a string.
774 92 Luci Stanescu
  [[BR]]''address_type'':[[BR]]
775 92 Luci Stanescu
  The address type contained in the "o" (origin) line of the SDP as a string.
776 99 Adrian Georgescu
  [[BR]]''name'':[[BR]]
777 92 Luci Stanescu
  The contents of the "s" (session name) line of the SDP as a string.
778 92 Luci Stanescu
  [[BR]]''info'':[[BR]]
779 92 Luci Stanescu
  The contents of the session level "i" (information) line of the SDP as a string.
780 99 Adrian Georgescu
  If this is {{{None}}} or an empty string, the SDP has no "i" line.
781 92 Luci Stanescu
  [[BR]]''connection'':[[BR]]
782 92 Luci Stanescu
  The contents of the "c" (connection) line of the SDP as a {{{(Frozen)SDPConnection}}} object.
783 92 Luci Stanescu
  If this is set to {{{None}}}, the SDP has no session level "c" line.
784 99 Adrian Georgescu
  [[BR]]''start_time'':[[BR]]
785 92 Luci Stanescu
  The first value of the "t" (time) line of the SDP as an int.
786 92 Luci Stanescu
  [[BR]]''stop_time'':[[BR]]
787 92 Luci Stanescu
  The second value of the "t" (time) line of the SDP as an int.
788 99 Adrian Georgescu
  [[BR]]''attributes'':[[BR]]
789 92 Luci Stanescu
  The session level "a" lines (attributes) in the SDP represented by a list of {{{(Frozen)SDPAttribute}}} objects.
790 92 Luci Stanescu
  [[BR]]''media'':[[BR]]
791 92 Luci Stanescu
  The media sections of the SDP represented by a list of {{{(Frozen)SDPMediaStream}}} objects.
792 92 Luci Stanescu
793 92 Luci Stanescu
 '''new'''(''cls'', ''sdp_session'')::
794 99 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).
795 92 Luci Stanescu
796 92 Luci Stanescu
==== attributes ====
797 92 Luci Stanescu
798 92 Luci Stanescu
799 92 Luci Stanescu
 '''has_ice_proposal'''::
800 92 Luci Stanescu
  This read-only attribute returns {{{True}}} if the SDP contains any attributes which indicate the existence of an ice proposal and {{{False}}} otherwise.
801 92 Luci Stanescu
802 92 Luci Stanescu
=== SDPMediaStream ===
803 92 Luci Stanescu
804 92 Luci Stanescu
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.
805 92 Luci Stanescu
It is a simple wrapper for the PJSIP [http://www.pjsip.org/pjmedia/docs/html/structpjmedia__sdp__media.htm pjmedia_sdp_media] structure.
806 92 Luci Stanescu
One or more {{{(Frozen)SDPMediaStream}}} objects are usually contained in a {{{(Frozen)SDPSession}}} object.
807 92 Luci Stanescu
It supports comparison to other {{{(Frozen)SDPMedia}}} objects using the == and != expressions.
808 92 Luci Stanescu
As all the attributes of this class are set by attributes of the {{{__init__}}} method, they will be documented along with that method.
809 92 Luci Stanescu
810 92 Luci Stanescu
==== methods ====
811 92 Luci Stanescu
812 92 Luci Stanescu
813 99 Adrian Georgescu
 '''!__init!__'''(''self'', '''media''', '''port''', '''transport''', '''port_count'''=1, '''formats'''={{{None}}}, '''info'''={{{None}}}, '''connection'''={{{None}}}, '''attributes'''={{{None}}})::
814 92 Luci Stanescu
  Creates the SDPMedia object with the specified parameters as attributes.
815 92 Luci Stanescu
  Each of these attributes can be accessed and changed on the object once instanced.
816 92 Luci Stanescu
  [[BR]]''media'':[[BR]]
817 92 Luci Stanescu
  The media type contained in the "m" (media) line as a string.
818 92 Luci Stanescu
  [[BR]]''port'':[[BR]]
819 92 Luci Stanescu
  The transport port contained in the "m" (media) line as an int.
820 92 Luci Stanescu
  [[BR]]''transport'':[[BR]]
821 99 Adrian Georgescu
  The transport protocol in the "m" (media) line as a string.
822 92 Luci Stanescu
  [[BR]]''port_count'':[[BR]]
823 92 Luci Stanescu
  The port count in the "m" (media) line as an int.
824 99 Adrian Georgescu
  If this is set to 1, it is not included in the SDP.
825 92 Luci Stanescu
  [[BR]]''formats'':[[BR]]
826 92 Luci Stanescu
  The media formats in the "m" (media) line represented by a list of strings.
827 92 Luci Stanescu
  [[BR]]''info'':[[BR]]
828 92 Luci Stanescu
  The contents of the "i" (information) line of this media section as a string.
829 92 Luci Stanescu
  If this is {{{None}}} or an empty string, the media section has no "i" line.
830 99 Adrian Georgescu
  [[BR]]''connection'':[[BR]]
831 92 Luci Stanescu
  The contents of the "c" (connection) line that is somewhere below the "m" line of this section as a {{{(Frozen)SDPConnection}}} object.
832 92 Luci Stanescu
  If this is set to {{{None}}}, this media section has no "c" line.
833 92 Luci Stanescu
  [[BR]]''attributes'':[[BR]]
834 99 Adrian Georgescu
  The "a" lines (attributes) that are somewhere below the "m" line of this section represented by a list of {{{(Frozen)SDPAttribute}}} objects.
835 92 Luci Stanescu
836 92 Luci Stanescu
 '''new'''(''cls'', ''sdp_media'')::
837 92 Luci Stanescu
  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).
838 99 Adrian Georgescu
839 92 Luci Stanescu
==== attributes ====
840 92 Luci Stanescu
841 92 Luci Stanescu
842 99 Adrian Georgescu
 '''direction'''::
843 92 Luci Stanescu
  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".
844 92 Luci Stanescu
  If none of these attributes is present, the default direction is "sendrecv".
845 92 Luci Stanescu
846 92 Luci Stanescu
=== SDPConnection ===
847 92 Luci Stanescu
848 92 Luci Stanescu
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.
849 92 Luci Stanescu
It is a simple wrapper for the PJSIP [http://www.pjsip.org/pjmedia/docs/html/structpjmedia__sdp__conn.htm pjmedia_sdp_conn] structure.
850 92 Luci Stanescu
A {{{(Frozen)SDPConnection}}} object can be contained in a {{{(Frozen)SDPSession}}} object or {{{(Frozen)SDPMediaStream}}} object.
851 92 Luci Stanescu
It supports comparison to other {{{(Frozen)SDPConnection}}} objects using the == and != expressions.
852 92 Luci Stanescu
As all the attributes of this class are set by attributes of the {{{__init__}}} method, they will be documented along with that method.
853 92 Luci Stanescu
854 92 Luci Stanescu
==== methods ====
855 92 Luci Stanescu
856 92 Luci Stanescu
857 99 Adrian Georgescu
 '''!__init!__'''(''self'', '''address''', '''net_type'''="IN", '''address_type'''="IP4")::
858 92 Luci Stanescu
  Creates the SDPConnection object with the specified parameters as attributes.
859 92 Luci Stanescu
  Each of these attributes can be accessed and changed on the object once instanced.
860 92 Luci Stanescu
  [[BR]]''address'':[[BR]]
861 92 Luci Stanescu
  The address part of the connection line as a string.
862 99 Adrian Georgescu
  [[BR]]''net_type'':[[BR]]
863 92 Luci Stanescu
  The network type part of the connection line as a string.
864 92 Luci Stanescu
  [[BR]]''address_type'':[[BR]]
865 99 Adrian Georgescu
  The address type part of the connection line as a string.
866 92 Luci Stanescu
867 92 Luci Stanescu
 '''new'''(''cls'', ''sdp_connection'')::
868 99 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).
869 92 Luci Stanescu
870 92 Luci Stanescu
=== SDPAttributeList ===
871 92 Luci Stanescu
872 92 Luci Stanescu
{{{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:
873 92 Luci Stanescu
874 92 Luci Stanescu
875 99 Adrian Georgescu
 '''!__contains!__'''(''self'', ''item'')::
876 92 Luci Stanescu
  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:
877 92 Luci Stanescu
  {{{
878 92 Luci Stanescu
  'ice-pwd' in sdp_session.attributes
879 92 Luci Stanescu
  }}}
880 92 Luci Stanescu
881 92 Luci Stanescu
 '''getall'''(''self'', ''name'')::
882 92 Luci Stanescu
  Returns all the values of the attributes with the given name in a list.
883 99 Adrian Georgescu
884 92 Luci Stanescu
 '''getfirst'''(''self'', ''name'', ''default''={{{None}}})::
885 92 Luci Stanescu
  Return the first value of the attribute with the given name, or ''default'' is no such attribute exists.
886 92 Luci Stanescu
887 99 Adrian Georgescu
=== SDPAttribute ===
888 92 Luci Stanescu
889 92 Luci Stanescu
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.
890 92 Luci Stanescu
It is a simple wrapper for the PJSIP [http://www.pjsip.org/pjmedia/docs/html/structpjmedia__sdp__attr.htm pjmedia_sdp_attr] structure.
891 99 Adrian Georgescu
One or more {{{(Frozen)SDPAttribute}}} objects can be contained in a {{{(Frozen)SDPSession}}} object or {{{(Frozen)SDPMediaStream}}} object.
892 92 Luci Stanescu
It supports comparison to other {{{(Frozen)SDPAttribute}}} objects using the == and != expressions.
893 92 Luci Stanescu
As all the attributes of this class are set by attributes of the {{{__init__}}} method, they will be documented along with that method.
894 92 Luci Stanescu
895 99 Adrian Georgescu
==== methods ====
896 92 Luci Stanescu
897 92 Luci Stanescu
898 99 Adrian Georgescu
 '''!__init!__'''(''self'', '''name''', '''value''')::
899 92 Luci Stanescu
  Creates the SDPAttribute object with the specified parameters as attributes.
900 92 Luci Stanescu
  Each of these attributes can be accessed and changed on the object once instanced.
901 92 Luci Stanescu
  [[BR]]''name'':[[BR]]
902 92 Luci Stanescu
  The name part of the attribute line as a string.
903 92 Luci Stanescu
  [[BR]]''value'':[[BR]]
904 99 Adrian Georgescu
  The value part of the attribute line as a string.
905 92 Luci Stanescu
906 92 Luci Stanescu
 '''new'''(''cls'', ''sdp_attribute'')::
907 92 Luci Stanescu
  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).
908 92 Luci Stanescu
909 92 Luci Stanescu
910 93 Luci Stanescu
=== RTPTransport ===
911 93 Luci Stanescu
912 93 Luci Stanescu
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.
913 93 Luci Stanescu
Internally it wraps a [http://www.pjsip.org/pjmedia/docs/html/group__PJMEDIA__TRANSPORT.htm pjmedia_transport] object.
914 93 Luci Stanescu
Initially this object will only be used by the {{{AudioTransport}}} object, but in the future it can also be used for video and [wiki:RTTProposal Real-Time Text].
915 93 Luci Stanescu
For this reason the {{{AudioTransport}}} and {{{RTPTransport}}} are two distinct objects.
916 93 Luci Stanescu
917 93 Luci Stanescu
The {{{RTPTransport}}} object also allows support for ICE and SRTP functionality from PJSIP.
918 93 Luci Stanescu
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.
919 93 Luci Stanescu
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.
920 93 Luci Stanescu
This process of SDP negotiation is represented by the internal state machine of the object, as shown in the following diagram:
921 93 Luci Stanescu
922 93 Luci Stanescu
> The Real-time Transport Protocol (or RTP) defines a standardized packet format for delivering audio and video over the Internet.
923 93 Luci Stanescu
> It was developed by the Audio-Video Transport Working Group of the IETF and published in [http://tools.ietf.org/html/rfc3550 RFC 3550].
924 93 Luci Stanescu
> RTP is used in streaming media systems (together with the RTSP) as well as in videoconferencing and push to talk systems.
925 93 Luci Stanescu
> 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.
926 93 Luci Stanescu
927 93 Luci Stanescu
[[Image(sipsimple-rtp-transport-state-machine.png, nolink)]]
928 93 Luci Stanescu
929 93 Luci Stanescu
State changes are triggered by the following events:
930 93 Luci Stanescu
 1. The application calls the {{{set_INIT()}}} method after object creation and ICE+STUN is not used.
931 93 Luci Stanescu
 2. The application calls the {{{set_INIT()}}} method after object creation and ICE+STUN is used.
932 93 Luci Stanescu
 3. A successful STUN response is received from the STUN server.
933 93 Luci Stanescu
 4. The {{{set_LOCAL()}}} method is called.
934 93 Luci Stanescu
 5. The {{{set_ESTABLISHED()}}} method is called.
935 93 Luci Stanescu
 6. The {{{set_INIT()}}} method is called while the object is in the {{{LOCAL}}} or {{{ESTABLISHED}}} state.
936 93 Luci Stanescu
 7. A method is called on the application, but in the meantime the {{{Engine}}} has stopped.
937 93 Luci Stanescu
    The object can no longer be used.
938 93 Luci Stanescu
 8. There was an error in getting the STUN candidates from the STUN server.
939 93 Luci Stanescu
940 93 Luci Stanescu
> 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.
941 93 Luci Stanescu
> This means that the RTPTransport object is also unusable once it has reached the STUN_FAILED state.
942 93 Luci Stanescu
> A workaround would be destroy the RTPTransport object and create a new one that uses ICE without STUN.
943 93 Luci Stanescu
944 93 Luci Stanescu
These states allow for two SDP negotiation scenarios to occur, represented by two paths that can be followed through the state machine.
945 93 Luci Stanescu
In this example we will assume that ICE with STUN is not used, as it is independent of the SDP negotiation procedure.
946 93 Luci Stanescu
 * The first scenario is where the local party generates the SDP offer.
947 93 Luci Stanescu
   For a stream that it wishes to include in this SDP offer, it instantiates a {{{RTPTransport}}} object.
948 93 Luci Stanescu
   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.
949 93 Luci Stanescu
   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).
950 93 Luci Stanescu
   Depending on the options used for the {{{RTPTransport}}} instantiation (such as ICE and SRTP), this may change the {{{SDPSession}}} object.
951 93 Luci Stanescu
   This (possibly changed) {{{SDPSession}}} object then needs to be passed to the {{{Invitation}}} object.
952 93 Luci Stanescu
   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.
953 93 Luci Stanescu
   This will not change either of the {{{(Frozen)SDPSession}}} objects (which is why they can also be frozen).
954 93 Luci Stanescu
 * The second scenario is where the local party is offered a media stream in SDP and wants to accept it.
955 93 Luci Stanescu
   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.
956 93 Luci Stanescu
   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.
957 93 Luci Stanescu
   In this case the local SDP object may be changed, after which it can be passed to the {{{Invitation}}} object.
958 93 Luci Stanescu
959 93 Luci Stanescu
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.
960 93 Luci Stanescu
Before doing this however, the internal transport object must no longer be in use.
961 93 Luci Stanescu
962 93 Luci Stanescu
==== methods ====
963 93 Luci Stanescu
964 99 Adrian Georgescu
965 93 Luci Stanescu
 '''!__init!__'''(''self'', '''local_rtp_address'''={{{None}}}, '''use_srtp'''={{{False}}}, '''srtp_forced'''={{{False}}}, '''use_ice'''={{{False}}}, '''ice_stun_address'''={{{None}}}, '''ice_stun_port'''=3478)::
966 93 Luci Stanescu
  Creates a new {{{RTPTransport}}} object and opens the RTP and RTCP UDP sockets.
967 93 Luci Stanescu
  If additional features are requested, they will be initialized.
968 93 Luci Stanescu
  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.
969 93 Luci Stanescu
  [[BR]]''local_rtp_address'':[[BR]]
970 93 Luci Stanescu
  Optionally contains the local IPv4 address to listen on.
971 93 Luci Stanescu
  If this is not specified, PJSIP will listen on all network interfaces.
972 93 Luci Stanescu
  [[BR]]''use_srtp'':[[BR]]
973 93 Luci Stanescu
  A boolean indicating if SRTP should be used.
974 93 Luci Stanescu
  If this is set to {{{True}}}, SRTP information will be added to the SDP when it passes this object.
975 93 Luci Stanescu
  [[BR]]''srtp_forced'':[[BR]]
976 93 Luci Stanescu
  A boolean indicating if use of SRTP is set to mandatory in the SDP.
977 93 Luci Stanescu
  If this is set to {{{True}}} and the remote party does not support SRTP, the SDP negotiation for this stream will fail.
978 93 Luci Stanescu
  This argument is relevant only if {{{use_srtp}}} is set to {{{True}}}.
979 93 Luci Stanescu
  [[BR]]''use_ice'':[[BR]]
980 93 Luci Stanescu
  A boolean indicating if ICE should be used.
981 93 Luci Stanescu
  If this is set to {{{True}}}, ICE candidates will be added to the SDP when it passes this object.
982 93 Luci Stanescu
  [[BR]]''ice_stun_address'':[[BR]]
983 93 Luci Stanescu
  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.
984 93 Luci Stanescu
  If this is set to {{{None}}} no STUN candidate will be added, otherwise the object will be put into the {{{WAIT_STUN}}} state until a reply, either positive or negative, is received from the specified STUN server.
985 93 Luci Stanescu
  When this happens a {{{RTPTransportGotSTUNResponse}}} notification is sent.
986 93 Luci Stanescu
  This argument is relevant only if {{{use_ice}}} is set to {{{True}}}.
987 93 Luci Stanescu
  [[BR]]''ice_stun_address'':[[BR]]
988 93 Luci Stanescu
  An int indicating the UDP port of the STUN server that should be used to add a STUN candidate to the ICE candidates.
989 93 Luci Stanescu
  This argument is relevant only if {{{use_ice}}} is set to {{{True}}} and {{{ice_stun_address}}} is not {{{None}}}.
990 99 Adrian Georgescu
991 93 Luci Stanescu
 '''set_INIT'''(''self'')::
992 93 Luci Stanescu
  This moves the internal state machine into the {{{INIT}}} state.
993 93 Luci Stanescu
  If the state machine is in the {{{LOCAL}}} or {{{ESTABLISHED}}} states, this effectively resets the {{{RTPTransport}}} object for re-use.
994 99 Adrian Georgescu
995 93 Luci Stanescu
 '''set_LOCAL'''(''self'', '''local_sdp''', '''sdp_index''')::
996 93 Luci Stanescu
  This moves the the internal state machine into the {{{LOCAL}}} state.
997 93 Luci Stanescu
  [[BR]]''local_sdp'':[[BR]]
998 93 Luci Stanescu
  The local SDP to be proposed in the form of a {{{SDPSession}}} object.
999 93 Luci Stanescu
  Note that this object may be modified by this method.
1000 93 Luci Stanescu
  [[BR]]''sdp_index'':[[BR]]
1001 93 Luci Stanescu
  The index in the SDP for the media stream for which this object was created.
1002 99 Adrian Georgescu
1003 93 Luci Stanescu
 '''set_ESTABLISHED'''(''self'', '''local_sdp''', '''remote_sdp''', '''sdp_index''')::
1004 93 Luci Stanescu
  This moves the the internal state machine into the {{{ESTABLISHED}}} state.
1005 93 Luci Stanescu
  [[BR]]''local_sdp'':[[BR]]
1006 93 Luci Stanescu
  The local SDP to be proposed in the form of a {{{SDPSession}}} object.
1007 93 Luci Stanescu
  Note that this object may be modified by this method, but only when moving from the {{{LOCAL}}} to the {{{ESTABLISHED}}} state.
1008 93 Luci Stanescu
  [[BR]]''remote_sdp'':[[BR]]
1009 93 Luci Stanescu
  The remote SDP that was received in in the form of a {{{SDPSession}}} object.
1010 93 Luci Stanescu
  [[BR]]''sdp_index'':[[BR]]
1011 93 Luci Stanescu
  The index in the SDP for the media stream for which this object was created.
1012 93 Luci Stanescu
1013 93 Luci Stanescu
==== attributes ====
1014 93 Luci Stanescu
1015 99 Adrian Georgescu
1016 93 Luci Stanescu
 '''state'''::
1017 93 Luci Stanescu
  Indicates which state the internal state machine is in.
1018 93 Luci Stanescu
  See the previous section for a list of states the state machine can be in.
1019 93 Luci Stanescu
  This attribute is read-only.
1020 99 Adrian Georgescu
1021 93 Luci Stanescu
 '''local_rtp_address'''::
1022 93 Luci Stanescu
  The local IPv4 address of the interface the {{{RTPTransport}}} object is listening on and the address that should be included in the SDP.
1023 93 Luci Stanescu
  If no address was specified during object instantiation, PJSIP will take guess out of the IP addresses of all interfaces.
1024 93 Luci Stanescu
  This attribute is read-only and will be {{{None}}} if PJSIP is not listening on the transport.
1025 99 Adrian Georgescu
1026 93 Luci Stanescu
 '''local_rtp_port'''::
1027 93 Luci Stanescu
  The UDP port PJSIP is listening on for RTP traffic.
1028 93 Luci Stanescu
  RTCP traffic will always be this port plus one.
1029 93 Luci Stanescu
  This attribute is read-only and will be {{{None}}} if PJSIP is not listening on the transport.
1030 99 Adrian Georgescu
1031 93 Luci Stanescu
 '''remote_rtp_address_sdp'''::
1032 93 Luci Stanescu
  The remote IP address that was seen in the SDP.
1033 93 Luci Stanescu
  This attribute is read-only and will be {{{None}}} unless the object is in the {{{ESTABLISHED}}} state.
1034 99 Adrian Georgescu
1035 93 Luci Stanescu
 '''remote_rtp_port_sdp'''::
1036 93 Luci Stanescu
  The remote UDP port for RTP that was seen in the SDP.
1037 93 Luci Stanescu
  This attribute is read-only and will be {{{None}}} unless the object is in the {{{ESTABLISHED}}} state.
1038 99 Adrian Georgescu
1039 93 Luci Stanescu
 '''remote_rtp_address_ice'''::
1040 93 Luci Stanescu
  The remote IP address that was selected by the ICE negotation.
1041 93 Luci Stanescu
  This attribute is read-only and will be {{{None}}} until the ICE negotation succeeds.
1042 99 Adrian Georgescu
1043 93 Luci Stanescu
 '''remote_rtp_port_ice'''::
1044 93 Luci Stanescu
  The remote port that was selected by the ICE negotation.
1045 93 Luci Stanescu
  This attribute is read-only and will be {{{None}}} until the ICE negotation succeeds.
1046 99 Adrian Georgescu
1047 93 Luci Stanescu
 '''remote_rtp_address_received'''::
1048 93 Luci Stanescu
  The remote IP address from which RTP data was received.
1049 93 Luci Stanescu
  This attribute is read-only and will be {{{None}}} unless RTP was actually received.
1050 99 Adrian Georgescu
1051 93 Luci Stanescu
 '''remote_rtp_port_received'''::
1052 93 Luci Stanescu
  The remote UDP port from which RTP data was received.
1053 93 Luci Stanescu
  This attribute is read-only and will be {{{None}}} unless RTP was actually received.
1054 99 Adrian Georgescu
1055 93 Luci Stanescu
 '''use_srtp'''::
1056 93 Luci Stanescu
  A boolean indicating if the use of SRTP was requested when the object was instantiated.
1057 93 Luci Stanescu
  This attribute is read-only.
1058 99 Adrian Georgescu
1059 93 Luci Stanescu
 '''force_srtp'''::
1060 93 Luci Stanescu
  A boolean indicating if SRTP being mandatory for this transport if it is enabled was requested when the object was instantiated.
1061 93 Luci Stanescu
  This attribute is read-only.
1062 99 Adrian Georgescu
1063 93 Luci Stanescu
 '''srtp_active'''::
1064 93 Luci Stanescu
  A boolean indicating if SRTP encryption and decryption is running.
1065 93 Luci Stanescu
  Querying this attribute only makes sense once the object is in the {{{ESTABLISHED}}} state and use of SRTP was requested.
1066 93 Luci Stanescu
  This attribute is read-only.
1067 99 Adrian Georgescu
1068 93 Luci Stanescu
 '''use_ice'''::
1069 93 Luci Stanescu
  A boolean indicating if the use of ICE was requested when the object was instantiated.
1070 93 Luci Stanescu
  This attribute is read-only.
1071 99 Adrian Georgescu
1072 93 Luci Stanescu
 '''ice_active''::
1073 93 Luci Stanescu
  A boolean indicating if ICE is being used.
1074 93 Luci Stanescu
  This attribute is read-only.
1075 99 Adrian Georgescu
1076 93 Luci Stanescu
 '''ice_stun_address'''::
1077 93 Luci Stanescu
  A string indicating the IP address of the STUN server that was requested to be used.
1078 93 Luci Stanescu
  This attribute is read-only.
1079 99 Adrian Georgescu
1080 93 Luci Stanescu
 '''ice_stun_port'''::
1081 93 Luci Stanescu
  A string indicating the UDP port of the STUN server that was requested to be used.
1082 93 Luci Stanescu
  This attribute is read-only.
1083 99 Adrian Georgescu
1084 93 Luci Stanescu
 '''local_rtp_candidate_type'''::
1085 93 Luci Stanescu
  Returns the ICE candidate type which has been selected for the local endpoint.
1086 99 Adrian Georgescu
1087 93 Luci Stanescu
 '''remote_rtp_candidate_type'''::
1088 93 Luci Stanescu
  Returns the ICE candidate type which has been selected for the remote endpoint.
1089 93 Luci Stanescu
1090 93 Luci Stanescu
==== notifications ====
1091 93 Luci Stanescu
1092 99 Adrian Georgescu
1093 93 Luci Stanescu
 '''RTPTransportDidInitialize'''::
1094 93 Luci Stanescu
  This notification is sent when a {{{RTPTransport}}} object has successfully initialized.
1095 93 Luci Stanescu
  If STUN+ICE is not requested, this is sent immediately on {{{set_INIT()}}}, otherwise it is sent after the STUN query has succeeded.
1096 93 Luci Stanescu
  [[BR]]''timestamp'':[[BR]]
1097 93 Luci Stanescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1098 99 Adrian Georgescu
1099 93 Luci Stanescu
 '''RTPTransportDidFail'''::
1100 93 Luci Stanescu
  This notification is sent by a {{{RTPTransport}}} object that fails to retrieve ICE candidates from the STUN server after {{{set_INIT()}}} is called.
1101 93 Luci Stanescu
  [[BR]]''timestamp'':[[BR]]
1102 93 Luci Stanescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1103 93 Luci Stanescu
  [[BR]]''reason'':[[BR]]
1104 93 Luci Stanescu
  A string describing the failure reason.
1105 99 Adrian Georgescu
1106 93 Luci Stanescu
 '''RTPTransportICENegotiationStateDidChange'''::
1107 93 Luci Stanescu
  This notification is sent to indicate the progress of the ICE negotiation.
1108 93 Luci Stanescu
  [[BR]]''state'':[[BR]]
1109 93 Luci Stanescu
  A string describing the current ICE negotiation state.
1110 99 Adrian Georgescu
1111 93 Luci Stanescu
 '''RTPTransportICENegotiationDidFail'''::
1112 93 Luci Stanescu
  This notification is sent when the ICE negotiation fails.
1113 93 Luci Stanescu
  [[BR]]''reason'':[[BR]]
1114 93 Luci Stanescu
  A string describing the failure reason of ICE negotation.
1115 99 Adrian Georgescu
1116 93 Luci Stanescu
 '''RTPTransportICENegotiationDidSucceed'''::
1117 93 Luci Stanescu
  This notification is sent when the ICE negotation succeeds.
1118 93 Luci Stanescu
  [[BR]]''chosen_local_candidates'' and ''chosen_remote_candidates'':[[BR]]
1119 93 Luci Stanescu
  Dictionaries with the following keys:
1120 93 Luci Stanescu
   * rtp_cand_type: the type of the RTP candidate
1121 93 Luci Stanescu
   * rtp_cand_ip: the IP address of the RTP candidate
1122 93 Luci Stanescu
   * rtcp_cand_type: the type of the RTCP candidate
1123 93 Luci Stanescu
   * rtcp_cand_ip: the IP address of teh RTCP candidate
1124 93 Luci Stanescu
  [[BR]]''duration'':[[BR]]
1125 93 Luci Stanescu
  The amount of time the ICE negotiation took.
1126 93 Luci Stanescu
  [[BR]]''local_candidates'' and ''remote_candidates'':[[BR]]
1127 93 Luci Stanescu
  Lists of tuples with the following elements:
1128 93 Luci Stanescu
   * Item ID
1129 93 Luci Stanescu
   * Component ID
1130 93 Luci Stanescu
   * Address
1131 93 Luci Stanescu
   * Component Type
1132 93 Luci Stanescu
  [[BR]]''connectivity_checks_results'':[[BR]]
1133 93 Luci Stanescu
  A list of tuples with the following elements:
1134 93 Luci Stanescu
   * Item ID
1135 93 Luci Stanescu
   * Component ID
1136 93 Luci Stanescu
   * Source
1137 93 Luci Stanescu
   * Destination
1138 93 Luci Stanescu
   * Nomination
1139 93 Luci Stanescu
   * State
1140 93 Luci Stanescu
1141 93 Luci Stanescu
=== AudioTransport ===
1142 93 Luci Stanescu
1143 93 Luci Stanescu
This object represent an audio stream as it is transported over the network.
1144 93 Luci Stanescu
It contains an instance of {{{RTPTransport}}} and wraps a [http://www.pjsip.org/pjmedia/docs/html/group__PJMED__STRM.htm pjmedia_stream] object, which in turn manages the RTP encapsulation, RTCP session, audio codec and adaptive jitter buffer.
1145 93 Luci Stanescu
It also generates a {{{SDPMediaStream}}} object to be included in the local SDP.
1146 93 Luci Stanescu
1147 93 Luci Stanescu
The {{{AudioTransport}}} is an object that, once started, is connected to a {{{AudioMixer}}} instance, and both produces and consumes sound.
1148 93 Luci Stanescu
1149 93 Luci Stanescu
Like the {{{RTPTransport}}} object there are two usage scenarios.
1150 93 Luci Stanescu
 * In the first scenario, only the {{{RTPTransport}}} instance to be used is passed to the AudioTransport object.
1151 93 Luci Stanescu
   The application can then generate the {{{SDPMediaStream}}} object by calling the {{{get_local_media()}}} method and should include it in the SDP offer.
1152 93 Luci Stanescu
   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.
1153 93 Luci Stanescu
   The stream can then be connected to the conference bridge.
1154 93 Luci Stanescu
 * 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.
1155 93 Luci Stanescu
   The local {{{SDPMediaStream}}} object can again be generated by calling the {{{get_local_media()}}} method and is to be included in the SDP answer.
1156 93 Luci Stanescu
   The audio stream is started directly when the object is created.
1157 93 Luci Stanescu
1158 93 Luci Stanescu
Unlike the {{{RTPTransport}}} object, this object cannot be reused.
1159 93 Luci Stanescu
1160 93 Luci Stanescu
==== methods ====
1161 93 Luci Stanescu
1162 99 Adrian Georgescu
1163 93 Luci Stanescu
 '''!__init!__'''(''self'', '''mixer''', '''transport''', '''remote_sdp'''={{{None}}}, '''sdp_index'''=0, '''enable_silence_detection'''=True, '''codecs'''={{{None}}})::
1164 93 Luci Stanescu
  Creates a new {{{AudioTransport}}} object and start the underlying stream if the remote SDP is already known.
1165 93 Luci Stanescu
  [[BR]]''mixer'':[[BR]]
1166 93 Luci Stanescu
  The {{{AudioMixer}}} object that this object is to be connected to.
1167 93 Luci Stanescu
  [[BR]]''transport'':[[BR]]
1168 93 Luci Stanescu
  The transport to use in the form of a {{{RTPTransport}}} object.
1169 93 Luci Stanescu
  [[BR]]''remote_sdp'':[[BR]]
1170 93 Luci Stanescu
  The remote SDP that was received in the form of a {{{SDPSession}}} object.
1171 93 Luci Stanescu
  [[BR]]''sdp_index'':[[BR]]
1172 93 Luci Stanescu
  The index within the SDP of the audio stream that should be created.
1173 93 Luci Stanescu
  [[BR]]''enable_silence_detection''[[BR]]
1174 93 Luci Stanescu
  Boolean that indicates if silence detection should be used for this audio stream.
1175 93 Luci Stanescu
  When enabled, this {{{AudioTransport}}} object will stop sending audio to the remote party if the input volume is below a certain threshold.
1176 93 Luci Stanescu
  [[BR]]''codecs''[[BR]]
1177 93 Luci Stanescu
  A list of strings indicating the codecs that should be proposed in the SDP of this {{{AudioTransport}}}, in order of preference.
1178 93 Luci Stanescu
  This overrides the global codecs list set on the {{{Engine}}}.
1179 93 Luci Stanescu
  The values of this list are case insensitive.
1180 99 Adrian Georgescu
1181 93 Luci Stanescu
 '''get_local_media'''(''self'', '''is_offer''', '''direction'''="sendrecv")::
1182 93 Luci Stanescu
  Generates a {{{SDPMediaStream}}} object which describes the audio stream.
1183 93 Luci Stanescu
  This object should be included in a {{{SDPSession}}} object that gets passed to the {{{Invitation}}} object.
1184 93 Luci Stanescu
  This method should also be used to obtain the SDP to include in re-INVITEs and replies to re-INVITEs.
1185 93 Luci Stanescu
  [[BR]]''is_offer'':[[BR]]
1186 93 Luci Stanescu
  A boolean indicating if the SDP requested is to be included in an offer.
1187 93 Luci Stanescu
  If this is {{{False}}} it is to be included in an answer.
1188 93 Luci Stanescu
  [[BR]]''direction'':[[BR]]
1189 93 Luci Stanescu
  The direction attribute to put in the SDP.
1190 99 Adrian Georgescu
1191 93 Luci Stanescu
 '''start'''(''self'', '''local_sdp''', '''remote_sdp''', '''sdp_index''', '''no_media_timeout'''=10, '''media_check_interval'''=30)::
1192 93 Luci Stanescu
  This method should only be called once, when the application has previously sent an SDP offer and the answer has been received.
1193 93 Luci Stanescu
  [[BR]]''local_sdp'':[[BR]]
1194 93 Luci Stanescu
  The full local SDP that was included in the SDP negotiation in the form of a {{{SDPSession}}} object.
1195 93 Luci Stanescu
  [[BR]]''remote_sdp'':[[BR]]
1196 93 Luci Stanescu
  The remote SDP that was received in the form of a {{{SDPSession}}} object.
1197 93 Luci Stanescu
  [[BR]]''sdp_index'':[[BR]]
1198 93 Luci Stanescu
  The index within the SDP of the audio stream.
1199 93 Luci Stanescu
  [[BR]]''no_media_timeout'':[[BR]]
1200 93 Luci Stanescu
  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.
1201 93 Luci Stanescu
  Setting this to 0 disables this an all subsequent RTP checks.
1202 93 Luci Stanescu
  [[BR]]''media_check_interval'':[[BR]]
1203 93 Luci Stanescu
  This indicates the interval at which the RTP stream should be checked, after it has initially received RTP at after {{{no_media_timeout}}} seconds.
1204 93 Luci Stanescu
  It means that if between two of these interval checks no RTP has been received, a {{{RTPAudioTransportDidNotGetRTP}}} notification will be sent.
1205 93 Luci Stanescu
  Setting this to 0 will disable checking the RTP at intervals.
1206 93 Luci Stanescu
  The initial check may still be performed if its timeout is non-zero.
1207 99 Adrian Georgescu
1208 93 Luci Stanescu
 '''stop'''(''self'')::
1209 93 Luci Stanescu
  This method stops and destroys the audio stream encapsulated by this object.
1210 93 Luci Stanescu
  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.
1211 93 Luci Stanescu
  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.
1212 99 Adrian Georgescu
1213 93 Luci Stanescu
 '''send_dtmf'''(''self'', '''digit''')::
1214 93 Luci Stanescu
  For a negotiated audio transport this sends one DTMF digit to the other party
1215 93 Luci Stanescu
  [[BR]]''digit'':[[BR]]
1216 93 Luci Stanescu
  A string of length one indicating the DTMF digit to send.
1217 93 Luci Stanescu
  This can be either a digit, the pound sign (#), the asterisk sign (*) or the letters A through D.
1218 99 Adrian Georgescu
1219 93 Luci Stanescu
 '''update_direction'''(''self'', '''direction''')::
1220 93 Luci Stanescu
  This method should be called after SDP negotiation has completed to update the direction of the media stream.
1221 93 Luci Stanescu
  [[BR]]''direction'':[[BR]]
1222 93 Luci Stanescu
  The direction that has been negotiated.
1223 93 Luci Stanescu
1224 93 Luci Stanescu
==== attributes ====
1225 93 Luci Stanescu
1226 99 Adrian Georgescu
1227 93 Luci Stanescu
 '''mixer'''::
1228 93 Luci Stanescu
  The {{{AudioMixer}}} object that was passed when the object got instantiated.
1229 93 Luci Stanescu
  This attribute is read-only.
1230 99 Adrian Georgescu
1231 93 Luci Stanescu
 '''transport'''::
1232 93 Luci Stanescu
  The {{{RTPTransport}}} object that was passed when the object got instantiated.
1233 93 Luci Stanescu
  This attribute is read-only.
1234 99 Adrian Georgescu
1235 93 Luci Stanescu
 '''slot'''::
1236 93 Luci Stanescu
  A read-only property indicating the slot number at which this object is attached to the associated conference bridge.
1237 93 Luci Stanescu
  If the {{{AudioTransport}}} is not active (i.e. has not been started), this attribute will be {{{None}}}.
1238 99 Adrian Georgescu
1239 93 Luci Stanescu
 '''volume'''::
1240 93 Luci Stanescu
  A writable property indicating the % of volume at which this object contributes audio to the conference bridge.
1241 93 Luci Stanescu
  By default this is set to 100.
1242 99 Adrian Georgescu
1243 93 Luci Stanescu
 '''is_active'''::
1244 93 Luci Stanescu
  A boolean indicating if the object is currently sending and receiving audio.
1245 93 Luci Stanescu
  This attribute is read-only.
1246 99 Adrian Georgescu
1247 93 Luci Stanescu
 '''is_started'''::
1248 93 Luci Stanescu
  A boolean indicating if the object has been started.
1249 93 Luci Stanescu
  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.
1250 93 Luci Stanescu
  This is to prevent the object from being re-used.
1251 93 Luci Stanescu
  This attribute is read-only.
1252 99 Adrian Georgescu
1253 93 Luci Stanescu
 '''codec'''::
1254 93 Luci Stanescu
  Once the SDP negotiation is complete, this attribute indicates the audio codec that was negotiated, otherwise it will be {{{None}}}.
1255 93 Luci Stanescu
  This attribute is read-only.
1256 99 Adrian Georgescu
1257 93 Luci Stanescu
 '''sample_rate'''::
1258 93 Luci Stanescu
  Once the SDP negotiation is complete, this attribute indicates the sample rate of the audio codec that was negotiated, otherwise it will be {{{None}}}.
1259 93 Luci Stanescu
  This attribute is read-only.
1260 99 Adrian Georgescu
1261 93 Luci Stanescu
 '''direction'''::
1262 93 Luci Stanescu
  The current direction of the audio transport, which is one of "sendrecv", "sendonly", "recvonly" or "inactive".
1263 93 Luci Stanescu
  This attribute is read-only, although it can be set using the {{{update_direction()}}} method.
1264 93 Luci Stanescu
1265 93 Luci Stanescu
==== notifications ====
1266 93 Luci Stanescu
1267 99 Adrian Georgescu
1268 93 Luci Stanescu
 '''RTPAudioTransportGotDTMF'''::
1269 93 Luci Stanescu
  This notification will be sent when an incoming DTMF digit is received from the remote party.
1270 93 Luci Stanescu
  [[BR]]''timestamp'':[[BR]]
1271 93 Luci Stanescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1272 93 Luci Stanescu
  [[BR]]''digit'':[[BR]]
1273 93 Luci Stanescu
  The DTMF digit that was received, in the form of a string of length one.
1274 93 Luci Stanescu
  This can be either a number or letters A through D.
1275 99 Adrian Georgescu
1276 93 Luci Stanescu
 '''RTPAudioTransportDidNotGetRTP'''::
1277 93 Luci Stanescu
  This notification will be sent when no RTP packets have been received from the remote party for some time.
1278 93 Luci Stanescu
  See the {{{start()}}} method for a more exact description.
1279 93 Luci Stanescu
  [[BR]]''timestamp'':[[BR]]
1280 93 Luci Stanescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1281 93 Luci Stanescu
  [[BR]]''got_any'':[[BR]]
1282 93 Luci Stanescu
  A boolean data attribute indicating if the {{{AudioTransport}}} every saw any RTP packets from the remote party.
1283 93 Luci Stanescu
  In effect, if no RTP was received after {{{no_media_timeout}}} seconds, its value will be {{{False}}}.
1284 93 Luci Stanescu
1285 46 Ruud Klaver
=== Request ===
1286 46 Ruud Klaver
1287 46 Ruud Klaver
The {{{sipsimple.core.Request}}} object encapsulates a single SIP request transaction from the client side, which includes sending the request, receiving the response and possibly waiting for the result of the request to expire.
1288 94 Luci Stanescu
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).
1289 46 Ruud Klaver
1290 46 Ruud Klaver
The lifetime of this object is linear and is described by the following diagram:
1291 46 Ruud Klaver
1292 46 Ruud Klaver
[[Image(sipsimple-request-lifetime.png, nolink)]]
1293 46 Ruud Klaver
1294 46 Ruud Klaver
The bar denotes which state the object is in and at the top are the notifications which may be emitted at certain points in time.
1295 46 Ruud Klaver
Directly after the object is instantiated, it will be in the {{{INIT}}} state.
1296 46 Ruud Klaver
The request will be sent over the network once its {{{send()}}} method is called, moving the object into the {{{IN_PROGRESS}}} state.
1297 46 Ruud Klaver
On each provisional response that is received in reply to this request, the {{{SIPRequestGotProvisionalResponse}}} notification is sent, with data describing the response.
1298 46 Ruud Klaver
Note that this may not occur at all if not provisional responses are received.
1299 46 Ruud Klaver
When the {{{send()}}} method has been called and it does not return an exception, the object will send either a {{{SIPRequestDidSucceed}}} or a {{{SIPRequestDidFail}}} notification.
1300 46 Ruud Klaver
Both of these notifications include data on the response that triggered it.
1301 46 Ruud Klaver
Note that a SIP response that requests authentication (401 or 407) will be handled internally the first time, if a {{{Credentials}}} object was supplied.
1302 46 Ruud Klaver
If this is the sort of request that expires (detected by a {{{Expires}}} header in the response or a {{{expires}}} parameter in the {{{Contact}}} header of the response), and the request was successful, the object will go into the {{{EXPIRING}}} state.
1303 46 Ruud Klaver
A certain amount of time before the result of the request will expire, governed by the {{{expire_warning_time}}} class attribute and the actual returned expiration time, a {{{SIPRequestWillExpire}}} notification will be sent.
1304 46 Ruud Klaver
This should usually trigger whomever is using this {{{Request}}} object to construct a new {{{Request}}} for a refreshing operation.
1305 49 Ruud Klaver
When the {{{Request}}} actually expires, or when the {{{EXPIRING}}} state is skipped directly after sending {{{SIPRequestDidSucceed}}} or {{{SIPRequestDidFail}}}, a {{{SIPRequestDidEnd}}} notification will be sent.
1306 1 Adrian Georgescu
1307 94 Luci Stanescu
==== methods ====
1308 1 Adrian Georgescu
1309 99 Adrian Georgescu
1310 110 Adrian Georgescu
 '''!__init!__'''(''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}}})::
1311 94 Luci Stanescu
  Creates a new {{{Request}}} object in the {{{INIT}}} state.
1312 94 Luci Stanescu
  The arguments to this method are documented in the attributes section.
1313 99 Adrian Georgescu
1314 94 Luci Stanescu
 '''send'''(''self'', '''timeout'''={{{None}}})::
1315 94 Luci Stanescu
   Compose the SIP request and send it to the destination.
1316 94 Luci Stanescu
   This moves the {{{Request}}} object into the {{{IN_PROGRESS}}} state.
1317 94 Luci Stanescu
  [[BR]]''timeout'':[[BR]]
1318 94 Luci Stanescu
  This can be either an int or a float, indicating in how many seconds the request should timeout with an internally generated 408 response.
1319 94 Luci Stanescu
  This is is {{{None}}}, the internal 408 is only triggered by the internal PJSIP transaction timeout.
1320 94 Luci Stanescu
  Note that, even if the timeout is specified, the PJSIP timeout is also still valid.
1321 99 Adrian Georgescu
1322 94 Luci Stanescu
 '''end'''(''self'')::
1323 94 Luci Stanescu
  Terminate the transaction, whichever state it is in, sending the appropriate notifications.
1324 94 Luci Stanescu
  Note that calling this method while in the {{{INIT}}} state does nothing.
1325 94 Luci Stanescu
1326 47 Ruud Klaver
==== attributes ====
1327 47 Ruud Klaver
1328 99 Adrian Georgescu
1329 62 Ruud Klaver
 '''expire_warning_time''' (class attribute)::
1330 47 Ruud Klaver
  The {{{SIPRequestWillExpire}}} notification will be sent halfway between the positive response and the actual expiration time, but at least this amount of seconds before.
1331 47 Ruud Klaver
  The default value is 30 seconds.
1332 99 Adrian Georgescu
1333 47 Ruud Klaver
 '''state'''::
1334 47 Ruud Klaver
  Indicates the state the {{{Request}}} object is in, in the form of a string.
1335 1 Adrian Georgescu
  Refer to the diagram above for possible states.
1336 1 Adrian Georgescu
  This attribute is read-only.
1337 99 Adrian Georgescu
1338 1 Adrian Georgescu
 '''method'''::
1339 1 Adrian Georgescu
  The method of the SIP request as a string.
1340 1 Adrian Georgescu
  This attribute is set on instantiation and is read-only.
1341 99 Adrian Georgescu
1342 94 Luci Stanescu
 '''from_header'''::
1343 94 Luci Stanescu
  The {{{FrozenFromHeader}}} object to put in the {{{From}}} header of the request.
1344 1 Adrian Georgescu
  This attribute is set on instantiation and is read-only.
1345 99 Adrian Georgescu
1346 94 Luci Stanescu
 '''to_header'''::
1347 94 Luci Stanescu
  The {{{FrozenToHeader}}} object to put in the {{{To}}} header of the request.
1348 1 Adrian Georgescu
  This attribute is set on instantiation and is read-only.
1349 99 Adrian Georgescu
1350 1 Adrian Georgescu
 '''request_uri'''::
1351 94 Luci Stanescu
  The SIP URI to put as request URI in the request, in the form of a {{{FrozenSIPURI}}} object.
1352 62 Ruud Klaver
  This attribute is set on instantiation and is read-only.
1353 99 Adrian Georgescu
1354 94 Luci Stanescu
 '''route_header'''::
1355 94 Luci Stanescu
  Where to send the SIP request to, including IP, port and transport, in the form of a {{{FrozenRouteHeader}}} object.
1356 47 Ruud Klaver
  This will also be included in the {{{Route}}} header of the request.
1357 47 Ruud Klaver
  This attribute is set on instantiation and is read-only.
1358 99 Adrian Georgescu
1359 47 Ruud Klaver
 '''credentials'''::
1360 94 Luci Stanescu
  The credentials to be used when challenged for authentication, represented by a {{{FrozenCredentials}}} object.
1361 47 Ruud Klaver
  If no credentials were supplied when the object was created this attribute is {{{None}}}.
1362 47 Ruud Klaver
  This attribute is set on instantiation and is read-only.
1363 99 Adrian Georgescu
1364 94 Luci Stanescu
 '''contact_header'''::
1365 94 Luci Stanescu
  The {{{FrozenContactHeader}}} object to put in the {{{Contact}}} header of the request.
1366 1 Adrian Georgescu
  If this was not specified, this attribute is {{{None}}}.
1367 1 Adrian Georgescu
  It is set on instantiation and is read-only.
1368 99 Adrian Georgescu
1369 47 Ruud Klaver
 '''call_id'''::
1370 47 Ruud Klaver
  The {{{Call-ID}}} to be used for this transaction as a string.
1371 46 Ruud Klaver
  If no call id was specified on instantiation, this attribute contains the generated id.
1372 46 Ruud Klaver
  This attribute is set on instantiation and is read-only.
1373 99 Adrian Georgescu
1374 62 Ruud Klaver
 '''cseq'''::
1375 48 Ruud Klaver
  The sequence number to use in the request as an int.
1376 48 Ruud Klaver
  If no sequence number was specified on instantiation, this attribute contains the generated sequence number.
1377 48 Ruud Klaver
  Note that this number may be increased by one if an authentication challenge is received and a {{{Credentials}}} object is given.
1378 48 Ruud Klaver
  This attribute is read-only.
1379 99 Adrian Georgescu
1380 48 Ruud Klaver
 '''extra_headers'''::
1381 94 Luci Stanescu
  Extra headers to include in the request as a frozenlist of header objects.
1382 48 Ruud Klaver
  This attribute is set on instantiation and is read-only.
1383 99 Adrian Georgescu
1384 48 Ruud Klaver
 '''content_type'''::
1385 48 Ruud Klaver
  What string to put as content type in the {{{Content-Type}}} headers, if the request contains a body.
1386 57 Ruud Klaver
  If no body was specified, this attribute is {{{None}}}
1387 48 Ruud Klaver
  It is set on instantiation and is read-only.
1388 99 Adrian Georgescu
1389 48 Ruud Klaver
 '''body'''::
1390 48 Ruud Klaver
  The body of the request as a string.
1391 46 Ruud Klaver
  If no body was specified, this attribute is {{{None}}}
1392 49 Ruud Klaver
  It is set on instantiation and is read-only.
1393 99 Adrian Georgescu
1394 49 Ruud Klaver
 '''expires_in'''::
1395 49 Ruud Klaver
  This read-only property indicates in how many seconds from now this {{{Request}}} will expire, if it is in the {{{EXPIRING}}} state.
1396 49 Ruud Klaver
  If this is not the case, this property is 0.
1397 49 Ruud Klaver
1398 109 Adrian Georgescu
 '''peer_address'''::
1399 109 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.
1400 109 Adrian Georgescu
1401 49 Ruud Klaver
==== notifications ====
1402 49 Ruud Klaver
1403 99 Adrian Georgescu
1404 49 Ruud Klaver
 '''SIPRequestGotProvisionalResponse'''::
1405 49 Ruud Klaver
  This notification will be sent on every provisional response received in reply to the sent request.
1406 49 Ruud Klaver
  [[BR]]''timestamp'':[[BR]]
1407 49 Ruud Klaver
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1408 49 Ruud Klaver
  [[BR]]''code'':[[BR]]
1409 49 Ruud Klaver
  The SIP response code of the received provisional response as an int, which will be in the 1xx range.
1410 49 Ruud Klaver
  [[BR]]''reason'':[[BR]]
1411 49 Ruud Klaver
  The reason text string included with the SIP response code.
1412 49 Ruud Klaver
  [[BR]]''headers'':[[BR]]
1413 94 Luci Stanescu
  The headers included in the provisional response as a dict, the values of which are header objects.
1414 49 Ruud Klaver
  [[BR]]''body'':[[BR]]
1415 49 Ruud Klaver
  The body of the provisional response as a string, or {{{None}}} if there was no body.
1416 99 Adrian Georgescu
1417 49 Ruud Klaver
 '''SIPRequestDidSucceed'''::
1418 49 Ruud Klaver
  This notification will be sent when a positive final response was received in reply to the request.
1419 49 Ruud Klaver
  [[BR]]''timestamp'':[[BR]]
1420 49 Ruud Klaver
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1421 49 Ruud Klaver
  [[BR]]''code'':[[BR]]
1422 49 Ruud Klaver
  The SIP response code of the received positive final response as an int, which will be in the 2xx range.
1423 49 Ruud Klaver
  [[BR]]''reason'':[[BR]]
1424 49 Ruud Klaver
  The reason text string included with the SIP response code.
1425 49 Ruud Klaver
  [[BR]]''headers'':[[BR]]
1426 94 Luci Stanescu
  The headers included in the positive final response as a dict, the values of which are header objects.
1427 1 Adrian Georgescu
  [[BR]]''body'':[[BR]]
1428 1 Adrian Georgescu
  The body of the positive final response as a string, or {{{None}}} if there was no body.
1429 1 Adrian Georgescu
  [[BR]]''expires'':[[BR]]
1430 1 Adrian Georgescu
  Indicates in how many seconds the {{{Request}}} will expire as an int.
1431 1 Adrian Georgescu
  If it does not expire and the {{{EXPIRING}}} state is skipped, this attribute is 0.
1432 99 Adrian Georgescu
1433 1 Adrian Georgescu
 '''SIPRequestDidFail'''::
1434 1 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.
1435 1 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
1436 1 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1437 1 Adrian Georgescu
  [[BR]]''code'':[[BR]]
1438 1 Adrian Georgescu
  The SIP response code of the received negative final response as an int.
1439 1 Adrian Georgescu
  This could also be a response code generated by PJSIP internally, or 0 when an internal error occurs.
1440 1 Adrian Georgescu
  [[BR]]''reason'':[[BR]]
1441 1 Adrian Georgescu
  The reason text string included with the SIP response code or error.
1442 1 Adrian Georgescu
  [[BR]]''headers'': (only if a negative final response was received)[[BR]]
1443 94 Luci Stanescu
  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.
1444 1 Adrian Georgescu
  [[BR]]''body'': (only if a negative final response was received)[[BR]]
1445 1 Adrian Georgescu
  The body of the negative final response as a string, or {{{None}}} if there was no body.
1446 1 Adrian Georgescu
  This attribute is absent if no response was received.
1447 99 Adrian Georgescu
1448 1 Adrian Georgescu
 '''SIPRequestWillExpire'''::
1449 1 Adrian Georgescu
  This notification will be sent when a {{{Request}}} in the {{{EXPIRING}}} state will expire soon.
1450 1 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
1451 1 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1452 1 Adrian Georgescu
  [[BR]]''expires'':[[BR]]
1453 1 Adrian Georgescu
  An int indicating in how many seconds from now the {{{Request}}} will actually expire.
1454 99 Adrian Georgescu
1455 1 Adrian Georgescu
 '''SIPRequestDidEnd'''::
1456 1 Adrian Georgescu
  This notification will be sent when a {{{Request}}} object enters the {{{TERMINATED}}} state and can no longer be used.
1457 1 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
1458 1 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1459 1 Adrian Georgescu
1460 94 Luci Stanescu
=== IncomingRequest ===
1461 94 Luci Stanescu
1462 94 Luci Stanescu
This is a relatively simple object that can manage responding to incoming requests in a single transaction.
1463 94 Luci Stanescu
For this reason it does not handle requests that create a dialog.
1464 94 Luci Stanescu
To register methods for which requests should be formed into an {{{IncomingRequest}}} object, the application should set the {{{incoming_requests}}} set attribute on the {{{Engine}}}.
1465 94 Luci Stanescu
Receiving {{{INVITE}}}, {{{SUBSCRIBE}}}, {{{ACK}}} and {{{BYE}}} through this object is not supported.
1466 94 Luci Stanescu
1467 94 Luci Stanescu
The application is notified of an incoming request through the {{{SIPIncomingRequestGotRequest}}} notification.
1468 94 Luci Stanescu
It can answer this request by calling the {{{answer}}} method on the sender of this notification.
1469 94 Luci Stanescu
Note that if the {{{IncomingRequest}}} object gets destroyed before it is answered, a 500 response is automatically sent.
1470 94 Luci Stanescu
1471 94 Luci Stanescu
==== attributes ====
1472 94 Luci Stanescu
1473 99 Adrian Georgescu
1474 94 Luci Stanescu
 '''state'''::
1475 94 Luci Stanescu
  This read-only attribute indicates the state the object is in.
1476 94 Luci Stanescu
  This can be {{{None}}} if the object was created by the application, essentially meaning the object is inert, {{{"incoming"}}} or {{{"answered"}}}.
1477 94 Luci Stanescu
1478 94 Luci Stanescu
==== methods ====
1479 94 Luci Stanescu
1480 99 Adrian Georgescu
1481 94 Luci Stanescu
 '''answer'''(''self'', '''code''', '''reason'''={{{None}}}, '''extra_headers'''={{{None}}})::
1482 94 Luci Stanescu
  Reply to the received request with a final response.
1483 94 Luci Stanescu
  [[BR]]''code'':[[BR]]
1484 94 Luci Stanescu
  The SIP response code to send.
1485 94 Luci Stanescu
  This should be 200 or higher.
1486 94 Luci Stanescu
  [[BR]]''reason'':[[BR]]
1487 94 Luci Stanescu
  The reason text to include in the response.
1488 94 Luci Stanescu
  If this is {{{None}}}, the default text for the given response code is used.
1489 94 Luci Stanescu
  [[BR]]''extra_headers'':[[BR]]
1490 94 Luci Stanescu
  The extra headers to include in the response as an iterable of header objects.
1491 94 Luci Stanescu
1492 94 Luci Stanescu
==== notifications ====
1493 94 Luci Stanescu
1494 99 Adrian Georgescu
1495 94 Luci Stanescu
 '''SIPIncomingRequestGotRequest'''::
1496 94 Luci Stanescu
  This notification will be sent when a new {{{IncomingRequest}}} is created as result of a received request.
1497 94 Luci Stanescu
  The application should listen for this notification, retain a reference to the object that sent it and answer it.
1498 94 Luci Stanescu
  [[BR]]''timestamp'':[[BR]]
1499 94 Luci Stanescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1500 94 Luci Stanescu
  [[BR]]''method'':[[BR]]
1501 94 Luci Stanescu
  The method of the SIP request as a string.
1502 94 Luci Stanescu
  [[BR]]''request_uri'':[[BR]]
1503 94 Luci Stanescu
  The request URI of the request as a {{{FrozenSIPURI}}} object.
1504 94 Luci Stanescu
  [[BR]]''headers'':[[BR]]
1505 94 Luci Stanescu
  The headers of the request as a dict, the values of which are the relevant header objects.
1506 94 Luci Stanescu
  [[BR]]''body'':[[BR]]
1507 94 Luci Stanescu
  The body of the request as a string, or {{{None}}} if no body was included.
1508 99 Adrian Georgescu
1509 94 Luci Stanescu
 '''SIPIncomingRequestSentResponse'''::
1510 94 Luci Stanescu
  This notification is sent when a response to the request is sent by the object.
1511 94 Luci Stanescu
  [[BR]]''timestamp'':[[BR]]
1512 94 Luci Stanescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1513 94 Luci Stanescu
  [[BR]]''code'':[[BR]]
1514 94 Luci Stanescu
  The code of the SIP response as an int.
1515 94 Luci Stanescu
  [[BR]]''reason'':[[BR]]
1516 94 Luci Stanescu
  The reason text of the SIP response as an int.
1517 94 Luci Stanescu
  [[BR]]''headers'':[[BR]]
1518 94 Luci Stanescu
  The headers of the response as a dict, the values of which are the relevant header objects.
1519 94 Luci Stanescu
  [[BR]]''body'':[[BR]]
1520 94 Luci Stanescu
  This will be {{{None}}}.
1521 94 Luci Stanescu
1522 51 Ruud Klaver
=== Message ===
1523 1 Adrian Georgescu
1524 94 Luci Stanescu
The {{{Message}}} class is a simple wrapper for the {{{Request}}} class, with the purpose of sending {{{MESSAGE}}} requests, as described in [http://tools.ietf.org/html/rfc3428 RFC 3428].
1525 51 Ruud Klaver
It is a one-shot object that manages only one {{{Request}}} object.
1526 51 Ruud Klaver
1527 94 Luci Stanescu
==== methods ====
1528 94 Luci Stanescu
1529 99 Adrian Georgescu
1530 94 Luci Stanescu
 '''!__init!__'''(''self'', '''from_header''', '''to_header''', '''route_header''', '''content_type''', '''body''', '''credentials'''={{{None}}}, '''extra_headers'''={{{[]}}})::
1531 94 Luci Stanescu
  Creates a new {{{Message}}} object with the specified arguments.
1532 94 Luci Stanescu
  These arguments are documented in the attributes section for this class.
1533 99 Adrian Georgescu
1534 94 Luci Stanescu
 '''send'''(''self'', '''timeout'''={{{None}}})::
1535 94 Luci Stanescu
  Send the {{{MESSAGE}}} request to the remote party.
1536 94 Luci Stanescu
  [[BR]]''timeout'':[[BR]]
1537 94 Luci Stanescu
  This argument as the same meaning as it does for {{{Request.send()}}}.
1538 99 Adrian Georgescu
1539 94 Luci Stanescu
 '''end'''(''self'')::
1540 94 Luci Stanescu
  Stop trying to send the {{{MESSAGE}}} request.
1541 94 Luci Stanescu
  If it was not sent yet, calling this method does nothing.
1542 94 Luci Stanescu
1543 1 Adrian Georgescu
==== attributes ====
1544 1 Adrian Georgescu
1545 99 Adrian Georgescu
1546 94 Luci Stanescu
 '''from_header'''::
1547 94 Luci Stanescu
  The {{{FrozenFromHeader}}} to put in the {{{From}}} header of the {{{MESSAGE}}} request.
1548 1 Adrian Georgescu
  This attribute is set on instantiation and is read-only.
1549 99 Adrian Georgescu
1550 94 Luci Stanescu
 '''to_header'''::
1551 94 Luci Stanescu
  The {{{FrozenToHeader}}} to put in the {{{To}}} header of the {{{MESSAGE}}} request.
1552 1 Adrian Georgescu
  This attribute is set on instantiation and is read-only.
1553 99 Adrian Georgescu
1554 94 Luci Stanescu
 '''route_header'''::
1555 94 Luci Stanescu
  Where to send the {{{MESSAGE}}} request to, including IP, port and transport, in the form of a {{{FrozenRouteHeader}}} object.
1556 1 Adrian Georgescu
  This will also be included in the {{{Route}}} header of the request.
1557 1 Adrian Georgescu
  This attribute is set on instantiation and is read-only.
1558 99 Adrian Georgescu
1559 1 Adrian Georgescu
 '''content_type'''::
1560 1 Adrian Georgescu
  What string to put as content type in the {{{Content-Type}}} headers.
1561 1 Adrian Georgescu
  It is set on instantiation and is read-only.
1562 99 Adrian Georgescu
1563 1 Adrian Georgescu
 '''body'''::
1564 1 Adrian Georgescu
  The body of the {{{MESSAGE}}} request as a string.
1565 52 Ruud Klaver
  If no body was specified, this attribute is {{{None}}}
1566 52 Ruud Klaver
  It is set on instantiation and is read-only.
1567 99 Adrian Georgescu
1568 52 Ruud Klaver
 '''credentials'''::
1569 94 Luci Stanescu
  The credentials to be used when challenged for authentication, represented by a {{{FrozenCredentials}}} object.
1570 52 Ruud Klaver
  If no credentials were specified, this attribute is {{{None}}}.
1571 52 Ruud Klaver
  This attribute is set on instantiation and is read-only.
1572 99 Adrian Georgescu
1573 1 Adrian Georgescu
 '''is_sent'''::
1574 1 Adrian Georgescu
  A boolean read-only property indicating if the {{{MESSAGE}}} request was sent.
1575 99 Adrian Georgescu
1576 1 Adrian Georgescu
 '''in_progress'''::
1577 52 Ruud Klaver
  A boolean read-only property indicating if the object is waiting for the response from the remote party.
1578 52 Ruud Klaver
1579 109 Adrian Georgescu
 '''peer_address'''::
1580 109 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.
1581 109 Adrian Georgescu
1582 52 Ruud Klaver
==== notifications ====
1583 52 Ruud Klaver
1584 99 Adrian Georgescu
1585 52 Ruud Klaver
 '''SIPMessageDidSucceed'''::
1586 52 Ruud Klaver
  This notification will be sent when the remote party acknowledged the reception of the {{{MESSAGE}}} request.
1587 52 Ruud Klaver
  It has not data attributes.
1588 99 Adrian Georgescu
1589 52 Ruud Klaver
 '''SIPMessageDidFail'''::
1590 52 Ruud Klaver
  This notification will be sent when transmission of the {{{MESSAGE}}} request fails for whatever reason.
1591 52 Ruud Klaver
  [[BR]]''code'':[[BR]]
1592 52 Ruud Klaver
  An int indicating the SIP or internal PJSIP code that was given in response to the {{{MESSAGE}}} request.
1593 1 Adrian Georgescu
  This is 0 if the failure is caused by an internal error.
1594 58 Ruud Klaver
  [[BR]]''reason'':[[BR]]
1595 1 Adrian Georgescu
  A status string describing the failure, either taken from the SIP response or the internal error.
1596 52 Ruud Klaver
1597 52 Ruud Klaver
=== Registration ===
1598 52 Ruud Klaver
1599 94 Luci Stanescu
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.
1600 86 Ruud Klaver
For details, see [http://tools.ietf.org/html/rfc3261 RFC 3261].
1601 1 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.
1602 1 Adrian Georgescu
The application should then perform a DNS lookup to find the relevant SIP registrar and call the {{{register()}}} method on this object.
1603 52 Ruud Klaver
1604 52 Ruud Klaver
==== methods ====
1605 52 Ruud Klaver
1606 99 Adrian Georgescu
1607 94 Luci Stanescu
 '''!__init!__'''(''self'', '''from_header''', '''credentials'''={{{None}}}, '''duration'''=300)::
1608 52 Ruud Klaver
  Creates a new {{{Registration}}} object with the specified arguments.
1609 52 Ruud Klaver
  These arguments are documented in the attributes section for this class.
1610 99 Adrian Georgescu
1611 94 Luci Stanescu
 '''register'''(''self'', '''contact_header''', '''route_header''', '''timeout'''={{{None}}})::
1612 52 Ruud Klaver
  Calling this method will attempt to send a new {{{REGISTER}}} request to the registrar provided, whatever state the object is in.
1613 52 Ruud Klaver
  If the object is currently busy sending a {{{REGISTER}}}, this request will be preempted for the new one.
1614 52 Ruud Klaver
  Once sent, the {{{Registration}}} object will send either a {{{SIPRegistrationDidSucceed}}} or a {{{SIPRegistrationDidFail}}} notification.
1615 94 Luci Stanescu
  The {{{contact_header}}} argument is mentioned in the attributes section of this class.
1616 94 Luci Stanescu
  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()}}}.
1617 99 Adrian Georgescu
1618 1 Adrian Georgescu
 '''end'''(''self'', '''timeout'''={{{None}}})::
1619 1 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.
1620 94 Luci Stanescu
  The {{{RouteHeader}}} used for this will be the same as the last successfully sent {{{REGISTER}}} request.
1621 1 Adrian Georgescu
  If another {{{REGISTER}}} is currently being sent, it will be preempted.
1622 1 Adrian Georgescu
  When the unregistering {{{REGISTER}}} request is sent, a {{{SIPRegistrationWillEnd}}} notification is sent.
1623 1 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.
1624 1 Adrian Georgescu
  Calling this method when the object is not registered will do nothing.
1625 1 Adrian Georgescu
  The {{{timeout}}} argument has the same meaning as for the {{{register()}}} method.
1626 1 Adrian Georgescu
1627 94 Luci Stanescu
==== attributes ====
1628 94 Luci Stanescu
1629 99 Adrian Georgescu
1630 94 Luci Stanescu
 '''from_header''::
1631 94 Luci Stanescu
  The {{{(Frozen)FromHeader}}} the {{{Registration}}} was sent with.
1632 99 Adrian Georgescu
1633 94 Luci Stanescu
 '''credentials'''::
1634 94 Luci Stanescu
  The credentials to be used when challenged for authentication by the registrar, represented by a {{{(Frozen)Credentials}}} object. 
1635 94 Luci Stanescu
  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.
1636 94 Luci Stanescu
  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.
1637 99 Adrian Georgescu
1638 94 Luci Stanescu
 '''duration'''::
1639 94 Luci Stanescu
  The amount of time in seconds to request the registration for at the registrar.
1640 94 Luci Stanescu
  This attribute is set at object instantiation and can be updated for subsequent {{{REGISTER}}} requests.
1641 99 Adrian Georgescu
1642 94 Luci Stanescu
 '''is_registered'''::
1643 94 Luci Stanescu
  A boolean read-only property indicating if this object is currently registered.
1644 99 Adrian Georgescu
1645 94 Luci Stanescu
 '''contact_header'''::
1646 94 Luci Stanescu
  If the {{{Registration}}} object is registered, this attribute contains the latest contact header that was sent to the registrar as a {{{FrozenContactHeader}}} object.
1647 94 Luci Stanescu
  Otherwise, this attribute is {{{None}}}
1648 99 Adrian Georgescu
1649 94 Luci Stanescu
 '''expires_in'''::
1650 94 Luci Stanescu
  If registered, this read-only property indicates in how many seconds from now this {{{Registration}}} will expire.
1651 94 Luci Stanescu
  If this is not the case, this property is 0.
1652 94 Luci Stanescu
1653 109 Adrian Georgescu
 '''peer_address'''::
1654 109 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.
1655 109 Adrian Georgescu
1656 69 Ruud Klaver
==== notifications ====
1657 69 Ruud Klaver
1658 99 Adrian Georgescu
1659 69 Ruud Klaver
 '''SIPRegistrationDidSucceed'''::
1660 69 Ruud Klaver
  This notification will be sent when the {{{register()}}} method was called and the registration succeeded.
1661 69 Ruud Klaver
  [[BR]]''code'':[[BR]]
1662 69 Ruud Klaver
  The SIP response code as received from the registrar as an int.
1663 69 Ruud Klaver
  [[BR]]''reason'':[[BR]]
1664 1 Adrian Georgescu
  The reason string received from the SIP registrar.
1665 94 Luci Stanescu
  [[BR]]''route_header'':[[BR]]
1666 94 Luci Stanescu
  The {{{(Frozen)RouteHeader}}} object passed as an argument to the {{{register()}}} method.
1667 94 Luci Stanescu
  [[BR]]''contact_header'':[[BR]]
1668 94 Luci Stanescu
  The contact header that was sent to the registrar as a {{{FrozenContactHeader}}} object.
1669 94 Luci Stanescu
  [[BR]]''contact_header_list'':[[BR]]
1670 94 Luci Stanescu
  A full list of contact headers that are registered for this SIP account, including the one used for this registration.
1671 94 Luci Stanescu
  The format of this data attribute is a list of FrozenContactHeader objects.
1672 1 Adrian Georgescu
  [[BR]]''expires_in'':[[BR]]
1673 69 Ruud Klaver
  The number of seconds before this registration expires
1674 99 Adrian Georgescu
1675 69 Ruud Klaver
 '''SIPRegistrationDidFail'''::
1676 69 Ruud Klaver
  This notification will be sent when the {{{register()}}} method was called and the registration failed, for whatever reason.
1677 69 Ruud Klaver
  [[BR]]''code'':[[BR]]
1678 69 Ruud Klaver
  The SIP response code as received from the registrar as an int.
1679 69 Ruud Klaver
  This can also be a PJSIP generated response code, or 0 if the failure was because of an internal error.
1680 69 Ruud Klaver
  [[BR]]''reason'':[[BR]]
1681 69 Ruud Klaver
  The reason string received from the SIP registrar or the error string.
1682 94 Luci Stanescu
  [[BR]]''route_header'':[[BR]]
1683 94 Luci Stanescu
  The {{{(Frozen)RouteHeader}}} object passed as an argument to the {{{register()}}} method.
1684 99 Adrian Georgescu
1685 69 Ruud Klaver
 '''SIPRegistrationWillExpire'''::
1686 1 Adrian Georgescu
  This notification will be sent when a registration will expire soon.
1687 69 Ruud Klaver
  It should be used as an indication to re-perform DNS lookup of the registrar and call the {{{register()}}} method.
1688 69 Ruud Klaver
  [[BR]]''expires'':[[BR]]
1689 69 Ruud Klaver
  The number of seconds in which the registration will expire.
1690 99 Adrian Georgescu
1691 69 Ruud Klaver
 '''SIPRegistrationWillEnd'''::
1692 69 Ruud Klaver
  Will be sent whenever the {{{end()}}} method was called and an unregistering {{{REGISTER}}} is sent.
1693 99 Adrian Georgescu
1694 69 Ruud Klaver
 '''SIPRegistrationDidNotEnd'''::
1695 69 Ruud Klaver
  This notification will be sent when the unregistering {{{REGISTER}}} request failed for some reason.
1696 69 Ruud Klaver
  [[BR]]''code'':[[BR]]
1697 69 Ruud Klaver
  The SIP response code as received from the registrar as an int.
1698 69 Ruud Klaver
  This can also be a PJSIP generated response code, or 0 if the failure was because of an internal error.
1699 1 Adrian Georgescu
  [[BR]]''reason'':[[BR]]
1700 1 Adrian Georgescu
  The reason string received from the SIP registrar or the error string.
1701 99 Adrian Georgescu
1702 1 Adrian Georgescu
 '''SIPRegistrationDidEnd'''::
1703 69 Ruud Klaver
  This notification will be sent when a {{{Registration}}} has become unregistered.
1704 69 Ruud Klaver
  [[BR]]''expired'':[[BR]]
1705 69 Ruud Klaver
  This boolean indicates if the object is unregistered because the registration expired, in which case it will be set to {{{True}}}.
1706 69 Ruud Klaver
  If this data attribute is {{{False}}}, it means that unregistration was explicitly requested through the {{{end()}}} method.
1707 69 Ruud Klaver
1708 69 Ruud Klaver
==== example code ====
1709 69 Ruud Klaver
1710 69 Ruud Klaver
For an example on how to use this object, see the Integration section.
1711 69 Ruud Klaver
1712 69 Ruud Klaver
=== Publication ===
1713 69 Ruud Klaver
1714 69 Ruud Klaver
Publication of SIP events is an Internet standard published at [http://tools.ietf.org/html/rfc3903 RFC 3903]. 
1715 69 Ruud Klaver
{{{PUBLISH}}} is similar to {{{REGISTER}}} in that it allows a user to create, modify, and remove state in another entity which manages this state on behalf of the user.
1716 69 Ruud Klaver
1717 69 Ruud Klaver
A {{{Publication}}} object represents publishing some content for a particular SIP account and a particular event type at the SIP presence agent through a series of {{{PUBLISH}}} request.
1718 69 Ruud Klaver
This object is similar in behaviour to the {{{Registration}}} object, as it is also based on a sequence of {{{Request}}} objects.
1719 69 Ruud Klaver
As with this other object, the {{{Publication}}} object will notify the application when a published item is about to expire and it is the applications responsibility to perform a DNS lookup and call the {{{publish()}}} method in order to send the {{{PUBLISH}}} request.
1720 69 Ruud Klaver
1721 69 Ruud Klaver
==== methods ====
1722 69 Ruud Klaver
1723 99 Adrian Georgescu
1724 94 Luci Stanescu
 '''!__init!__'''(''self'', '''from_header''', '''event''', '''content_type''', '''credentials'''={{{None}}}, '''duration'''=300)::
1725 69 Ruud Klaver
  Creates a new {{{Publication}}} object with the specified arguments.
1726 69 Ruud Klaver
  These arguments are documented in the attributes section for this class.
1727 99 Adrian Georgescu
1728 94 Luci Stanescu
 '''publish'''(''self'', '''body''', '''route_header''', '''timeout'''={{{None}}})::
1729 69 Ruud Klaver
  Send an actual {{{PUBLISH}}} request to the specified presence agent.
1730 69 Ruud Klaver
  [[BR]]''body'':[[BR]]
1731 69 Ruud Klaver
  The body to place in the {{{PUBLISH}}} request as a string.
1732 69 Ruud Klaver
  This body needs to be of the content type specified at object creation.
1733 69 Ruud Klaver
  For the initial request, a body will need to be specified.
1734 69 Ruud Klaver
  For subsequent refreshing {{{PUBLISH}}} requests, the body can be {{{None}}} to indicate that the last published body should be refreshed.
1735 69 Ruud Klaver
  If there was an ETag error with the previous refreshing {{{PUBLISH}}}, calling this method with a body of {{{None}}} will throw a {{{PublicationError}}}.
1736 94 Luci Stanescu
  [[BR]]''route_header'':[[BR]]
1737 94 Luci Stanescu
  The host where the request should be sent to in the form of a {{{(Frozen)RouteHeader}}} object.
1738 69 Ruud Klaver
  [[BR]]''timeout'':[[BR]]
1739 69 Ruud Klaver
  This can be either an int or a float, indicating in how many seconds the {{{SUBSCRIBE}}} request should timeout with an internally generated 408 response.
1740 69 Ruud Klaver
  This is is {{{None}}}, the internal 408 is only triggered by the internal PJSIP transaction timeout.
1741 69 Ruud Klaver
  Note that, even if the timeout is specified, the PJSIP timeout is also still valid.
1742 99 Adrian Georgescu
1743 69 Ruud Klaver
 '''end'''(''self'', '''timeout'''={{{None}}})::
1744 1 Adrian Georgescu
  End the publication by sending a {{{PUBLISH}}} request with an {{{Expires}}} header of 0.
1745 86 Ruud Klaver
  If the object is not published, this will result in a {{{PublicationError}}} being thrown.
1746 86 Ruud Klaver
  [[BR]]''timeout'':[[BR]]
1747 86 Ruud Klaver
  The meaning of this argument is the same as it is for the {{{publish()}}} method.
1748 86 Ruud Klaver
1749 94 Luci Stanescu
==== attributes ====
1750 94 Luci Stanescu
1751 99 Adrian Georgescu
1752 94 Luci Stanescu
 '''from_header''::
1753 94 Luci Stanescu
  The {{{(Frozen)FromHeader}}} the {{{Publication}}} was sent with.
1754 99 Adrian Georgescu
1755 94 Luci Stanescu
 '''event''::
1756 94 Luci Stanescu
  The name of the event this object is publishing for the specified SIP URI, as a string.
1757 99 Adrian Georgescu
1758 94 Luci Stanescu
 '''content_type''::
1759 94 Luci Stanescu
  The {{{Content-Type}}} of the body that will be in the {{{PUBLISH}}} requests.
1760 94 Luci Stanescu
  Typically this will remain the same throughout the publication session, but the attribute may be updated by the application if needed.
1761 94 Luci Stanescu
  Note that this attribute needs to be in the typical MIME type form, containing a "/" character.
1762 99 Adrian Georgescu
1763 94 Luci Stanescu
 '''credentials'''::
1764 94 Luci Stanescu
  The credentials to be used when challenged for authentication by the presence agent, represented by a {{{(Frozen)Credentials}}} object. 
1765 94 Luci Stanescu
  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.
1766 94 Luci Stanescu
  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.
1767 99 Adrian Georgescu
1768 94 Luci Stanescu
 '''duration'''::
1769 94 Luci Stanescu
  The amount of time in seconds that the publication should be valid for.
1770 94 Luci Stanescu
  This attribute is set at object instantiation and can be updated for subsequent {{{PUBLISH}}} requests.
1771 99 Adrian Georgescu
1772 94 Luci Stanescu
 '''is_published'''::
1773 94 Luci Stanescu
  A boolean read-only property indicating if this object is currently published.
1774 99 Adrian Georgescu
1775 94 Luci Stanescu
 '''expires_in'''::
1776 94 Luci Stanescu
  If published, this read-only property indicates in how many seconds from now this {{{Publication}}} will expire.
1777 94 Luci Stanescu
  If this is not the case, this property is 0.
1778 94 Luci Stanescu
1779 109 Adrian Georgescu
 '''peer_address'''::
1780 109 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.
1781 109 Adrian Georgescu
1782 86 Ruud Klaver
==== notifications ====
1783 86 Ruud Klaver
1784 99 Adrian Georgescu
1785 86 Ruud Klaver
 '''SIPPublicationDidSucceed'''::
1786 86 Ruud Klaver
  This notification will be sent when the {{{publish()}}} method was called and the publication succeeded.
1787 86 Ruud Klaver
  [[BR]]''code'':[[BR]]
1788 86 Ruud Klaver
  The SIP response code as received from the SIP presence agent as an int.
1789 86 Ruud Klaver
  [[BR]]''reason'':[[BR]]
1790 86 Ruud Klaver
  The reason string received from the SIP presence agent.
1791 94 Luci Stanescu
  [[BR]]''route_header'':[[BR]]
1792 94 Luci Stanescu
  The {{{(Frozen)RouteHeader}}} object passed as an argument to the {{{publish()}}} method.
1793 86 Ruud Klaver
  [[BR]]''expires_in'':[[BR]]
1794 86 Ruud Klaver
  The number of seconds before this publication expires
1795 99 Adrian Georgescu
1796 86 Ruud Klaver
 '''SIPPublicationDidFail'''::
1797 86 Ruud Klaver
  This notification will be sent when the {{{publish()}}} method was called and the publication failed, for whatever reason.
1798 86 Ruud Klaver
  [[BR]]''code'':[[BR]]
1799 86 Ruud Klaver
  The SIP response code as received from the presence agent as an int.
1800 86 Ruud Klaver
  This can also be a PJSIP generated response code, or 0 if the failure was because of an internal error.
1801 86 Ruud Klaver
  [[BR]]''reason'':[[BR]]
1802 86 Ruud Klaver
  The reason string received from the presence agent or the error string.
1803 94 Luci Stanescu
  [[BR]]''route_header'':[[BR]]
1804 94 Luci Stanescu
  The {{{(Frozen)RouteHeader}}} object passed as an argument to the {{{publish()}}} method.
1805 99 Adrian Georgescu
1806 86 Ruud Klaver
 '''SIPPublicationWillExpire'''::
1807 86 Ruud Klaver
  This notification will be sent when a publication will expire soon.
1808 86 Ruud Klaver
  It should be used as an indication to re-perform DNS lookup of the presence agent and call the {{{publish()}}} method.
1809 86 Ruud Klaver
  [[BR]]''expires'':[[BR]]
1810 86 Ruud Klaver
  The number of seconds in which the publication will expire.
1811 99 Adrian Georgescu
1812 86 Ruud Klaver
 '''SIPPublicationWillEnd'''::
1813 86 Ruud Klaver
  Will be sent whenever the {{{end()}}} method was called and an unpublishing {{{PUBLISH}}} is sent.
1814 99 Adrian Georgescu
1815 86 Ruud Klaver
 '''SIPPublicationDidNotEnd'''::
1816 86 Ruud Klaver
  This notification will be sent when the unpublishing {{{PUBLISH}}} request failed for some reason.
1817 86 Ruud Klaver
  [[BR]]''code'':[[BR]]
1818 1 Adrian Georgescu
  The SIP response code as received from the presence agent as an int.
1819 1 Adrian Georgescu
  This can also be a PJSIP generated response code, or 0 if the failure was because of an internal error.
1820 1 Adrian Georgescu
  [[BR]]''reason'':[[BR]]
1821 1 Adrian Georgescu
  The reason string received from the presence agent or the error string.
1822 99 Adrian Georgescu
1823 59 Ruud Klaver
 '''SIPPublicationDidEnd'''::
1824 1 Adrian Georgescu
  This notification will be sent when a {{{Publication}}} has become unpublished.
1825 1 Adrian Georgescu
  [[BR]]''expired'':[[BR]]
1826 1 Adrian Georgescu
  This boolean indicates if the object is unpublished because the publication expired, in which case it will be set to {{{True}}}.
1827 1 Adrian Georgescu
  If this data attribute is {{{False}}}, it means that unpublication was explicitly requested through the {{{end()}}} method.
1828 1 Adrian Georgescu
1829 59 Ruud Klaver
=== Subscription ===
1830 59 Ruud Klaver
1831 1 Adrian Georgescu
Subscription and notifications for SIP events is an Internet standard published at [http://tools.ietf.org/html/rfc3856 RFC 3856].
1832 1 Adrian Georgescu
1833 1 Adrian Georgescu
This SIP primitive class represents a subscription to a specific event type of a particular SIP URI.
1834 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.
1835 1 Adrian Georgescu
The event type and the content types that are acceptable for it need to be registered first, either through the {{{init_options}}} attribute of {{{Engine}}} (before starting it), or by calling the {{{add_event()}}} method of the {{{Engine}}} instance.
1836 1 Adrian Georgescu
Whenever a {{{NOTIFY}}} is received, the application will receive the {{{SIPSubscriptionGotNotify}}} event.
1837 59 Ruud Klaver
1838 59 Ruud Klaver
Internally a {{{Subscription}}} object has a state machine, which reflects the state of the subscription.
1839 1 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}}}.
1840 1 Adrian Georgescu
The last three states are directly copied from the contents of the {{{Subscription-State}}} header of the received {{{NOTIFY}}} request.
1841 71 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.
1842 1 Adrian Georgescu
The state of the object is presented in the {{{state}}} attribute and changes of the state are indicated by means of the {{{SIPSubscriptionChangedState}}} notification.
1843 59 Ruud Klaver
This notification is only informational, an application using this object should take actions based on the other notifications sent by this object.
1844 1 Adrian Georgescu
1845 1 Adrian Georgescu
==== methods ====
1846 1 Adrian Georgescu
1847 99 Adrian Georgescu
1848 110 Adrian Georgescu
 '''!__init!__'''(''self'', '''request_uri''', '''from_header''', '''to_header''', '''contact_header, '''event''', '''route_header''', '''credentials'''={{{None}}}, '''refresh'''=300)::
1849 1 Adrian Georgescu
  Creates a new {{{Subscription}}} object which will be in the {{{NULL}}} state.
1850 1 Adrian Georgescu
  The arguments for this method are documented in the attributes section above.
1851 99 Adrian Georgescu
1852 1 Adrian Georgescu
 '''subscribe'''(''self'', '''extra_headers'''={{{None}}}, '''content_type'''={{{None}}}, '''body'''={{{None}}}, '''timeout'''={{{None}}})::
1853 1 Adrian Georgescu
  Calling this method triggers sending a {{{SUBSCRIBE}}} request to the presence agent.
1854 1 Adrian Georgescu
  The arguments passed will be stored and used for subsequent refreshing {{{SUBSCRIBE}}} requests.
1855 1 Adrian Georgescu
  This method may be used both to send the initial request and to update the arguments while the subscription is ongoing.
1856 1 Adrian Georgescu
  It may not be called when the object is in the {{{TERMINATED}}} state.
1857 1 Adrian Georgescu
  [[BR]]''extra_headers'':[[BR]]
1858 1 Adrian Georgescu
  A dictionary of additional headers to include in the {{{SUBSCRIBE}}} requests.
1859 1 Adrian Georgescu
  [[BR]]''content_type'':[[BR]]
1860 1 Adrian Georgescu
  The {{{Content-Type}}} of the supplied {{{body}}} argument as a string.
1861 1 Adrian Georgescu
  If this argument is supplied, the {{{body}}} argument cannot be {{{None}}}.
1862 1 Adrian Georgescu
  [[BR]]''body'':[[BR]]
1863 1 Adrian Georgescu
  The optional body to include in the {{{SUBSCRIBE}}} request as a string.
1864 1 Adrian Georgescu
  If this argument is supplied, the {{{content_type}}} argument cannot be {{{None}}}.
1865 1 Adrian Georgescu
  [[BR]]''timeout'':[[BR]]
1866 1 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.
1867 1 Adrian Georgescu
  If this is {{{None}}}, the internal 408 is only triggered by the internal PJSIP transaction timeout.
1868 1 Adrian Georgescu
  Note that, even if the timeout is specified, the PJSIP timeout is also still valid.
1869 99 Adrian Georgescu
1870 1 Adrian Georgescu
 '''end'''(''self'', '''timeout'''={{{None}}})::
1871 1 Adrian Georgescu
  This will end the subscription by sending a {{{SUBSCRIBE}}} request with an {{{Expires}}} value of 0.
1872 1 Adrian Georgescu
  If this object is no longer subscribed, this method will return without performing any action.
1873 1 Adrian Georgescu
  This method cannot be called when the object is in the {{{NULL}}} state.
1874 1 Adrian Georgescu
  The {{{timeout}}} argument has the same meaning as it does for the {{{subscribe()}}} method.
1875 59 Ruud Klaver
1876 95 Luci Stanescu
==== attributes ====
1877 95 Luci Stanescu
1878 99 Adrian Georgescu
1879 95 Luci Stanescu
 '''state'''::
1880 95 Luci Stanescu
  Indicates which state the internal state machine is in.
1881 95 Luci Stanescu
  See the previous section for a list of states the state machine can be in.
1882 99 Adrian Georgescu
1883 95 Luci Stanescu
 '''from_header'''::
1884 1 Adrian Georgescu
  The {{{FrozenFromHeader}}} to be put in the {{{From}}} header of the {{{SUBSCRIBE}}} requests.
1885 95 Luci Stanescu
  This attribute is set on object instantiation and is read-only.
1886 1 Adrian Georgescu
1887 1 Adrian Georgescu
 '''to_header'''::
1888 1 Adrian Georgescu
  The {{{FrozenToHeader}}} that is the target for the subscription.
1889 1 Adrian Georgescu
  This attribute is set on object instantiation and is read-only.
1890 1 Adrian Georgescu
1891 95 Luci Stanescu
 '''contact_header'''::
1892 1 Adrian Georgescu
  The {{{FrozenContactHeader}}} to be put in the {{{Contact}}} header of the {{{SUBSCRIBE}}} requests.
1893 99 Adrian Georgescu
  This attribute is set on object instantiation and is read-only.
1894 95 Luci Stanescu
1895 1 Adrian Georgescu
 '''event'''::
1896 1 Adrian Georgescu
  The event package for which the subscription is as a string.
1897 1 Adrian Georgescu
  This attribute is set on object instantiation and is read-only.
1898 1 Adrian Georgescu
1899 1 Adrian Georgescu
 '''route_header'''::
1900 1 Adrian Georgescu
  The outbound proxy to use in the form of a {{{FrozenRouteHeader}}} object.
1901 1 Adrian Georgescu
  This attribute is set on object instantiation and is read-only.
1902 1 Adrian Georgescu
1903 1 Adrian Georgescu
 '''credentials'''::
1904 1 Adrian Georgescu
  The SIP credentials needed to authenticate at the SIP proxy in the form of a {{{FrozenCredentials}}} object.
1905 1 Adrian Georgescu
  If none was specified when creating the {{{Subscription}}} object, this attribute is {{{None}}}.
1906 1 Adrian Georgescu
  This attribute is set on object instantiation and is read-only.
1907 1 Adrian Georgescu
1908 1 Adrian Georgescu
 '''refresh'''::
1909 1 Adrian Georgescu
  The refresh interval in seconds that was requested on object instantiation as an int.
1910 1 Adrian Georgescu
  This attribute is set on object instantiation and is read-only.
1911 1 Adrian Georgescu
1912 1 Adrian Georgescu
 '''extra_headers'''::
1913 1 Adrian Georgescu
  This contains the {{{frozenlist}}} of extra headers that was last passed to a successful call to the {{{subscribe()}}} method.
1914 1 Adrian Georgescu
  If the argument was not provided, this attribute is an empty list.
1915 1 Adrian Georgescu
  This attribute is read-only.
1916 95 Luci Stanescu
1917 1 Adrian Georgescu
 '''content_type'''::
1918 1 Adrian Georgescu
  This attribute contains the {{{Content-Type}}} of the body that was last passed to a successful call to the {{{subscribe()}}} method.
1919 1 Adrian Georgescu
  If the argument was not provided, this attribute is {{{None}}}.
1920 95 Luci Stanescu
1921 1 Adrian Georgescu
 '''body'''::
1922 1 Adrian Georgescu
  This attribute contains the {{{body}}} string argument that was last passed to a successful call to the {{{subscribe()}}} method.
1923 99 Adrian Georgescu
  If the argument was not provided, this attribute is {{{None}}}.
1924 1 Adrian Georgescu
1925 109 Adrian Georgescu
 '''peer_address'''::
1926 109 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.
1927 109 Adrian Georgescu
1928 1 Adrian Georgescu
==== notifications ====
1929 1 Adrian Georgescu
1930 1 Adrian Georgescu
1931 95 Luci Stanescu
 '''SIPSubscriptionChangedState'''::
1932 95 Luci Stanescu
  This notification will be sent every time the internal state machine of a {{{Subscription}}} object changes state.
1933 95 Luci Stanescu
  [[BR]]''timestamp'':[[BR]]
1934 1 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1935 1 Adrian Georgescu
  [[BR]]''prev_state'':[[BR]]
1936 1 Adrian Georgescu
  The previous state that the sate machine was in.
1937 1 Adrian Georgescu
  [[BR]]''state'':[[BR]]
1938 99 Adrian Georgescu
  The new state the state machine moved into.
1939 1 Adrian Georgescu
1940 1 Adrian Georgescu
 '''SIPSubscriptionWillStart'''::
1941 1 Adrian Georgescu
  This notification will be emitted when the initial {{{SUBSCRIBE}}} request is sent.
1942 1 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
1943 95 Luci Stanescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1944 1 Adrian Georgescu
1945 1 Adrian Georgescu
 '''SIPSubscriptionDidStart'''::
1946 1 Adrian Georgescu
  This notification will be sent when the initial {{{SUBSCRIBE}}} was accepted by the presence agent.
1947 95 Luci Stanescu
  [[BR]]''timestamp'':[[BR]]
1948 1 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1949 1 Adrian Georgescu
1950 1 Adrian Georgescu
 '''SIPSubscriptionGotNotify'''::
1951 1 Adrian Georgescu
  This notification will be sent when a {{{NOTIFY}}} is received that corresponds to a particular {{{Subscription}}} object.
1952 95 Luci Stanescu
  Note that this notification could be sent when a {{{NOTIFY}}} without a body is received.
1953 1 Adrian Georgescu
  [[BR]]''request_uri'':[[BR]]
1954 1 Adrian Georgescu
  The request URI of the {{{NOTIFY}}} request as a {{{SIPURI}}} object.
1955 107 Adrian Georgescu
  [[BR]]''from_header'':[[BR]]
1956 107 Adrian Georgescu
  The From header of the {{{NOTIFY}}} request as a {{{FrozenFromHeader}}} object.
1957 107 Adrian Georgescu
  [[BR]]''to_header'':[[BR]]
1958 107 Adrian Georgescu
  The To header of the {{{NOTIFY}}} request as a {{{FrozenToHeader}}} object.
1959 107 Adrian Georgescu
  [[BR]]''content_type'':[[BR]]
1960 107 Adrian Georgescu
  The Content-Type header value of the {{{NOTIFY}}} request as a {{{ContentType}}} object.
1961 107 Adrian Georgescu
  [[BR]]''event'':[[BR]]
1962 107 Adrian Georgescu
  The Event header value of the {{{NOTIFY}}} request as a string object.
1963 1 Adrian Georgescu
  [[BR]]''headers'':[[BR]]
1964 1 Adrian Georgescu
  The headers of the {{{NOTIFY}}} request as a dict.
1965 1 Adrian Georgescu
  Each SIP header is represented in its parsed for as long as PJSIP supports it.
1966 1 Adrian Georgescu
  The format of the parsed value depends on the header.
1967 1 Adrian Georgescu
  [[BR]]''body'':[[BR]]
1968 1 Adrian Georgescu
  The body of the {{{NOTIFY}}} request as a string, or {{{None}}} if no body was included.
1969 107 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
1970 107 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.  
1971 95 Luci Stanescu
1972 1 Adrian Georgescu
 '''SIPSubscriptionDidFail'''::
1973 95 Luci Stanescu
  This notification will be sent whenever there is a failure, such as a rejected initial or refreshing {{{SUBSCRIBE}}}.
1974 1 Adrian Georgescu
  After this notification the {{{Subscription}}} object is in the {{{TERMINATED}}} state and can no longer be used.
1975 95 Luci Stanescu
  [[BR]]''timestamp'':[[BR]]
1976 99 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1977 1 Adrian Georgescu
  [[BR]]''code'':[[BR]]
1978 1 Adrian Georgescu
  An integer SIP code from the fatal response that was received from the remote party of generated by PJSIP.
1979 1 Adrian Georgescu
  If the error is internal to the SIP core, this attribute will have a value of 0.
1980 1 Adrian Georgescu
  [[BR]]''reason'':[[BR]]
1981 95 Luci Stanescu
  An text string describing the failure that occurred.
1982 106 Adrian Georgescu
  [[BR]]''min_expires'':[[BR]]
1983 106 Adrian Georgescu
  An integer containing the value from the Min-Expires header. Will be None if the response doesn't contain the header.
1984 1 Adrian Georgescu
1985 59 Ruud Klaver
 '''SIPSubscriptionDidEnd'''::
1986 1 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.
1987 1 Adrian Georgescu
  After this notification the {{{Subscription}}} object is in the {{{TERMINATED}}} state and can no longer be used.
1988 1 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
1989 1 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1990 1 Adrian Georgescu
1991 1 Adrian Georgescu
=== IncomingSubscription ===
1992 1 Adrian Georgescu
1993 1 Adrian Georgescu
Subscription and notifications for SIP events is an Internet standard published at [http://tools.ietf.org/html/rfc3856 RFC 3856].
1994 1 Adrian Georgescu
1995 1 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.
1996 1 Adrian Georgescu
This means that it can accept a {{{SUBSCRIBE}}} request and subsequent refreshing {{{SUBSCRIBE}}}s and sent {{{NOTIFY}}} requests containing event state.
1997 1 Adrian Georgescu
1998 1 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.
1999 1 Adrian Georgescu
This event needs to be known by the {{{Engine}}}, i.e. it should already be present in the {{{events}}} dictionary attribute.
2000 1 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.
2001 1 Adrian Georgescu
This will be indicated to the application through a {{{SIPIncomingSubscriptionGotSubscribe}}} notification.
2002 1 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.
2003 1 Adrian Georgescu
2004 1 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.
2005 1 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.
2006 1 Adrian Georgescu
Whenever a refreshing {{{SUBSCRIBE}}} is received, the latest contents to be set are sent in the resulting {{{NOTIFY}}} request.
2007 1 Adrian Georgescu
The subscription can be ended by using the {{{end()}}} method.
2008 1 Adrian Georgescu
2009 1 Adrian Georgescu
==== methods ====
2010 1 Adrian Georgescu
2011 1 Adrian Georgescu
2012 99 Adrian Georgescu
 '''!__init!__'''(''self'')::
2013 59 Ruud Klaver
  An application should never create an {{{IncomingSubscription}}} object itself.
2014 59 Ruud Klaver
  Doing this will create a useless object in the {{{None}}} state.
2015 59 Ruud Klaver
2016 59 Ruud Klaver
 '''reject'''(''self'', '''code''')::
2017 99 Adrian Georgescu
  Will reply to the initial {{{SUBSCRIBE}}} with a negative response.
2018 59 Ruud Klaver
  This method can only be called in the {{{"incoming"}}} state and sets the subscription to the {{{"terminated"}}} state.
2019 59 Ruud Klaver
  [[BR]]''code'':[[BR]]
2020 59 Ruud Klaver
  The SIP response code to use.
2021 59 Ruud Klaver
  This should be a negative response, i.e. in the 3xx, 4xx, 5xx or 6xx range.
2022 99 Adrian Georgescu
2023 59 Ruud Klaver
 '''accept_pending'''(''self'')::
2024 1 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.
2025 59 Ruud Klaver
  The application can later decide to fully accept the subscription or terminate it.
2026 59 Ruud Klaver
  This method can only be called in the {{{"incoming"}}} state.
2027 59 Ruud Klaver
2028 59 Ruud Klaver
 '''accept'''(''self'', '''content_type'''={{{None}}}, '''content'''={{{None}}})::
2029 59 Ruud Klaver
  Accept the initial incoming {{{SUBSCRIBE}}} and respond to it with a 200 OK, or fully accept an {{{IncomingSubscription}}} that is in the {{{"pending"}}} state.
2030 59 Ruud Klaver
  In either case, a {{{NOTIFY}}} will be sent to update the state to "active", optionally with the content specified in the arguments.
2031 59 Ruud Klaver
  This method can only be called in the {{{"incoming"}}} or {{{"pending"}}} state.
2032 59 Ruud Klaver
  [[BR]]''content_type'':[[BR]]
2033 59 Ruud Klaver
  The Content-Type of the content to be set supplied as a string containing a {{{"/"}}} character.
2034 59 Ruud Klaver
  Note that if this argument is set, the {{{content}}} argument should also be set.
2035 84 Ruud Klaver
  [[BR]]''content'':[[BR]]
2036 84 Ruud Klaver
  The body of the {{{NOTIFY}}} to send when accepting the subscription, as a string.
2037 84 Ruud Klaver
  Note that if this argument is set, the {{{content_type}}} argument should also be set.
2038 84 Ruud Klaver
2039 84 Ruud Klaver
 '''push_content'''(''self'', '''content_type''', '''content''')::
2040 99 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.
2041 84 Ruud Klaver
  This method can only be called in the {{{"active"}}} state.
2042 84 Ruud Klaver
  [[BR]]''content_type'':[[BR]]
2043 84 Ruud Klaver
  The Content-Type of the content to be set supplied as a string containing a {{{"/"}}} character.
2044 84 Ruud Klaver
  [[BR]]''content'':[[BR]]
2045 84 Ruud Klaver
  The body of the {{{NOTIFY}}} as a string.
2046 84 Ruud Klaver
2047 84 Ruud Klaver
==== attributes ====
2048 84 Ruud Klaver
2049 84 Ruud Klaver
2050 84 Ruud Klaver
 '''state'''::
2051 99 Adrian Georgescu
  Indicates which state the incoming subscription session is in.
2052 84 Ruud Klaver
  This can be one of {{{None}}}, {{{"incoming"}}}, {{{"pending"}}}, {{{"active"}}} or {{{"terminated"}}}.
2053 84 Ruud Klaver
  This attribute is read-only.
2054 1 Adrian Georgescu
2055 1 Adrian Georgescu
 '''event'''::
2056 1 Adrian Georgescu
  The name of the event package that this {{{IncomingSubscription}}} relates to.
2057 1 Adrian Georgescu
  This attribute is a read-only string.
2058 1 Adrian Georgescu
2059 1 Adrian Georgescu
 '''content_type'''::
2060 1 Adrian Georgescu
  The {{{Content-Type}}} of the last set content in this subscription session.
2061 1 Adrian Georgescu
  Inititally this will be {{{None}}}.
2062 1 Adrian Georgescu
  This attribute is a read-only string.
2063 1 Adrian Georgescu
2064 1 Adrian Georgescu
 '''content'''::
2065 1 Adrian Georgescu
  The last set content in this subscription session as a read-only string.
2066 109 Adrian Georgescu
2067 109 Adrian Georgescu
 '''peer_address'''::
2068 109 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 1 Adrian Georgescu
2070 1 Adrian Georgescu
==== notifications ====
2071 1 Adrian Georgescu
2072 1 Adrian Georgescu
2073 84 Ruud Klaver
 '''SIPIncomingSubscriptionChangedState'''::
2074 84 Ruud Klaver
  This notification will be sent every time the an {{{IncomingSubscription}}} object changes state.
2075 84 Ruud Klaver
  This notification is mostly indicative, an application should not let its logic depend on it.
2076 84 Ruud Klaver
  [[BR]]''timestamp'':[[BR]]
2077 84 Ruud Klaver
  A {{{datetime.datetime}}} object indicating when the notification was sent.
2078 84 Ruud Klaver
  [[BR]]''prev_state'':[[BR]]
2079 84 Ruud Klaver
  The previous state that the subscription was in.
2080 84 Ruud Klaver
  [[BR]]''state'':[[BR]]
2081 99 Adrian Georgescu
  The new state the subscription has.
2082 84 Ruud Klaver
2083 84 Ruud Klaver
 '''SIPIncomingSubscriptionGotSubscribe'''::
2084 84 Ruud Klaver
  This notification will be sent when a new {{{IncomingSubscription}}} is created as result of an incoming {{{SUBSCRIBE}}} request.
2085 99 Adrian Georgescu
  The application should listen for this notification, retain a reference to the object that sent it and either accept or reject it.
2086 84 Ruud Klaver
  [[BR]]''timestamp'':[[BR]]
2087 84 Ruud Klaver
  A {{{datetime.datetime}}} object indicating when the notification was sent.
2088 84 Ruud Klaver
  [[BR]]''method'':[[BR]]
2089 84 Ruud Klaver
  The method of the SIP request as a string, which will be {{{SUBSCRIBE}}}.
2090 84 Ruud Klaver
  [[BR]]''request_uri'':[[BR]]
2091 84 Ruud Klaver
  The request URI of the {{{SUBSCRIBE}}} request as a {{{FrozenSIPURI}}} object.
2092 99 Adrian Georgescu
  [[BR]]''headers'':[[BR]]
2093 84 Ruud Klaver
  The headers of the {{{SUBSCRIBE}}} request as a dict, the values of which are the relevant header objects.
2094 84 Ruud Klaver
  [[BR]]''body'':[[BR]]
2095 84 Ruud Klaver
  The body of the {{{SUBSCRIBE}}} request as a string, or {{{None}}} if no body was included.
2096 84 Ruud Klaver
2097 99 Adrian Georgescu
 '''SIPIncomingSubscriptionGotRefreshingSubscribe'''::
2098 84 Ruud Klaver
  This notification indicates that a refreshing {{{SUBSCRIBE}}} request was received from the subscriber.
2099 84 Ruud Klaver
  It is purely informative, no action needs to be taken by the application as a result of it.
2100 84 Ruud Klaver
  [[BR]]''timestamp'':[[BR]]
2101 84 Ruud Klaver
  A {{{datetime.datetime}}} object indicating when the notification was sent.
2102 84 Ruud Klaver
  [[BR]]''method'':[[BR]]
2103 84 Ruud Klaver
  The method of the SIP request as a string, which will be {{{SUBSCRIBE}}}.
2104 84 Ruud Klaver
  [[BR]]''request_uri'':[[BR]]
2105 84 Ruud Klaver
  The request URI of the {{{SUBSCRIBE}}} request as a {{{FrozenSIPURI}}} object.
2106 84 Ruud Klaver
  [[BR]]''headers'':[[BR]]
2107 84 Ruud Klaver
  The headers of the {{{SUBSCRIBE}}} request as a dict, the values of which are the relevant header objects.
2108 99 Adrian Georgescu
  [[BR]]''body'':[[BR]]
2109 84 Ruud Klaver
  The body of the {{{SUBSCRIBE}}} request as a string, or {{{None}}} if no body was included.
2110 84 Ruud Klaver
2111 84 Ruud Klaver
 '''SIPIncomingSubscriptionGotUnsubscribe'''::
2112 84 Ruud Klaver
  This notification indicates that a {{{SUBSCRIBE}}} request with an {{{Expires}}} header of 0 was received from the subscriber, effectively requesting to unsubscribe.
2113 84 Ruud Klaver
  It is purely informative, no action needs to be taken by the application as a result of it.
2114 84 Ruud Klaver
  [[BR]]''timestamp'':[[BR]]
2115 84 Ruud Klaver
  A {{{datetime.datetime}}} object indicating when the notification was sent.
2116 84 Ruud Klaver
  [[BR]]''method'':[[BR]]
2117 95 Luci Stanescu
  The method of the SIP request as a string, which will be {{{SUBSCRIBE}}}.
2118 95 Luci Stanescu
  [[BR]]''request_uri'':[[BR]]
2119 99 Adrian Georgescu
  The request URI of the {{{SUBSCRIBE}}} request as a {{{FrozenSIPURI}}} object.
2120 95 Luci Stanescu
  [[BR]]''headers'':[[BR]]
2121 95 Luci Stanescu
  The headers of the {{{SUBSCRIBE}}} request as a dict, the values of which are the relevant header objects.
2122 95 Luci Stanescu
  [[BR]]''body'':[[BR]]
2123 95 Luci Stanescu
  The body of the {{{SUBSCRIBE}}} request or response as a string, or {{{None}}} if no body was included.
2124 99 Adrian Georgescu
2125 95 Luci Stanescu
 '''SIPIncomingSubscriptionAnsweredSubscribe'''::
2126 95 Luci Stanescu
  This notification is sent whenever a response to a {{{SUBSCRIBE}}} request is sent by the object, including an unsubscribing {{{SUBSCRIBE}}}.
2127 95 Luci Stanescu
  It is purely informative, no action needs to be taken by the application as a result of it.
2128 99 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
2129 95 Luci Stanescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
2130 95 Luci Stanescu
  [[BR]]''code'':[[BR]]
2131 95 Luci Stanescu
  The code of the SIP response as an int.
2132 95 Luci Stanescu
  [[BR]]''reason'':[[BR]]
2133 99 Adrian Georgescu
  The reason text of the SIP response as an int.
2134 95 Luci Stanescu
  [[BR]]''headers'':[[BR]]
2135 95 Luci Stanescu
  The headers of the response as a dict, the values of which are the relevant header objects.
2136 95 Luci Stanescu
  [[BR]]''body'':[[BR]]
2137 1 Adrian Georgescu
  This will be {{{None}}}.
2138 1 Adrian Georgescu
2139 99 Adrian Georgescu
 '''SIPIncomingSubscriptionSentNotify'''::
2140 1 Adrian Georgescu
  This notification indicates that a {{{NOTIFY}}} request was sent to the subscriber.
2141 1 Adrian Georgescu
  It is purely informative, no action needs to be taken by the application as a result of it.
2142 1 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
2143 1 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
2144 1 Adrian Georgescu
  [[BR]]''method'':[[BR]]
2145 1 Adrian Georgescu
  The method of the SIP request as a string, which will be {{{NOTIFY}}}.
2146 1 Adrian Georgescu
  [[BR]]''request_uri'':[[BR]]
2147 1 Adrian Georgescu
  The request URI of the {{{NOTIFY}}} request as a {{{FrozenSIPURI}}} object.
2148 1 Adrian Georgescu
  [[BR]]''headers'':[[BR]]
2149 99 Adrian Georgescu
  The headers of the {{{NOTIFY}}} request as a dict, the values of which are the relevant header objects.
2150 1 Adrian Georgescu
  [[BR]]''body'':[[BR]]
2151 1 Adrian Georgescu
  The body of the {{{NOTIFY}}} request or response as a string, or {{{None}}} if no body was included.
2152 1 Adrian Georgescu
2153 1 Adrian Georgescu
 '''SIPIncomingSubscriptionNotifyDidSucceed'''::
2154 1 Adrian Georgescu
  This indicates that a positive final response was received from the subscriber in reply to a sent {{{NOTIFY}}} request.
2155 18 Adrian Georgescu
  The notification is purely informative, no action needs to be taken by the application as a result of it.
2156 1 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
2157 1 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
2158 17 Ruud Klaver
  [[BR]]''code'':[[BR]]
2159 17 Ruud Klaver
  The code of the SIP response as an int.
2160 17 Ruud Klaver
  [[BR]]''reason'':[[BR]]
2161 17 Ruud Klaver
  The reason text of the SIP response as a string.
2162 17 Ruud Klaver
  [[BR]]''headers'':[[BR]]
2163 99 Adrian Georgescu
  The headers of the response as a dict, the values of which are the relevant header objects.
2164 17 Ruud Klaver
  [[BR]]''body'':[[BR]]
2165 17 Ruud Klaver
  This will be {{{None}}}.
2166 17 Ruud Klaver
2167 17 Ruud Klaver
 '''SIPIncomingSubscriptionNotifyDidFail'''::
2168 1 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.
2169 1 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
2170 1 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
2171 1 Adrian Georgescu
  [[BR]]''code'':[[BR]]
2172 1 Adrian Georgescu
  The code of the SIP response as an int.
2173 1 Adrian Georgescu
  If this is 0, the notification was sent as a result of an internal error.
2174 1 Adrian Georgescu
  [[BR]]''reason'':[[BR]]
2175 1 Adrian Georgescu
  The reason text of the SIP response as a string or the internal error if the code attribute is 0.
2176 1 Adrian Georgescu
  [[BR]]''headers'': (if the notification was caused by a negative response)[[BR]]
2177 99 Adrian Georgescu
  The headers of the response as a dict, the values of which are the relevant header objects.
2178 17 Ruud Klaver
  [[BR]]''body'': (if the notification was caused by a negative response)[[BR]]
2179 1 Adrian Georgescu
  This will be {{{None}}}.
2180 1 Adrian Georgescu
2181 1 Adrian Georgescu
 '''SIPIncomingSubscriptionNotifyDidEnd'''::
2182 1 Adrian Georgescu
  This notification is sent whenever the {{{IncomingSubscription}}} object reaches the {{{"terminated"}}} state and is no longer valid.
2183 1 Adrian Georgescu
  After receiving this notification, the application should not longer try to use the object.
2184 1 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
2185 17 Ruud Klaver
  A {{{datetime.datetime}}} object indicating when the notification was sent.
2186 1 Adrian Georgescu
2187 112 Adrian Georgescu
=== Referral ===
2188 112 Adrian Georgescu
2189 112 Adrian Georgescu
Subscription and notifications for SIP events is an Internet standard published at [http://tools.ietf.org/html/rfc3856 RFC 3856].
2190 112 Adrian Georgescu
The REFER method, defined in [http://tools.ietf.org/html/rfc3515 RFC 3515] uses the subscription mechanism to to tell SIP endpoints to refer to specific resources.
2191 112 Adrian Georgescu
2192 112 Adrian Georgescu
This SIP primitive class represents a referral requested by the client to a target URI.
2193 112 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.
2194 112 Adrian Georgescu
Whenever a {{{NOTIFY}}} is received, the application will receive the {{{SIPReferralGotNotify}}} notification.
2195 112 Adrian Georgescu
2196 112 Adrian Georgescu
Not creating an implicit subscription is supporte as per [http://tools.ietf.org/html/rfc4488 RFC 4488]
2197 112 Adrian Georgescu
2198 112 Adrian Georgescu
Internally a {{{Referral}}} object has a state machine, which reflects the state of the subscription. (The same as the {{{Subsciption}}} since it uses the same event framework)
2199 112 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}}}.
2200 112 Adrian Georgescu
The last three states are directly copied from the contents of the {{{Subscription-State}}} header of the received {{{NOTIFY}}} request.
2201 112 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.
2202 112 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.
2203 112 Adrian Georgescu
This notification is only informational, an application using this object should take actions based on the other notifications sent by this object.
2204 112 Adrian Georgescu
2205 112 Adrian Georgescu
==== methods ====
2206 112 Adrian Georgescu
2207 112 Adrian Georgescu
2208 112 Adrian Georgescu
 '''!__init!__'''(''self'', '''request_uri''', '''from_header''', '''to_header''', '''refer_to_header, '''contact_header''', '''route_header''', '''credentials'''={{{None}}})::
2209 112 Adrian Georgescu
  Creates a new {{{Referral}}} object which will be in the {{{NULL}}} state.
2210 112 Adrian Georgescu
  The arguments for this method are documented in the attributes section above.
2211 112 Adrian Georgescu
2212 112 Adrian Georgescu
 '''send_refer'''(''self'', '''create_subscription'''={{{1}}}, '''extra_headers'''={{{list()}}}, '''timeout'''={{{None}}})::
2213 112 Adrian Georgescu
  Calling this method triggers sending a {{{REFER}}} request to the presence agent.
2214 112 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.
2215 112 Adrian Georgescu
  It may not be called when the object is in the {{{TERMINATED}}} state.
2216 112 Adrian Georgescu
  [[BR]]''create_subscription'':[[BR]]
2217 112 Adrian Georgescu
  Boolean flag indicating if an implicit subscription should be created.
2218 112 Adrian Georgescu
  [[BR]]''extra_headers'':[[BR]]
2219 112 Adrian Georgescu
  A list of additional headers to include in the {{{REFER}}} requests.
2220 112 Adrian Georgescu
  [[BR]]''timeout'':[[BR]]
2221 112 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.
2222 112 Adrian Georgescu
  If this is {{{None}}}, the internal 408 is only triggered by the internal PJSIP transaction timeout.
2223 112 Adrian Georgescu
  Note that, even if the timeout is specified, the PJSIP timeout is also still valid.
2224 112 Adrian Georgescu
2225 112 Adrian Georgescu
 '''refresh'''(''self'', '''contact_header'''={{{None}}}, '''extra_headers'''={{{list()}}}, '''timeout'''={{{None}}})::
2226 112 Adrian Georgescu
  [[BR]]''contact_header'':[[BR]]
2227 112 Adrian Georgescu
  An optional {{{ContactHeader}}} object which will replace the local contact header and will be used from this moment on.
2228 112 Adrian Georgescu
  [[BR]]''extra_headers'':[[BR]]
2229 112 Adrian Georgescu
  A list of additional headers to include in the refreshing {{{SUBSCRIBE}}} request.
2230 112 Adrian Georgescu
  [[BR]]''timeout'':[[BR]]
2231 112 Adrian Georgescu
  The {{{timeout}}} argument has the same meaning as it does for the {{{send_refer()}}} method.
2232 112 Adrian Georgescu
2233 112 Adrian Georgescu
 '''end'''(''self'', '''timeout'''={{{None}}})::
2234 112 Adrian Georgescu
  This will end the referral subscription by sending a {{{SUBSCRIBE}}} request with an {{{Expires}}} value of 0.
2235 112 Adrian Georgescu
  If this object is no longer subscribed, this method will return without performing any action.
2236 112 Adrian Georgescu
  This method cannot be called when the object is in the {{{NULL}}} state.
2237 112 Adrian Georgescu
  The {{{timeout}}} argument has the same meaning as it does for the {{{send_refer()}}} method.
2238 112 Adrian Georgescu
2239 112 Adrian Georgescu
==== attributes ====
2240 112 Adrian Georgescu
2241 112 Adrian Georgescu
2242 112 Adrian Georgescu
 '''state'''::
2243 112 Adrian Georgescu
  Indicates which state the internal state machine is in.
2244 112 Adrian Georgescu
  See the previous section for a list of states the state machine can be in.
2245 112 Adrian Georgescu
2246 112 Adrian Georgescu
 '''from_header'''::
2247 112 Adrian Georgescu
  The {{{FrozenFromHeader}}} to be put in the {{{From}}} header of the {{{REFER}}} and {{{SUBSCRIBE}}} requests.
2248 112 Adrian Georgescu
  This attribute is set on object instantiation and is read-only.
2249 112 Adrian Georgescu
2250 112 Adrian Georgescu
 '''to_header'''::
2251 112 Adrian Georgescu
  The {{{FrozenToHeader}}} that is the target for the referral.
2252 112 Adrian Georgescu
  This attribute is set on object instantiation and is read-only.
2253 112 Adrian Georgescu
2254 112 Adrian Georgescu
 '''refer_to_header'''::
2255 112 Adrian Georgescu
  The {{{FrozenReferToHeader}}} that is the target resource for the referral.
2256 112 Adrian Georgescu
  This attribute is set on object instantiation and is read-only.
2257 112 Adrian Georgescu
2258 112 Adrian Georgescu
 '''local_contact_header'''::
2259 112 Adrian Georgescu
  The {{{FrozenContactHeader}}} to be put in the {{{Contact}}} header of the {{{REFER}}} and {{{SUBSCRIBE}}} requests.
2260 112 Adrian Georgescu
  This attribute is set on object instantiation and is read-only.
2261 112 Adrian Georgescu
2262 112 Adrian Georgescu
 '''remote_contact_header'''::
2263 112 Adrian Georgescu
 The {{{FrozenContactHeader}}} received from the remote endpoint. This attribute is read-only.
2264 112 Adrian Georgescu
2265 112 Adrian Georgescu
 '''route_header'''::
2266 112 Adrian Georgescu
  The outbound proxy to use in the form of a {{{FrozenRouteHeader}}} object.
2267 112 Adrian Georgescu
  This attribute is set on object instantiation and is read-only.
2268 112 Adrian Georgescu
2269 112 Adrian Georgescu
 '''credentials'''::
2270 112 Adrian Georgescu
  The SIP credentials needed to authenticate at the SIP proxy in the form of a {{{FrozenCredentials}}} object.
2271 112 Adrian Georgescu
  If none was specified when creating the {{{Referral}}} object, this attribute is {{{None}}}.
2272 112 Adrian Georgescu
  This attribute is set on object instantiation and is read-only.
2273 112 Adrian Georgescu
2274 112 Adrian Georgescu
 '''refresh'''::
2275 112 Adrian Georgescu
  The refresh interval in seconds that was requested on object instantiation as an int.
2276 112 Adrian Georgescu
  This attribute is set when a {{{NOTIFY}}} request is received and is read-only.
2277 112 Adrian Georgescu
2278 112 Adrian Georgescu
 '''extra_headers'''::
2279 112 Adrian Georgescu
  This contains the {{{frozenlist}}} of extra headers that was last passed to a successful call to the {{{subscribe()}}} method.
2280 112 Adrian Georgescu
  If the argument was not provided, this attribute is an empty list.
2281 112 Adrian Georgescu
  This attribute is read-only.
2282 112 Adrian Georgescu
2283 112 Adrian Georgescu
 '''peer_address'''::
2284 112 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.
2285 112 Adrian Georgescu
2286 112 Adrian Georgescu
==== notifications ====
2287 112 Adrian Georgescu
2288 112 Adrian Georgescu
2289 112 Adrian Georgescu
 '''SIPReferralChangedState'''::
2290 112 Adrian Georgescu
  This notification will be sent every time the internal state machine of a {{{Referral}}} object changes state.
2291 112 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
2292 112 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
2293 112 Adrian Georgescu
  [[BR]]''prev_state'':[[BR]]
2294 112 Adrian Georgescu
  The previous state that the sate machine was in.
2295 112 Adrian Georgescu
  [[BR]]''state'':[[BR]]
2296 112 Adrian Georgescu
  The new state the state machine moved into.
2297 112 Adrian Georgescu
2298 112 Adrian Georgescu
 '''SIPReferralWillStart'''::
2299 112 Adrian Georgescu
  This notification will be emitted when the initial {{{REFER}}} request is sent.
2300 112 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
2301 112 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
2302 112 Adrian Georgescu
2303 112 Adrian Georgescu
 '''SIPReferralDidStart'''::
2304 112 Adrian Georgescu
  This notification will be sent when the initial {{{REFER}}} was accepted by the remote endpoint.
2305 112 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
2306 112 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
2307 112 Adrian Georgescu
2308 112 Adrian Georgescu
 '''SIPReferralGotNotify'''::
2309 112 Adrian Georgescu
  This notification will be sent when a {{{NOTIFY}}} is received that corresponds to a particular {{{Referral}}} object.
2310 112 Adrian Georgescu
  Note that this notification could be sent when a {{{NOTIFY}}} without a body is received.
2311 112 Adrian Georgescu
  [[BR]]''request_uri'':[[BR]]
2312 112 Adrian Georgescu
  The request URI of the {{{NOTIFY}}} request as a {{{SIPURI}}} object.
2313 112 Adrian Georgescu
  [[BR]]''from_header'':[[BR]]
2314 112 Adrian Georgescu
  The From header of the {{{NOTIFY}}} request as a {{{FrozenFromHeader}}} object.
2315 112 Adrian Georgescu
  [[BR]]''to_header'':[[BR]]
2316 112 Adrian Georgescu
  The To header of the {{{NOTIFY}}} request as a {{{FrozenToHeader}}} object.
2317 112 Adrian Georgescu
  [[BR]]''content_type'':[[BR]]
2318 112 Adrian Georgescu
  The Content-Type header value of the {{{NOTIFY}}} request as a {{{ContentType}}} object.
2319 112 Adrian Georgescu
  [[BR]]''event'':[[BR]]
2320 112 Adrian Georgescu
  The Event header value of the {{{NOTIFY}}} request as a string object.
2321 112 Adrian Georgescu
  [[BR]]''headers'':[[BR]]
2322 112 Adrian Georgescu
  The headers of the {{{NOTIFY}}} request as a dict.
2323 112 Adrian Georgescu
  Each SIP header is represented in its parsed for as long as PJSIP supports it.
2324 112 Adrian Georgescu
  The format of the parsed value depends on the header.
2325 112 Adrian Georgescu
  [[BR]]''body'':[[BR]]
2326 112 Adrian Georgescu
  The body of the {{{NOTIFY}}} request as a string, or {{{None}}} if no body was included.
2327 112 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
2328 112 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.  
2329 112 Adrian Georgescu
2330 112 Adrian Georgescu
 '''SIPReferralDidFail'''::
2331 112 Adrian Georgescu
  This notification will be sent whenever there is a failure, such as a rejected initial {{{REFER}}} or refreshing {{{SUBSCRIBE}}}.
2332 112 Adrian Georgescu
  After this notification the {{{Referral}}} object is in the {{{TERMINATED}}} state and can no longer be used.
2333 112 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
2334 112 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
2335 112 Adrian Georgescu
  [[BR]]''code'':[[BR]]
2336 112 Adrian Georgescu
  An integer SIP code from the fatal response that was received from the remote party of generated by PJSIP.
2337 112 Adrian Georgescu
  If the error is internal to the SIP core, this attribute will have a value of 0.
2338 112 Adrian Georgescu
  [[BR]]''reason'':[[BR]]
2339 112 Adrian Georgescu
  An text string describing the failure that occurred.
2340 112 Adrian Georgescu
2341 112 Adrian Georgescu
 '''SIPReferralDidEnd'''::
2342 112 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.
2343 112 Adrian Georgescu
  After this notification the {{{Referral}}} object is in the {{{TERMINATED}}} state and can no longer be used.
2344 112 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
2345 112 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
2346 112 Adrian Georgescu
2347 113 Adrian Georgescu
=== IncomingReferral ===
2348 113 Adrian Georgescu
2349 113 Adrian Georgescu
Subscription and notifications for SIP events is an Internet standard published at [http://tools.ietf.org/html/rfc3856 RFC 3856].
2350 113 Adrian Georgescu
The REFER method, defined in [http://tools.ietf.org/html/rfc3515 RFC 3515] uses the subscription mechanism to to tell SIP endpoints to refer to specific resources.
2351 113 Adrian Georgescu
2352 113 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.
2353 113 Adrian Georgescu
This means that it can accept a {{{REFER}}} request and subsequent refreshing {{{SUBSCRIBE}}}s and sent {{{NOTIFY}}} requests containing event state.
2354 113 Adrian Georgescu
2355 113 Adrian Georgescu
Any incoming {{{REFER}}} request causes the creation of a {{{IncomingReferral}}} object.
2356 113 Adrian Georgescu
This will be indicated to the application through a {{{SIPIncomingReferralGotRefer}}} notification.
2357 113 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.
2358 113 Adrian Georgescu
2359 113 Adrian Georgescu
The application can either reject the referral by calling the {{{reject()}}} method or accept it through the {{{accept()}}} method.
2360 113 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.
2361 113 Adrian Georgescu
Whenever a refreshing {{{SUBSCRIBE}}} is received, the latest contents to be set are sent in the resulting {{{NOTIFY}}} request.
2362 113 Adrian Georgescu
The subscription can be ended by using the {{{end()}}} method.
2363 113 Adrian Georgescu
2364 113 Adrian Georgescu
==== methods ====
2365 113 Adrian Georgescu
2366 113 Adrian Georgescu
2367 113 Adrian Georgescu
 '''!__init!__'''(''self'')::
2368 113 Adrian Georgescu
  An application should never create an {{{IncomingSubscription}}} object itself.
2369 113 Adrian Georgescu
  Doing this will create a useless object in the {{{None}}} state.
2370 113 Adrian Georgescu
2371 113 Adrian Georgescu
 '''reject'''(''self'', '''code''')::
2372 113 Adrian Georgescu
  Will reply to the initial {{{REFER}}} with a negative response.
2373 113 Adrian Georgescu
  This method can only be called in the {{{"incoming"}}} state and sets the referral to the {{{"terminated"}}} state.
2374 113 Adrian Georgescu
  [[BR]]''code'':[[BR]]
2375 113 Adrian Georgescu
  The SIP response code to use.
2376 113 Adrian Georgescu
  This should be a negative response, i.e. in the 3xx, 4xx, 5xx or 6xx range.
2377 113 Adrian Georgescu
2378 113 Adrian Georgescu
 '''accept'''(''self'', '''code'''={{{202}}}, '''duration'''={{{180}}})::
2379 113 Adrian Georgescu
  Accept the initial incoming {{{REFER}}} and respond to it with a 202 Accepted.
2380 113 Adrian Georgescu
  A {{{NOTIFY}}} will be sent to update the state to "active", with a payload indicating the referral is in 100 Trying state.
2381 113 Adrian Georgescu
  This method can only be called in the {{{"incoming"}}} state.
2382 113 Adrian Georgescu
  [[BR]]''code'':[[BR]]
2383 113 Adrian Georgescu
  The code to be  used for the initial reply.
2384 113 Adrian Georgescu
  [[BR]]''duration'':[[BR]]
2385 113 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.
2386 113 Adrian Georgescu
2387 113 Adrian Georgescu
 '''send_notify'''(''self'', '''code''', '''status'''={{{None}}})::
2388 113 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.
2389 113 Adrian Georgescu
  This method can only be called in the {{{"active"}}} state.
2390 113 Adrian Georgescu
  [[BR]]''code'':[[BR]]
2391 113 Adrian Georgescu
  The response code to be used to generate the sipfrag payload.
2392 113 Adrian Georgescu
  [[BR]]''status'':[[BR]]
2393 113 Adrian Georgescu
  Optional status reason to be used to build the sipfrag payload. If none was specified the standard reason string will be used.
2394 113 Adrian Georgescu
2395 113 Adrian Georgescu
==== attributes ====
2396 113 Adrian Georgescu
2397 113 Adrian Georgescu
2398 113 Adrian Georgescu
 '''state'''::
2399 113 Adrian Georgescu
  Indicates which state the incoming referral dialog is in.
2400 113 Adrian Georgescu
  This can be one of {{{None}}}, {{{"incoming"}}}, {{{"pending"}}}, {{{"active"}}} or {{{"terminated"}}}.
2401 113 Adrian Georgescu
  This attribute is read-only.
2402 113 Adrian Georgescu
2403 113 Adrian Georgescu
 '''local_contact_header'''::
2404 113 Adrian Georgescu
  The {{{FrozenContactHeader}}} to be put in the {{{Contact}}} header of the {{{REFER}}} and {{{SUBSCRIBE}}} responses and {{{NOTIFY}}} requests.
2405 113 Adrian Georgescu
  This attribute is set on object instantiation and is read-only.
2406 113 Adrian Georgescu
2407 113 Adrian Georgescu
 '''remote_contact_header'''::
2408 113 Adrian Georgescu
 The {{{FrozenContactHeader}}} received from the remote endpoint. This attribute is read-only.
2409 113 Adrian Georgescu
2410 113 Adrian Georgescu
 '''peer_address'''::
2411 113 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.
2412 113 Adrian Georgescu
2413 113 Adrian Georgescu
==== notifications ====
2414 113 Adrian Georgescu
2415 113 Adrian Georgescu
2416 113 Adrian Georgescu
 '''SIPIncomingReferralChangedState'''::
2417 113 Adrian Georgescu
  This notification will be sent every time the an {{{IncomingReferral}}} object changes state.
2418 113 Adrian Georgescu
  This notification is mostly indicative, an application should not let its logic depend on it.
2419 113 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
2420 113 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
2421 113 Adrian Georgescu
  [[BR]]''prev_state'':[[BR]]
2422 113 Adrian Georgescu
  The previous state that the subscription was in.
2423 113 Adrian Georgescu
  [[BR]]''state'':[[BR]]
2424 113 Adrian Georgescu
  The new state the subscription has.
2425 113 Adrian Georgescu
2426 113 Adrian Georgescu
 '''SIPIncomingReferralGotRefer'''::
2427 113 Adrian Georgescu
  This notification will be sent when a new {{{IncomingReferral}}} is created as result of an incoming {{{REFER}}} request.
2428 113 Adrian Georgescu
  The application should listen for this notification, retain a reference to the object that sent it and either accept or reject it.
2429 113 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
2430 113 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
2431 113 Adrian Georgescu
  [[BR]]''method'':[[BR]]
2432 113 Adrian Georgescu
  The method of the SIP request as a string, which will be {{{REFER}}}.
2433 113 Adrian Georgescu
  [[BR]]''request_uri'':[[BR]]
2434 113 Adrian Georgescu
  The request URI of the {{{REFER}}} request as a {{{FrozenSIPURI}}} object.
2435 113 Adrian Georgescu
  [[BR]]''refer_to'':[[BR]]
2436 113 Adrian Georgescu
  The Refer-To header as a {{{FrozenReferToHeader}}} object.
2437 113 Adrian Georgescu
  [[BR]]''headers'':[[BR]]
2438 113 Adrian Georgescu
  The headers of the {{{REFER}}} request as a dict, the values of which are the relevant header objects.
2439 113 Adrian Georgescu
  [[BR]]''body'':[[BR]]
2440 113 Adrian Georgescu
  The body of the {{{REFER}}} request as a string, or {{{None}}} if no body was included.
2441 113 Adrian Georgescu
2442 113 Adrian Georgescu
 '''SIPIncomingReferralGotRefreshingSubscribe'''::
2443 113 Adrian Georgescu
  This notification indicates that a refreshing {{{SUBSCRIBE}}} request was received from the subscriber.
2444 113 Adrian Georgescu
  It is purely informative, no action needs to be taken by the application as a result of it.
2445 113 Adrian Georgescu
2446 113 Adrian Georgescu
 '''SIPIncomingReferralGotUnsubscribe'''::
2447 113 Adrian Georgescu
  This notification indicates that a {{{SUBSCRIBE}}} request with an {{{Expires}}} header of 0 was received from the subscriber, effectively requesting to unsubscribe.
2448 113 Adrian Georgescu
  It is purely informative, no action needs to be taken by the application as a result of it.
2449 113 Adrian Georgescu
2450 113 Adrian Georgescu
 '''SIPIncomingReferralAnsweredRefer'''::
2451 113 Adrian Georgescu
  This notification is sent whenever a response to a {{{REFER}}} request is sent by the object.
2452 113 Adrian Georgescu
  It is purely informative, no action needs to be taken by the application as a result of it.
2453 113 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
2454 113 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
2455 113 Adrian Georgescu
  [[BR]]''code'':[[BR]]
2456 113 Adrian Georgescu
  The code of the SIP response as an int.
2457 113 Adrian Georgescu
  [[BR]]''reason'':[[BR]]
2458 113 Adrian Georgescu
  The reason text of the SIP response as an int.
2459 113 Adrian Georgescu
  [[BR]]''headers'':[[BR]]
2460 113 Adrian Georgescu
  The headers of the response as a dict, the values of which are the relevant header objects.
2461 113 Adrian Georgescu
  [[BR]]''body'':[[BR]]
2462 113 Adrian Georgescu
  This will be {{{None}}}.
2463 113 Adrian Georgescu
2464 113 Adrian Georgescu
 '''SIPIncomingReferralSentNotify'''::
2465 113 Adrian Georgescu
  This notification indicates that a {{{NOTIFY}}} request was sent to the subscriber.
2466 113 Adrian Georgescu
  It is purely informative, no action needs to be taken by the application as a result of it.
2467 113 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
2468 113 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
2469 113 Adrian Georgescu
  [[BR]]''method'':[[BR]]
2470 113 Adrian Georgescu
  The method of the SIP request as a string, which will be {{{NOTIFY}}}.
2471 113 Adrian Georgescu
  [[BR]]''request_uri'':[[BR]]
2472 113 Adrian Georgescu
  The request URI of the {{{NOTIFY}}} request as a {{{FrozenSIPURI}}} object.
2473 113 Adrian Georgescu
  [[BR]]''headers'':[[BR]]
2474 113 Adrian Georgescu
  The headers of the {{{NOTIFY}}} request as a dict, the values of which are the relevant header objects.
2475 113 Adrian Georgescu
  [[BR]]''body'':[[BR]]
2476 113 Adrian Georgescu
  The body of the {{{NOTIFY}}} request or response as a string, or {{{None}}} if no body was included.
2477 113 Adrian Georgescu
2478 113 Adrian Georgescu
 '''SIPIncomingReferralNotifyDidSucceed'''::
2479 113 Adrian Georgescu
  This indicates that a positive final response was received from the subscriber in reply to a sent {{{NOTIFY}}} request.
2480 113 Adrian Georgescu
  The notification is purely informative, no action needs to be taken by the application as a result of it.
2481 113 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
2482 113 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
2483 113 Adrian Georgescu
  [[BR]]''code'':[[BR]]
2484 113 Adrian Georgescu
  The code of the SIP response as an int.
2485 113 Adrian Georgescu
  [[BR]]''reason'':[[BR]]
2486 113 Adrian Georgescu
  The reason text of the SIP response as a string.
2487 113 Adrian Georgescu
  [[BR]]''headers'':[[BR]]
2488 113 Adrian Georgescu
  The headers of the response as a dict, the values of which are the relevant header objects.
2489 113 Adrian Georgescu
  [[BR]]''body'':[[BR]]
2490 113 Adrian Georgescu
  This will be {{{None}}}.
2491 113 Adrian Georgescu
2492 113 Adrian Georgescu
 '''SIPIncomingReferralNotifyDidFail'''::
2493 113 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.
2494 113 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
2495 113 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
2496 113 Adrian Georgescu
  [[BR]]''code'':[[BR]]
2497 113 Adrian Georgescu
  The code of the SIP response as an int.
2498 113 Adrian Georgescu
  If this is 0, the notification was sent as a result of an internal error.
2499 113 Adrian Georgescu
  [[BR]]''reason'':[[BR]]
2500 113 Adrian Georgescu
  The reason text of the SIP response as a string or the internal error if the code attribute is 0.
2501 113 Adrian Georgescu
  [[BR]]''headers'': (if the notification was caused by a negative response)[[BR]]
2502 113 Adrian Georgescu
  The headers of the response as a dict, the values of which are the relevant header objects.
2503 113 Adrian Georgescu
  [[BR]]''body'': (if the notification was caused by a negative response)[[BR]]
2504 113 Adrian Georgescu
  This will be {{{None}}}.
2505 113 Adrian Georgescu
2506 113 Adrian Georgescu
 '''SIPIncomingReferralDidEnd'''::
2507 113 Adrian Georgescu
  This notification is sent whenever the {{{IncomingReferral}}} object reaches the {{{"terminated"}}} state and is no longer valid.
2508 113 Adrian Georgescu
  After receiving this notification, the application should not longer try to use the object.
2509 113 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
2510 113 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
2511 113 Adrian Georgescu
2512 103 Adrian Georgescu
=== AudioMixer ===
2513 1 Adrian Georgescu
2514 103 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.
2515 103 Adrian Georgescu
It wraps a [http://www.pjsip.org/pjmedia/docs/html/group__PJMEDIA__CONF.htm PJSIP conference bridge], the concept of which is explained in the [http://trac.pjsip.org/repos/wiki/Python_SIP/Media PJSIP documentation].
2516 103 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.
2517 103 Adrian Georgescu
The sound devices, both input and output, together always occupy slot 0.
2518 103 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 [wiki:SipMiddlewareApi#Audio {{{sipsimple.audio}}}] module, but also consists of other audio-enabled objects (such as the AudioStream).
2519 1 Adrian Georgescu
2520 103 Adrian Georgescu
==== methods ====
2521 1 Adrian Georgescu
2522 1 Adrian Georgescu
2523 103 Adrian Georgescu
 '''!__init!__'''(''self'', '''input_device''', '''output_device''', '''sample_rate''', '''ec_tail_length'''=200, '''slot_count'''=254)::
2524 103 Adrian Georgescu
  Creates a new {{{ConferenceBridge}}} object.
2525 103 Adrian Georgescu
  [[BR]]''input_device'':[[BR]]
2526 103 Adrian Georgescu
  The name of the audio input device to use as a string, or {{{None}}} if no input device is to be used.
2527 103 Adrian Georgescu
  A list of known input devices can be queried through the {{{Engine.input_devices}}} attribute.
2528 105 Luci Stanescu
  If {{{"system_default"}}} is used, PJSIP will select the system default output device, or {{{None}}} if no audio input device is present.
2529 103 Adrian Georgescu
  The device that was selected can be queried afterwards through the {{{input_device}}} attribute.
2530 103 Adrian Georgescu
  [[BR]]''output_device'':[[BR]]
2531 103 Adrian Georgescu
  The name of the audio output device to use as a string, or {{{None}}} if no output device is to be used.
2532 103 Adrian Georgescu
  A list of known output devices can be queried through the {{{Engine.output_devices}}} attribute.
2533 105 Luci Stanescu
  If {{{"system_default"}}} is used, PJSIP will select the system default output device, or {{{None}}} if no audio output device is present.
2534 103 Adrian Georgescu
  The device that was selected can be queried afterwards through the {{{output_device}}} attribute.
2535 103 Adrian Georgescu
  [[BR]]''sample_rate'':[[BR]]
2536 103 Adrian Georgescu
  The sample rate on which the conference bridge and sound devices should operate in Hz.
2537 103 Adrian Georgescu
  This must be a multiple of 50.
2538 103 Adrian Georgescu
  [[BR]]''ec_tail_length'':[[BR]]
2539 103 Adrian Georgescu
  The echo cancellation tail length in ms.
2540 103 Adrian Georgescu
  If this value is 0, no echo cancellation is used.
2541 103 Adrian Georgescu
  [[BR]]''slot_count'':[[BR]]
2542 103 Adrian Georgescu
  The number of slots to allocate on the conference bridge.
2543 103 Adrian Georgescu
  Not that this includes the slot that is occupied by the sound devices.
2544 99 Adrian Georgescu
2545 103 Adrian Georgescu
 '''set_sound_devices'''(''self'', '''input_device''', '''output_device''', '''ec_tail_length''')::
2546 103 Adrian Georgescu
  Change the sound devices used (including echo cancellation) by the conference bridge.
2547 103 Adrian Georgescu
  The meaning of the parameters is that same as for {{{__init__()}}}.
2548 1 Adrian Georgescu
2549 103 Adrian Georgescu
 '''connect_slots'''(''self'', '''src_slot''', '''dst_slot''')::
2550 103 Adrian Georgescu
  Connect two slots on the conference bridge, making audio flow from {{{src_slot}}} to {{{dst_slot}}}.
2551 1 Adrian Georgescu
2552 103 Adrian Georgescu
 '''disconnect_slots'''(''self'', '''src_slot''', '''dst_slot''')::
2553 103 Adrian Georgescu
  Break the connection between the specified slots.
2554 103 Adrian Georgescu
  Note that when an audio object is stopped or destroyed, its connections on the conference bridge will automatically be removed.
2555 103 Adrian Georgescu
2556 1 Adrian Georgescu
==== attributes ====
2557 1 Adrian Georgescu
2558 99 Adrian Georgescu
2559 103 Adrian Georgescu
 '''input_device'''::
2560 103 Adrian Georgescu
  A string specifying the audio input device that is currently being used.
2561 103 Adrian Georgescu
  If there is no input device, this attribute will be {{{None}}}.
2562 103 Adrian Georgescu
  This attribute is read-only, but may be updated by calling the {{{set_sound_devices()}}} method.
2563 1 Adrian Georgescu
2564 103 Adrian Georgescu
 '''output_device'''::
2565 103 Adrian Georgescu
  A string specifying the audio output device that is currently being used.
2566 103 Adrian Georgescu
  If there is no output device, this attribute will be {{{None}}}.
2567 103 Adrian Georgescu
  This attribute is read-only, but may be updated by calling the {{{set_sound_devices()}}} method.
2568 1 Adrian Georgescu
2569 103 Adrian Georgescu
 '''sample_rate'''::
2570 103 Adrian Georgescu
  The sample rate in Hz that the conference bridge is currently operating on.
2571 103 Adrian Georgescu
  This read-only attribute is passed when the object is created.
2572 99 Adrian Georgescu
2573 103 Adrian Georgescu
 '''ec_tail_length'''::
2574 103 Adrian Georgescu
  The current echo cancellation tail length in ms.
2575 103 Adrian Georgescu
  If this value is 0, no echo cancellation is used.
2576 103 Adrian Georgescu
  This attribute is read-only, but may be updated by calling the {{{set_sound_devices()}}} method.
2577 1 Adrian Georgescu
2578 103 Adrian Georgescu
 '''slot_count'''::
2579 103 Adrian Georgescu
  The total number of slots that is available on the conference bridge
2580 103 Adrian Georgescu
  This read-only attribute is passed when the object is created.
2581 1 Adrian Georgescu
2582 103 Adrian Georgescu
 '''used_slot_count'''::
2583 103 Adrian Georgescu
  A read-only attribute indicating the number of slots that are used by objects.
2584 1 Adrian Georgescu
2585 103 Adrian Georgescu
 '''input_volume'''::
2586 103 Adrian Georgescu
  This writable property indicates the % of volume that is read from the audio input device.
2587 103 Adrian Georgescu
  By default this value is 100.
2588 1 Adrian Georgescu
2589 103 Adrian Georgescu
 '''output_volume'''::
2590 103 Adrian Georgescu
  This writable property indicates the % of volume that is sent to the audio output device.
2591 103 Adrian Georgescu
  By default this value is 100.
2592 1 Adrian Georgescu
2593 103 Adrian Georgescu
 '''muted'''::
2594 103 Adrian Georgescu
  This writable boolean property indicates if the input audio device is muted.
2595 1 Adrian Georgescu
2596 103 Adrian Georgescu
 '''connected_slots'''::
2597 103 Adrian Georgescu
  A read-only list of tupples indicating which slot is connected to which.
2598 103 Adrian Georgescu
  Connections are directional.
2599 1 Adrian Georgescu
2600 103 Adrian Georgescu
=== MixerPort ===
2601 1 Adrian Georgescu
2602 103 Adrian Georgescu
This a simple object which simply copies all the audio data it gets as input to it output. It's main purpose is that of facilitating the creation the of the middleware {{{AudioBridge}}} object.
2603 1 Adrian Georgescu
2604 103 Adrian Georgescu
==== methods ====
2605 1 Adrian Georgescu
2606 1 Adrian Georgescu
2607 103 Adrian Georgescu
 '''!__init!__'''(''self'', ''mixer'')::
2608 103 Adrian Georgescu
  Create a new MixerPort which is associated with the specified AudioMixer.
2609 1 Adrian Georgescu
2610 103 Adrian Georgescu
 '''start'''(''self'')::
2611 103 Adrian Georgescu
  Activate the mixer port. This will reserve a slot on the AudioMixer and allow it to be connected to other slots.
2612 78 Ruud Klaver
2613 103 Adrian Georgescu
 '''stop'''(''self'')::
2614 103 Adrian Georgescu
  Deactivate the mixer port. This will release the slot previously allocated on the AudioMixer and all connections which it had will be discarded.
2615 78 Ruud Klaver
2616 103 Adrian Georgescu
==== attributes ====
2617 78 Ruud Klaver
2618 103 Adrian Georgescu
2619 103 Adrian Georgescu
 '''mixer'''::
2620 103 Adrian Georgescu
  The AudioMixer this MixerPort is associated with
2621 103 Adrian Georgescu
  This attribute is read-only.
2622 103 Adrian Georgescu
2623 103 Adrian Georgescu
 '''is_active'''::
2624 103 Adrian Georgescu
  Whether or not this MixerPort has a slot associated in its AudioMixer.
2625 103 Adrian Georgescu
  This attribute is read-only.
2626 103 Adrian Georgescu
2627 103 Adrian Georgescu
 '''slot'''::
2628 103 Adrian Georgescu
  The slot this MixerPort has reserved on AudioMixer or {{{None}}} if it is not active.
2629 103 Adrian Georgescu
  This attribute is read-only.
2630 103 Adrian Georgescu
2631 103 Adrian Georgescu
2632 103 Adrian Georgescu
=== WaveFile ===
2633 103 Adrian Georgescu
2634 103 Adrian Georgescu
This is a simple object that allows playing back of a {{{.wav}}} file over the PJSIP conference bridge.
2635 103 Adrian Georgescu
Only 16-bit PCM and A-law/U-law formats are supported.
2636 103 Adrian Georgescu
Its main purpose is the playback of ringtones or previously recorded conversations.
2637 103 Adrian Georgescu
2638 103 Adrian Georgescu
This object is associated with a {{{AudioMixer}}} instance and, once the {{{start()}}} method is called, connects to it and sends the sound to all its connections.
2639 103 Adrian Georgescu
Note that the slot of the {{{WaveFile}}} object will not start playing until it is connected to another slot on the AudioMixer.
2640 103 Adrian Georgescu
If the {{{stop()}}} method is called or the end of the {{{.wav}}} file is reached, a {{{WaveFileDidFinishPlaying}}} notification is sent by the object.
2641 103 Adrian Georgescu
After this the {{{start()}}} method may be called again in order to re-use the object.
2642 103 Adrian Georgescu
2643 103 Adrian Georgescu
It is the application's responsibility to keep a reference to the {{{WaveFile}}} object for the duration of playback.
2644 103 Adrian Georgescu
If the reference count of the object reaches 0, playback will be stopped automatically.
2645 103 Adrian Georgescu
In this case no notification will be sent.
2646 103 Adrian Georgescu
2647 78 Ruud Klaver
==== methods ====
2648 99 Adrian Georgescu
2649 95 Luci Stanescu
2650 103 Adrian Georgescu
 '''!__init!__'''(''self'', '''mixer''', '''filename''')::
2651 103 Adrian Georgescu
  Creates a new {{{WaveFile}}} object.
2652 103 Adrian Georgescu
  [[BR]]''mixer'':[[BR]]
2653 103 Adrian Georgescu
  The {{{AudioMixer}}} object that this object is to be connected to.
2654 103 Adrian Georgescu
  [[BR]]''filename'':[[BR]]
2655 103 Adrian Georgescu
  The name of the {{{.wav}}} file to be played back as a string.
2656 103 Adrian Georgescu
  This should include the full path to the file.
2657 95 Luci Stanescu
2658 103 Adrian Georgescu
 '''start'''(''self'')::
2659 103 Adrian Georgescu
  Start playback of the {{{.wav}}} file.
2660 95 Luci Stanescu
2661 103 Adrian Georgescu
 '''stop'''(''self'')::
2662 103 Adrian Georgescu
  Stop playback of the file.
2663 95 Luci Stanescu
2664 103 Adrian Georgescu
==== attributes ====
2665 78 Ruud Klaver
2666 78 Ruud Klaver
2667 103 Adrian Georgescu
 '''mixer'''::
2668 103 Adrian Georgescu
  The {{{AudioMixer}}} this object is associated with.
2669 103 Adrian Georgescu
  This attribute is read-only.
2670 1 Adrian Georgescu
2671 103 Adrian Georgescu
 '''filename'''::
2672 103 Adrian Georgescu
  The name of the {{{.wav}}} file, as specified when the object was created.
2673 103 Adrian Georgescu
  This attribute is read-only.
2674 103 Adrian Georgescu
2675 103 Adrian Georgescu
 '''slot'''::
2676 103 Adrian Georgescu
  A read-only property indicating the slot number at which this object is attached to the associated AudioMixer.
2677 103 Adrian Georgescu
  If the {{{WaveFile}}} is not active, this attribute will be {{{None}}}.
2678 103 Adrian Georgescu
2679 103 Adrian Georgescu
 '''volume'''::
2680 103 Adrian Georgescu
  A writable property indicating the % of volume at which this object contributes audio to the AudioMixer.
2681 103 Adrian Georgescu
  By default this is set to 100.
2682 103 Adrian Georgescu
2683 103 Adrian Georgescu
 '''is_active'''::
2684 103 Adrian Georgescu
  A boolean read-only property that indicates if the file is currently being played.
2685 103 Adrian Georgescu
2686 95 Luci Stanescu
==== notifications ====
2687 95 Luci Stanescu
2688 99 Adrian Georgescu
2689 103 Adrian Georgescu
 '''WaveFileDidFinishPlaying'''::
2690 103 Adrian Georgescu
  This notification will be sent whenever playing of the {{{.wav}}} has stopped.
2691 103 Adrian Georgescu
  After sending this event, the playback may be re-started.
2692 95 Luci Stanescu
  [[BR]]''timestamp'':[[BR]]
2693 95 Luci Stanescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
2694 99 Adrian Georgescu
2695 103 Adrian Georgescu
=== RecordingWaveFile ===
2696 103 Adrian Georgescu
2697 103 Adrian Georgescu
This is a simple object that allows recording audio to a PCM {{{.wav}}} file.
2698 103 Adrian Georgescu
2699 103 Adrian Georgescu
This object is associated with a {{{AudioMixer}}} instance and, once the {{{start()}}} method is called, crecords sound from its connections.
2700 103 Adrian Georgescu
Note that the {{{RecordingWaveFile}}} will not record anything if it does not have any connections.
2701 103 Adrian Georgescu
Recording to the file can be stopped either by calling the {{{stop()}}} method or by removing all references to the object.
2702 103 Adrian Georgescu
Once the {{{stop()}}} method has been called, the {{{start()}}} method may not be called again.
2703 103 Adrian Georgescu
It is the application's responsibility to keep a reference to the {{{RecordingWaveFile}}} object for the duration of the recording, it will be stopped automatically when the reference count reaches 0.
2704 103 Adrian Georgescu
2705 103 Adrian Georgescu
==== methods ====
2706 103 Adrian Georgescu
2707 103 Adrian Georgescu
2708 103 Adrian Georgescu
 '''!__init!__'''(''self'', '''mixer''', '''filename''')::
2709 103 Adrian Georgescu
  Creates a new {{{RecordingWaveFile}}} object.
2710 103 Adrian Georgescu
  [[BR]]''mixer'':[[BR]]
2711 103 Adrian Georgescu
  The {{{AudioMixer}}} object that this object is to be associated with.
2712 103 Adrian Georgescu
  [[BR]]''filename'':[[BR]]
2713 103 Adrian Georgescu
  The name of the {{{.wav}}} file to record to as a string.
2714 103 Adrian Georgescu
  This should include the full path to the file.
2715 103 Adrian Georgescu
2716 103 Adrian Georgescu
 '''start'''(''self'')::
2717 103 Adrian Georgescu
  Start recording the sound to the {{{.wav}}} file.
2718 103 Adrian Georgescu
2719 103 Adrian Georgescu
 '''stop'''(''self'')::
2720 103 Adrian Georgescu
  Stop recording to the file.
2721 103 Adrian Georgescu
2722 103 Adrian Georgescu
==== attributes ====
2723 103 Adrian Georgescu
2724 103 Adrian Georgescu
2725 103 Adrian Georgescu
 '''mixer'''::
2726 103 Adrian Georgescu
  The {{{AudioMixer}}} this object is associated with.
2727 103 Adrian Georgescu
  This attribute is read-only.
2728 103 Adrian Georgescu
2729 103 Adrian Georgescu
 '''filename'''::
2730 103 Adrian Georgescu
  The name of the {{{.wav}}} file, as specified when the object was created.
2731 103 Adrian Georgescu
  This attribute is read-only.
2732 103 Adrian Georgescu
2733 103 Adrian Georgescu
 '''slot'''::
2734 103 Adrian Georgescu
  A read-only property indicating the slot number at which this object is attached to the associated AudioMixer.
2735 103 Adrian Georgescu
  If the {{{RecordingWaveFile}}} is not active, this attribute will be {{{None}}}.
2736 103 Adrian Georgescu
2737 103 Adrian Georgescu
 '''is_active'''::
2738 103 Adrian Georgescu
  A boolean read-only attribute that indicates if the file is currently being written to.
2739 103 Adrian Georgescu
2740 103 Adrian Georgescu
=== ToneGenerator ===
2741 103 Adrian Georgescu
2742 103 Adrian Georgescu
A {{{ToneGenerator}}} can generate a series of dual frequency tones and has a shortcut method for generating valid DTMF tones.
2743 103 Adrian Georgescu
Each instance of this object is associated with a {{{AudioMixer}}} object, which it will connect to once started.
2744 103 Adrian Georgescu
The tones will be sent to the slots on the AudioMixer its slot is connected to.
2745 103 Adrian Georgescu
Once started, a {{{ToneGenerator}}} can be stopped by calling the {{{stop()}}} method and is automatically destroyed when the reference count reaches 0.
2746 103 Adrian Georgescu
2747 103 Adrian Georgescu
> Note: this object has threading issues when the application uses multiple AudioMixers. It should not be used.
2748 103 Adrian Georgescu
2749 103 Adrian Georgescu
==== methods ====
2750 103 Adrian Georgescu
2751 103 Adrian Georgescu
2752 103 Adrian Georgescu
 '''!__init!__'''(''self'', '''mixer''')::
2753 103 Adrian Georgescu
  Creates a new {{{ToneGenerator}}} object.
2754 103 Adrian Georgescu
  [[BR]]''mixer'':[[BR]]
2755 103 Adrian Georgescu
  The {{{AudioMixer}}} object that this object is to be connected to.
2756 103 Adrian Georgescu
2757 103 Adrian Georgescu
 '''start'''(''self'')::
2758 103 Adrian Georgescu
  Start the tone generator and connect it to its associated {{{AudioMixer}}}.
2759 103 Adrian Georgescu
2760 103 Adrian Georgescu
 '''stop'''(''self'')::
2761 103 Adrian Georgescu
  Stop the tone generator and remove it from the conference bridge.
2762 103 Adrian Georgescu
2763 103 Adrian Georgescu
 '''play_tones(''self'', '''tones''')::
2764 103 Adrian Georgescu
  Play a sequence of single or dual frequency tones over the audio device.
2765 103 Adrian Georgescu
  [[BR]]''tones'':[[BR]]
2766 103 Adrian Georgescu
  This should be a list of 3-item tuples, in the form of {{{[(<freq1>, <freq2>, <duration>), ...]}}}, with Hz as unit for the frequencies and ms as unit for the duration.
2767 103 Adrian Georgescu
  If {{{freq2}}} is 0, this indicates that only {{{freq1}}} should be used for the tone.
2768 103 Adrian Georgescu
  If {{{freq1}}} is 0, this indicates a pause when no tone should be played for the set duration.
2769 103 Adrian Georgescu
2770 103 Adrian Georgescu
 '''play_dtmf(''self'', '''digit''')::
2771 103 Adrian Georgescu
  Play a single DTMF digit.
2772 103 Adrian Georgescu
  [[BR]]''digit'':[[BR]]
2773 103 Adrian Georgescu
  A string of length 1 containing a valid DTMF digit, i.e. 0 through 9, #, * or A through D.
2774 103 Adrian Georgescu
2775 103 Adrian Georgescu
==== attributes ====
2776 103 Adrian Georgescu
2777 103 Adrian Georgescu
2778 103 Adrian Georgescu
 '''mixer'''::
2779 103 Adrian Georgescu
  The {{{AudioMixer}}} this object is associated with.
2780 103 Adrian Georgescu
  This attribute is read-only.
2781 103 Adrian Georgescu
2782 103 Adrian Georgescu
 '''slot'''::
2783 103 Adrian Georgescu
  A read-only property indicating the slot number at which this object is attached to the associated AudioMixer.
2784 103 Adrian Georgescu
  If the {{{ToneGenerator}}} has not been started, this attribute will be {{{None}}}.
2785 103 Adrian Georgescu
2786 103 Adrian Georgescu
 '''volume'''::
2787 103 Adrian Georgescu
  A writable property indicating the % of volume at which this object contributes audio.
2788 103 Adrian Georgescu
  By default this is set to 100.
2789 103 Adrian Georgescu
2790 103 Adrian Georgescu
 '''is_active'''::
2791 103 Adrian Georgescu
  A boolean read-only property that indicates if the object has been started.
2792 103 Adrian Georgescu
2793 103 Adrian Georgescu
 '''is_busy'''::
2794 103 Adrian Georgescu
  A boolean read-only property indicating if the {{{ToneGenerator}}} is busy playing tones.
2795 103 Adrian Georgescu
2796 103 Adrian Georgescu
==== notifications ====
2797 103 Adrian Georgescu
2798 103 Adrian Georgescu
 '''ToneGeneratorDidFinishPlaying'''::
2799 103 Adrian Georgescu
  This notification will be sent whenever playing of the queued tones has finished.
2800 1 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
2801 1 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.