SipCoreApiDocumentation

Version 96 (Luci Stanescu, 03/26/2010 04:17 pm)

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