SipCoreApiDocumentation
Version 91 (Luci Stanescu, 03/24/2010 09:41 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 | 91 | Luci Stanescu | === Credentials and FrozenCredentials === |
436 | 91 | Luci Stanescu | |
437 | 91 | Luci Stanescu | These 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 | 91 | Luci Stanescu | As with the {{{SIPURI}}} object, 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 | 91 | Luci Stanescu | === SDPSession and FrozenSDPSession === |
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 | 91 | 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 | 91 | Luci Stanescu | === SDPMediaStream and FrozenSDPMediaStream === |
508 | 91 | Luci Stanescu | |
509 | 91 | Luci Stanescu | These 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 | 91 | Luci Stanescu | === SDPConnection and FrozenSDPConnection === |
549 | 91 | Luci Stanescu | |
550 | 91 | Luci Stanescu | This object 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 | 91 | Luci Stanescu | === SDPAttributeList and FrozenSDPAttributeList === |
571 | 91 | Luci Stanescu | |
572 | 91 | Luci Stanescu | These 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 | 91 | Luci Stanescu | === SDPAttribute and FrozenSDPAttribute === |
585 | 91 | Luci Stanescu | |
586 | 91 | Luci Stanescu | These 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 | 1 | Adrian Georgescu | ==== attributes ==== |
613 | 1 | Adrian Georgescu | |
614 | 1 | Adrian Georgescu | '''input_device''':: |
615 | 23 | Ruud Klaver | A string specifying the audio input device that is currently being used. |
616 | 1 | Adrian Georgescu | If there is no input device, this attribute will be {{{None}}}. |
617 | 1 | Adrian Georgescu | This attribute is read-only, but may be updated by calling the {{{set_sound_devices()}}} method. |
618 | 1 | Adrian Georgescu | '''output_device''':: |
619 | 1 | Adrian Georgescu | A string specifying the audio output device that is currently being used. |
620 | 1 | Adrian Georgescu | If there is no output device, this attribute will be {{{None}}}. |
621 | 1 | Adrian Georgescu | This attribute is read-only, but may be updated by calling the {{{set_sound_devices()}}} method. |
622 | 1 | Adrian Georgescu | '''sample_rate''':: |
623 | 1 | Adrian Georgescu | The sample rate in Hz that the conference bridge is currently operating on. |
624 | 1 | Adrian Georgescu | This read-only attribute is passed when the object is created. |
625 | 1 | Adrian Georgescu | '''ec_tail_length''':: |
626 | 1 | Adrian Georgescu | The current echo cancellation tail length in ms. |
627 | 1 | Adrian Georgescu | If this value is 0, no echo cancellation is used. |
628 | 1 | Adrian Georgescu | This attribute is read-only, but may be updated by calling the {{{set_sound_devices()}}} method. |
629 | 1 | Adrian Georgescu | '''slot_count''':: |
630 | 1 | Adrian Georgescu | The total number of slots that is available on the conference bridge |
631 | 1 | Adrian Georgescu | This read-only attribute is passed when the object is created. |
632 | 1 | Adrian Georgescu | '''used_slot_count''':: |
633 | 1 | Adrian Georgescu | A read-only attribute indicating the number of slots that are used by objects. |
634 | 91 | Luci Stanescu | '''input_volume''':: |
635 | 91 | Luci Stanescu | This writable property indicates the % of volume that is read from the audio input device. |
636 | 91 | Luci Stanescu | By default this value is 100. |
637 | 91 | Luci Stanescu | '''output_volume''':: |
638 | 1 | Adrian Georgescu | This writable property indicates the % of volume that is sent to the audio output device. |
639 | 1 | Adrian Georgescu | By default this value is 100. |
640 | 91 | Luci Stanescu | '''muted''':: |
641 | 61 | Ruud Klaver | This writable boolean property indicates if the input audio device is muted. |
642 | 1 | Adrian Georgescu | '''connected_slots''':: |
643 | 61 | Ruud Klaver | A read-only list of tupples indicating which slot is connected to which. |
644 | 1 | Adrian Georgescu | Connections are directional. |
645 | 1 | Adrian Georgescu | |
646 | 1 | Adrian Georgescu | ==== methods ==== |
647 | 61 | Ruud Klaver | |
648 | 1 | Adrian Georgescu | '''!__init!__'''(''self'', '''input_device''', '''output_device''', '''sample_rate''', '''ec_tail_length'''=200, '''slot_count'''=254):: |
649 | 1 | Adrian Georgescu | Creates a new {{{ConferenceBridge}}} object. |
650 | 61 | Ruud Klaver | [[BR]]''input_device'':[[BR]] |
651 | 61 | Ruud Klaver | The name of the audio input device to use as a string, or {{{None}}} if no input device is to be used. |
652 | 1 | Adrian Georgescu | A list of known input devices can be queried through the {{{Engine.input_devices}}} attribute. |
653 | 1 | Adrian Georgescu | If {{{"default"}}} is used, PJSIP will select the system default output device, or {{{None}}} if no audio input device is present. |
654 | 1 | Adrian Georgescu | The device that was selected can be queried afterwards through the {{{input_device}}} attribute. |
655 | 1 | Adrian Georgescu | [[BR]]''output_device'':[[BR]] |
656 | 1 | Adrian Georgescu | The name of the audio output device to use as a string, or {{{None}}} if no output device is to be used. |
657 | 1 | Adrian Georgescu | A list of known output devices can be queried through the {{{Engine.output_devices}}} attribute. |
658 | 1 | Adrian Georgescu | If {{{"default"}}} is used, PJSIP will select the system default output device, or {{{None}}} if no audio output device is present. |
659 | 22 | Ruud Klaver | The device that was selected can be queried afterwards through the {{{output_device}}} attribute. |
660 | 33 | Ruud Klaver | [[BR]]''sample_rate'':[[BR]] |
661 | 22 | Ruud Klaver | The sample rate on which the conference bridge and sound devices should operate in Hz. |
662 | 1 | Adrian Georgescu | This must be a multiple of 50. |
663 | 1 | Adrian Georgescu | [[BR]]''ec_tail_length'':[[BR]] |
664 | 1 | Adrian Georgescu | The echo cancellation tail length in ms. |
665 | 1 | Adrian Georgescu | If this value is 0, no echo cancellation is used. |
666 | 22 | Ruud Klaver | [[BR]]''slot_count'':[[BR]] |
667 | 1 | Adrian Georgescu | The number of slots to allocate on the conference bridge. |
668 | 1 | Adrian Georgescu | Not that this includes the slot that is occupied by the sound devices. |
669 | 22 | Ruud Klaver | '''set_sound_devices'''(''self'', '''input_device''', '''output_device''', '''ec_tail_length'''):: |
670 | 45 | Ruud Klaver | Change the sound devices used (including echo cancellation) by the conference bridge. |
671 | 1 | Adrian Georgescu | The meaning of the parameters is that same as for {{{__init__()}}}. |
672 | 22 | Ruud Klaver | '''connect_slots'''(''self'', '''src_slot''', '''dst_slot'''):: |
673 | 1 | Adrian Georgescu | Connect two slots on the conference bridge, making audio flow from {{{src_slot}}} to {{{dst_slot}}}. |
674 | 35 | Ruud Klaver | '''disconnect_slots'''(''self'', '''src_slot''', '''dst_slot'''):: |
675 | 1 | Adrian Georgescu | Break the connection between the specified slots. |
676 | 1 | Adrian Georgescu | Note that when an audio object is stopped or destroyed, its connections on the conference bridge will automatically be removed. |
677 | 22 | Ruud Klaver | |
678 | 46 | Ruud Klaver | === Request === |
679 | 46 | Ruud Klaver | |
680 | 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. |
681 | 46 | Ruud Klaver | Although this class can be used by the application to construct and send an arbitrary SIP request, most applications will use the classes provided in the {{{sipsimple.primitives}}} module, which are built on top of one or several {{{Request}}} objects and deal with instances of specific SIP methods. |
682 | 46 | Ruud Klaver | |
683 | 46 | Ruud Klaver | The lifetime of this object is linear and is described by the following diagram: |
684 | 46 | Ruud Klaver | |
685 | 46 | Ruud Klaver | [[Image(sipsimple-request-lifetime.png, nolink)]] |
686 | 46 | Ruud Klaver | |
687 | 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. |
688 | 46 | Ruud Klaver | Directly after the object is instantiated, it will be in the {{{INIT}}} state. |
689 | 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. |
690 | 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. |
691 | 46 | Ruud Klaver | Note that this may not occur at all if not provisional responses are received. |
692 | 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. |
693 | 46 | Ruud Klaver | Both of these notifications include data on the response that triggered it. |
694 | 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. |
695 | 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. |
696 | 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. |
697 | 46 | Ruud Klaver | This should usually trigger whomever is using this {{{Request}}} object to construct a new {{{Request}}} for a refreshing operation. |
698 | 46 | 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. |
699 | 46 | Ruud Klaver | |
700 | 46 | Ruud Klaver | ==== attributes ==== |
701 | 46 | Ruud Klaver | |
702 | 49 | Ruud Klaver | '''expire_warning_time''' (class attribute):: |
703 | 49 | 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. |
704 | 49 | Ruud Klaver | The default value is 30 seconds. |
705 | 47 | Ruud Klaver | '''state''':: |
706 | 47 | Ruud Klaver | Indicates the state the {{{Request}}} object is in, in the form of a string. |
707 | 47 | Ruud Klaver | Refer to the diagram above for possible states. |
708 | 47 | Ruud Klaver | This attribute is read-only. |
709 | 47 | Ruud Klaver | '''method''':: |
710 | 47 | Ruud Klaver | The method of the SIP request as a string. |
711 | 47 | Ruud Klaver | This attribute is set on instantiation and is read-only. |
712 | 47 | Ruud Klaver | '''from_uri''':: |
713 | 47 | Ruud Klaver | The SIP URI to put in the {{{From}}} header of the request, in the form of a {{{SIPURI}}} object. |
714 | 62 | Ruud Klaver | This attribute is set on instantiation and is read-only. |
715 | 47 | Ruud Klaver | '''to_uri''':: |
716 | 47 | Ruud Klaver | The SIP URI to put in the {{{To}}} header of the request, in the form of a {{{SIPURI}}} object. |
717 | 47 | Ruud Klaver | This attribute is set on instantiation and is read-only. |
718 | 47 | Ruud Klaver | '''request_uri''':: |
719 | 47 | Ruud Klaver | The SIP URI to put as request URI in the request, in the form of a {{{SIPURI}}} object. |
720 | 47 | Ruud Klaver | This attribute is set on instantiation and is read-only. |
721 | 1 | Adrian Georgescu | '''route''':: |
722 | 1 | Adrian Georgescu | Where to send the SIP request to, including IP, port and transport, in the form of a {{{SIPURI}}} object. |
723 | 1 | Adrian Georgescu | This will also be included in the {{{Route}}} header of the request. |
724 | 1 | Adrian Georgescu | This attribute is set on instantiation and is read-only. |
725 | 62 | Ruud Klaver | '''credentials''':: |
726 | 62 | Ruud Klaver | The credentials to be used when challenged for authentication, represented by a {{{Credentials}}} object. |
727 | 62 | Ruud Klaver | If no credentials were supplied when the object was created this attribute is {{{None}}}. |
728 | 62 | Ruud Klaver | This attribute is set on instantiation and is read-only. |
729 | 47 | Ruud Klaver | '''contact_uri''':: |
730 | 47 | Ruud Klaver | The SIP URI to put in the {{{Contact}}} header of the request, in the form of a {{{SIPURI}}} object. |
731 | 47 | Ruud Klaver | If this was not specified, this attribute is {{{None}}}. |
732 | 47 | Ruud Klaver | It is set on instantiation and is read-only. |
733 | 47 | Ruud Klaver | '''call_id''':: |
734 | 47 | Ruud Klaver | The {{{Call-ID}}} to be used for this transaction as a string. |
735 | 47 | Ruud Klaver | If no call id was specified on instantiation, this attribute contains the generated id. |
736 | 47 | Ruud Klaver | This attribute is set on instantiation and is read-only. |
737 | 47 | Ruud Klaver | '''cseq''':: |
738 | 47 | Ruud Klaver | The sequence number to use in the request as an int. |
739 | 47 | Ruud Klaver | If no sequence number was specified on instantiation, this attribute contains the generated sequence number. |
740 | 47 | Ruud Klaver | Note that this number may be increased by one if an authentication challenge is received and a {{{Credentials}}} object is given. |
741 | 47 | Ruud Klaver | This attribute is read-only. |
742 | 47 | Ruud Klaver | '''extra_headers''':: |
743 | 47 | Ruud Klaver | Extra headers to include in the request as a dictionary. |
744 | 47 | Ruud Klaver | This attribute is set on instantiation and is read-only. |
745 | 47 | Ruud Klaver | '''content_type''':: |
746 | 47 | Ruud Klaver | What string to put as content type in the {{{Content-Type}}} headers, if the request contains a body. |
747 | 47 | Ruud Klaver | If no body was specified, this attribute is {{{None}}} |
748 | 47 | Ruud Klaver | It is set on instantiation and is read-only. |
749 | 47 | Ruud Klaver | '''body''':: |
750 | 47 | Ruud Klaver | The body of the request as a string. |
751 | 47 | Ruud Klaver | If no body was specified, this attribute is {{{None}}} |
752 | 47 | Ruud Klaver | It is set on instantiation and is read-only. |
753 | 47 | Ruud Klaver | '''expires_in''':: |
754 | 1 | Adrian Georgescu | This read-only property indicates in how many seconds from now this {{{Request}}} will expire, if it is in the {{{EXPIRING}}} state. |
755 | 47 | Ruud Klaver | If this is not the case, this property is 0. |
756 | 47 | Ruud Klaver | |
757 | 46 | Ruud Klaver | ==== methods ==== |
758 | 46 | Ruud Klaver | |
759 | 62 | Ruud Klaver | '''!__init!__'''(''self'', '''method''', '''from_uri''', '''to_uri''', '''request_uri''', '''route''', '''credentials'''={{{None}}}, '''contact_uri'''={{{None}}}, '''call_id'''={{{None}}}, '''cseq'''={{{None}}}, '''extra_headers'''={{{None}}}, '''content_type'''={{{None}}}, '''body'''={{{None}}}):: |
760 | 48 | Ruud Klaver | Creates a new {{{Request}}} object in the {{{INIT}}} state. |
761 | 48 | Ruud Klaver | The arguments to this method are documented in the attributes section. |
762 | 48 | Ruud Klaver | '''send'''(''self'', '''timeout'''={{{None}}}):: |
763 | 48 | Ruud Klaver | Compose the SIP request and send it to the destination. |
764 | 48 | Ruud Klaver | This moves the {{{Request}}} object into the {{{IN_PROGRESS}}} state. |
765 | 48 | Ruud Klaver | [[BR]]''timeout'':[[BR]] |
766 | 48 | Ruud Klaver | This can be either an int or a float, indicating in how many seconds the request should timeout with an internally generated 408 response. |
767 | 48 | Ruud Klaver | This is is {{{None}}}, the internal 408 is only triggered by the internal PJSIP transaction timeout. |
768 | 48 | Ruud Klaver | Note that, even if the timeout is specified, the PJSIP timeout is also still valid. |
769 | 57 | Ruud Klaver | '''end'''(''self''):: |
770 | 48 | Ruud Klaver | Terminate the transaction, whichever state it is in, sending the appropriate notifications. |
771 | 48 | Ruud Klaver | Note that calling this method while in the {{{INIT}}} state does nothing. |
772 | 48 | Ruud Klaver | |
773 | 46 | Ruud Klaver | ==== notifications ==== |
774 | 49 | Ruud Klaver | |
775 | 49 | Ruud Klaver | '''SIPRequestGotProvisionalResponse''':: |
776 | 49 | Ruud Klaver | This notification will be sent on every provisional response received in reply to the sent request. |
777 | 49 | Ruud Klaver | [[BR]]''timestamp'':[[BR]] |
778 | 49 | Ruud Klaver | A {{{datetime.datetime}}} object indicating when the notification was sent. |
779 | 49 | Ruud Klaver | [[BR]]''code'':[[BR]] |
780 | 49 | Ruud Klaver | The SIP response code of the received provisional response as an int, which will be in the 1xx range. |
781 | 49 | Ruud Klaver | [[BR]]''reason'':[[BR]] |
782 | 49 | Ruud Klaver | The reason text string included with the SIP response code. |
783 | 49 | Ruud Klaver | [[BR]]''headers'':[[BR]] |
784 | 49 | Ruud Klaver | The headers included in the provisional response as a dictionary. |
785 | 49 | Ruud Klaver | [[BR]]''body'':[[BR]] |
786 | 49 | Ruud Klaver | The body of the provisional response as a string, or {{{None}}} if there was no body. |
787 | 49 | Ruud Klaver | '''SIPRequestDidSucceed''':: |
788 | 49 | Ruud Klaver | This notification will be sent when a positive final response was received in reply to the request. |
789 | 49 | Ruud Klaver | [[BR]]''timestamp'':[[BR]] |
790 | 49 | Ruud Klaver | A {{{datetime.datetime}}} object indicating when the notification was sent. |
791 | 49 | Ruud Klaver | [[BR]]''code'':[[BR]] |
792 | 49 | Ruud Klaver | The SIP response code of the received positive final response as an int, which will be in the 2xx range. |
793 | 49 | Ruud Klaver | [[BR]]''reason'':[[BR]] |
794 | 49 | Ruud Klaver | The reason text string included with the SIP response code. |
795 | 49 | Ruud Klaver | [[BR]]''headers'':[[BR]] |
796 | 49 | Ruud Klaver | The headers included in the positive final response as a dictionary. |
797 | 49 | Ruud Klaver | [[BR]]''body'':[[BR]] |
798 | 49 | Ruud Klaver | The body of the positive final response as a string, or {{{None}}} if there was no body. |
799 | 49 | Ruud Klaver | [[BR]]''expires'':[[BR]] |
800 | 49 | Ruud Klaver | Indicates in how many seconds the {{{Request}}} will expire as an int. |
801 | 49 | Ruud Klaver | If it does not expire and the {{{EXPIRING}}} state is skipped, this attribute is 0. |
802 | 49 | Ruud Klaver | '''SIPRequestDidFail''':: |
803 | 49 | Ruud Klaver | This notification will be sent when a negative final response is received in reply to the request or if an internal error occurs. |
804 | 49 | Ruud Klaver | [[BR]]''timestamp'':[[BR]] |
805 | 49 | Ruud Klaver | A {{{datetime.datetime}}} object indicating when the notification was sent. |
806 | 49 | Ruud Klaver | [[BR]]''code'':[[BR]] |
807 | 49 | Ruud Klaver | The SIP response code of the received negative final response as an int. |
808 | 49 | Ruud Klaver | This could also be a response code generated by PJSIP internally, or 0 when an internal error occurs. |
809 | 49 | Ruud Klaver | [[BR]]''reason'':[[BR]] |
810 | 49 | Ruud Klaver | The reason text string included with the SIP response code or error. |
811 | 49 | Ruud Klaver | [[BR]]''headers'': (only if a negative final response was received)[[BR]] |
812 | 49 | Ruud Klaver | The headers included in the negative final response as a dictionary, if this is what triggered the notification. |
813 | 49 | Ruud Klaver | [[BR]]''body'': (only if a negative final response was received)[[BR]] |
814 | 49 | Ruud Klaver | The body of the negative final response as a string, or {{{None}}} if there was no body. |
815 | 49 | Ruud Klaver | This attribute is absent if no response was received. |
816 | 49 | Ruud Klaver | '''SIPRequestWillExpire''':: |
817 | 49 | Ruud Klaver | This notification will be sent when a {{{Request}}} in the {{{EXPIRING}}} state will expire soon. |
818 | 49 | Ruud Klaver | [[BR]]''timestamp'':[[BR]] |
819 | 49 | Ruud Klaver | A {{{datetime.datetime}}} object indicating when the notification was sent. |
820 | 49 | Ruud Klaver | [[BR]]''expires'':[[BR]] |
821 | 49 | Ruud Klaver | An int indicating in how many seconds from now the {{{Request}}} will actually expire. |
822 | 49 | Ruud Klaver | '''SIPRequestDidEnd''':: |
823 | 49 | Ruud Klaver | This notification will be sent when a {{{Request}}} object enters the {{{TERMINATED}}} state and can no longer be used. |
824 | 49 | Ruud Klaver | [[BR]]''timestamp'':[[BR]] |
825 | 49 | Ruud Klaver | A {{{datetime.datetime}}} object indicating when the notification was sent. |
826 | 46 | Ruud Klaver | |
827 | 51 | Ruud Klaver | === Message === |
828 | 51 | Ruud Klaver | |
829 | 51 | Ruud Klaver | The {{{sipsimple.primitives.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]. |
830 | 51 | Ruud Klaver | It is a one-shot object that manages only one {{{Request}}} object. |
831 | 51 | Ruud Klaver | |
832 | 51 | Ruud Klaver | ==== attributes ==== |
833 | 51 | Ruud Klaver | |
834 | 64 | Ruud Klaver | '''from_uri''':: |
835 | 64 | Ruud Klaver | The SIP URI to put in the {{{From}}} header of the {{{MESSAGE}}} request, in the form of a {{{SIPURI}}} object. |
836 | 51 | Ruud Klaver | This attribute is set on instantiation and is read-only. |
837 | 51 | Ruud Klaver | '''to_uri''':: |
838 | 51 | Ruud Klaver | The SIP URI to put in the {{{To}}} header of the {{{MESSAGE}}} request, in the form of a {{{SIPURI}}} object. |
839 | 51 | Ruud Klaver | This attribute is set on instantiation and is read-only. |
840 | 51 | Ruud Klaver | '''route''':: |
841 | 51 | Ruud Klaver | Where to send the {{{MESSAGE}}} request to, including IP, port and transport, in the form of a {{{SIPURI}}} object. |
842 | 51 | Ruud Klaver | This will also be included in the {{{Route}}} header of the request. |
843 | 51 | Ruud Klaver | This attribute is set on instantiation and is read-only. |
844 | 51 | Ruud Klaver | '''content_type''':: |
845 | 51 | Ruud Klaver | What string to put as content type in the {{{Content-Type}}} headers. |
846 | 51 | Ruud Klaver | It is set on instantiation and is read-only. |
847 | 51 | Ruud Klaver | '''body''':: |
848 | 51 | Ruud Klaver | The body of the {{{MESSAGE}}} request as a string. |
849 | 1 | Adrian Georgescu | If no body was specified, this attribute is {{{None}}} |
850 | 1 | Adrian Georgescu | It is set on instantiation and is read-only. |
851 | 64 | Ruud Klaver | '''credentials''':: |
852 | 64 | Ruud Klaver | The credentials to be used when challenged for authentication, represented by a {{{Credentials}}} object. |
853 | 64 | Ruud Klaver | If no credentials were specified, this attribute is {{{None}}}. |
854 | 64 | Ruud Klaver | This attribute is set on instantiation and is read-only. |
855 | 51 | Ruud Klaver | '''is_sent''':: |
856 | 51 | Ruud Klaver | A boolean read-only property indicating if the {{{MESSAGE}}} request was sent. |
857 | 51 | Ruud Klaver | '''in_progress''':: |
858 | 51 | Ruud Klaver | A boolean read-only property indicating if the object is waiting for the response from the remote party. |
859 | 51 | Ruud Klaver | |
860 | 51 | Ruud Klaver | ==== methods ==== |
861 | 51 | Ruud Klaver | |
862 | 51 | Ruud Klaver | '''!__init!__'''(''self'', '''credentials''', '''to_uri''', '''route''', '''content_type''', '''body'''):: |
863 | 51 | Ruud Klaver | Creates a new {{{Message}}} object with the specified arguments. |
864 | 51 | Ruud Klaver | These arguments are documented in the attributes section for this class. |
865 | 51 | Ruud Klaver | '''send'''(''self'', '''timeout'''={{{None}}}):: |
866 | 51 | Ruud Klaver | Send the {{{MESSAGE}}} request to the remote party. |
867 | 51 | Ruud Klaver | [[BR]]''timeout'':[[BR]] |
868 | 51 | Ruud Klaver | This argument as the same meaning as it does for {{{Request.send()}}}. |
869 | 51 | Ruud Klaver | '''end'''(''self''):: |
870 | 51 | Ruud Klaver | Stop trying to send the {{{MESSAGE}}} request. |
871 | 51 | Ruud Klaver | If it was not sent yet, calling this method does nothing. |
872 | 51 | Ruud Klaver | |
873 | 51 | Ruud Klaver | ==== notifications ==== |
874 | 51 | Ruud Klaver | |
875 | 51 | Ruud Klaver | '''SIPMessageDidSucceed''':: |
876 | 51 | Ruud Klaver | This notification will be sent when the remote party acknowledged the reception of the {{{MESSAGE}}} request. |
877 | 52 | Ruud Klaver | It has not data attributes. |
878 | 51 | Ruud Klaver | '''SIPMessageDidFail''':: |
879 | 51 | Ruud Klaver | This notification will be sent when transmission of the {{{MESSAGE}}} request fails for whatever reason. |
880 | 51 | Ruud Klaver | [[BR]]''code'':[[BR]] |
881 | 1 | Adrian Georgescu | An int indicating the SIP or internal PJSIP code that was given in response to the {{{MESSAGE}}} request. |
882 | 1 | Adrian Georgescu | This is 0 if the failure is caused by an internal error. |
883 | 1 | Adrian Georgescu | [[BR]]''reason'':[[BR]] |
884 | 1 | Adrian Georgescu | A status string describing the failure, either taken from the SIP response or the internal error. |
885 | 52 | Ruud Klaver | |
886 | 52 | Ruud Klaver | === Registration === |
887 | 52 | Ruud Klaver | |
888 | 52 | Ruud Klaver | The {{{sipsimple.primitives.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. |
889 | 52 | Ruud Klaver | For details, see [http://tools.ietf.org/html/rfc3261 RFC 3261]. |
890 | 52 | Ruud Klaver | 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. |
891 | 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. |
892 | 1 | Adrian Georgescu | |
893 | 52 | Ruud Klaver | ==== attributes ==== |
894 | 69 | Ruud Klaver | |
895 | 64 | Ruud Klaver | '''uri'':: |
896 | 64 | Ruud Klaver | The SIP URI of the account the {{{Registration}}} is for in the form of a {{{SIPURI}}} object. |
897 | 52 | Ruud Klaver | '''credentials''':: |
898 | 64 | Ruud Klaver | The credentials to be used when challenged for authentication by the registrar, represented by a {{{Credentials}}} object. |
899 | 64 | Ruud Klaver | 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. |
900 | 52 | Ruud Klaver | 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. |
901 | 52 | Ruud Klaver | '''duration''':: |
902 | 52 | Ruud Klaver | The amount of time in seconds to request the registration for at the registrar. |
903 | 52 | Ruud Klaver | This attribute is set at object instantiation and can be updated for subsequent {{{REGISTER}}} requests. |
904 | 52 | Ruud Klaver | '''is_registered''':: |
905 | 52 | Ruud Klaver | A boolean read-only property indicating if this object is currently registered. |
906 | 52 | Ruud Klaver | '''contact_uri''':: |
907 | 52 | Ruud Klaver | If the {{{Registration}}} object is registered, this attribute contains the latest contact URI that was sent to the registrar as a {{{SIPURI}}} object. |
908 | 1 | Adrian Georgescu | Otherwise, this attribute is {{{None}}} |
909 | 52 | Ruud Klaver | '''expires_in''':: |
910 | 52 | Ruud Klaver | If registered, this read-only property indicates in how many seconds from now this {{{Registration}}} will expire. |
911 | 52 | Ruud Klaver | If this is not the case, this property is 0. |
912 | 52 | Ruud Klaver | |
913 | 52 | Ruud Klaver | ==== methods ==== |
914 | 52 | Ruud Klaver | |
915 | 64 | Ruud Klaver | '''!__init!__'''(''self'', '''uri''', '''credentials'''={{{None}}}, '''duration'''=300):: |
916 | 52 | Ruud Klaver | Creates a new {{{Registration}}} object with the specified arguments. |
917 | 52 | Ruud Klaver | These arguments are documented in the attributes section for this class. |
918 | 52 | Ruud Klaver | '''register'''(''self'', '''contact_uri''', '''route''', '''timeout'''={{{None}}}):: |
919 | 52 | Ruud Klaver | Calling this method will attempt to send a new {{{REGISTER}}} request to the registrar provided, whatever state the object is in. |
920 | 52 | Ruud Klaver | If the object is currently busy sending a {{{REGISTER}}}, this request will be preempted for the new one. |
921 | 52 | Ruud Klaver | Once sent, the {{{Registration}}} object will send either a {{{SIPRegistrationDidSucceed}}} or a {{{SIPRegistrationDidFail}}} notification. |
922 | 58 | Ruud Klaver | The {{{contact_uri}}} argument is mentioned in the attributes section of this class. |
923 | 52 | Ruud Klaver | The {{{route}}} argument specifies the IP address, port and transport of the SIP registrar in the form of a {{{Route}}} object and {{{timeout}}} has the same meaning as it does for {{{Request.send()}}}. |
924 | 52 | Ruud Klaver | '''end'''(''self'', '''timeout'''={{{None}}}):: |
925 | 52 | Ruud Klaver | 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. |
926 | 52 | Ruud Klaver | The {{{Route}}} used for this will be the same as the last successfully sent {{{REGISTER}}} request. |
927 | 52 | Ruud Klaver | If another {{{REGISTER}}} is currently being sent, it will be preempted. |
928 | 71 | Adrian Georgescu | When the unregistering {{{REGISTER}}} request is sent, a {{{SIPRegistrationWillEnd}}} notification is sent. |
929 | 86 | Ruud Klaver | 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. |
930 | 52 | Ruud Klaver | Calling this method when the object is not registered will do nothing. |
931 | 52 | Ruud Klaver | The {{{timeout}}} argument has the same meaning as for the {{{register()}}} method. |
932 | 52 | Ruud Klaver | |
933 | 52 | Ruud Klaver | ==== notifications ==== |
934 | 52 | Ruud Klaver | |
935 | 52 | Ruud Klaver | '''SIPRegistrationDidSucceed''':: |
936 | 52 | Ruud Klaver | This notification will be sent when the {{{register()}}} method was called and the registration succeeded. |
937 | 52 | Ruud Klaver | [[BR]]''code'':[[BR]] |
938 | 52 | Ruud Klaver | The SIP response code as received from the registrar as an int. |
939 | 52 | Ruud Klaver | [[BR]]''reason'':[[BR]] |
940 | 52 | Ruud Klaver | The reason string received from the SIP registrar. |
941 | 52 | Ruud Klaver | [[BR]]''route'':[[BR]] |
942 | 52 | Ruud Klaver | The {{{Route}}} object passed as an argument to the {{{register()}}} method. |
943 | 52 | Ruud Klaver | [[BR]]''contact_uri'':[[BR]] |
944 | 52 | Ruud Klaver | The contact URI that was sent to the registrar as a {{{SIPURI}}} object. |
945 | 52 | Ruud Klaver | [[BR]]''contact_uri_list'':[[BR]] |
946 | 52 | Ruud Klaver | A full list of contact URIs that are registered for this SIP account, including the one used for this registration. |
947 | 52 | Ruud Klaver | The format of this data attribute is a list of 2-item tuples. |
948 | 52 | Ruud Klaver | The first item is a SIP URI indicating the contact URI, the second item is a dictionary of additional parameters, including the {{{expires}}} parameter. |
949 | 52 | Ruud Klaver | [[BR]]''expires_in'':[[BR]] |
950 | 52 | Ruud Klaver | The number of seconds before this registration expires |
951 | 52 | Ruud Klaver | '''SIPRegistrationDidFail''':: |
952 | 52 | Ruud Klaver | This notification will be sent when the {{{register()}}} method was called and the registration failed, for whatever reason. |
953 | 52 | Ruud Klaver | [[BR]]''code'':[[BR]] |
954 | 52 | Ruud Klaver | The SIP response code as received from the registrar as an int. |
955 | 52 | Ruud Klaver | This can also be a PJSIP generated response code, or 0 if the failure was because of an internal error. |
956 | 52 | Ruud Klaver | [[BR]]''reason'':[[BR]] |
957 | 52 | Ruud Klaver | The reason string received from the SIP registrar or the error string. |
958 | 52 | Ruud Klaver | [[BR]]''route'':[[BR]] |
959 | 52 | Ruud Klaver | The {{{Route}}} object passed as an argument to the {{{register()}}} method. |
960 | 52 | Ruud Klaver | '''SIPRegistrationWillExpire''':: |
961 | 52 | Ruud Klaver | This notification will be sent when a registration will expire soon. |
962 | 1 | Adrian Georgescu | It should be used as an indication to re-perform DNS lookup of the registrar and call the {{{register()}}} method. |
963 | 69 | Ruud Klaver | [[BR]]''expires'':[[BR]] |
964 | 58 | Ruud Klaver | The number of seconds in which the registration will expire. |
965 | 52 | Ruud Klaver | '''SIPRegistrationWillEnd''':: |
966 | 52 | Ruud Klaver | Will be sent whenever the {{{end()}}} method was called and an unregistering {{{REGISTER}}} is sent. |
967 | 52 | Ruud Klaver | '''SIPRegistrationDidNotEnd''':: |
968 | 52 | Ruud Klaver | This notification will be sent when the unregistering {{{REGISTER}}} request failed for some reason. |
969 | 52 | Ruud Klaver | [[BR]]''code'':[[BR]] |
970 | 52 | Ruud Klaver | The SIP response code as received from the registrar as an int. |
971 | 52 | Ruud Klaver | This can also be a PJSIP generated response code, or 0 if the failure was because of an internal error. |
972 | 52 | Ruud Klaver | [[BR]]''reason'':[[BR]] |
973 | 52 | Ruud Klaver | The reason string received from the SIP registrar or the error string. |
974 | 52 | Ruud Klaver | '''SIPRegistrationDidEnd''':: |
975 | 52 | Ruud Klaver | This notification will be sent when a {{{Registration}}} has become unregistered. |
976 | 58 | Ruud Klaver | [[BR]]''expired'':[[BR]] |
977 | 52 | Ruud Klaver | This boolean indicates if the object is unregistered because the registration expired, in which case it will be set to {{{True}}}. |
978 | 52 | Ruud Klaver | If this data attribute is {{{False}}}, it means that unregistration was explicitly requested through the {{{end()}}} method. |
979 | 52 | Ruud Klaver | |
980 | 52 | Ruud Klaver | ==== example code ==== |
981 | 51 | Ruud Klaver | |
982 | 1 | Adrian Georgescu | For an example on how to use this object, see the Integration section. |
983 | 1 | Adrian Georgescu | |
984 | 1 | Adrian Georgescu | === Publication === |
985 | 1 | Adrian Georgescu | |
986 | 1 | Adrian Georgescu | Publication of SIP events is an Internet standard published at [http://tools.ietf.org/html/rfc3903 RFC 3903]. |
987 | 70 | 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. |
988 | 1 | Adrian Georgescu | |
989 | 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. |
990 | 69 | Ruud Klaver | This object is similar in behaviour to the {{{Registration}}} object, as it is also based on a sequence of {{{Request}}} objects. |
991 | 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. |
992 | 1 | Adrian Georgescu | |
993 | 1 | Adrian Georgescu | ==== attributes ==== |
994 | 1 | Adrian Georgescu | |
995 | 69 | Ruud Klaver | '''uri'':: |
996 | 69 | Ruud Klaver | The SIP URI of the account the {{{Publication}}} is for in the form of a {{{SIPURI}}} object. |
997 | 69 | Ruud Klaver | '''event'':: |
998 | 69 | Ruud Klaver | The name of the event this object is publishing for the specified SIP URI, as a string. |
999 | 69 | Ruud Klaver | '''content_type'':: |
1000 | 69 | Ruud Klaver | The {{{Content-Type}}} of the body that will be in the {{{PUBLISH}}} requests. |
1001 | 69 | Ruud Klaver | Typically this will remain the same throughout the publication session, but the attribute may be updated by the application if needed. |
1002 | 69 | Ruud Klaver | Note that this attribute needs to be in the typical MIME type form, containing a "/" character. |
1003 | 1 | Adrian Georgescu | '''credentials''':: |
1004 | 69 | Ruud Klaver | The credentials to be used when challenged for authentication by the presence agent, represented by a {{{Credentials}}} object. |
1005 | 69 | Ruud Klaver | 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. |
1006 | 69 | Ruud Klaver | Note that, in contrast to most other classes mentioned in this document, the {{{Publication}}} class does not make a copy of the {{{Credentials}}} object on instantiation, but instead retains a reference to it. |
1007 | 69 | Ruud Klaver | '''duration''':: |
1008 | 69 | Ruud Klaver | The amount of time in seconds that the publication should be valid for. |
1009 | 69 | Ruud Klaver | This attribute is set at object instantiation and can be updated for subsequent {{{PUBLISH}}} requests. |
1010 | 69 | Ruud Klaver | '''is_published''':: |
1011 | 69 | Ruud Klaver | A boolean read-only property indicating if this object is currently published. |
1012 | 69 | Ruud Klaver | '''expires_in''':: |
1013 | 69 | Ruud Klaver | If published, this read-only property indicates in how many seconds from now this {{{Publication}}} will expire. |
1014 | 69 | Ruud Klaver | If this is not the case, this property is 0. |
1015 | 1 | Adrian Georgescu | |
1016 | 1 | Adrian Georgescu | ==== methods ==== |
1017 | 1 | Adrian Georgescu | |
1018 | 69 | Ruud Klaver | '''!__init!__'''(''self'', '''uri''', '''event''', '''content_type''', '''credentials'''={{{None}}}, '''duration'''=300):: |
1019 | 69 | Ruud Klaver | Creates a new {{{Publication}}} object with the specified arguments. |
1020 | 69 | Ruud Klaver | These arguments are documented in the attributes section for this class. |
1021 | 69 | Ruud Klaver | '''publish'''(''self'', '''body''', '''route''', '''timeout'''={{{None}}}):: |
1022 | 69 | Ruud Klaver | Send an actual {{{PUBLISH}}} request to the specified presence agent. |
1023 | 69 | Ruud Klaver | [[BR]]''body'':[[BR]] |
1024 | 69 | Ruud Klaver | The body to place in the {{{PUBLISH}}} request as a string. |
1025 | 69 | Ruud Klaver | This body needs to be of the content type specified at object creation. |
1026 | 69 | Ruud Klaver | For the initial request, a body will need to be specified. |
1027 | 69 | Ruud Klaver | For subsequent refreshing {{{PUBLISH}}} requests, the body can be {{{None}}} to indicate that the last published body should be refreshed. |
1028 | 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}}}. |
1029 | 1 | Adrian Georgescu | [[BR]]''route'':[[BR]] |
1030 | 69 | Ruud Klaver | The host where the request should be sent to in the form of a {{{Route}}} object. |
1031 | 69 | Ruud Klaver | [[BR]]''timeout'':[[BR]] |
1032 | 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. |
1033 | 69 | Ruud Klaver | This is is {{{None}}}, the internal 408 is only triggered by the internal PJSIP transaction timeout. |
1034 | 69 | Ruud Klaver | Note that, even if the timeout is specified, the PJSIP timeout is also still valid. |
1035 | 69 | Ruud Klaver | '''end'''(''self'', '''timeout'''={{{None}}}):: |
1036 | 69 | Ruud Klaver | End the publication by sending a {{{PUBLISH}}} request with an {{{Expires}}} header of 0. |
1037 | 69 | Ruud Klaver | If the object is not published, this will result in a {{{PublicationError}}} being thrown. |
1038 | 69 | Ruud Klaver | [[BR]]''timeout'':[[BR]] |
1039 | 69 | Ruud Klaver | The meaning of this argument is the same as it is for the {{{publish()}}} method. |
1040 | 1 | Adrian Georgescu | |
1041 | 1 | Adrian Georgescu | ==== notifications ==== |
1042 | 1 | Adrian Georgescu | |
1043 | 69 | Ruud Klaver | '''SIPPublicationDidSucceed''':: |
1044 | 69 | Ruud Klaver | This notification will be sent when the {{{publish()}}} method was called and the publication succeeded. |
1045 | 69 | Ruud Klaver | [[BR]]''code'':[[BR]] |
1046 | 69 | Ruud Klaver | The SIP response code as received from the SIP presence agent as an int. |
1047 | 69 | Ruud Klaver | [[BR]]''reason'':[[BR]] |
1048 | 69 | Ruud Klaver | The reason string received from the SIP presence agent. |
1049 | 69 | Ruud Klaver | [[BR]]''route'':[[BR]] |
1050 | 69 | Ruud Klaver | The {{{Route}}} object passed as an argument to the {{{publish()}}} method. |
1051 | 69 | Ruud Klaver | [[BR]]''expires_in'':[[BR]] |
1052 | 69 | Ruud Klaver | The number of seconds before this publication expires |
1053 | 69 | Ruud Klaver | '''SIPPublicationDidFail''':: |
1054 | 69 | Ruud Klaver | This notification will be sent when the {{{publish()}}} method was called and the publication failed, for whatever reason. |
1055 | 69 | Ruud Klaver | [[BR]]''code'':[[BR]] |
1056 | 69 | Ruud Klaver | The SIP response code as received from the presence agent as an int. |
1057 | 69 | Ruud Klaver | This can also be a PJSIP generated response code, or 0 if the failure was because of an internal error. |
1058 | 69 | Ruud Klaver | [[BR]]''reason'':[[BR]] |
1059 | 69 | Ruud Klaver | The reason string received from the presence agent or the error string. |
1060 | 69 | Ruud Klaver | [[BR]]''route'':[[BR]] |
1061 | 69 | Ruud Klaver | The {{{Route}}} object passed as an argument to the {{{publish()}}} method. |
1062 | 69 | Ruud Klaver | '''SIPPublicationWillExpire''':: |
1063 | 69 | Ruud Klaver | This notification will be sent when a publication will expire soon. |
1064 | 69 | Ruud Klaver | It should be used as an indication to re-perform DNS lookup of the presence agent and call the {{{publish()}}} method. |
1065 | 69 | Ruud Klaver | [[BR]]''expires'':[[BR]] |
1066 | 69 | Ruud Klaver | The number of seconds in which the publication will expire. |
1067 | 69 | Ruud Klaver | '''SIPPublicationWillEnd''':: |
1068 | 69 | Ruud Klaver | Will be sent whenever the {{{end()}}} method was called and an unpublishing {{{PUBLISH}}} is sent. |
1069 | 69 | Ruud Klaver | '''SIPPublicationDidNotEnd''':: |
1070 | 69 | Ruud Klaver | This notification will be sent when the unpublishing {{{PUBLISH}}} request failed for some reason. |
1071 | 69 | Ruud Klaver | [[BR]]''code'':[[BR]] |
1072 | 69 | Ruud Klaver | The SIP response code as received from the presence agent as an int. |
1073 | 69 | Ruud Klaver | This can also be a PJSIP generated response code, or 0 if the failure was because of an internal error. |
1074 | 69 | Ruud Klaver | [[BR]]''reason'':[[BR]] |
1075 | 69 | Ruud Klaver | The reason string received from the presence agent or the error string. |
1076 | 69 | Ruud Klaver | '''SIPPublicationDidEnd''':: |
1077 | 69 | Ruud Klaver | This notification will be sent when a {{{Publication}}} has become unpublished. |
1078 | 69 | Ruud Klaver | [[BR]]''expired'':[[BR]] |
1079 | 69 | Ruud Klaver | This boolean indicates if the object is unpublished because the publication expired, in which case it will be set to {{{True}}}. |
1080 | 69 | Ruud Klaver | If this data attribute is {{{False}}}, it means that unpublication was explicitly requested through the {{{end()}}} method. |
1081 | 1 | Adrian Georgescu | |
1082 | 86 | Ruud Klaver | === IncomingRequest === |
1083 | 86 | Ruud Klaver | |
1084 | 86 | Ruud Klaver | This is a relatively simple object that can manage responding to incoming requests in a single transaction. |
1085 | 86 | Ruud Klaver | For this reason it does not handle requests that create a dialog. |
1086 | 86 | Ruud Klaver | 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}}}. |
1087 | 86 | Ruud Klaver | Receiving {{{INVITE}}}, {{{SUBSCRIBE}}}, {{{ACK}}} and {{{BYE}}} through this object is not supported. |
1088 | 86 | Ruud Klaver | |
1089 | 86 | Ruud Klaver | The application is notified of an incoming request through the {{{SIPIncomingRequestGotRequest}}} notification. |
1090 | 86 | Ruud Klaver | It can answer this request by calling the {{{answer}}} method on the sender of this notification. |
1091 | 86 | Ruud Klaver | Note that if the {{{IncomingRequest}}} object gets destroyed before it is answered, a 500 response is automatically sent. |
1092 | 86 | Ruud Klaver | |
1093 | 86 | Ruud Klaver | ==== attributes ==== |
1094 | 86 | Ruud Klaver | |
1095 | 86 | Ruud Klaver | '''state''':: |
1096 | 86 | Ruud Klaver | This read-only attribute indicates the state the object is in. |
1097 | 86 | Ruud Klaver | This can be {{{None}}} if the object was created by the application, essentially meaning the object is inert, {{{"incoming"}}} or {{{"answered"}}}. |
1098 | 86 | Ruud Klaver | |
1099 | 86 | Ruud Klaver | ==== methods ==== |
1100 | 86 | Ruud Klaver | |
1101 | 86 | Ruud Klaver | '''answer'''(''self'', '''code''', '''reason'''={{{None}}}, '''extra_headers'''={{{None}}}):: |
1102 | 86 | Ruud Klaver | Reply to the received request with a final response. |
1103 | 86 | Ruud Klaver | [[BR]]''code'':[[BR]] |
1104 | 86 | Ruud Klaver | The SIP response code to send. |
1105 | 86 | Ruud Klaver | This should be 200 or higher. |
1106 | 86 | Ruud Klaver | [[BR]]''reason'':[[BR]] |
1107 | 86 | Ruud Klaver | The reason text to include in the response. |
1108 | 86 | Ruud Klaver | If this is {{{None}}}, the default text for the given response code is used. |
1109 | 86 | Ruud Klaver | [[BR]]''extra_headers'':[[BR]] |
1110 | 86 | Ruud Klaver | The extra headers to include in the response as an iterable of header objects. |
1111 | 86 | Ruud Klaver | |
1112 | 86 | Ruud Klaver | ==== notifications ==== |
1113 | 86 | Ruud Klaver | |
1114 | 86 | Ruud Klaver | '''SIPIncomingRequestGotRequest''':: |
1115 | 86 | Ruud Klaver | This notification will be sent when a new {{{IncomingRequest}}} is created as result of a received request. |
1116 | 86 | Ruud Klaver | The application should listen for this notification, retain a reference to the object that sent it and answer it. |
1117 | 86 | Ruud Klaver | [[BR]]''timestamp'':[[BR]] |
1118 | 86 | Ruud Klaver | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1119 | 86 | Ruud Klaver | [[BR]]''method'':[[BR]] |
1120 | 86 | Ruud Klaver | The method of the SIP request as a string. |
1121 | 86 | Ruud Klaver | [[BR]]''request_uri'':[[BR]] |
1122 | 86 | Ruud Klaver | The request URI of the request as a {{{FrozenSIPURI}}} object. |
1123 | 86 | Ruud Klaver | [[BR]]''headers'':[[BR]] |
1124 | 86 | Ruud Klaver | The headers of the request as a dict, the values of which are the relevant header objects. |
1125 | 86 | Ruud Klaver | [[BR]]''body'':[[BR]] |
1126 | 86 | Ruud Klaver | The body of the request as a string, or {{{None}}} if no body was included. |
1127 | 86 | Ruud Klaver | '''SIPIncomingRequestSentResponse''':: |
1128 | 86 | Ruud Klaver | This notification is sent when a response to the request is sent by the object. |
1129 | 86 | Ruud Klaver | [[BR]]''timestamp'':[[BR]] |
1130 | 86 | Ruud Klaver | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1131 | 86 | Ruud Klaver | [[BR]]''code'':[[BR]] |
1132 | 86 | Ruud Klaver | The code of the SIP response as an int. |
1133 | 86 | Ruud Klaver | [[BR]]''reason'':[[BR]] |
1134 | 86 | Ruud Klaver | The reason text of the SIP response as an int. |
1135 | 86 | Ruud Klaver | [[BR]]''headers'':[[BR]] |
1136 | 86 | Ruud Klaver | The headers of the response as a dict, the values of which are the relevant header objects. |
1137 | 86 | Ruud Klaver | [[BR]]''body'':[[BR]] |
1138 | 86 | Ruud Klaver | This will be {{{None}}}. |
1139 | 86 | Ruud Klaver | |
1140 | 1 | Adrian Georgescu | === Subscription === |
1141 | 1 | Adrian Georgescu | |
1142 | 1 | Adrian Georgescu | Subscription and notifications for SIP events is an Internet standard published at [http://tools.ietf.org/html/rfc3856 RFC 3856]. |
1143 | 1 | Adrian Georgescu | |
1144 | 59 | Ruud Klaver | This SIP primitive class represents a subscription to a specific event type of a particular SIP URI. |
1145 | 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. |
1146 | 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. |
1147 | 1 | Adrian Georgescu | Whenever a {{{NOTIFY}}} is received, the application will receive the {{{SIPSubscriptionGotNotify}}} event. |
1148 | 1 | Adrian Georgescu | |
1149 | 1 | Adrian Georgescu | Internally a {{{Subscription}}} object has a state machine, which reflects the state of the subscription. |
1150 | 59 | Ruud Klaver | 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}}}. |
1151 | 59 | Ruud Klaver | The last three states are directly copied from the contents of the {{{Subscription-State}}} header of the received {{{NOTIFY}}} request. |
1152 | 1 | 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. |
1153 | 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. |
1154 | 1 | Adrian Georgescu | This notification is only informational, an application using this object should take actions based on the other notifications sent by this object. |
1155 | 1 | Adrian Georgescu | |
1156 | 1 | Adrian Georgescu | ==== attributes ==== |
1157 | 1 | Adrian Georgescu | |
1158 | 59 | Ruud Klaver | '''state''':: |
1159 | 59 | Ruud Klaver | Indicates which state the internal state machine is in. |
1160 | 1 | Adrian Georgescu | See the previous section for a list of states the state machine can be in. |
1161 | 1 | Adrian Georgescu | '''from_uri''':: |
1162 | 71 | Adrian Georgescu | The SIP URI to be put in the {{{From}}} header of the {{{SUBSCRIBE}}} requests in the form of a {{{SIPURI}}} object. |
1163 | 1 | Adrian Georgescu | This attribute is set on object instantiation and is read-only. |
1164 | 59 | Ruud Klaver | '''to_uri''':: |
1165 | 59 | Ruud Klaver | The SIP URI that is the target for the subscription in the form of a {{{SIPURI}}} object. |
1166 | 59 | Ruud Klaver | This attribute is set on object instantiation and is read-only. |
1167 | 1 | Adrian Georgescu | '''contact_uri''':: |
1168 | 71 | Adrian Georgescu | The SIP URI to be put in the {{{Contact}}} header of the {{{SUBSCRIBE}}} requests in the form of a {{{SIPURI}}} object. |
1169 | 1 | Adrian Georgescu | This attribute is set on object instantiation and is read-only. |
1170 | 1 | Adrian Georgescu | '''event''':: |
1171 | 1 | Adrian Georgescu | The event package for which the subscription is as a string. |
1172 | 1 | Adrian Georgescu | This attribute is set on object instantiation and is read-only. |
1173 | 59 | Ruud Klaver | '''route''':: |
1174 | 59 | Ruud Klaver | The outbound proxy to use in the form of a {{{Route}}} object. |
1175 | 59 | Ruud Klaver | This attribute is set on object instantiation and is read-only. |
1176 | 1 | Adrian Georgescu | '''credentials''':: |
1177 | 59 | Ruud Klaver | The SIP credentials needed to authenticate at the SIP proxy in the form of a {{{Credentials}}} object. |
1178 | 59 | Ruud Klaver | If none was specified when creating the {{{Subscription}}} object, this attribute is {{{None}}}. |
1179 | 59 | Ruud Klaver | This attribute is set on object instantiation and is read-only. |
1180 | 59 | Ruud Klaver | '''refresh''':: |
1181 | 59 | Ruud Klaver | The refresh interval in seconds that was requested on object instantiation as an int. |
1182 | 59 | Ruud Klaver | This attribute is set on object instantiation and is read-only. |
1183 | 59 | Ruud Klaver | '''extra_headers''':: |
1184 | 59 | Ruud Klaver | This contains the dictionary of extra headers that was last passed to a successful call to the {{{subscribe()}}} method. |
1185 | 59 | Ruud Klaver | If the argument was not provided, this attribute is an empty dictionary. |
1186 | 59 | Ruud Klaver | This attribute is read-only. |
1187 | 59 | Ruud Klaver | '''content_type''':: |
1188 | 59 | Ruud Klaver | This attribute contains the {{{Content-Type}}} of the body that was last passed to a successful call to the {{{subscribe()}}} method. |
1189 | 59 | Ruud Klaver | If the argument was not provided, this attribute is {{{None}}}. |
1190 | 1 | Adrian Georgescu | '''body''':: |
1191 | 1 | Adrian Georgescu | This attribute contains the {{{body}}} string argument that was last passed to a successful call to the {{{subscribe()}}} method. |
1192 | 1 | Adrian Georgescu | If the argument was not provided, this attribute is {{{None}}}. |
1193 | 59 | Ruud Klaver | |
1194 | 59 | Ruud Klaver | ==== methods ==== |
1195 | 59 | Ruud Klaver | |
1196 | 59 | Ruud Klaver | '''!__init!__'''(''self'', '''from_uri''', '''to_uri''', '''contact_uri, '''event''', '''route''', '''credentials'''={{{None}}}, '''refresh'''=300):: |
1197 | 59 | Ruud Klaver | Creates a new {{{Subscription}}} object which will be in the {{{NULL}}} state. |
1198 | 59 | Ruud Klaver | The arguments for this method are documented in the attributes section above. |
1199 | 59 | Ruud Klaver | '''subscribe'''(''self'', '''extra_headers'''={{{None}}}, '''content_type'''={{{None}}}, '''body'''={{{None}}}, '''timeout'''={{{None}}}):: |
1200 | 59 | Ruud Klaver | Calling this method triggers sending a {{{SUBSCRIBE}}} request to the presence agent. |
1201 | 1 | Adrian Georgescu | The arguments passed will be stored and used for subsequent refreshing {{{SUBSCRIBE}}} requests. |
1202 | 59 | Ruud Klaver | This method may be used both to send the initial request and to update the arguments while the subscription is ongoing. |
1203 | 59 | Ruud Klaver | It may not be called when the object is in the {{{TERMINATED}}} state. |
1204 | 59 | Ruud Klaver | [[BR]]''extra_headers'':[[BR]] |
1205 | 59 | Ruud Klaver | A dictionary of additional headers to include in the {{{SUBSCRIBE}}} requests. |
1206 | 59 | Ruud Klaver | [[BR]]''content_type'':[[BR]] |
1207 | 59 | Ruud Klaver | The {{{Content-Type}}} of the supplied {{{body}}} argument as a string. |
1208 | 59 | Ruud Klaver | If this argument is supplied, the {{{body}}} argument cannot be {{{None}}}. |
1209 | 59 | Ruud Klaver | [[BR]]''body'':[[BR]] |
1210 | 59 | Ruud Klaver | The optional body to include in the {{{SUBSCRIBE}}} request as a string. |
1211 | 59 | Ruud Klaver | If this argument is supplied, the {{{content_type}}} argument cannot be {{{None}}}. |
1212 | 59 | Ruud Klaver | [[BR]]''timeout'':[[BR]] |
1213 | 59 | Ruud Klaver | This can be either an int or a float, indicating in how many seconds the request should timeout with an internally generated 408 response. |
1214 | 59 | Ruud Klaver | If this is {{{None}}}, the internal 408 is only triggered by the internal PJSIP transaction timeout. |
1215 | 59 | Ruud Klaver | Note that, even if the timeout is specified, the PJSIP timeout is also still valid. |
1216 | 59 | Ruud Klaver | '''end'''(''self'', '''timeout'''={{{None}}}):: |
1217 | 59 | Ruud Klaver | This will end the subscription by sending a {{{SUBSCRIBE}}} request with an {{{Expires}}} value of 0. |
1218 | 1 | Adrian Georgescu | If this object is no longer subscribed, this method will return without performing any action. |
1219 | 1 | Adrian Georgescu | This method cannot be called when the object is in the {{{NULL}}} state. |
1220 | 1 | Adrian Georgescu | The {{{timeout}}} argument has the same meaning as it does for the {{{subscribe()}}} method. |
1221 | 1 | Adrian Georgescu | |
1222 | 1 | Adrian Georgescu | ==== notifications ==== |
1223 | 1 | Adrian Georgescu | |
1224 | 1 | Adrian Georgescu | '''SIPSubscriptionChangedState''':: |
1225 | 59 | Ruud Klaver | This notification will be sent every time the internal state machine of a {{{Subscription}}} object changes state. |
1226 | 59 | Ruud Klaver | [[BR]]''timestamp'':[[BR]] |
1227 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1228 | 1 | Adrian Georgescu | [[BR]]''prev_state'':[[BR]] |
1229 | 59 | Ruud Klaver | The previous state that the sate machine was in. |
1230 | 59 | Ruud Klaver | [[BR]]''state'':[[BR]] |
1231 | 59 | Ruud Klaver | The new state the state machine moved into. |
1232 | 59 | Ruud Klaver | '''SIPSubscriptionWillStart''':: |
1233 | 59 | Ruud Klaver | This notification will be emitted when the initial {{{SUBSCRIBE}}} request is sent. |
1234 | 59 | Ruud Klaver | [[BR]]''timestamp'':[[BR]] |
1235 | 59 | Ruud Klaver | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1236 | 59 | Ruud Klaver | '''SIPSubscriptionDidStart''':: |
1237 | 29 | Luci Stanescu | This notification will be sent when the initial {{{SUBSCRIBE}}} was accepted by the presence agent. |
1238 | 29 | Luci Stanescu | [[BR]]''timestamp'':[[BR]] |
1239 | 59 | Ruud Klaver | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1240 | 1 | Adrian Georgescu | '''SIPSubscriptionGotNotify''':: |
1241 | 1 | Adrian Georgescu | This notification will be sent when a {{{NOTIFY}}} is received that corresponds to a particular {{{Subscription}}} object. |
1242 | 59 | Ruud Klaver | Note that this notification could be sent when a {{{NOTIFY}}} without a body is received. |
1243 | 59 | Ruud Klaver | [[BR]]''timestamp'':[[BR]] |
1244 | 59 | Ruud Klaver | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1245 | 59 | Ruud Klaver | [[BR]]''method'':[[BR]] |
1246 | 59 | Ruud Klaver | The method of the SIP request as a string. |
1247 | 59 | Ruud Klaver | This will always be {{{NOTIFY}}}. |
1248 | 59 | Ruud Klaver | [[BR]]''request_uri'':[[BR]] |
1249 | 59 | Ruud Klaver | The request URI of the {{{NOTIFY}}} request as a {{{SIPURI}}} object. |
1250 | 59 | Ruud Klaver | [[BR]]''headers'':[[BR]] |
1251 | 1 | Adrian Georgescu | The headers of the {{{NOTIFY}}} request as a dict. |
1252 | 59 | Ruud Klaver | Each SIP header is represented in its parsed for as long as PJSIP supports it. |
1253 | 59 | Ruud Klaver | The format of the parsed value depends on the header. |
1254 | 59 | Ruud Klaver | [[BR]]''body'':[[BR]] |
1255 | 59 | Ruud Klaver | The body of the {{{NOTIFY}}} request as a string, or {{{None}}} if no body was included. |
1256 | 59 | Ruud Klaver | The content type of the body can be learned from the {{{Content-Type}}} header in the headers data attribute. |
1257 | 59 | Ruud Klaver | '''SIPSubscriptionDidFail''':: |
1258 | 59 | Ruud Klaver | This notification will be sent whenever there is a failure, such as a rejected initial or refreshing {{{SUBSCRIBE}}}. |
1259 | 59 | Ruud Klaver | After this notification the {{{Subscription}}} object is in the {{{TERMINATED}}} state and can no longer be used. |
1260 | 59 | Ruud Klaver | [[BR]]''timestamp'':[[BR]] |
1261 | 59 | Ruud Klaver | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1262 | 59 | Ruud Klaver | [[BR]]''code'':[[BR]] |
1263 | 59 | Ruud Klaver | An integer SIP code from the fatal response that was received from the remote party of generated by PJSIP. |
1264 | 59 | Ruud Klaver | If the error is internal to the SIP core, this attribute will have a value of 0. |
1265 | 59 | Ruud Klaver | [[BR]]''reason'':[[BR]] |
1266 | 71 | Adrian Georgescu | An text string describing the failure that occurred. |
1267 | 59 | Ruud Klaver | '''SIPSubscriptionDidEnd''':: |
1268 | 59 | 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. |
1269 | 1 | Adrian Georgescu | After this notification the {{{Subscription}}} object is in the {{{TERMINATED}}} state and can no longer be used. |
1270 | 56 | Ruud Klaver | [[BR]]''timestamp'':[[BR]] |
1271 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1272 | 1 | Adrian Georgescu | |
1273 | 84 | Ruud Klaver | === IncomingSubscription === |
1274 | 84 | Ruud Klaver | |
1275 | 84 | Ruud Klaver | Subscription and notifications for SIP events is an Internet standard published at [http://tools.ietf.org/html/rfc3856 RFC 3856]. |
1276 | 84 | Ruud Klaver | |
1277 | 84 | Ruud Klaver | 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. |
1278 | 84 | Ruud Klaver | This means that it can accept a {{{SUBSCRIBE}}} request and subsequent refreshing {{{SUBSCRIBE}}}s and sent {{{NOTIFY}}} requests containing event state. |
1279 | 84 | Ruud Klaver | |
1280 | 84 | Ruud Klaver | 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. |
1281 | 84 | Ruud Klaver | This event needs to be known by the {{{Engine}}}, i.e. it should already be present in the {{{events}}} dictionary attribute. |
1282 | 84 | Ruud Klaver | 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. |
1283 | 84 | Ruud Klaver | This will be indicated to the application through a {{{SIPIncomingSubscriptionGotSubscribe}}} notification. |
1284 | 84 | Ruud Klaver | 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. |
1285 | 84 | Ruud Klaver | |
1286 | 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. |
1287 | 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. |
1288 | 84 | Ruud Klaver | Whenever a refreshing {{{SUBSCRIBE}}} is received, the latest contents to be set are sent in the resulting {{{NOTIFY}}} request. |
1289 | 84 | Ruud Klaver | The subscription can be ended by using the {{{end()}}} method. |
1290 | 84 | Ruud Klaver | |
1291 | 84 | Ruud Klaver | ==== attributes ==== |
1292 | 84 | Ruud Klaver | |
1293 | 84 | Ruud Klaver | '''state''':: |
1294 | 84 | Ruud Klaver | Indicates which state the incoming subscription session is in. |
1295 | 84 | Ruud Klaver | This can be one of {{{None}}}, {{{"incoming"}}}, {{{"pending"}}}, {{{"active"}}} or {{{"terminated"}}}. |
1296 | 84 | Ruud Klaver | This attribute is read-only. |
1297 | 84 | Ruud Klaver | '''event''':: |
1298 | 84 | Ruud Klaver | The name of the event package that this {{{IncomingSubscription}}} relates to. |
1299 | 84 | Ruud Klaver | This attribute is a read-only string. |
1300 | 84 | Ruud Klaver | '''content_type''':: |
1301 | 84 | Ruud Klaver | The {{{Content-Type}}} of the last set content in this subscription session. |
1302 | 84 | Ruud Klaver | Inititally this will be {{{None}}}. |
1303 | 84 | Ruud Klaver | This attribute is a read-only string. |
1304 | 84 | Ruud Klaver | '''content''':: |
1305 | 84 | Ruud Klaver | The last set content in this subscription session as a read-only string. |
1306 | 84 | Ruud Klaver | |
1307 | 84 | Ruud Klaver | ==== methods ==== |
1308 | 84 | Ruud Klaver | |
1309 | 84 | Ruud Klaver | '''!__init!__'''(''self''):: |
1310 | 84 | Ruud Klaver | An application should never create an {{{IncomingSubscription}}} object itself. |
1311 | 84 | Ruud Klaver | Doing this will create a useless object in the {{{None}}} state. |
1312 | 84 | Ruud Klaver | '''reject'''(''self'', '''code'''):: |
1313 | 84 | Ruud Klaver | Will reply to the initial {{{SUBSCRIBE}}} with a negative response. |
1314 | 84 | Ruud Klaver | This method can only be called in the {{{"incoming"}}} state and sets the subscription to the {{{"terminated"}}} state. |
1315 | 84 | Ruud Klaver | [[BR]]''code'':[[BR]] |
1316 | 84 | Ruud Klaver | The SIP response code to use. |
1317 | 84 | Ruud Klaver | This should be a negative response, i.e. in the 3xx, 4xx, 5xx or 6xx range. |
1318 | 84 | Ruud Klaver | '''accept_pending'''(''self''):: |
1319 | 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. |
1320 | 84 | Ruud Klaver | The application can later decide to fully accept the subscription or terminate it. |
1321 | 84 | Ruud Klaver | This method can only be called in the {{{"incoming"}}} state. |
1322 | 84 | Ruud Klaver | '''accept'''(''self'', '''content_type'''={{{None}}}, '''content'''={{{None}}}):: |
1323 | 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. |
1324 | 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. |
1325 | 84 | Ruud Klaver | This method can only be called in the {{{"incoming"}}} or {{{"pending"}}} state. |
1326 | 84 | Ruud Klaver | [[BR]]''content_type'':[[BR]] |
1327 | 84 | Ruud Klaver | The Content-Type of the content to be set supplied as a string containing a {{{"/"}}} character. |
1328 | 84 | Ruud Klaver | Note that if this argument is set, the {{{content}}} argument should also be set. |
1329 | 84 | Ruud Klaver | [[BR]]''content'':[[BR]] |
1330 | 84 | Ruud Klaver | The body of the {{{NOTIFY}}} to send when accepting the subscription, as a string. |
1331 | 84 | Ruud Klaver | Note that if this argument is set, the {{{content_type}}} argument should also be set. |
1332 | 84 | Ruud Klaver | '''push_content'''(''self'', '''content_type''', '''content'''):: |
1333 | 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. |
1334 | 84 | Ruud Klaver | This method can only be called in the {{{"active"}}} state. |
1335 | 84 | Ruud Klaver | [[BR]]''content_type'':[[BR]] |
1336 | 84 | Ruud Klaver | The Content-Type of the content to be set supplied as a string containing a {{{"/"}}} character. |
1337 | 84 | Ruud Klaver | [[BR]]''content'':[[BR]] |
1338 | 84 | Ruud Klaver | The body of the {{{NOTIFY}}} as a string. |
1339 | 84 | Ruud Klaver | |
1340 | 84 | Ruud Klaver | ==== notifications ==== |
1341 | 84 | Ruud Klaver | |
1342 | 84 | Ruud Klaver | '''SIPIncomingSubscriptionChangedState''':: |
1343 | 84 | Ruud Klaver | This notification will be sent every time the an {{{IncomingSubscription}}} object changes state. |
1344 | 84 | Ruud Klaver | This notification is mostly indicative, an application should not let its logic depend on it. |
1345 | 84 | Ruud Klaver | [[BR]]''timestamp'':[[BR]] |
1346 | 84 | Ruud Klaver | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1347 | 84 | Ruud Klaver | [[BR]]''prev_state'':[[BR]] |
1348 | 84 | Ruud Klaver | The previous state that the subscription was in. |
1349 | 84 | Ruud Klaver | [[BR]]''state'':[[BR]] |
1350 | 84 | Ruud Klaver | The new state the subscription has. |
1351 | 84 | Ruud Klaver | '''SIPIncomingSubscriptionGotSubscribe''':: |
1352 | 84 | Ruud Klaver | This notification will be sent when a new {{{IncomingSubscription}}} is created as result of an incoming {{{SUBSCRIBE}}} request. |
1353 | 84 | Ruud Klaver | The application should listen for this notification, retain a reference to the object that sent it and either accept or reject it. |
1354 | 84 | Ruud Klaver | [[BR]]''timestamp'':[[BR]] |
1355 | 84 | Ruud Klaver | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1356 | 84 | Ruud Klaver | [[BR]]''method'':[[BR]] |
1357 | 84 | Ruud Klaver | The method of the SIP request as a string, which will be {{{SUBSCRIBE}}}. |
1358 | 84 | Ruud Klaver | [[BR]]''request_uri'':[[BR]] |
1359 | 84 | Ruud Klaver | The request URI of the {{{SUBSCRIBE}}} request as a {{{FrozenSIPURI}}} object. |
1360 | 84 | Ruud Klaver | [[BR]]''headers'':[[BR]] |
1361 | 1 | Adrian Georgescu | The headers of the {{{SUBSCRIBE}}} request as a dict, the values of which are the relevant header objects. |
1362 | 84 | Ruud Klaver | [[BR]]''body'':[[BR]] |
1363 | 86 | Ruud Klaver | The body of the {{{SUBSCRIBE}}} request as a string, or {{{None}}} if no body was included. |
1364 | 84 | Ruud Klaver | '''SIPIncomingSubscriptionGotRefreshingSubscribe''':: |
1365 | 84 | Ruud Klaver | This notification indicates that a refreshing {{{SUBSCRIBE}}} request was received from the subscriber. |
1366 | 84 | Ruud Klaver | It is purely informative, no action needs to be taken by the application as a result of it. |
1367 | 84 | Ruud Klaver | [[BR]]''timestamp'':[[BR]] |
1368 | 84 | Ruud Klaver | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1369 | 84 | Ruud Klaver | [[BR]]''method'':[[BR]] |
1370 | 84 | Ruud Klaver | The method of the SIP request as a string, which will be {{{SUBSCRIBE}}}. |
1371 | 84 | Ruud Klaver | [[BR]]''request_uri'':[[BR]] |
1372 | 84 | Ruud Klaver | The request URI of the {{{SUBSCRIBE}}} request as a {{{FrozenSIPURI}}} object. |
1373 | 1 | Adrian Georgescu | [[BR]]''headers'':[[BR]] |
1374 | 84 | Ruud Klaver | The headers of the {{{SUBSCRIBE}}} request as a dict, the values of which are the relevant header objects. |
1375 | 84 | Ruud Klaver | [[BR]]''body'':[[BR]] |
1376 | 86 | Ruud Klaver | The body of the {{{SUBSCRIBE}}} request as a string, or {{{None}}} if no body was included. |
1377 | 84 | Ruud Klaver | '''SIPIncomingSubscriptionGotUnsubscribe''':: |
1378 | 84 | Ruud Klaver | This notification indicates that a {{{SUBSCRIBE}}} request with an {{{Expires}}} header of 0 was received from the subscriber, effectively requesting to unsubscribe. |
1379 | 84 | Ruud Klaver | It is purely informative, no action needs to be taken by the application as a result of it. |
1380 | 84 | Ruud Klaver | [[BR]]''timestamp'':[[BR]] |
1381 | 84 | Ruud Klaver | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1382 | 84 | Ruud Klaver | [[BR]]''method'':[[BR]] |
1383 | 84 | Ruud Klaver | The method of the SIP request as a string, which will be {{{SUBSCRIBE}}}. |
1384 | 84 | Ruud Klaver | [[BR]]''request_uri'':[[BR]] |
1385 | 84 | Ruud Klaver | The request URI of the {{{SUBSCRIBE}}} request as a {{{FrozenSIPURI}}} object. |
1386 | 84 | Ruud Klaver | [[BR]]''headers'':[[BR]] |
1387 | 1 | Adrian Georgescu | The headers of the {{{SUBSCRIBE}}} request as a dict, the values of which are the relevant header objects. |
1388 | 84 | Ruud Klaver | [[BR]]''body'':[[BR]] |
1389 | 84 | Ruud Klaver | The body of the {{{SUBSCRIBE}}} request or response as a string, or {{{None}}} if no body was included. |
1390 | 84 | Ruud Klaver | '''SIPIncomingSubscriptionAnsweredSubscribe''':: |
1391 | 86 | Ruud Klaver | This notification is sent whenever a response to a {{{SUBSCRIBE}}} request is sent by the object, including an unsubscribing {{{SUBSCRIBE}}}. |
1392 | 84 | Ruud Klaver | It is purely informative, no action needs to be taken by the application as a result of it. |
1393 | 84 | Ruud Klaver | [[BR]]''timestamp'':[[BR]] |
1394 | 84 | Ruud Klaver | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1395 | 84 | Ruud Klaver | [[BR]]''code'':[[BR]] |
1396 | 84 | Ruud Klaver | The code of the SIP response as an int. |
1397 | 84 | Ruud Klaver | [[BR]]''reason'':[[BR]] |
1398 | 84 | Ruud Klaver | The reason text of the SIP response as an int. |
1399 | 84 | Ruud Klaver | [[BR]]''headers'':[[BR]] |
1400 | 84 | Ruud Klaver | The headers of the response as a dict, the values of which are the relevant header objects. |
1401 | 84 | Ruud Klaver | [[BR]]''body'':[[BR]] |
1402 | 84 | Ruud Klaver | This will be {{{None}}}. |
1403 | 84 | Ruud Klaver | '''SIPIncomingSubscriptionSentNotify''':: |
1404 | 84 | Ruud Klaver | This notification indicates that a {{{NOTIFY}}} request was sent to the subscriber. |
1405 | 84 | Ruud Klaver | It is purely informative, no action needs to be taken by the application as a result of it. |
1406 | 84 | Ruud Klaver | [[BR]]''timestamp'':[[BR]] |
1407 | 84 | Ruud Klaver | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1408 | 84 | Ruud Klaver | [[BR]]''method'':[[BR]] |
1409 | 84 | Ruud Klaver | The method of the SIP request as a string, which will be {{{NOTIFY}}}. |
1410 | 84 | Ruud Klaver | [[BR]]''request_uri'':[[BR]] |
1411 | 84 | Ruud Klaver | The request URI of the {{{NOTIFY}}} request as a {{{FrozenSIPURI}}} object. |
1412 | 84 | Ruud Klaver | [[BR]]''headers'':[[BR]] |
1413 | 84 | Ruud Klaver | The headers of the {{{NOTIFY}}} request as a dict, the values of which are the relevant header objects. |
1414 | 84 | Ruud Klaver | [[BR]]''body'':[[BR]] |
1415 | 84 | Ruud Klaver | The body of the {{{NOTIFY}}} request or response as a string, or {{{None}}} if no body was included. |
1416 | 84 | Ruud Klaver | '''SIPIncomingSubscriptionNotifyDidSucceed''':: |
1417 | 84 | Ruud Klaver | This indicates that a positive final response was received from the subscriber in reply to a sent {{{NOTIFY}}} request. |
1418 | 84 | Ruud Klaver | The notification is purely informative, no action needs to be taken by the application as a result of it. |
1419 | 84 | Ruud Klaver | [[BR]]''timestamp'':[[BR]] |
1420 | 84 | Ruud Klaver | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1421 | 84 | Ruud Klaver | [[BR]]''code'':[[BR]] |
1422 | 84 | Ruud Klaver | The code of the SIP response as an int. |
1423 | 84 | Ruud Klaver | [[BR]]''reason'':[[BR]] |
1424 | 84 | Ruud Klaver | The reason text of the SIP response as a string. |
1425 | 84 | Ruud Klaver | [[BR]]''headers'':[[BR]] |
1426 | 84 | Ruud Klaver | The headers of the response as a dict, the values of which are the relevant header objects. |
1427 | 84 | Ruud Klaver | [[BR]]''body'':[[BR]] |
1428 | 84 | Ruud Klaver | This will be {{{None}}}. |
1429 | 84 | Ruud Klaver | '''SIPIncomingSubscriptionNotifyDidFail''':: |
1430 | 84 | Ruud Klaver | 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. |
1431 | 84 | Ruud Klaver | [[BR]]''timestamp'':[[BR]] |
1432 | 84 | Ruud Klaver | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1433 | 84 | Ruud Klaver | [[BR]]''code'':[[BR]] |
1434 | 84 | Ruud Klaver | The code of the SIP response as an int. |
1435 | 84 | Ruud Klaver | If this is 0, the notification was sent as a result of an internal error. |
1436 | 84 | Ruud Klaver | [[BR]]''reason'':[[BR]] |
1437 | 84 | Ruud Klaver | The reason text of the SIP response as a string or the internal error if the code attribute is 0. |
1438 | 1 | Adrian Georgescu | [[BR]]''headers'': (if the notification was caused by a negative response)[[BR]] |
1439 | 56 | Ruud Klaver | The headers of the response as a dict, the values of which are the relevant header objects. |
1440 | 1 | Adrian Georgescu | [[BR]]''body'': (if the notification was caused by a negative response)[[BR]] |
1441 | 1 | Adrian Georgescu | This will be {{{None}}}. |
1442 | 1 | Adrian Georgescu | '''SIPIncomingSubscriptionNotifyDidEnd''':: |
1443 | 1 | Adrian Georgescu | This notification is sent whenever the {{{IncomingSubscription}}} object reaches the {{{"terminated"}}} state and is no longer valid. |
1444 | 1 | Adrian Georgescu | After receiving this notification, the application should not longer try to use the object. |
1445 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
1446 | 41 | Ruud Klaver | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1447 | 1 | Adrian Georgescu | |
1448 | 41 | Ruud Klaver | === Invitation === |
1449 | 53 | Ruud Klaver | |
1450 | 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. |
1451 | 72 | Ruud Klaver | 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. |
1452 | 72 | Ruud Klaver | The {{{Invitation}}} class represents both incoming and outgoing sessions. |
1453 | 72 | Ruud Klaver | |
1454 | 72 | Ruud Klaver | 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. |
1455 | 72 | Ruud Klaver | In order to represent re-{{{INVITE}}}s and user-requested disconnections, three more states have been added to this state machine. |
1456 | 72 | Ruud Klaver | The progression through this state machine is fairly linear and is dependent on whether this is an incoming or an outgoing session. |
1457 | 72 | Ruud Klaver | State changes are triggered either by incoming or by outgoing SIP requests and responses. |
1458 | 72 | Ruud Klaver | The states and the transitions between them are shown in the following diagram: |
1459 | 72 | Ruud Klaver | |
1460 | 72 | Ruud Klaver | [[Image(sipsimple-core-invite-state-machine.png, nolink)]] |
1461 | 1 | Adrian Georgescu | |
1462 | 1 | Adrian Georgescu | The state changes of this machine are triggered by the following: |
1463 | 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. |
1464 | 1 | Adrian Georgescu | 2. The application requested an outgoing session by calling the {{{send_invite()}}} method and and initial {{{INVITE}}} request is sent. |
1465 | 1 | Adrian Georgescu | 3. A new incoming session is received by the core. |
1466 | 1 | Adrian Georgescu | The application should look out for state change to this state in order to be notified of new incoming sessions. |
1467 | 1 | Adrian Georgescu | 4. A provisional response (1xx) is received from the remove party. |
1468 | 1 | Adrian Georgescu | 5. A provisional response (1xx) is sent to the remote party, after the application called the {{{respond_to_invite_provisionally()}}} method. |
1469 | 1 | Adrian Georgescu | 6. A positive final response (2xx) is received from the remote party. |
1470 | 1 | Adrian Georgescu | 7. A positive final response (2xx) is sent to the remote party, after the application called the {{{accept_invite()}}} method. |
1471 | 1 | Adrian Georgescu | 8. A positive final response (2xx) is sent or received, depending on the orientation of the session. |
1472 | 1 | Adrian Georgescu | 9. An {{{ACK}}} is sent or received, depending on the orientation of the session. |
1473 | 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. |
1474 | 1 | Adrian Georgescu | 10. The local party sent a re-{{{INVITE}}} to the remote party by calling the {{{send_reinvite()}}} method. |
1475 | 1 | Adrian Georgescu | 11. The remote party has sent a final response to the re-{{{INVITE}}}. |
1476 | 1 | Adrian Georgescu | 12. The remote party has sent a re-{{{INVITE}}}. |
1477 | 29 | Luci Stanescu | 13. The local party has responded to the re-{{{INVITE}}} by calling the {{{respond_to_reinvite()}}} method. |
1478 | 1 | Adrian Georgescu | 14. The application requests that the session ends by calling the {{{end()}}} method. |
1479 | 1 | Adrian Georgescu | 15. A response is received from the remote party to whichever message was sent by the local party to end the session. |
1480 | 1 | Adrian Georgescu | 16. A message is received from the remote party which ends the session. |
1481 | 1 | Adrian Georgescu | |
1482 | 1 | Adrian Georgescu | The application is notified of a state change in either state machine through the {{{SIPInvitationChangedState}}} notification, which has as data the current and previous states. |
1483 | 1 | Adrian Georgescu | If the event is triggered by and incoming message, extensive data about that message, such as method/code, headers and body, is also included with the notification. |
1484 | 1 | Adrian Georgescu | The application should compare the previous and current states and perform the appropriate action. |
1485 | 1 | Adrian Georgescu | |
1486 | 1 | Adrian Georgescu | An {{{Invitiation}}} object also emits the {{{SIPInvitationGotSDPUpdate}}} notification, which indicates that SDP negotiation between the two parties has been completed. |
1487 | 1 | Adrian Georgescu | This will occur (at least) once during the initial session negotiation steps, during re-{{{INVITE}}}s in both directions and whenever an {{{UPDATE}}} request is received. |
1488 | 1 | Adrian Georgescu | In the last case, the {{{Invitation}}} object will automatically include the current local SDP in the response. |
1489 | 1 | Adrian Georgescu | |
1490 | 1 | Adrian Georgescu | ==== attributes ==== |
1491 | 1 | Adrian Georgescu | |
1492 | 1 | Adrian Georgescu | '''state''':: |
1493 | 1 | Adrian Georgescu | The state the {{{Invitation}}} state machine is currently in. |
1494 | 1 | Adrian Georgescu | See the diagram above for possible states. |
1495 | 1 | Adrian Georgescu | This attribute is read-only. |
1496 | 1 | Adrian Georgescu | '''is_outgoing''':: |
1497 | 1 | Adrian Georgescu | Boolean indicating if the original {{{INVITE}}} was outgoing, or incoming if set to {{{False}}}. |
1498 | 1 | Adrian Georgescu | '''credentials''':: |
1499 | 1 | Adrian Georgescu | The SIP credentials needed to authenticate at the SIP proxy in the form of a {{{Credentials}}} object. |
1500 | 29 | Luci Stanescu | If this {{{Invitation}}} object represents an incoming {{{INVITE}}} session this attribute will be {{{None}}}. |
1501 | 1 | Adrian Georgescu | On an outgoing session this attribute will be {{{None}}} if it was not specified when the object was created. |
1502 | 1 | Adrian Georgescu | This attribute is set on object instantiation and is read-only. |
1503 | 1 | Adrian Georgescu | '''from_uri''':: |
1504 | 1 | Adrian Georgescu | The SIP URI of the caller represented by a {{{SIPURI}}} object. |
1505 | 1 | Adrian Georgescu | If this is an outgoing {{{INVITE}}} session, this is the from_uri from the !__init!__ method. |
1506 | 1 | Adrian Georgescu | Otherwise the URI is taken from the {{{From:}}} header of the initial {{{INVITE}}}. |
1507 | 1 | Adrian Georgescu | This attribute is set on object instantiation and is read-only. |
1508 | 1 | Adrian Georgescu | '''to_uri''':: |
1509 | 1 | Adrian Georgescu | The SIP URI of the callee represented by a {{{SIPURI}}} object. |
1510 | 1 | Adrian Georgescu | If this is an outgoing {{{INVITE}}} session, this is the to_uri from the !__init!__ method. |
1511 | 1 | Adrian Georgescu | Otherwise the URI is taken from the {{{To:}}} header of the initial {{{INVITE}}}. |
1512 | 1 | Adrian Georgescu | This attribute is set on object instantiation and is read-only. |
1513 | 1 | Adrian Georgescu | '''local_uri''':: |
1514 | 1 | Adrian Georgescu | The local SIP URI used in this session. |
1515 | 1 | Adrian Georgescu | If the original {{{INVITE}}} was incoming, this is the same as {{{to_uri}}}, otherwise it will be the same as {{{from_uri}}}. |
1516 | 1 | Adrian Georgescu | '''remote_uri''':: |
1517 | 1 | Adrian Georgescu | The SIP URI of the remote party in this session. |
1518 | 1 | Adrian Georgescu | If the original {{{INVITE}}} was incoming, this is the same as {{{from_uri}}}, otherwise it will be the same as {{{to_uri}}}. |
1519 | 1 | Adrian Georgescu | '''route''':: |
1520 | 1 | Adrian Georgescu | The outbound proxy that was requested to be used in the form of a {{{Route}}} object, including the desired transport. |
1521 | 1 | Adrian Georgescu | If this {{{Invitation}}} object represents an incoming {{{INVITE}}} session this attribute will always be {{{None}}}. |
1522 | 1 | Adrian Georgescu | This attribute is set on object instantiation and is read-only. |
1523 | 1 | Adrian Georgescu | '''call_id''':: |
1524 | 1 | Adrian Georgescu | The call ID of the {{{INVITE}}} session as a read-only string. |
1525 | 1 | Adrian Georgescu | In the {{{NULL}}} and {{{DISCONNECTED}}} states, this attribute is {{{None}}}. |
1526 | 84 | Ruud Klaver | '''transport''':: |
1527 | 23 | Ruud Klaver | A string indicating the transport used for the application. |
1528 | 1 | Adrian Georgescu | This can be "udp", "tcp" or "tls". |
1529 | 1 | Adrian Georgescu | '''local_contact_uri''':: |
1530 | 1 | Adrian Georgescu | The Contact URI that the local side provided to the remote side within this {{{INVITE}}} session as a {{{SIPURI}}} object. |
1531 | 1 | Adrian Georgescu | Note that this can either be set on object creation or updated using the {{{update_local_contact()}}} method. |
1532 | 1 | Adrian Georgescu | '''local_contact_parameters''':: |
1533 | 1 | Adrian Georgescu | The Contact header parameters that the local side provided to the remote side within this {{{INVITE}}} session as dictionary. |
1534 | 1 | Adrian Georgescu | Note that this can either be set on object creation or updated using the {{{update_local_contact()}}} method. |
1535 | 71 | Adrian Georgescu | |
1536 | 1 | Adrian Georgescu | ==== methods ==== |
1537 | 1 | Adrian Georgescu | |
1538 | 1 | Adrian Georgescu | '''!__init!__'''(''self'', '''from_uri''', '''to_uri''', '''route''', '''credentials'''={{{None}}}, '''contact_uri'''={{{None}}}, '''contact_parameters'''={{{None}}}):: |
1539 | 1 | Adrian Georgescu | Creates a new {{{Invitation}}} object for an outgoing session. |
1540 | 71 | Adrian Georgescu | [[BR]]''from_uri'':[[BR]] |
1541 | 71 | Adrian Georgescu | The SIP URI of the local account in the form of a {{{SIPURI}}} object. |
1542 | 71 | Adrian Georgescu | [[BR]]''to_uri'':[[BR]] |
1543 | 71 | Adrian Georgescu | The SIP URI we want to send the {{{INVITE}}} to, represented as a {{{SIPURI}}} object. |
1544 | 1 | Adrian Georgescu | [[BR]]''route'':[[BR]] |
1545 | 71 | Adrian Georgescu | The outbound proxy to use in the form of a {{{Route}}} object. |
1546 | 1 | Adrian Georgescu | This includes the desired transport to use. |
1547 | 1 | Adrian Georgescu | [[BR]]''credentials'':[[BR]] |
1548 | 1 | Adrian Georgescu | The optional SIP credentials needed to authenticate at the SIP proxy in the form of a {{{Credentials}}} object. |
1549 | 1 | Adrian Georgescu | [[BR]]''contact_uri'':[[BR]] |
1550 | 1 | Adrian Georgescu | The Contact URI to include in the {{{INVITE}}} request, a {{{SIPURI}}} object. |
1551 | 1 | Adrian Georgescu | If this is {{{None}}}, a Contact URI will be internally generated. |
1552 | 1 | Adrian Georgescu | [[BR]]''contact_parameters'':[[BR]] |
1553 | 1 | Adrian Georgescu | The parameters to be included in the Contact header of the {{{INVITE}}} request as a dictionary. |
1554 | 1 | Adrian Georgescu | Entries that have their value set to {{{None}}} will have only the key set as a header parameter. |
1555 | 1 | Adrian Georgescu | If this argument is {{{None}}}, no Contact header parameters will be included. |
1556 | 1 | Adrian Georgescu | '''get_active_local_sdp'''(''self''):: |
1557 | 1 | Adrian Georgescu | Returns a new {{{SDPSession}}} object representing the currently active local SDP. |
1558 | 1 | Adrian Georgescu | If no SDP was negotiated yet, this returns {{{None}}}. |
1559 | 1 | Adrian Georgescu | '''get_active_remote_sdp'''(''self''):: |
1560 | 1 | Adrian Georgescu | Returns a new {{{SDPSession}}} object representing the currently active local SDP. |
1561 | 1 | Adrian Georgescu | If no SDP was negotiated yet, this returns {{{None}}}. |
1562 | 1 | Adrian Georgescu | '''get_offered_local_sdp'''(''self''):: |
1563 | 1 | Adrian Georgescu | Returns a new {{{SDPSession}}} object representing the currently proposed local SDP. |
1564 | 1 | Adrian Georgescu | If no local offered SDP has been set, this returns {{{None}}}. |
1565 | 1 | Adrian Georgescu | '''set_offered_local_sdp'''(''self'', '''local_sdp'''):: |
1566 | 1 | Adrian Georgescu | Sets the offered local SDP, either for an initial {{{INVITE}}} or re-{{{INVITE}}}, or as an SDP answer in response to an initial {{{INVITE}}} or re-{{{INVITE}}}. |
1567 | 1 | Adrian Georgescu | [[BR]]''local_sdp'':[[BR]] |
1568 | 1 | Adrian Georgescu | The SDP to send as offer or answer to the remote party. |
1569 | 1 | Adrian Georgescu | '''get_offered_remote_sdp'''(''self''):: |
1570 | 1 | Adrian Georgescu | Returns a new {{{SDPSession}}} object representing the currently proposed remote SDP. |
1571 | 24 | Ruud Klaver | If no remote SDP has been offered in the current state, this returns {{{None}}}. |
1572 | 1 | Adrian Georgescu | '''update_local_contact'''(''self'', '''contact_uri''', '''parameters'''={{{None}}}):: |
1573 | 1 | Adrian Georgescu | This method allows the application to update the contents of the Contact header sent in (re-){{{INVITE}}} requests. |
1574 | 1 | Adrian Georgescu | It can be useful to set to Contact URI to something different than the default on an incoming {{{INVITE}}} session, on a IP address change during the session. |
1575 | 1 | Adrian Georgescu | Note that that the number of calls to this method should be limited, as memory is allocated each time it is called which is only released when the {{{Invitation}}} object reaches the {{{DISCONNECTED}}} state. |
1576 | 1 | Adrian Georgescu | [[BR]]''contact_uri'':[[BR]] |
1577 | 1 | Adrian Georgescu | The Contact URI to include in the {{{INVITE}}} request, a {{{SIPURI}}} object. |
1578 | 1 | Adrian Georgescu | [[BR]]''contact_parameters'':[[BR]] |
1579 | 1 | Adrian Georgescu | The parameters to be included in the Contact header of the {{{INVITE}}} request as a dictionary. |
1580 | 1 | Adrian Georgescu | Entries that have their value set to {{{None}}} will have only the key set as a header parameter. |
1581 | 1 | Adrian Georgescu | If this argument is {{{None}}}, no Contact header parameters will be included. |
1582 | 1 | Adrian Georgescu | '''send_invite'''(''self'', '''extra_headers'''={{{None}}}, '''timeout'''={{{None}}}):: |
1583 | 1 | Adrian Georgescu | This tries to move the state machine into the {{{CALLING}}} state by sending the initial {{{INVITE}}} request. |
1584 | 1 | Adrian Georgescu | It may only be called from the {{{NULL}}} state on an outgoing {{{Invitation}}} object. |
1585 | 1 | Adrian Georgescu | [[BR]]''extra_headers'':[[BR]] |
1586 | 1 | Adrian Georgescu | Any extra headers that should be included in the {{{INVITE}}} request in the form of a dict. |
1587 | 1 | Adrian Georgescu | [[BR]]''timeout'':[[BR]] |
1588 | 1 | Adrian Georgescu | How many seconds to wait for the remote party to reply before changing the state to {{{DISCONNECTED}}} and internally replying with a 408, as an int or a float. |
1589 | 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. |
1590 | 1 | Adrian Georgescu | '''respond_to_invite_provisionally'''(''self'', '''response_code'''=180, '''extra_headers'''={{{None}}}):: |
1591 | 1 | Adrian Georgescu | This tries to move the state machine into the {{{EARLY}}} state by sending a provisional response to the initial {{{INVITE}}}. |
1592 | 1 | Adrian Georgescu | It may only be called from the {{{INCOMING}}} state on an incoming {{{Invitation}}} object. |
1593 | 1 | Adrian Georgescu | [[BR]]''response_code'':[[BR]] |
1594 | 1 | Adrian Georgescu | The code of the provisional response to use as an int. |
1595 | 1 | Adrian Georgescu | This should be in the 1xx range. |
1596 | 1 | Adrian Georgescu | [[BR]]''extra_headers'':[[BR]] |
1597 | 1 | Adrian Georgescu | Any extra headers that should be included in the response in the form of a dict. |
1598 | 1 | Adrian Georgescu | '''accept_invite'''(''self'', '''extra_headers'''={{{None}}}):: |
1599 | 1 | Adrian Georgescu | This tries to move the state machine into the {{{CONNECTING}}} state by sending a 200 OK response to the initial {{{INVITE}}}. |
1600 | 1 | Adrian Georgescu | It may only be called from the {{{INCOMING}}} or {{{EARLY}}} states on an incoming {{{Invitation}}} object. |
1601 | 1 | Adrian Georgescu | [[BR]]''extra_headers'':[[BR]] |
1602 | 1 | Adrian Georgescu | Any extra headers that should be included in the response in the form of a dict. |
1603 | 1 | Adrian Georgescu | '''end'''(''self'', '''response_code'''=603, '''extra_headers'''={{{None}}}, '''timeout'''={{{None}}}):: |
1604 | 1 | Adrian Georgescu | This moves the {{{INVITE}}} state machine into the {{{DISCONNECTING}}} state by sending the necessary SIP message. |
1605 | 1 | Adrian Georgescu | When a response from the remote party is received, the state machine will go into the {{{DISCONNECTED}}} state. |
1606 | 1 | Adrian Georgescu | Depending on the current state, this could be a CANCEL or BYE request or a negative response. |
1607 | 1 | Adrian Georgescu | [[BR]]''response_code'':[[BR]] |
1608 | 1 | Adrian Georgescu | The code of the response to use as an int, if transmission of a response is needed. |
1609 | 1 | Adrian Georgescu | [[BR]]''extra_headers'':[[BR]] |
1610 | 1 | Adrian Georgescu | Any extra headers that should be included in the request or response in the form of a dict. |
1611 | 1 | Adrian Georgescu | [[BR]]''timeout'':[[BR]] |
1612 | 1 | Adrian Georgescu | How many seconds to wait for the remote party to reply before changing the state to {{{DISCONNECTED}}}, as an int or a float. |
1613 | 1 | Adrian Georgescu | If this is set to {{{None}}}, the default PJSIP timeout will be used, which currently appears to be 3.5 seconds for an established session. |
1614 | 1 | Adrian Georgescu | '''respond_to_reinvite'''(''self'', '''response_code'''=200, '''extra_headers'''={{{None}}}):: |
1615 | 1 | Adrian Georgescu | Respond to a received re-{{{INVITE}}} with a response that is either provisional (1xx), positive (2xx) or negative (3xx and upwards). |
1616 | 1 | Adrian Georgescu | This method can be called by the application when the state machine is in the {{{REINVITED}}} state and will move the state machine back into the {{{CONFIRMED}}} state. |
1617 | 1 | Adrian Georgescu | Before giving a positive final response, the SDP needs to be set using the {{{set_offered_local_sdp()}}} method. |
1618 | 1 | Adrian Georgescu | [[BR]]''response_code'':[[BR]] |
1619 | 1 | Adrian Georgescu | The code of the response to use as an int. |
1620 | 1 | Adrian Georgescu | This should be a 3 digit number. |
1621 | 1 | Adrian Georgescu | [[BR]]''extra_headers'':[[BR]] |
1622 | 1 | Adrian Georgescu | '''send_reinvite'''(''self'', '''extra_headers'''={{{None}}}):: |
1623 | 1 | Adrian Georgescu | The application may only call this method when the state machine is in the {{{CONFIRMED}}} state to induce sending a re-{{{INVITE}}}. |
1624 | 1 | Adrian Georgescu | Before doing this it needs to set the new local SDP offer by calling the {{{set_offered_local_sdp()}}} method. |
1625 | 1 | Adrian Georgescu | After this method is called, the state machine will be in the {{{REINVITING}}} state, until a final response from the remote party is received. |
1626 | 1 | Adrian Georgescu | [[BR]]''extra_headers'':[[BR]] |
1627 | 1 | Adrian Georgescu | Any extra headers that should be included in the re-{{{INVITE}}} in the form of a dict. |
1628 | 1 | Adrian Georgescu | |
1629 | 1 | Adrian Georgescu | ==== notifications ==== |
1630 | 1 | Adrian Georgescu | |
1631 | 1 | Adrian Georgescu | '''SIPInvitationChangedState''':: |
1632 | 1 | Adrian Georgescu | This notification is sent by an {{{Invitation}}} object whenever its state machine changes state. |
1633 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
1634 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1635 | 1 | Adrian Georgescu | [[BR]]''prev_state'':[[BR]] |
1636 | 1 | Adrian Georgescu | The previous state of the INVITE state machine. |
1637 | 1 | Adrian Georgescu | [[BR]]''state'':[[BR]] |
1638 | 1 | Adrian Georgescu | The new state of the INVITE state machine, which may be the same as the previous state. |
1639 | 1 | Adrian Georgescu | [[BR]]''method'': (only if the state change got triggered by an incoming SIP request)[[BR]] |
1640 | 1 | Adrian Georgescu | The method of the SIP request as a string. |
1641 | 1 | Adrian Georgescu | [[BR]]''request_uri'': (only if the state change got triggered by an incoming SIP request)[[BR]] |
1642 | 1 | Adrian Georgescu | The request URI of the SIP request as a {{{SIPURI}}} object. |
1643 | 1 | Adrian Georgescu | [[BR]]''code'': (only if the state change got triggered by an incoming SIP response or internal timeout or error)[[BR]] |
1644 | 1 | Adrian Georgescu | The code of the SIP response or error as an int. |
1645 | 1 | Adrian Georgescu | [[BR]]''reason'': (only if the state change got triggered by an incoming SIP response or internal timeout or error)[[BR]] |
1646 | 1 | Adrian Georgescu | The reason text of the SIP response or error as a string. |
1647 | 1 | Adrian Georgescu | [[BR]]''headers'': (only if the state change got triggered by an incoming SIP request or response)[[BR]] |
1648 | 1 | Adrian Georgescu | The headers of the SIP request or response as a dict. |
1649 | 1 | Adrian Georgescu | Each SIP header is represented in its parsed for as long as PJSIP supports it. |
1650 | 1 | Adrian Georgescu | The format of the parsed value depends on the header. |
1651 | 1 | Adrian Georgescu | [[BR]]''body'': (only if the state change got triggered by an incoming SIP request or response)[[BR]] |
1652 | 18 | Adrian Georgescu | The body of the SIP request or response as a string, or {{{None}}} if no body was included. |
1653 | 1 | Adrian Georgescu | The content type of the body can be learned from the {{{Content-Type:}}} header in the headers argument. |
1654 | 1 | Adrian Georgescu | '''SIPInvitationGotSDPUpdate''':: |
1655 | 17 | Ruud Klaver | This notification is sent by an {{{Invitation}}} object whenever SDP negotiation has been performed. |
1656 | 17 | Ruud Klaver | It should be used by the application as an indication to start, change or stop any associated media streams. |
1657 | 17 | Ruud Klaver | [[BR]]''timestamp'':[[BR]] |
1658 | 17 | Ruud Klaver | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1659 | 17 | Ruud Klaver | [[BR]]''succeeded'':[[BR]] |
1660 | 17 | Ruud Klaver | A boolean indicating if the SDP negotiation has succeeded. |
1661 | 17 | Ruud Klaver | [[BR]]''error'': (only if SDP negotiation did not succeed)[[BR]] |
1662 | 17 | Ruud Klaver | A string indicating why SDP negotiation failed. |
1663 | 17 | Ruud Klaver | [[BR]]''local_sdp'': (only if SDP negotiation succeeded)[[BR]] |
1664 | 1 | Adrian Georgescu | A SDPSession object indicating the local SDP that was negotiated. |
1665 | 1 | Adrian Georgescu | [[BR]]''remote_sdp'': (only if SDP negotiation succeeded)[[BR]] |
1666 | 1 | Adrian Georgescu | A SDPSession object indicating the remote SDP that was negotiated. |
1667 | 1 | Adrian Georgescu | |
1668 | 1 | Adrian Georgescu | === RTPTransport === |
1669 | 1 | Adrian Georgescu | |
1670 | 1 | Adrian Georgescu | This object represents a transport for RTP media, the basis of which is a pair of UDP sockets, one for RTP and one for RTCP. |
1671 | 1 | Adrian Georgescu | Internally it wraps a [http://www.pjsip.org/pjmedia/docs/html/group__PJMEDIA__TRANSPORT.htm pjmedia_transport] object. |
1672 | 1 | Adrian Georgescu | Initially this object will only be used by the {{{AudioTransport}}} object, but in the future it can also be used for video and [wiki:RTTProposal Real-Time Text]. |
1673 | 17 | Ruud Klaver | For this reason the {{{AudioTransport}}} and {{{RTPTransport}}} are two distinct objects. |
1674 | 1 | Adrian Georgescu | |
1675 | 1 | Adrian Georgescu | The {{{RTPTransport}}} object also allows support for ICE and SRTP functionality from PJSIP. |
1676 | 1 | Adrian Georgescu | Because these features are related to both the UDP transport and the SDP formatting, the SDP carried in SIP signaling message will need to "pass through" this object during the SDP negotiation. |
1677 | 1 | Adrian Georgescu | The code using this object, which in most cases will be the {{{AudioTransport}}} object, will need to call certain methods on the object at appropriate times. |
1678 | 1 | Adrian Georgescu | This process of SDP negotiation is represented by the internal state machine of the object, as shown in the following diagram: |
1679 | 1 | Adrian Georgescu | |
1680 | 17 | Ruud Klaver | > The Real-time Transport Protocol (or RTP) defines a standardized packet format for delivering audio and video over the Internet. |
1681 | 1 | Adrian Georgescu | > It was developed by the Audio-Video Transport Working Group of the IETF and published in [http://tools.ietf.org/html/rfc3550 RFC 3550]. |
1682 | 1 | Adrian Georgescu | > RTP is used in streaming media systems (together with the RTSP) as well as in videoconferencing and push to talk systems. |
1683 | 1 | Adrian Georgescu | > For these it carries media streams controlled by Session Initiation Protocol (SIP) signaling protocols, making it the technical foundation of the Voice over IP industry. |
1684 | 1 | Adrian Georgescu | |
1685 | 1 | Adrian Georgescu | [[Image(sipsimple-rtp-transport-state-machine.png, nolink)]] |
1686 | 1 | Adrian Georgescu | |
1687 | 1 | Adrian Georgescu | State changes are triggered by the following events: |
1688 | 1 | Adrian Georgescu | 1. The application calls the {{{set_INIT()}}} method after object creation and ICE+STUN is not used. |
1689 | 1 | Adrian Georgescu | 2. The application calls the {{{set_INIT()}}} method after object creation and ICE+STUN is used. |
1690 | 1 | Adrian Georgescu | 3. A successful STUN response is received from the STUN server. |
1691 | 1 | Adrian Georgescu | 4. The {{{set_LOCAL()}}} method is called. |
1692 | 1 | Adrian Georgescu | 5. The {{{set_ESTABLISHED()}}} method is called. |
1693 | 1 | Adrian Georgescu | 6. The {{{set_INIT()}}} method is called while the object is in the {{{LOCAL}}} or {{{ESTABLISHED}}} state. |
1694 | 45 | Ruud Klaver | 7. A method is called on the application, but in the meantime the {{{Engine}}} has stopped. |
1695 | 1 | Adrian Georgescu | The object can no longer be used. |
1696 | 1 | Adrian Georgescu | 8. There was an error in getting the STUN candidates from the STUN server. |
1697 | 1 | Adrian Georgescu | |
1698 | 71 | Adrian Georgescu | > It would make sense to be able to use the object even if the STUN request fails (and have ICE not include a STUN candidate), but for some reason the pjmedia_transport is unusable once STUN negotiation has failed. |
1699 | 1 | Adrian Georgescu | > This means that the RTPTransport object is also unusable once it has reached the STUN_FAILED state. |
1700 | 1 | Adrian Georgescu | > A workaround would be destroy the RTPTransport object and create a new one that uses ICE without STUN. |
1701 | 1 | Adrian Georgescu | |
1702 | 1 | Adrian Georgescu | These states allow for two SDP negotiation scenarios to occur, represented by two paths that can be followed through the state machine. |
1703 | 1 | Adrian Georgescu | In this example we will assume that ICE with STUN is not used, as it is independent of the SDP negotiation procedure. |
1704 | 1 | Adrian Georgescu | * The first scenario is where the local party generates the SDP offer. |
1705 | 1 | Adrian Georgescu | For a stream that it wishes to include in this SDP offer, it instantiates a {{{RTPTransport}}} object. |
1706 | 1 | Adrian Georgescu | After instantiation the object is initialized by calling the {{{set_INIT()}}} method and the local RTP address and port can be fetched from it using the {{{local_rtp_address}}} and {{{local_rtp_port}}} respectively, which can be used to generate the local SDP in the form of a {{{SDPSession}}} object (note that it needs the full object, not just the relevant {{{SDPMedia}}} object). |
1707 | 1 | Adrian Georgescu | This local SDP then needs to be passed to the {{{set_LOCAL()}}} method, which moves the state machine into the {{{LOCAL}}} state. |
1708 | 1 | Adrian Georgescu | Depending on the options used for the {{{RTPTransport}}} instantiation (such as ICE and SRTP), this may change the {{{SDPSession}}} object. |
1709 | 1 | Adrian Georgescu | This (possibly changed) {{{SDPSession}}} object then needs to be passed to the {{{Invitation}}} object. |
1710 | 1 | Adrian Georgescu | After SDP negotiation is completed, the application needs to pass both the local and remote SDP, in the form of {{{SDPSession}}} objects, to the {{{RTPTransport}}} object using the {{{set_ESTABLISHED()}}} method, moving the state machine into the {{{ESTABLISHED}}} state. |
1711 | 1 | Adrian Georgescu | This will not change either of the {{{SDPSession}}} objects. |
1712 | 1 | Adrian Georgescu | * The second scenario is where the local party is offered a media stream in SDP and wants to accept it. |
1713 | 1 | Adrian Georgescu | In this case a {{{RTPTransport}}} is also instantiated and initialized using the {{{set_INIT()}}} method, and the application can generate the local SDP in response to the remote SDP, using the {{{local_rtp_address}}} and {{{local_rtp_port}}} attributes. |
1714 | 1 | Adrian Georgescu | Directly after this it should pass the generated local SDP and received remote SDP, in the form of {{{SDPSession}}} objects, to the {{{set_ESTABLISHED()}}} method. |
1715 | 1 | Adrian Georgescu | In this case the local SDP object may be changed, after which it can be passed to the {{{Invitation}}} object. |
1716 | 1 | Adrian Georgescu | |
1717 | 1 | Adrian Georgescu | Whenever the {{{RTPTransport}}} object is in the {{{LOCAL}}} or {{{ESTABLISHED}}} states, it may be reset to the {{{INIT}}} state to facilitate re-use of the existing transport and its features. |
1718 | 1 | Adrian Georgescu | Before doing this however, the internal transport object must no longer be in use. |
1719 | 1 | Adrian Georgescu | |
1720 | 1 | Adrian Georgescu | ==== attributes ==== |
1721 | 1 | Adrian Georgescu | |
1722 | 1 | Adrian Georgescu | '''state''':: |
1723 | 1 | Adrian Georgescu | Indicates which state the internal state machine is in. |
1724 | 1 | Adrian Georgescu | See the previous section for a list of states the state machine can be in. |
1725 | 1 | Adrian Georgescu | This attribute is read-only. |
1726 | 1 | Adrian Georgescu | '''local_rtp_address''':: |
1727 | 19 | Ruud Klaver | The local IPv4 address of the interface the {{{RTPTransport}}} object is listening on and the address that should be included in the SDP. |
1728 | 1 | Adrian Georgescu | If no address was specified during object instantiation, PJSIP will take guess out of the IP addresses of all interfaces. |
1729 | 1 | Adrian Georgescu | This attribute is read-only and will be {{{None}}} if PJSIP is not listening on the transport. |
1730 | 1 | Adrian Georgescu | '''local_rtp_port''':: |
1731 | 1 | Adrian Georgescu | The UDP port PJSIP is listening on for RTP traffic. |
1732 | 1 | Adrian Georgescu | RTCP traffic will always be this port plus one. |
1733 | 1 | Adrian Georgescu | This attribute is read-only and will be {{{None}}} if PJSIP is not listening on the transport. |
1734 | 1 | Adrian Georgescu | '''remote_rtp_address_sdp''':: |
1735 | 1 | Adrian Georgescu | The remote IP address that was seen in the SDP. |
1736 | 1 | Adrian Georgescu | This attribute is read-only and will be {{{None}}} unless the object is in the {{{ESTABLISHED}}} state. |
1737 | 1 | Adrian Georgescu | '''remote_rtp_port_sdp''':: |
1738 | 1 | Adrian Georgescu | The remote UDP port for RTP that was seen in the SDP. |
1739 | 1 | Adrian Georgescu | This attribute is read-only and will be {{{None}}} unless the object is in the {{{ESTABLISHED}}} state. |
1740 | 45 | Ruud Klaver | '''remote_rtp_address_received''':: |
1741 | 1 | Adrian Georgescu | The remote IP address from which RTP data was received. |
1742 | 1 | Adrian Georgescu | This attribute is read-only and will be {{{None}}} unless RTP was actually received. |
1743 | 1 | Adrian Georgescu | '''remote_rtp_port_received''':: |
1744 | 1 | Adrian Georgescu | The remote UDP port from which RTP data was received. |
1745 | 1 | Adrian Georgescu | This attribute is read-only and will be {{{None}}} unless RTP was actually received. |
1746 | 1 | Adrian Georgescu | '''use_srtp''':: |
1747 | 1 | Adrian Georgescu | A boolean indicating if the use of SRTP was requested when the object was instantiated. |
1748 | 1 | Adrian Georgescu | This attribute is read-only. |
1749 | 1 | Adrian Georgescu | '''force_srtp''':: |
1750 | 1 | Adrian Georgescu | A boolean indicating if SRTP being mandatory for this transport if it is enabled was requested when the object was instantiated. |
1751 | 1 | Adrian Georgescu | This attribute is read-only. |
1752 | 1 | Adrian Georgescu | '''srtp_active''':: |
1753 | 1 | Adrian Georgescu | A boolean indicating if SRTP encryption and decryption is running. |
1754 | 1 | Adrian Georgescu | Querying this attribute only makes sense once the object is in the {{{ESTABLISHED}}} state and use of SRTP was requested. |
1755 | 29 | Luci Stanescu | This attribute is read-only. |
1756 | 1 | Adrian Georgescu | '''use_ice''':: |
1757 | 1 | Adrian Georgescu | A boolean indicating if the use of ICE was requested when the object was instantiated. |
1758 | 1 | Adrian Georgescu | This attribute is read-only. |
1759 | 1 | Adrian Georgescu | '''ice_stun_address''':: |
1760 | 34 | Ruud Klaver | A string indicating the IP address of the STUN server that was requested to be used. |
1761 | 34 | Ruud Klaver | This attribute is read-only. |
1762 | 34 | Ruud Klaver | '''ice_stun_port''':: |
1763 | 34 | Ruud Klaver | A string indicating the UDP port of the STUN server that was requested to be used. |
1764 | 1 | Adrian Georgescu | This attribute is read-only. |
1765 | 1 | Adrian Georgescu | |
1766 | 1 | Adrian Georgescu | ==== methods ==== |
1767 | 1 | Adrian Georgescu | |
1768 | 1 | Adrian Georgescu | '''!__init!__'''(''self'', '''local_rtp_address'''={{{None}}}, '''use_srtp'''={{{False}}}, '''srtp_forced'''={{{False}}}, '''use_ice'''={{{False}}}, '''ice_stun_address'''={{{None}}}, '''ice_stun_port'''=3478):: |
1769 | 1 | Adrian Georgescu | Creates a new {{{RTPTransport}}} object and opens the RTP and RTCP UDP sockets. |
1770 | 71 | Adrian Georgescu | If additional features are requested, they will be initialized. |
1771 | 1 | Adrian Georgescu | After object instantiation, it is either in the {{{INIT}}} or the {{{WAIT_STUN}}} state, depending on the values of the {{{use_ice}}} and {{{ice_stun_address}}} arguments. |
1772 | 1 | Adrian Georgescu | [[BR]]''local_rtp_address'':[[BR]] |
1773 | 1 | Adrian Georgescu | Optionally contains the local IPv4 address to listen on. |
1774 | 1 | Adrian Georgescu | If this is not specified, PJSIP will listen on all network interfaces. |
1775 | 1 | Adrian Georgescu | [[BR]]''use_srtp'':[[BR]] |
1776 | 1 | Adrian Georgescu | A boolean indicating if SRTP should be used. |
1777 | 17 | Ruud Klaver | If this is set to {{{True}}}, SRTP information will be added to the SDP when it passes this object. |
1778 | 17 | Ruud Klaver | [[BR]]''srtp_forced'':[[BR]] |
1779 | 1 | Adrian Georgescu | A boolean indicating if use of SRTP is set to mandatory in the SDP. |
1780 | 71 | Adrian Georgescu | If this is set to {{{True}}} and the remote party does not support SRTP, the SDP negotiation for this stream will fail. |
1781 | 1 | Adrian Georgescu | This argument is relevant only if {{{use_srtp}}} is set to {{{True}}}. |
1782 | 29 | Luci Stanescu | [[BR]]''use_ice'':[[BR]] |
1783 | 17 | Ruud Klaver | A boolean indicating if ICE should be used. |
1784 | 17 | Ruud Klaver | If this is set to {{{True}}}, ICE candidates will be added to the SDP when it passes this object. |
1785 | 1 | Adrian Georgescu | [[BR]]''ice_stun_address'':[[BR]] |
1786 | 1 | Adrian Georgescu | A string indicating the address (IP address or hostname) of the STUN server that should be used to add a STUN candidate to the ICE candidates. |
1787 | 29 | 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. |
1788 | 17 | Ruud Klaver | When this happens a {{{RTPTransportGotSTUNResponse}}} notification is sent. |
1789 | 17 | Ruud Klaver | This argument is relevant only if {{{use_ice}}} is set to {{{True}}}. |
1790 | 17 | Ruud Klaver | [[BR]]''ice_stun_address'':[[BR]] |
1791 | 17 | Ruud Klaver | An int indicating the UDP port of the STUN server that should be used to add a STUN candidate to the ICE candidates. |
1792 | 17 | Ruud Klaver | This argument is relevant only if {{{use_ice}}} is set to {{{True}}} and {{{ice_stun_address}}} is not {{{None}}}. |
1793 | 1 | Adrian Georgescu | '''set_INIT'''(''self''):: |
1794 | 1 | Adrian Georgescu | This moves the internal state machine into the {{{INIT}}} state. |
1795 | 1 | Adrian Georgescu | If the state machine is in the {{{LOCAL}}} or {{{ESTABLISHED}}} states, this effectively resets the {{{RTPTransport}}} object for re-use. |
1796 | 1 | Adrian Georgescu | '''set_LOCAL'''(''self'', '''local_sdp''', '''sdp_index'''):: |
1797 | 1 | Adrian Georgescu | This moves the the internal state machine into the {{{LOCAL}}} state. |
1798 | 1 | Adrian Georgescu | [[BR]]''local_sdp'':[[BR]] |
1799 | 1 | Adrian Georgescu | The local SDP to be proposed in the form of a {{{SDPSession}}} object. |
1800 | 1 | Adrian Georgescu | Note that this object may be modified by this method. |
1801 | 1 | Adrian Georgescu | [[BR]]''sdp_index'':[[BR]] |
1802 | 1 | Adrian Georgescu | The index in the SDP for the media stream for which this object was created. |
1803 | 1 | Adrian Georgescu | '''set_ESTABLISHED'''(''self'', '''local_sdp''', '''remote_sdp''', '''sdp_index'''):: |
1804 | 1 | Adrian Georgescu | This moves the the internal state machine into the {{{ESTABLISHED}}} state. |
1805 | 1 | Adrian Georgescu | [[BR]]''local_sdp'':[[BR]] |
1806 | 1 | Adrian Georgescu | The local SDP to be proposed in the form of a {{{SDPSession}}} object. |
1807 | 1 | Adrian Georgescu | Note that this object may be modified by this method, but only when moving from the {{{LOCAL}}} to the {{{ESTABLISHED}}} state. |
1808 | 1 | Adrian Georgescu | [[BR]]''remote_sdp'':[[BR]] |
1809 | 1 | Adrian Georgescu | The remote SDP that was received in in the form of a {{{SDPSession}}} object. |
1810 | 1 | Adrian Georgescu | [[BR]]''sdp_index'':[[BR]] |
1811 | 1 | Adrian Georgescu | The index in the SDP for the media stream for which this object was created. |
1812 | 1 | Adrian Georgescu | |
1813 | 1 | Adrian Georgescu | ==== notifications ==== |
1814 | 1 | Adrian Georgescu | |
1815 | 1 | Adrian Georgescu | '''RTPTransportDidInitialize''':: |
1816 | 1 | Adrian Georgescu | This notification is sent when a {{{RTPTransport}}} object has successfully initialized. |
1817 | 1 | Adrian Georgescu | If STUN+ICE is not requested, this is sent immediately on {{{set_INIT()}}}, otherwise it is sent after the STUN query has succeeded. |
1818 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
1819 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1820 | 1 | Adrian Georgescu | '''RTPTransportDidFail''':: |
1821 | 1 | Adrian Georgescu | This notification is sent by a {{{RTPTransport}}} object that fails to retrieve ICE candidates from the STUN server after {{{set_INIT()}}} is called. |
1822 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
1823 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1824 | 1 | Adrian Georgescu | [[BR]]''reason'':[[BR]] |
1825 | 1 | Adrian Georgescu | A string describing the failure reason. |
1826 | 1 | Adrian Georgescu | |
1827 | 1 | Adrian Georgescu | === AudioTransport === |
1828 | 1 | Adrian Georgescu | |
1829 | 1 | Adrian Georgescu | This object represent an audio stream as it is transported over the network. |
1830 | 1 | Adrian Georgescu | 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. |
1831 | 1 | Adrian Georgescu | It also generates a {{{SDPMedia}}} object to be included in the local SDP. |
1832 | 1 | Adrian Georgescu | |
1833 | 75 | Ruud Klaver | The {{{AudioTransport}}} is an object that, once started, is connected to a {{{ConferenceBridge}}} instance, and both produces and consumes sound. |
1834 | 75 | Ruud Klaver | |
1835 | 1 | Adrian Georgescu | Like the {{{RTPTransport}}} object there are two usage scenarios. |
1836 | 1 | Adrian Georgescu | * In the first scenario, only the {{{RTPTransport}}} instance to be used is passed to the AudioTransport object. |
1837 | 1 | Adrian Georgescu | The application can then generate the {{{SDPMedia}}} object by calling the {{{get_local_media()}}} method and should include it in the SDP offer. |
1838 | 40 | Ruud Klaver | 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. |
1839 | 1 | Adrian Georgescu | The stream can then be connected to the conference bridge. |
1840 | 1 | Adrian Georgescu | * In the other scenario the remote SDP is already known because it was received in an SDP offer and can be passed directly on object instantiation. |
1841 | 1 | Adrian Georgescu | The local {{{SDPMedia}}} object can again be generated by calling the {{{get_local_media()}}} method and is to be included in the SDP answer. |
1842 | 1 | Adrian Georgescu | The audio stream is started directly when the object is created. |
1843 | 1 | Adrian Georgescu | |
1844 | 1 | Adrian Georgescu | Unlike the {{{RTPTransport}}} object, this object cannot be reused. |
1845 | 1 | Adrian Georgescu | |
1846 | 1 | Adrian Georgescu | ==== attributes ==== |
1847 | 1 | Adrian Georgescu | |
1848 | 75 | Ruud Klaver | '''conference_bridge''':: |
1849 | 75 | Ruud Klaver | The {{{ConferenceBridge}}} object that was passed when the object got instantiated. |
1850 | 75 | Ruud Klaver | This attribute is read-only. |
1851 | 1 | Adrian Georgescu | '''transport''':: |
1852 | 71 | Adrian Georgescu | The {{{RTPTransport}}} object that was passed when the object got instantiated. |
1853 | 40 | Ruud Klaver | This attribute is read-only. |
1854 | 75 | Ruud Klaver | '''slot''':: |
1855 | 75 | Ruud Klaver | A read-only property indicating the slot number at which this object is attached to the associated conference bridge. |
1856 | 75 | Ruud Klaver | If the {{{AudioTransport}}} is not active (i.e. has not been started), this attribute will be {{{None}}}. |
1857 | 75 | Ruud Klaver | '''volume''':: |
1858 | 75 | Ruud Klaver | A writable property indicating the % of volume at which this object contributes audio to the conference bridge. |
1859 | 75 | Ruud Klaver | By default this is set to 100. |
1860 | 40 | Ruud Klaver | '''is_active''':: |
1861 | 40 | Ruud Klaver | A boolean indicating if the object is currently sending and receiving audio. |
1862 | 1 | Adrian Georgescu | This attribute is read-only. |
1863 | 1 | Adrian Georgescu | '''is_started''':: |
1864 | 1 | Adrian Georgescu | A boolean indicating if the object has been started. |
1865 | 1 | Adrian Georgescu | Both this attribute and the {{{is_active}}} attribute get set to {{{True}}} once the {{{start()}}} method is called, but unlike the {{{is_active}}} attribute this attribute does not get set to {{{False}}} once {{{stop()}}} is called. |
1866 | 1 | Adrian Georgescu | This is to prevent the object from being re-used. |
1867 | 1 | Adrian Georgescu | This attribute is read-only. |
1868 | 1 | Adrian Georgescu | '''codec''':: |
1869 | 1 | Adrian Georgescu | Once the SDP negotiation is complete, this attribute indicates the audio codec that was negotiated, otherwise it will be {{{None}}}. |
1870 | 54 | Ruud Klaver | This attribute is read-only. |
1871 | 1 | Adrian Georgescu | '''sample_rate''':: |
1872 | 1 | Adrian Georgescu | Once the SDP negotiation is complete, this attribute indicates the sample rate of the audio codec that was negotiated, otherwise it will be {{{None}}}. |
1873 | 1 | Adrian Georgescu | This attribute is read-only. |
1874 | 1 | Adrian Georgescu | '''direction''':: |
1875 | 1 | Adrian Georgescu | The current direction of the audio transport, which is one of "sendrecv", "sendonly", "recvonly" or "inactive". |
1876 | 1 | Adrian Georgescu | This attribute is read-only, although it can be set using the {{{update_direction()}}} method. |
1877 | 1 | Adrian Georgescu | |
1878 | 54 | Ruud Klaver | ==== methods ==== |
1879 | 1 | Adrian Georgescu | |
1880 | 75 | Ruud Klaver | '''!__init!__'''(''self'', '''conference_bridge''', '''transport''', '''remote_sdp'''={{{None}}}, '''sdp_index'''=0, '''enable_silence_detection'''=True, '''codecs'''={{{None}}}):: |
1881 | 1 | Adrian Georgescu | Creates a new {{{AudioTransport}}} object and start the underlying stream if the remote SDP is already known. |
1882 | 75 | Ruud Klaver | [[BR]]''conference_bridge'':[[BR]] |
1883 | 75 | Ruud Klaver | The {{{ConferenceBridge}}} object that this object is to be connected to. |
1884 | 1 | Adrian Georgescu | [[BR]]''transport'':[[BR]] |
1885 | 1 | Adrian Georgescu | The transport to use in the form of a {{{RTPTransport}}} object. |
1886 | 55 | Ruud Klaver | [[BR]]''remote_sdp'':[[BR]] |
1887 | 55 | Ruud Klaver | The remote SDP that was received in the form of a {{{SDPSession}}} object. |
1888 | 55 | Ruud Klaver | [[BR]]''sdp_index'':[[BR]] |
1889 | 1 | Adrian Georgescu | The index within the SDP of the audio stream that should be created. |
1890 | 1 | Adrian Georgescu | [[BR]]''enable_silence_detection''[[BR]] |
1891 | 1 | Adrian Georgescu | Boolean that indicates if silence detection should be used for this audio stream. |
1892 | 1 | Adrian Georgescu | When enabled, this {{{AudioTransport}}} object will stop sending audio to the remote party if the input volume is below a certain threshold. |
1893 | 1 | Adrian Georgescu | [[BR]]''codecs''[[BR]] |
1894 | 1 | Adrian Georgescu | A list of strings indicating the codecs that should be proposed in the SDP of this {{{AudioTransport}}}, in order of preference. |
1895 | 1 | Adrian Georgescu | This overrides the global codecs list set on the {{{Engine}}}. |
1896 | 1 | Adrian Georgescu | The values of this list are case insensitive. |
1897 | 1 | Adrian Georgescu | '''get_local_media'''(''self'', '''is_offer''', '''direction'''="sendrecv"):: |
1898 | 1 | Adrian Georgescu | Generates a {{{SDPMedia}}} object which describes the audio stream. |
1899 | 1 | Adrian Georgescu | This object should be included in a {{{SDPSession}}} object that gets passed to the {{{Invitation}}} object. |
1900 | 1 | Adrian Georgescu | This method should also be used to obtain the SDP to include in re-INVITEs and replies to re-INVITEs. |
1901 | 1 | Adrian Georgescu | [[BR]]''is_offer'':[[BR]] |
1902 | 1 | Adrian Georgescu | A boolean indicating if the SDP requested is to be included in an offer. |
1903 | 1 | Adrian Georgescu | If this is {{{False}}} it is to be included in an answer. |
1904 | 1 | Adrian Georgescu | [[BR]]''direction'':[[BR]] |
1905 | 29 | Luci Stanescu | The direction attribute to put in the SDP. |
1906 | 1 | Adrian Georgescu | '''start'''(''self'', '''local_sdp''', '''remote_sdp''', '''sdp_index''', '''no_media_timeout'''=10, '''media_check_interval'''=30):: |
1907 | 1 | Adrian Georgescu | This method should only be called once, when the application has previously sent an SDP offer and the answer has been received. |
1908 | 1 | Adrian Georgescu | [[BR]]''local_sdp'':[[BR]] |
1909 | 1 | Adrian Georgescu | The full local SDP that was included in the SDP negotiation in the form of a {{{SDPSession}}} object. |
1910 | 1 | Adrian Georgescu | [[BR]]''remote_sdp'':[[BR]] |
1911 | 1 | Adrian Georgescu | The remote SDP that was received in the form of a {{{SDPSession}}} object. |
1912 | 55 | Ruud Klaver | [[BR]]''sdp_index'':[[BR]] |
1913 | 54 | Ruud Klaver | The index within the SDP of the audio stream. |
1914 | 54 | Ruud Klaver | [[BR]]''no_media_timeout'':[[BR]] |
1915 | 54 | Ruud Klaver | 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. |
1916 | 54 | Ruud Klaver | Setting this to 0 disables this an all subsequent RTP checks. |
1917 | 54 | Ruud Klaver | [[BR]]''media_check_interval'':[[BR]] |
1918 | 54 | Ruud Klaver | This indicates the interval at which the RTP stream should be checked, after it has initially received RTP at after {{{no_media_timeout}}} seconds. |
1919 | 54 | Ruud Klaver | It means that if between two of these interval checks no RTP has been received, a {{{RTPAudioTransportDidNotGetRTP}}} notification will be sent. |
1920 | 1 | Adrian Georgescu | Setting this to 0 will disable checking the RTP at intervals. |
1921 | 1 | Adrian Georgescu | The initial check may still be performed if its timeout is non-zero. |
1922 | 1 | Adrian Georgescu | '''stop'''(''self''):: |
1923 | 1 | Adrian Georgescu | This method stops and destroys the audio stream encapsulated by this object. |
1924 | 1 | Adrian Georgescu | After this it can no longer be used and should be deleted, while the {{{RTPTransport}}} object used by it can be re-used for something else. |
1925 | 1 | Adrian Georgescu | This method will be called automatically when the object is deleted after it was started, but this should not be relied on because of possible reference counting issues. |
1926 | 1 | Adrian Georgescu | '''send_dtmf'''(''self'', '''digit'''):: |
1927 | 1 | Adrian Georgescu | For a negotiated audio transport this sends one DTMF digit to the other party |
1928 | 1 | Adrian Georgescu | [[BR]]''digit'':[[BR]] |
1929 | 29 | Luci Stanescu | A string of length one indicating the DTMF digit to send. |
1930 | 1 | Adrian Georgescu | This can be either a number or letters A through D. |
1931 | 1 | Adrian Georgescu | '''update_direction'''(''self'', '''direction'''):: |
1932 | 1 | Adrian Georgescu | This method should be called after SDP negotiation has completed to update the direction of the media stream. |
1933 | 1 | Adrian Georgescu | [[BR]]''direction'':[[BR]] |
1934 | 1 | Adrian Georgescu | The direction that has been negotiated. |
1935 | 1 | Adrian Georgescu | |
1936 | 1 | Adrian Georgescu | ==== notifications ==== |
1937 | 1 | Adrian Georgescu | |
1938 | 1 | Adrian Georgescu | '''RTPAudioTransportGotDTMF''':: |
1939 | 1 | Adrian Georgescu | This notification will be sent when an incoming DTMF digit is received from the remote party. |
1940 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
1941 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1942 | 1 | Adrian Georgescu | [[BR]]''digit'':[[BR]] |
1943 | 1 | Adrian Georgescu | The DTMF digit that was received, in the form of a string of length one. |
1944 | 1 | Adrian Georgescu | This can be either a number or letters A through D. |
1945 | 1 | Adrian Georgescu | '''RTPAudioTransportDidNotGetRTP''':: |
1946 | 1 | Adrian Georgescu | This notification will be sent when no RTP packets have been received from the remote party for some time. |
1947 | 1 | Adrian Georgescu | See the {{{start()}}} method for a more exact description. |
1948 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
1949 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1950 | 1 | Adrian Georgescu | [[BR]]''got_any'':[[BR]] |
1951 | 1 | Adrian Georgescu | A boolean data attribute indicating if the {{{AudioTransport}}} every saw any RTP packets from the remote party. |
1952 | 1 | Adrian Georgescu | In effect, if no RTP was received after {{{no_media_timeout}}} seconds, its value will be {{{False}}}. |
1953 | 1 | Adrian Georgescu | |
1954 | 78 | Ruud Klaver | === ToneGenerator === |
1955 | 78 | Ruud Klaver | |
1956 | 78 | Ruud Klaver | A {{{ToneGenerator}}} can generate a series of dual frequency tones and has a shortcut method for generating valid DTMF tones. |
1957 | 78 | Ruud Klaver | Each instance of this object is associated with a {{{ConferenceBridge}}} object, which it will connect to once started. |
1958 | 78 | Ruud Klaver | The tones will be sent to the slots on the conference bridge its slot is connected to. |
1959 | 81 | Ruud Klaver | Once started, a {{{ToneGenerator}}} can be stopped by calling the {{{stop()}}} method and is automatically destroyed when the reference count reaches 0. |
1960 | 78 | Ruud Klaver | |
1961 | 78 | Ruud Klaver | ==== attributes ==== |
1962 | 78 | Ruud Klaver | |
1963 | 78 | Ruud Klaver | '''conference_bridge''':: |
1964 | 78 | Ruud Klaver | The {{{ConferenceBridge}}} object that was passed when the object got instantiated. |
1965 | 78 | Ruud Klaver | This attribute is read-only. |
1966 | 78 | Ruud Klaver | '''slot''':: |
1967 | 78 | Ruud Klaver | A read-only property indicating the slot number at which this object is attached to the associated conference bridge. |
1968 | 78 | Ruud Klaver | If the {{{ToneGenerator}}} has not been started, this attribute will be {{{None}}}. |
1969 | 78 | Ruud Klaver | '''volume''':: |
1970 | 78 | Ruud Klaver | A writable property indicating the % of volume at which this object contributes audio to the conference bridge. |
1971 | 78 | Ruud Klaver | By default this is set to 100. |
1972 | 78 | Ruud Klaver | '''is_active''':: |
1973 | 78 | Ruud Klaver | A boolean read-only property that indicates if the object has been started. |
1974 | 78 | Ruud Klaver | '''is_busy''':: |
1975 | 78 | Ruud Klaver | A boolean read-only property indicating if the {{{ToneGenerator}}} is busy playing tones. |
1976 | 78 | Ruud Klaver | |
1977 | 78 | Ruud Klaver | ==== methods ==== |
1978 | 78 | Ruud Klaver | |
1979 | 78 | Ruud Klaver | '''!__init!__'''(''self'', '''conference_bridge'''):: |
1980 | 78 | Ruud Klaver | Creates a new {{{ToneGenerator}}} object. |
1981 | 1 | Adrian Georgescu | [[BR]]''conference_bridge'':[[BR]] |
1982 | 1 | Adrian Georgescu | The {{{ConferenceBridge}}} object that this object is to be connected to. |
1983 | 78 | Ruud Klaver | '''start'''(''self''):: |
1984 | 81 | Ruud Klaver | Start the tone generator and connect it to its associated {{{ConferenceBridge}}}. |
1985 | 81 | Ruud Klaver | '''stop'''(''self''):: |
1986 | 81 | Ruud Klaver | Stop the tone generator and remove it from the conference bridge. |
1987 | 78 | Ruud Klaver | '''play_tones(''self'', '''tones'''):: |
1988 | 78 | Ruud Klaver | Play a sequence of single or dual frequency tones over the audio device. |
1989 | 78 | Ruud Klaver | [[BR]]''tones'':[[BR]] |
1990 | 78 | Ruud Klaver | 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. |
1991 | 78 | Ruud Klaver | If {{{freq2}}} is 0, this indicates that only {{{freq1}}} should be used for the tone. |
1992 | 78 | Ruud Klaver | If {{{freq1}}} is 0, this indicates a pause when no tone should be played for the set duration. |
1993 | 78 | Ruud Klaver | '''play_dtmf(''self'', '''digit'''):: |
1994 | 78 | Ruud Klaver | Play a single DTMF digit. |
1995 | 78 | Ruud Klaver | [[BR]]''digit'':[[BR]] |
1996 | 80 | Ruud Klaver | A string of length 1 containing a valid DTMF digit, i.e. 0 through 9, #, * or A through D. |
1997 | 78 | Ruud Klaver | |
1998 | 78 | Ruud Klaver | ==== notifications ==== |
1999 | 78 | Ruud Klaver | |
2000 | 78 | Ruud Klaver | '''ToneGeneratorDidFinishPlaying''':: |
2001 | 78 | Ruud Klaver | This notification will be sent whenever playing of the queued tones has finished. |
2002 | 78 | Ruud Klaver | [[BR]]''timestamp'':[[BR]] |
2003 | 78 | Ruud Klaver | A {{{datetime.datetime}}} object indicating when the notification was sent. |
2004 | 78 | Ruud Klaver | |
2005 | 78 | Ruud Klaver | |
2006 | 1 | Adrian Georgescu | === WaveFile === |
2007 | 1 | Adrian Georgescu | |
2008 | 76 | Ruud Klaver | This is a simple object that allows playing back of a {{{.wav}}} file over the PJSIP conference bridge. |
2009 | 1 | Adrian Georgescu | Only 16-bit PCM and A-law/U-law formats are supported. |
2010 | 76 | Ruud Klaver | Its main purpose is the playback of ringtones or previously recorded conversations. |
2011 | 1 | Adrian Georgescu | |
2012 | 77 | Ruud Klaver | This object is associated with a {{{ConferenceBridge}}} instance and, once the {{{start()}}} method is called, connects to it and send sound to it. |
2013 | 77 | Ruud Klaver | Note that the slot of the {{{WaveFile}}} object still needs to be connected to another slot on the conference bridge before the file actually starts playing. |
2014 | 76 | Ruud Klaver | If the {{{stop()}}} method is called or the end of the {{{.wav}}} file is reached, a {{{WaveFileDidFinishPlaying}}} notification is sent by the object. |
2015 | 1 | Adrian Georgescu | After this the {{{start()}}} method may be called again in order to re-use the object. |
2016 | 1 | Adrian Georgescu | |
2017 | 1 | Adrian Georgescu | It is the application's responsibility to keep a reference to the {{{WaveFile}}} object for the duration of playback. |
2018 | 76 | Ruud Klaver | If the reference count of the object reaches 0, playback will be stopped automatically. |
2019 | 1 | Adrian Georgescu | In this case no notification will be sent. |
2020 | 1 | Adrian Georgescu | |
2021 | 1 | Adrian Georgescu | ==== attributes ==== |
2022 | 1 | Adrian Georgescu | |
2023 | 76 | Ruud Klaver | '''conference_bridge''':: |
2024 | 76 | Ruud Klaver | The {{{ConferenceBridge}}} object that was passed when the object got instantiated. |
2025 | 76 | Ruud Klaver | This attribute is read-only. |
2026 | 1 | Adrian Georgescu | '''file_name''':: |
2027 | 1 | Adrian Georgescu | The name of the {{{.wav}}} file, as specified when the object was created. |
2028 | 76 | Ruud Klaver | '''slot''':: |
2029 | 76 | Ruud Klaver | A read-only property indicating the slot number at which this object is attached to the associated conference bridge. |
2030 | 76 | Ruud Klaver | If the {{{WaveFile}}} is not active, this attribute will be {{{None}}}. |
2031 | 76 | Ruud Klaver | '''volume''':: |
2032 | 76 | Ruud Klaver | A writable property indicating the % of volume at which this object contributes audio to the conference bridge. |
2033 | 76 | Ruud Klaver | By default this is set to 100. |
2034 | 1 | Adrian Georgescu | '''is_active''':: |
2035 | 1 | Adrian Georgescu | A boolean read-only property that indicates if the file is currently being played back. |
2036 | 1 | Adrian Georgescu | |
2037 | 15 | Ruud Klaver | ==== methods ==== |
2038 | 15 | Ruud Klaver | |
2039 | 76 | Ruud Klaver | '''!__init!__'''(''self'', '''conference_bridge''', '''file_name'''):: |
2040 | 1 | Adrian Georgescu | Creates a new {{{WaveFile}}} object. |
2041 | 76 | Ruud Klaver | [[BR]]''conference_bridge'':[[BR]] |
2042 | 76 | Ruud Klaver | The {{{ConferenceBridge}}} object that this object is to be connected to. |
2043 | 1 | Adrian Georgescu | [[BR]]''file_name'':[[BR]] |
2044 | 1 | Adrian Georgescu | The name of the {{{.wav}}} file to be played back as a string. |
2045 | 1 | Adrian Georgescu | This should include the full path to the file. |
2046 | 76 | Ruud Klaver | '''start'''(''self''):: |
2047 | 76 | Ruud Klaver | Start playback of the {{{.wav}}} file. |
2048 | 1 | Adrian Georgescu | '''stop'''(''self''):: |
2049 | 1 | Adrian Georgescu | Stop playback of the file. |
2050 | 15 | Ruud Klaver | |
2051 | 15 | Ruud Klaver | ==== notifications ==== |
2052 | 15 | Ruud Klaver | |
2053 | 15 | Ruud Klaver | '''WaveFileDidFinishPlaying''':: |
2054 | 76 | Ruud Klaver | This notification will be sent whenever playing of the {{{.wav}}} has stopped. |
2055 | 1 | Adrian Georgescu | After sending this event, the playback may be re-started. |
2056 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
2057 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
2058 | 1 | Adrian Georgescu | |
2059 | 1 | Adrian Georgescu | === RecordingWaveFile === |
2060 | 1 | Adrian Georgescu | |
2061 | 77 | Ruud Klaver | This is a simple object that allows recording audio from the conference bridge to a PCM {{{.wav}}} file. |
2062 | 1 | Adrian Georgescu | |
2063 | 77 | Ruud Klaver | This object is associated with a {{{ConferenceBridge}}} instance and, once the {{{start()}}} method is called, connects to it and send records sound from it. |
2064 | 77 | Ruud Klaver | Note that that at least one slot on the conference bridge needs to be connected to the {{{RecordingWaveFile}}} slot in order to actually start recording. |
2065 | 1 | Adrian Georgescu | Recording to the file can be stopped either by calling the {{{stop()}}} method or by removing all references to the object. |
2066 | 1 | Adrian Georgescu | Once the {{{stop()}}} method has been called, the {{{start()}}} method may not be called again. |
2067 | 77 | Ruud Klaver | 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. |
2068 | 1 | Adrian Georgescu | |
2069 | 1 | Adrian Georgescu | ==== attributes ==== |
2070 | 1 | Adrian Georgescu | |
2071 | 77 | Ruud Klaver | '''conference_bridge''':: |
2072 | 77 | Ruud Klaver | The {{{ConferenceBridge}}} object that was passed when the object got instantiated. |
2073 | 77 | Ruud Klaver | This attribute is read-only. |
2074 | 1 | Adrian Georgescu | '''file_name''':: |
2075 | 1 | Adrian Georgescu | The name of the {{{.wav}}} file, as specified when the object was created. |
2076 | 77 | Ruud Klaver | '''slot''':: |
2077 | 77 | Ruud Klaver | A read-only property indicating the slot number at which this object is attached to the associated conference bridge. |
2078 | 77 | Ruud Klaver | If the {{{RecordingWaveFile}}} is not active, this attribute will be {{{None}}}. |
2079 | 77 | Ruud Klaver | '''volume''':: |
2080 | 77 | Ruud Klaver | A writable property indicating the % of volume at which this object contributes audio to the conference bridge. |
2081 | 77 | Ruud Klaver | By default this is set to 100. |
2082 | 1 | Adrian Georgescu | '''is_active''':: |
2083 | 1 | Adrian Georgescu | A boolean read-only attribute that indicates if the file is currently being written to. |
2084 | 1 | Adrian Georgescu | |
2085 | 1 | Adrian Georgescu | ==== methods ==== |
2086 | 1 | Adrian Georgescu | |
2087 | 77 | Ruud Klaver | '''!__init!__'''(''self'', '''conference_bridge''', '''file_name'''):: |
2088 | 1 | Adrian Georgescu | Creates a new {{{RecordingWaveFile}}} object. |
2089 | 77 | Ruud Klaver | [[BR]]''conference_bridge'':[[BR]] |
2090 | 77 | Ruud Klaver | The {{{ConferenceBridge}}} object that this object is to be connected to. |
2091 | 1 | Adrian Georgescu | [[BR]]''file_name'':[[BR]] |
2092 | 1 | Adrian Georgescu | The name of the {{{.wav}}} file to record to as a string. |
2093 | 1 | Adrian Georgescu | This should include the full path to the file. |
2094 | 1 | Adrian Georgescu | '''start'''(''self''):: |
2095 | 1 | Adrian Georgescu | Start recording the sound on the conference bridge to the {{{.wav}}} file. |
2096 | 1 | Adrian Georgescu | '''stop'''(''self''):: |
2097 | 1 | Adrian Georgescu | Stop recording to the file. |