Project

General

Profile

SipMiddlewareApi » History » Version 75

Luci Stanescu, 03/26/2010 04:09 PM

1 1 Adrian Georgescu
= Middleware API =
2
3
[[TOC(WikiStart, Sip*, depth=3)]]
4
5 60 Adrian Georgescu
This chapter describes the event driven ''Middleware API'' that can be used by a developer to build a user interface for SIP SIMPLE client SDK.  
6 14 Adrian Georgescu
7 54 Adrian Georgescu
 * For sub-systems communications the Middleware uses the [http://pypi.python.org/pypi/python-application/ Notification Bus] provided by [http://pypi.python.org/pypi/python-application/ python-application]
8 49 Adrian Georgescu
 * For configuration the Middleware uses the [wiki:SipConfigurationAPI Configuration API] to access General and SIP account  settings
9 1 Adrian Georgescu
10 59 Adrian Georgescu
To see a working example for how to use Middleware, see the [http://sipsimpleclient.com/wiki/SipTesting#TestingGuide Command Line Tools] provided with the library.
11
12 53 Adrian Georgescu
[[Image(sipsimple-middleware.png, align=center, width=800)]]
13 1 Adrian Georgescu
14 64 Luci Stanescu
== Lookup support ==
15
16
The SIP SIMPLE middleware offers the {{{sipsimple.lookup}}} module which contains an implementation for doing DNS lookups for SIP proxies, MSRP relays and STUN servers. The interface offers both an asynchronous and synchronous interface. The asynchronous interface is based on notifications, while the synchronous one on green threads. In order to call the methods in a asynchronous manner, you just need to call the method and wait for the notification which is sent on behalf of the DNSLookup instance. The notifications sent by the DNSLookup object are DNSLookupDidSucceed and DNSLookupDidFail. In order to call the methods in a synchronous manner, you need to call the wait method on the object returned by the methods of DNSLookup. This wait method needs to be called from a green thread and will either return the result of the lookup or raise an exception.
17
18
=== DNS Lookup ===
19
20
This object implements DNS lookup support for SIP proxies according to RFC3263 and MSRP relay and STUN server lookup using SRV records. The object initially does NS record queries in order to determine the authoritative nameservers for the domain requested; these authoritative nameservers will then be used for NAPTR, SRV and A record queries. If this fails, the locally configured nameservers are used. The reason for doing this is that some home routers have broken NAPTR and/or SRV query support.
21
22
==== methods ====
23
24
 '''!__init!__'''(''self'')::
25
  Instantiate a new DNSLookup object.
26
 '''lookup_service'''(''self'', '''uri''', '''service''', '''timeout'''={{{3.0}}}, '''lifetime'''={{{15.0}}})::
27
  Perform an SRV lookup followed by A lookups for MSRP relays or STUN servers depending on the {{{service}}} parameter. If SRV queries on the {{{uri.host}}} domain fail, an A lookup is performed on it and the default port for the service is returned. Only the {{{uri.host}}} attribute is used. The return value is a list of (host, port) tuples.
28
  [[BR]]uri:[[BR]]
29
  A {{{(Frozen)SIPURI}}} from which the {{{host}}} attribute is used for the query domain.
30
  [[BR]]service:[[BR]]
31
  The service to lookup servers for, {{{"msrprelay"}}} or {{{"stun"}}}.
32
  [[BR]]timeout:[[BR]]
33
  How many seconds to wait for a response from a nameserver.
34
  [[BR]]lifetime:[[BR]]
35
  How many seconds to wait for a response from all nameservers in total.
36
 '''lookup_sip_proxy'''(''self'', '''uri''', '''supported_transports''', '''timeout'''={{{3.0}}}, '''lifetime'''={{{15.0}}})::
37
  Perform a RFC3263 compliant DNS lookup for a SIP proxy using the URI which is considered to point to a host if either the {{{host}}} attribute is an IP address, or the {{{port}}} is present. Otherwise, it is considered a domain for which NAPTR, SRV and A lookups are performed. If NAPTR or SRV queries fail, they fallback to using SRV and A queries. If the transport parameter is present in the URI, this will be used as far as it is part of the supported transports. If the URI has a {{{sips}}} schema, then only the TLS transport will be used as far as it doesn't conflict with the supported transports or the transport parameter. The return value is a list of {{{Route}}} objects containing the IP address, port and transport to use for routing in the order of preference given by the supported_transports argument.
38
  [[BR]]uri:[[BR]]
39
  A {{{(Frozen)SIPURI}}} from which the {{{host}}}, {{{port}}}, {{{parameters}}} and {{{secure}}} attributes are used.
40
  [[BR]]supported_transports:[[BR]]
41
  A sublist of {{{['udp', 'tcp', 'tls']}}} in the application's order of preference.
42
  [[BR]]timeout:[[BR]]
43
  How many seconds to wait for a response from a nameserver.
44
  [[BR]]lifetime:[[BR]]
45
  How many seconds to wait for a response from all nameservers in total.
46
47
==== notifications ====
48
49
 '''DNSLookupDidSucceed'''::
50
  This notification is sent when one of the lookup methods succeeds in finding a result.
51
  [[BR]]timestamp:[[BR]]
52
  A {{{datetime.datetime}}} object indicating when the notification was sent.
53
  [[BR]]result:[[BR]]
54
  The result of the DNS lookup in the format described in each method.
55
 '''DNSLookupDidFail'''::
56
  This notification is sent when one of the lookup methods fails in finding a result.
57
  [[BR]]timestamp:[[BR]]
58
  A {{{datetime.datetime}}} object indicating when the notification was sent.
59
  [[BR]]error:[[BR]]
60
  A {{{str}}} object describing the error which resulted in the DNS lookup failure.
61
 '''DNSLookupTrace'''::
62
  This notification is sent several times during a lookup process for each individual DNS query.
63
  [[BR]]timestamp:[[BR]]
64
  A {{{datetime.datetime}}} object indicating when the notification was sent.
65
  [[BR]]query_type:[[BR]]
66
  The type of the query, {{{"NAPTR"}}}, {{{"SRV"}}}, {{{"A"}}}, {{{"NS"}}} etc.
67
  [[BR]]query_name:[[BR]]
68
  The name which was queried.
69
  [[BR]]answer:[[BR]]
70
  The answer returned by dnspython, or {{{None}}} if an error occurred.
71
  [[BR]]error:[[BR]]
72
  The exception which caused the query to fail, or {{{None}}} if no error occurred.
73
  [[BR]]context:[[BR]]
74
  The name of the method which was called on the {{{DNSLookup}}} object.
75
  [[BR]]service:[[BR]]
76
  The service which was queried for, only available when context is {{{"lookup_service"}}}.
77
  [[BR]]uri:[[BR]]
78
  The uri which was queried for. 
79
80
=== Route ===
81
82
This is a convinience object which contains sufficient information to identify a route to a SIP proxy. This object is returned by {{{DNSLookup.lookup_sip_proxy}}} and can be used with the {{{Session}}} or a {{{(Frozen)RouteHeader}}} can be easily constructed from it to pass to one of the objects in the SIP core handling SIP dialogs/transactions ({{{Invitation}}}, {{{Subscription}}}, {{{Request}}}, {{{Registration}}}, {{{Message}}}, {{{Publication}}}). This object has three attributes which can be set in the constructor or after it was instantiated. They will only be documented as arguments to the constructor.
83
84
==== methods ====
85
86
 '''!__init!__'''(''self'', '''address''', '''port'''=None, '''transport'''={{{'udp'}}})::
87
  Creates the Route object with the specified parameters as attributes.
88
  Each of these attributes can be accessed on the object once instanced.
89
  [[BR]]''address'':[[BR]]
90
  The IPv4 address that the request in question should be sent to as a string.
91
  [[BR]]''port'':[[BR]]
92
  The port to send the requests to, represented as an int, or None if the default port is to be used.
93
  [[BR]]''transport'':[[BR]]
94
  The transport to use, this can be a string of either "udp", "tcp" or "tls" (case insensitive).
95
 '''get_uri'''(''self'')::
96
  Returns a {{{SIPURI}}} object which contains the adress, port and transport as parameter. This can be used to easily construct a {{{RouteHeader}}}:
97
  {{{
98
    route = Route("1.2.3.4", port=1234, transport="tls")
99
    route_header = RouteHeader(route.get_uri())
100
  }}}
101
102 62 Luci Stanescu
== High-level audio API ==
103
104
The high-level audio API hides the complexity of using the low-level PJMEDIA interface. This is implemented in the {{{sipsimple.audio}}} module and contains the following components:
105
 * IAudioPort: an interface describing an object capable of producing and/or consuming audio data.
106
 * AudioDevice: an object conforming to the IAudioPort interface which describes a physical audio device.
107
 * AudioBridge: a collection of objects conforming to IAudioPort which connects all of them in a full mesh.
108
 * WavePlayer: an object conforming to the IAudioPort interface which can playback the audio data from a {{{.wav}}} file.
109
 * WaveRecorder: an object conforming to the IAudioPort interface which can record audio data to a {{{.wav}}} file.
110
111
=== IAudioPort ===
112
113
The IAudioPort interface describes an object capable of producing and/or consuming audio data. This can be a dynamic object, which changes its role during its lifetime and notifies such changes using a notification, which is part of the interface.
114
115
==== attributes ====
116
117
 '''mixer'''::
118
  The {{{AudioMixer}}} this audio object is connected to. Only audio objects connected to the same mixer will be able to send audio data from one to another.
119
 '''consumer_slot'''::
120
  An integer representing the slot (see [wiki:SipCoreApiDocumentation#AudioMixer AudioMixer]) which this object uses to consume audio data, or {{{None}}} if this object is not a consumer.
121
 '''producer_slot'''::
122
  An integer representing the slot (see [wiki:SipCoreApiDocumentation#AudioMixer AudioMixer]) which this object uses to produce audio data, or {{{None}}} if this object is not a producer.
123
124
==== notifications ====
125
 
126
 '''AudioPortDidChangeSlots'''::
127
  This notification needs to be sent by implementations of this interface when the slots it has change, so as to let the {{{AudioBridges}}} it is part of know that reconnections need to be made.
128
  [[BR]]consumer_slot_changed:[[BR]]
129
  A bool indicating whether the consumer slot was changed.
130
  [[BR]]producer_slot_changed:[[BR]]
131
  A bool indicating whether the producer slot was changed.
132
  [[BR]]old_consumer_slot:[[BR]]
133
  The old slot for consuming audio data. Only required if consumer_slot_changed is {{{True}}}.
134
  [[BR]]new_consumer_slot:[[BR]]
135
  The new slot for consuming audio data. Only required if consumer_slot_changed is {{{True}}}.
136
  [[BR]]old_producer_slot:[[BR]]
137
  The old slot for producing audio data. Only required if producer_slot_changed is {{{True}}}.
138
  [[BR]]new_producer_slot:[[BR]]
139
  The new slot for producing audio data. Only required if producer_slot_changed is {{{True}}}.
140
141
=== AudioDevice ===
142
143
The AudioDevice represents the physical audio device which is part of a {{{AudioMixer}}}, implementing the {{{IAudioPort}}} interface. As such, it can be uniquely identified by the mixer it represents.
144
145
==== methods ====
146
147
 '''!__init!__'''(''self'', '''mixer''', '''input_muted'''={{{False}}}, '''output_muted'''={{{False}}}):
148
  Instantiates a new AudioDevice which represents the physical device associated with the specified {{{AudioMixer}}}.
149
  [[BR]]mixer:[[BR]]
150
  The {{{AudioMixer}}} whose physical device this object represents.
151
  [[BR]]input_muted:[[BR]]
152
  A boolean which indicates whether this object should act as a producer of audio data.
153
  [[BR]]output_muted:[[BR]]
154
  A boolean which indicates whether this object should act as a consumer of audio data.
155
156
==== attributes ====
157
158
 '''input_muted'''::
159
  A writable property which controls whether this object should act as a producer of audio data. An {{{AudioPortDidChange}}} slots notification is sent when this attribute is changed to force connections to be reconsidered within the {{{AudioBridges}}} this object is part of.
160
 '''output_muted'''::
161
  A writable property which controls whether this object should act as a consumer of audio data. An {{{AudioPortDidChange}}} slots notification is sent when this attribute is changed to force connections to be reconsidered within  the {{{AudioBridges}}} this object is part of.
162
163
=== AudioBridge ===
164
165
The {{{AudioBridge}}} is the basic component which is able to connect {{{IAudioPort}}} implementations. It acts as a container which connects as the producers to all the consumers which are part of it. An object which is both a producer and a consumer of audio data will not be connected to itself. Being an implementation of {{{IAudioPort}}} itself, an {{{AudioBridge}}} can be part of another {{{AudioBridge}}}. The {{{AudioBridge}}} does not keep strong references to the ports it contains and once the port's reference count reaches 0, it is automatically removed from the {{{AudioBridge}}}.
166
> Note: although this is not enforced, there should never be any cycles when connecting {{{AudioBridges}}}.
167
168
==== methods ====
169
170
 '''!__init!__'''(''self'', '''mixer''')::
171
  Instantiate a new {{{AudioBridge}}} which uses the specified {{{AudioMixer}}} for mixing.
172
 '''add'''(''self'', '''port''')::
173
  Add an implementation of {{{IAudioPort}}} to this AudioBridge. This will connect the new port to all the existing ports of the bridge. A port cannot be added more than once to an {{{AudioBridge}}}; thus, this object acts like a set.
174
 '''remove'''(''self'', '''port''')::
175
  Remove a port from this {{{AudioBridge}}}. The port must have previously been added to the {{{AudioBridge}}}, otherwise a {{{ValueError}}} is raised.
176
177
=== WavePlayer ===
178
179
A {{{WavePlayer}}} is an implementation of {{{IAudioPort}}} which is capable of producing audio data read from a {{{.wav}}} file. This object is completely reusable, as it can be started and stopped any number of times.
180
181
==== methods ====
182
183
 '''!__init!__'''(''self'', '''mixer''', '''filename''', '''volume'''={{{100}}}, '''loop_count'''={{{1}}}, '''pause_time'''={{{0}}}, '''initial_play'''={{{True}}})::
184
  Instantiate a new {{{WavePlayer}}} which is capable of playing a {{{.wav}}} file repeatedly. All the parameters are available as attributes of the object, but should not be changed once the object has been started.
185
  [[BR]]mixer:[[BR]]
186
  The {{{AudioMixer}}} this object is connected to.
187
  [[BR]]filename:[[BR]]
188
  The full path to the {{{.wav}}} file from which audio data is to be read.
189
  [[BR]]volume:[[BR]]
190
  The volume at which the file should be played.
191
  [[BR]]loop_count:[[BR]]
192
  The number of times the file should be played, or {{{0}}} for infinity.
193
  [[BR]]pause_time:[[BR]]
194
  How many seconds to wait between successive plays of the file. 
195
  [[BR]]initial_play:[[BR]]
196
  Whether or not the file to play once the {{{WavePlayer}}} is started, or to wait {{{pause_time}}} seconds before the first play.
197
 '''start'''(''self'')::
198
  Start playing the {{{.wav}}} file.
199
 '''stop'''(''self'')::
200
  Stop playuing the {{{.wav}}} file immediately.
201
202
==== attributes ====
203
204
 '''is_active'''::
205
  A boolean indicating whether or not this {{{WavePlayer}}} is currently playing.
206
207
==== notifications ====
208
209
 '''WavePlayerDidStart'''::
210
  This notification is sent when the {{{WavePlayer}}} starts playing the file the first time after the {{{start()}}} method has been called.
211
  [[BR]]timestamp:[[BR]]
212
  A {{{datetime.datetime}}} object indicating when the notification was sent.
213
 '''WavePlayerDidEnd'''::
214
  This notification is sent when the {{{WavePlayer}}} is done playing either as a result of playing the number of times it was told to, or because the {{{stop()}}} method has been called.
215
  [[BR]]timestamp:[[BR]]
216
  A {{{datetime.datetime}}} object indicating when the notification was sent.
217
 '''WavePlayerDidFail'''::
218
  This notification is sent when the {{{WavePlayer}}} is not capable of playing the {{{.wav}}} file.
219
  [[BR]]timestamp:[[BR]]
220
  A {{{datetime.datetime}}} object indicating when the notification was sent.
221
  [[BR]]error:[[BR]]
222
  The exception raised by the {{{WaveFile}}} which identifies the cause for not being able to play the {{{.wav}}} file.
223
224
=== WaveRecorder ===
225
226
A {{{WaveRecorder}}} is an implementation of {{{IAudioPort}}} is is capable of consuming audio data and writing it to a {{{.wav}}} file. Just like {{{WavePlayer}}}, this object is reusable: once stopped it can be started again, but if the filename attribute is not changed, the previously written file will be overwritten.
227
228
==== methods ====
229
230
 '''!__init!__'''(''self'', '''mixer''', '''filename''')::
231
  Instantiate a new {{{WaveRecorder}}}.
232
  [[BR]]mixer:[[BR]]
233
  The {{{AudioMixer}}} this {{{WaveRecorder}}} is connected to.
234
  [[BR]]filename:[[BR]]
235
  The full path to the {{{.wav}}} file where this object should write the audio data. The file must be writable. The directories up to the file will be created if possible when the {{{start()}}} method is called.
236
 '''start'''(''self'')::
237
  Start consuming audio data and writing it to the {{{.wav}}} file. If this object is not part of an {{{AudioBridge}}}, not audio data will be written.
238
 '''stop'''(''self'')::
239
  Stop consuming audio data and close the {{{.wav}}} file.
240
241
==== attributes ====
242
243
 '''is_active'''::
244
  A boolean indicating whether or not this {{{WaveRecorder}}} is currently recording audio data.
245
246 1 Adrian Georgescu
== SIPApplication ==
247
248 62 Luci Stanescu
Implemented in [browser:sipsimple/application.py]
249 1 Adrian Georgescu
250 62 Luci Stanescu
Implements a high-level application responsable for starting and stopping various sub-systems required to implement a fully featured SIP User Agent application. The SIPApplication class is a Singleton and can be instantiated from any part of the code, obtaining a reference to the same object. The SIPApplication takes care of initializing the following components:
251
 * the twisted thread
252
 * the configuration system, via the [wiki:SipConfigurationAPI#ConfigurationManager ConfigurationManager].
253
 * the core [wiki:SipCoreApiDocumentation#Engine Engine] using the settings in the configuration
254
 * the [wiki:SipMiddlewareApi#AccountManager AccountManager], using the accounts in the configuration
255 63 Luci Stanescu
 * the [wiki:SipMiddlewareApi#SessionManager SessionManager], in order to handle incoming sessions
256 62 Luci Stanescu
 * two [wiki:SipMiddlewareApi#AudioBridge AudioBridges], using the settings in the configuration
257 1 Adrian Georgescu
258 62 Luci Stanescu
The attributes in this class can be set and accessed on both this class and its subclasses, as they are implemented using descriptors which keep single value for each attribute, irrespective of the class from which that attribute is set/accessed. Usually, all attributes should be considered read-only.
259 1 Adrian Georgescu
260 62 Luci Stanescu
=== Methods  ===
261
262
 '''!__init!__'''(''self'')::
263
  Instantiates a new SIPApplication.
264
 '''start'''(''self'', '''config_backend''')::
265
  Starts the {{{SIPApplication}}} which initializes all the components in the correct order. The {{{config_backend}}} is used to start the {{{ConfigurationManager}}}. If any error occurs with loading the configuration, the exception raised by the {{{ConfigurationManager}}} is propagated by this method and {{{SIPApplication}}} can be started again. After this, any fatal errors will result in the SIPApplication being stopped and unusable, which means the whole application will need to stop. This method returns as soon as the twisted thread has been started, which means the application must wait for the {{{SIPApplicationDidStart}}} notification in order to know that the application started.
266
 '''stop'''(''self'')::
267
  Stop all the components started by the SIPApplication. This method returns immediately, but a {{{SIPApplicationDidEnd}}} notification is sent when all the components have been stopped.
268
269 1 Adrian Georgescu
=== Attributes ===
270
271 62 Luci Stanescu
 '''running'''::
272
  {{{True}}} if the SIPApplication is running (it has been started and it has not been told to stop), {{{False}}} otherwise.
273
 '''alert_audio_mixer'''::
274
  The {{{AudioMixer}}} object created on the alert audio device as defined by the configuration (by SIPSimpleSettings.audio.alert_device).
275
 '''alert_audio_bridge'''::
276
  An {{{AudioBridge}}} where {{{IAudioPort}}} objects can be added to playback sound to the alert device.
277
 '''alert_audio_device'''::
278
  An {{{AudioDevice}}} which corresponds to the alert device as defined by the configuration. This will always be part of the alert_audio_bridge.
279
 '''voice_audio_mixer'''::
280
  The {{{AudioMixer}}} object created on the voice audio device as defined by the configuration (by SIPSimpleSettings.audio.input_device and SIPSimpleSettings.audio.output_device).
281
 '''voice_audio_bridge'''::
282
  An {{{AudioBridge}}} where {{{IAudioPort}}} objects can be added to playback sound to the output device or record sound from the input device.
283
 '''voice_audio_device'''::
284
  An {{{AudioDevice}}} which corresponds to the voice device as defined by the configuration. This will always be part of the voice_audio_bridge.
285 1 Adrian Georgescu
286
=== Notifications  ===
287 62 Luci Stanescu
288
 '''SIPApplicationWillStart'''::
289
  This notification is sent just after the configuration has been loaded and the twisted thread started, but before any other components have been initialized.
290
  [[BR]]timestamp:[[BR]]
291
  A {{{datetime.datetime}}} object indicating when the notification was sent.
292
 '''SIPApplicationDidStart'''::
293
  This notification is sent when all the components have been initialized. Note: it doesn't mean that all components have succeeded, for example, the account might not have registered by this time, but the registration process will have started.
294
  [[BR]]timestamp:[[BR]]
295
  A {{{datetime.datetime}}} object indicating when the notification was sent.
296
 '''SIPApplicationWillEnd'''::
297
  This notification is sent as soon as the {{{stop()}}} method has been called.
298
  [[BR]]timestamp:[[BR]]
299
  A {{{datetime.datetime}}} object indicating when the notification was sent.
300
 '''SIPApplicationDidEnd'''::
301
  This notification is sent when all the components have been stopped. All components have been given reasonable time to shutdown gracefully, such as the account unregistering. However, because of factors outside the control of the middleware, such as network problems, some components might not have actually shutdown gracefully; this is needed because otherwise the SIPApplication could hang indefinitely (for example because the system is no longer connected to a network and it cannot be determined when it will be again).
302
  [[BR]]timestamp:[[BR]]
303
  A {{{datetime.datetime}}} object indicating when the notification was sent.
304
 '''SIPApplicationFailedToStartTLS'''::
305
  This notification is sent when a problem arises with initializing the TLS transport. In this case, the Engine will be started without TLS support and this notification contains the error which identifies the cause for not being able to start the TLS transport.
306
  [[BR]]timestamp:[[BR]]
307
  A {{{datetime.datetime}}} object indicating when the notification was sent.
308
  [[BR]]error:[[BR]]
309
  The exception raised by the Engine which identifies the cause for not being able to start the TLS transport.
310 50 Adrian Georgescu
311 1 Adrian Georgescu
312 63 Luci Stanescu
== SIP Sessions ==
313 1 Adrian Georgescu
314 63 Luci Stanescu
SIP sessions are supported by the {{{sipsimple.session.Session}}} class and independent stream classes, which need to implement the {{{sipsimple.streams.IMediaStream}}} interface. The {{{Session}}} class takes care of the signalling, while the streams offer the actual media support which is negotiated by the {{{Session}}}. The streams which are implemented in the SIP SIMPLE middleware are provided in modules within the {{{sipsimple.streams}}} package, but they are accessible for import directly from {{{sipsimple.streams}}}. Currently, the middleware implements two types of streams, one for RTP data, with a concrete implementation in the {{{AudioStream}}} class, and one for MSRP sessions, with concrete implementations in the {{{ChatStream}}}, {{{FileTransferStream}}} and {{{DesktopSharingStream}}} classes. However, the application can provide its own stream implementation, provided they respect the {{{IMediaStream}}} interface.
315
316 74 Luci Stanescu
The {{{sipsimple.streams}}} module also provides a mechanism for automatically registering media streams in order for them to be used for incoming sessions. This is explained in more detail in [wiki:SipMiddlewareApi#MediaStreamRegistry MediaStreamRegistry].
317 65 Luci Stanescu
318 44 Adrian Georgescu
=== Session ===
319 1 Adrian Georgescu
320
Implemented in [browser:sipsimple/session.py]
321 26 Luci Stanescu
322 1 Adrian Georgescu
A {{{sipsimple.session.Session}}} object represents a complete SIP session between the local and a remote endpoints. Both incoming and outgoing sessions are represented by this class.
323
324
A {{{Session}}} instance is a stateful object, meaning that it has a {{{state}}} attribute and that the lifetime of the session traverses different states, from session creation to termination.
325 2 Adrian Georgescu
State changes are triggered by methods called on the object by the application or by received network events.
326 1 Adrian Georgescu
These states and their transitions are represented in the following diagram:
327 63 Luci Stanescu
328 1 Adrian Georgescu
Although these states are crucial to the correct operation of the {{{Session}}} object, an application using this object does not need to keep track of these states, as a set of notifications is also emitted, which provide all the necessary information to the application.
329 63 Luci Stanescu
330
The {{{Session}}} is completely independent of the streams it contains, which need to be implementations of the {{{sipsimple.streams.IMediaStream}}} interface. This interface provides the API by which the {{{Session}}} communicates with the streams. This API should not be used by the application, unless it also provides stream implementations or a SIP INVITE session implementation.
331
332
==== methods ====
333
334
 '''!__init!__'''(''self'', '''account''')::
335
  Creates a new {{{Session}}} object in the {{{None}}} state.
336
  [[BR]]''account'':[[BR]]
337
  The local account to be associated with this {{{Session}}}.
338
 '''connect'''(''self'', '''to_header''', '''routes''', '''streams''')::
339
  Will set up the {{{Session}}} as outbound and propose the new session to the specified remote party and move the state machine to the {{{outgoing}}} state.
340
  Before contacting the remote party, a {{{SIPSessionNewOutgoing}}} notification will be emitted.
341
  If there is a failure or the remote party rejected the offer, a {{{SIPSessionDidFail}}} notification will be sent.
342
  Any time a ringing indication is received from the remote party, a {{{SIPSessionGotRingIndication}}} notification is sent.
343
  If the remote party accepted the session, a {{{SIPSessionWillStart}}} notification will be sent, followed by a {{{SIPSessionDidStart}}} notification when the session is actually established.
344
  This method may only be called while in the {{{None}}} state.
345
  [[BR]]''to_header'':[[BR]]
346
  A {{{sipsimple.core.ToHeader}}} object representing the remote identity to initiate the session to.
347
  [[BR]]''routes'':[[BR]]
348
  An iterable of {{{sipsimple.util.Route}}} objects, specifying the IP, port and transport to the outbound proxy.
349
  These routes will be tried in order, until one of them succeeds.
350
  [[BR]]''streams'':[[BR]]
351
  A list of stream objects which will be offered to the remote endpoint.
352
 '''send_ring_indication'''(''self'')::
353
  Sends a 180 provisional response in the case of an incoming session.
354
 '''accept'''(''self'', '''streams''')::
355
  Calling this methods will accept an incoming session and move the state machine to the {{{accepting}}} state.
356
  When there is a new incoming session, a {{{SIPSessionNewIncoming}}} notification is sent, after which the application can call this method on the sender of the notification.
357
  After this method is called, {{{SIPSessionWillStart}}} followed by {{{SIPSessionDidStart}}} will be emitted, or {{{SIPSessionDidFail}}} on an error.
358
  This method may only be called while in the {{{incoming}}} state.
359
  [[BR]]''streams'':[[BR]]
360
  A list of streams which needs to be a subset of the proposed streams which indicates which streams are to be accepted. All the other proposed streams will be rejected.
361
 '''reject'''(''self'', '''code'''={{{603}}}, '''reason'''={{{None}}})::
362
  Reject an incoming session and move it to the {{{terminaing}}} state, which eventually leads to the {{{terminated}}} state.
363
  Calling this method will cause the {{{Session}}} object to emit a {{{SIPSessionDidFail}}} notification once the session has been rejected.
364
  This method may only be called while in the {{{incoming}}} state.
365
  [[BR]]''code'':[[BR]]
366
  An integer which represents the SIP status code in the response which is to be sent. Usually, this is either 486 (Busy) or 603 (Decline/Busy Everywhere).
367
  [[BR]]''reason'':[[BR]]
368
  The string which is to be sent as the SIP status reason in the response, or None if PJSIP's default reason for the specified code is to be sent.
369
 '''accept_proposal'''(''self'', '''streams''')::
370
  When the remote party proposes to add some new streams, signaled by the {{{SIPSessionGotProposal}}} notification, the application can use this method to accept the stream(s) being proposed.
371
  After calling this method a {{{SIPSessionGotAcceptProposal}}} notification is sent, unless an error occurs while setting up the new stream, in which case a {{{SIPSessionHadProposalFailure}}} notification is sent and a rejection is sent to the remote party. As with any action which causes the streams in the session to change, a {{{SIPSessionDidRenegotiateStreams}}} notification is also sent.
372
  This method may only be called while in the {{{received_proposal}}} state.
373
  [[BR]]''streams'':[[BR]]
374
  A list of streams which needs to be a subset of the proposed streams which indicates which streams are to be accepted. All the other proposed streams will be rejected.
375
 '''reject_proposal'''(''self'', '''code'''={{{488}}}, '''reason'''={{{None}}})::
376
  When the remote party proposes new streams that the application does not want to accept, this method can be used to reject the proposal, after which a {{{SIPSessionGotRejectProposal}}} or {{{SIPSessionHadProposalFailure}}} notification is sent.
377
  This method may only be called while in the {{{received_proposal}}} state.
378
  [[BR]]''code'':[[BR]]
379
  An integer which represents the SIP status code in the response which is to be sent. Usually, this is 488 (Not Acceptable Here).
380
  [[BR]]''reason'':[[BR]]
381
  The string which is to be sent as the SIP status reason in the response, or None if PJSIP's default reason for the specified code is to be sent.
382
 '''add_stream'''(''self'', '''stream''')::
383
  Proposes a new stream to the remote party.
384
  Calling this method will cause a {{{SIPSessionGotProposal}}} notification to be emitted.
385
  After this, the state machine will move into the {{{sending_proposal}}} state until either a {{{SIPSessionGotAcceptProposal}}}, {{{SIPSessionGotRejectProposal}}} or {{{SIPSessionHadProposalFailure}}} notification is sent, informing the application if the remote party accepted the proposal. As with any action which causes the streams in the session to change, a {{{SIPSessionDidRenegotiateStreams}}} notification is also sent.
386
  This method may only be called while in the {{{connected}}} state.
387
 '''remove_stream'''(''self'', '''stream''')::
388
  Stop the stream and remove it from the session, informing the remote party of this. Although technically this is also done via an SDP negotiation which may fail, the stream will always get remove (if the remote party refuses the re-INVITE, the result will be that the remote party will have a different view of the active streams than the local party).
389
  This method may only be called while in the {{{connected}}} state.
390
 '''cancel_proposal'''(''self'')::
391
  This method cancels a proposal of adding a stream to the session by sending a CANCEL request. A {{{SIPSessionGotRejectProposal}}} notification will be sent with code 487.
392
 '''hold'''(''self'')::
393
  Put the streams of the session which support the notion of hold on hold.
394
  This will cause a {{{SIPSessionDidChangeHoldState}}} notification to be sent.
395
  This method may be called in any state and will send the re-INVITE as soon as it is possible.
396
 '''unhold'''(''self'')::
397
  Take the streams of the session which support the notion of hold out of hold.
398
  This will cause a {{{SIPSessionDidChangeHoldState}}} notification to be sent.
399
  This method may be called in any state and will send teh re-INVITE as soon as it is possible.
400
 '''end'''(''self'')::
401
  This method may be called any time after the {{{Session}}} has started in order to terminate the session by sending a BYE request.
402 1 Adrian Georgescu
  Right before termination a {{{SIPSessionWillEnd}}} notification is sent, after termination {{{SIPSessionDidEnd}}} is sent.
403
404 64 Luci Stanescu
==== attributes ====
405 1 Adrian Georgescu
406
 '''state'''::
407
  The state the object is currently in, being one of the states from the diagram above.
408
 '''account'''::
409 19 Ruud Klaver
  The {{{sipsimple.account.Account}}} or {{{sipsimple.account.BonjourAccount}}} object that the {{{Session}}} is associated with.
410 1 Adrian Georgescu
  On an outbound session, this is the account the application specified on object instantiation.
411
 '''direction'''::
412 32 Adrian Georgescu
  A string indicating the direction of the initial negotiation of the session.
413 63 Luci Stanescu
  This can be either {{{None}}}, "incoming" or "outgoing".
414
 '''transport'''::
415 1 Adrian Georgescu
  A string representing the transport this {{{Session}}} is using: {{{"udp"}}}, {{{"tcp"}}} or {{{"tls"}}}.
416
 '''start_time'''::
417
  The time the session started as a {{{datetime.datetime}}} object, or {{{None}}} if the session was not yet started.
418
 '''stop_time'''::
419
  The time the session stopped as a {{{datetime.datetime}}} object, or {{{None}}} if the session has not yet terminated.
420
 '''on_hold'''::
421
  Boolean indicating whether the session was put on hold, either by the local or the remote party.
422
 '''remote_user_agent'''::
423
  A string indicating the remote user agent, if it provided one.
424 63 Luci Stanescu
  Initially this will be {{{None}}}, it will be set as soon as this information is received from the remote party (which may be never).
425
 '''local_identity'''::
426
  The {{{sipsimple.core.FrozenFromHeader}}} or {{{sipsimple.core.FrozenToHeader}}} identifying the local party, if the session is active, {{{None}}} otherwise.
427
 '''remote_identity'''::
428
  The {{{sipsimple.core.FrozenFromHeader}}} or {{{sipsimple.core.FrozenToHeader}}} identifying the remote party, if the session is active, {{{None}}} otherwise.
429
 '''streams'''::
430
  A list of the currently active streams in the {{{Session}}}.
431
 '''proposed_streams'''::
432 1 Adrian Georgescu
  A list of the currently proposed streams in the {{{Session}}}, or {{{None}}} if there is no proposal in progress.
433
434 64 Luci Stanescu
==== notifications ====
435 1 Adrian Georgescu
436
 '''SIPSessionNewIncoming'''::
437 26 Luci Stanescu
  Will be sent when a new incoming {{{Session}}} is received.
438 63 Luci Stanescu
  The application should listen for this notification to get informed of incoming sessions.
439 1 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
440
  A {{{datetime.datetime}}} object indicating when the notification was sent.
441
  [[BR]]''streams'':[[BR]]
442 63 Luci Stanescu
  A list of streams that were proposed by the remote party.
443 1 Adrian Georgescu
 '''SIPSessionNewOutgoing'''::
444
  Will be sent when the applcation requests a new outgoing {{{Session}}}.
445
  [[BR]]''timestamp'':[[BR]]
446
  A {{{datetime.datetime}}} object indicating when the notification was sent.
447
  [[BR]]''streams'':[[BR]]
448 63 Luci Stanescu
  A list of streams that were proposed to the remote party.
449 1 Adrian Georgescu
 '''SIPSessionGotRingIndication'''::
450
  Will be sent when an outgoing {{{Session}}} receives an indication that a remote device is ringing.
451
  [[BR]]''timestamp'':[[BR]]
452 26 Luci Stanescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
453 63 Luci Stanescu
 '''SIPSessionGotProvisionalResponse'''::
454
  Will be sent whenever the {{{Session}}} receives a provisional response as a result of sending a (re-)INVITE.
455
  [[BR]]''timestamp'':[[BR]]
456
  A {{{datetime.datetime}}} object indicating when the notification was sent.
457
  [[BR]]''code'':[[BR]]
458
  The SIP status code received.
459
  [[BR]]''reason'':[[BR]]
460
  The SIP status reason received.
461 1 Adrian Georgescu
 '''SIPSessionWillStart'''::
462
  Will be sent just before a {{{Session}}} completes negotiation.
463
  In terms of SIP, this is sent after the final response to the {{{INVITE}}}, but before the {{{ACK}}}.
464
  [[BR]]''timestamp'':[[BR]]
465
  A {{{datetime.datetime}}} object indicating when the notification was sent.
466
 '''SIPSessionDidStart'''::
467 63 Luci Stanescu
  Will be sent when a {{{Session}}} completes negotiation and all the streams have started.
468 26 Luci Stanescu
  In terms of SIP this is sent after the {{{ACK}}} was sent or received.
469 1 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
470
  A {{{datetime.datetime}}} object indicating when the notification was sent.
471 63 Luci Stanescu
  [[BR]]''streams'':[[BR]]
472
  The list of streams which now form the active streams of the {{{Session}}}.
473 1 Adrian Georgescu
 '''SIPSessionDidFail'''::
474 63 Luci Stanescu
  This notification is sent whenever the session fails before it starts.
475 5 Redmine Admin
  The failure reason is included in the data attributes.
476 63 Luci Stanescu
  This notification is never followed by {{{SIPSessionDidEnd}}}.
477 1 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
478 26 Luci Stanescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
479 1 Adrian Georgescu
  [[BR]]''originator'':[[BR]]
480 63 Luci Stanescu
  A string indicating the originator of the {{{Session}}}. This will either be "local" or "remote".
481 1 Adrian Georgescu
  [[BR]]''code'':[[BR]]
482
  The SIP error code of the failure.
483
  [[BR]]''reason'':[[BR]]
484 63 Luci Stanescu
  A SIP status reason.
485
  [[BR]]''failure_reason'':[[BR]]
486
  A string which represents the reason for the failure, such as {{{"user_request"}}}, {{{"missing ACK"}}}, {{{"SIP core error..."}}}.
487 1 Adrian Georgescu
 '''SIPSessionWillEnd'''::
488 63 Luci Stanescu
  Will be sent just before terminating a {{{Session}}}.
489 1 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
490
  A {{{datetime.datetime}}} object indicating when the notification was sent.
491
 '''SIPSessionDidEnd'''::
492 63 Luci Stanescu
  Will be sent always when a {{{Session}}} ends as a result of remote or local session termination.
493 1 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
494 19 Ruud Klaver
  A {{{datetime.datetime}}} object indicating when the notification was sent.
495
  [[BR]]''originator'':[[BR]]
496 63 Luci Stanescu
  A string indicating who originated the termination. This will either be "local" or "remote".
497
  [[BR]]''end_reason'':[[BR]]
498
  A string representing the termination reason, such as {{{"user_request"}}}, {{{"SIP core error..."}}}.
499
 '''SIPSessionDidChangeHoldState'''::
500
  Will be sent when the session got put on hold or removed from hold, either by the local or the remote party.
501 1 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
502
  A {{{datetime.datetime}}} object indicating when the notification was sent.
503
  [[BR]]''originator'':[[BR]]
504
  A string indicating who originated the hold request, and consequently in which direction the session got put on hold.
505 63 Luci Stanescu
  [[BR]]''on_hold'':[[BR]]
506
  {{{True}}} if there is at least one stream which is on hold and {{{False}}} otherwise.
507
  [[BR]]''partial'':[[BR]]
508
  {{{True}}} if there is at least one stream which is on hold and one stream which supports hold but is not on hold and {{{False}}} otherwise.
509
 '''SIPSessionGotProposal'''::
510
  Will be sent when either the local or the remote party proposes to add streams to the session.
511 26 Luci Stanescu
  [[BR]]''timestamp'':[[BR]]
512 23 Ruud Klaver
  A {{{datetime.datetime}}} object indicating when the notification was sent.
513
  [[BR]]''originator'':[[BR]]
514 63 Luci Stanescu
  The party that initiated the stream proposal, can be either "local" or "remote".
515
  [[BR]]''streams'':[[BR]]
516
  A list of streams that were proposed.
517
 '''SIPSessionGotRejectProposal'''::
518
  Will be sent when either the local or the remote party rejects a proposal to have streams added to the session.
519 6 Ruud Klaver
  [[BR]]''timestamp'':[[BR]]
520
  A {{{datetime.datetime}}} object indicating when the notification was sent.
521 63 Luci Stanescu
  [[BR]]''originator'':[[BR]]
522
  The party that initiated the stream proposal, can be either "local" or "remote".
523 6 Ruud Klaver
  [[BR]]''code'':[[BR]]
524 63 Luci Stanescu
  The code with which the proposal was rejected.
525 1 Adrian Georgescu
  [[BR]]''reason'':[[BR]]
526 63 Luci Stanescu
  The reason for rejecting the stream proposal.
527
  [[BR]]''streams'':[[BR]]
528
  The list of streams which were rejected.
529
 '''SIPSessionGotAcceptProposal'''::
530
  Will be sent when either the local or the remote party accepts a proposal to have stream( added to the session.
531 24 Ruud Klaver
  [[BR]]''timestamp'':[[BR]]
532 1 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
533 63 Luci Stanescu
  [[BR]]''originator'':[[BR]]
534
  The party that initiated the stream proposal, can be either "local" or "remote".
535 1 Adrian Georgescu
  [[BR]]''streams'':[[BR]]
536 63 Luci Stanescu
  The list of streams which were accepted.
537
 '''SIPSessionHadProposalFailure'''::
538 24 Ruud Klaver
  Will be sent when a re-INVITE fails because of an internal reason (such as a stream not being able to start).
539
  [[BR]]''timestamp'':[[BR]]
540 63 Luci Stanescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
541
  [[BR]]''failure_reason'':[[BR]]
542
  The error which caused the proposal to fail.
543
  [[BR]]''streams'':[[BR]]
544
  THe streams which were part of this proposal.
545 24 Ruud Klaver
 '''SIPSessionDidRenegotiateStreams'''::
546 6 Ruud Klaver
  Will be sent when a media stream is either activated or deactivated.
547 26 Luci Stanescu
  An application should listen to this notification in order to know when a media stream can be used.
548 63 Luci Stanescu
  [[BR]]''timestamp'':[[BR]]
549 6 Ruud Klaver
  A {{{datetime.datetime}}} object indicating when the notification was sent.
550 63 Luci Stanescu
  [[BR]]''action'':[[BR]]
551
  A string which is either {{{"add"}}} or {{{"remove"}}} which specifies what happened to the streams the notificaton referes to
552
  [[BR]]''streams'':[[BR]]
553
  A list with the streams which were added or removed.
554
 '''SIPSessionDidProcessTransaction'''::
555
  Will be sent whenever a SIP transaction is complete in order to provide low-level details of the progress of the INVITE dialog.
556 37 Luci Stanescu
  [[BR]]''timestamp'':[[BR]]
557
  A {{{datetime.datetime}}} object indicating when the notification was sent.
558
  [[BR]]''originator'':[[BR]]
559
  The initiator of the transaction, {{{"local"}}} or {{{"remote"}}}.
560
  [[BR]]''method'':[[BR]]
561
  The method of the request.
562
  [[BR]]''code'':[[BR]]
563
  The SIP status code of the response.
564
  [[BR]]''reason'':[[BR]]
565
  The SIP status reason of the response.
566
  [[BR]]''ack_received'':[[BR]]
567
  This attribute is only present for INVITE transactions and has one of the values {{{True}}}, {{{False}}} or {{{"unknown"}}}. The last value may occur then PJSIP does not let us know whether the ACK was received or not.
568 1 Adrian Georgescu
569 37 Luci Stanescu
As an example for how to use the {{{Session}}} object, the following provides a basic Python program that initiates an outgoing SIP session request:
570
571
{{{
572
from threading import Event
573 50 Adrian Georgescu
574 48 Adrian Georgescu
from application.notification, NotificationCenter
575 37 Luci Stanescu
576
from sipsimple.core import SIPURI, ToHeader
577 50 Adrian Georgescu
578 38 Luci Stanescu
from sipsimple.account import AccountManager
579
from sipsimple.application import SIPApplication
580
from sipsimple.session import Session
581 50 Adrian Georgescu
from sipsimple.streams import AudioStream
582 38 Luci Stanescu
from sipsimple.util import Route
583 1 Adrian Georgescu
584 38 Luci Stanescu
585
class SimpleCallApplication(SIPApplication):
586 1 Adrian Georgescu
    def __init__(self, callee, route):
587
        SIPApplication.__init__(self)
588
        self.ended = Event()
589
        self.callee = calee
590 38 Luci Stanescu
        self.route = route
591
        self.session = None
592
        notification_center = NotificationCenter()
593
        notification_center.add_observer(self)
594 1 Adrian Georgescu
595
    def _NH_SIPApplicationDidStart(self, notification):
596
        account = AccountManager().default_account
597 38 Luci Stanescu
        self.session = Session(account)
598
        self.session.connect(self.callee, self.route, AudioStream(account))
599 1 Adrian Georgescu
600 38 Luci Stanescu
    def _NH_SIPSessionGotRingIndication(self, notification):
601
        print 'Ringing!'
602
603
    def _NH_SIPSessionDidStart(self, notification):
604
        print 'Session started!'
605
606
    def _NH_SIPSessionDidFail(self, notification):
607
        print 'Failed to connect'
608 1 Adrian Georgescu
        self.stop()
609 38 Luci Stanescu
610
    def _NH_SIPSessionDidEnd(self, notification):
611
        print 'Session ended'
612 1 Adrian Georgescu
        self.stop()
613
614 39 Luci Stanescu
    def _NH_SIPApplicationDidEnd(self, notification):
615 50 Adrian Georgescu
        self.ended.set()
616 39 Luci Stanescu
617
# place an audio call from the specified account to the specified URI, through
618
# the specified SIP proxy
619
application = SimpleCallApplication(ToHeader(SIPURI(user="bob", host="example.com")), Route("1.2.3.4"))
620
# block waiting for user input
621
print "Placing call, press enter to quit program"
622
raw_input()
623
application.session.end()
624
# block until the SIPApplication has stopped
625 1 Adrian Georgescu
application.ended.wait()
626 50 Adrian Georgescu
}}}
627 48 Adrian Georgescu
628 64 Luci Stanescu
=== SessionManager ===
629 39 Luci Stanescu
630
Implemented in [browser:sipsimple/session.py]
631
632 1 Adrian Georgescu
The {{{sipsimple.session.SessionManager}}} class is a singleton, which acts as the central aggregation point for sessions within the middleware.
633 50 Adrian Georgescu
Although it is mainly used internally, the application can use it to query information about all active sessions.
634 39 Luci Stanescu
The SessionManager is implemented as a singleton, meaning that only one instance of this class exists within the middleware. The SessionManager is started by the SIPApplication and takes care of handling incoming sessions.
635
636 64 Luci Stanescu
==== attributes ====
637 39 Luci Stanescu
638
 '''sessions'''::
639
  A property providing a copy of the list of all active {{{Sesssion}}} objects within the application, meaning any {{{Session}}} object that exists globally within the application and is not in the {{{NULL}}} or {{{TERMINATED}}} state.
640
641 64 Luci Stanescu
==== methods ====
642 39 Luci Stanescu
643
 '''!__init!__'''(''self'')::
644
  Instantiate a new {{{SessionManager}}} object.
645
646
 '''start'''(''self'')::
647
  Start the {{{SessionManager}}} in order to be able to handle incoming sessions.
648 1 Adrian Georgescu
649 65 Luci Stanescu
=== IMediaStream ===
650 39 Luci Stanescu
651
Implemented in [browser:sipsimple/streams/__init__.py]
652 1 Adrian Georgescu
653 65 Luci Stanescu
This interface describes the API which the {{{Session}}} uses to communicate with the streams. All streams used by the {{{Session}}} __must__ respect this interface.
654 1 Adrian Georgescu
655 66 Luci Stanescu
==== methods ====
656 1 Adrian Georgescu
657
 '''!__init!__'''(''self'', ''account'')::
658 65 Luci Stanescu
  Initializes the generic stream instance.
659 1 Adrian Georgescu
 '''new_from_sdp'''(''cls'', ''account'', ''remote_sdp'', ''stream_index'')::
660 65 Luci Stanescu
  A classmethod which returns an instance of this stream implementation if the sdp is accepted by the stream or None otherwise.
661
  [[BR]]account:[[BR]]
662
  The {{{sipsimple.account.Account}}} or {{{sipsimple.account.BonjourAccount}}} object the session which this stream would be part of is associated with.
663
  [[BR]]remote_sdp:[[BR]]
664
  The {{{FrozenSDPSession}}} which was received by the remote offer.
665
  [[BR]]stream_index:[[BR]]
666
  An integer representing the index within the list of media streams within the whole SDP which this stream would be instantiated for. 
667 1 Adrian Georgescu
 '''get_local_media'''(''self'', ''for_offer'')::
668 65 Luci Stanescu
  Return an {{{SDPMediaStream}}} which represents an offer for using this stream if {{{for_offer}}} is {{{True}}} and a response to an SDP proposal otherwise.
669
  [[BR]]for_offer:[[BR]]
670
  {{{True}}} if the {{{SDPMediaStream}}} will be used for an SDP proposal and {{{False}}} if for a response.
671 1 Adrian Georgescu
 '''initialize'''(''self'', ''session'', ''direction'')::
672 65 Luci Stanescu
  Initializes the stream. This method will get called as soon as the stream is known to be at least offered as part of the {{{Session}}}. If initialization goes fine, the stream must send a {{{MediaStreamDidInitialize}}} notification or a {{{MediaStreamDidFail}}} notification otherwise.
673
  [[BR]]session:[[BR]]
674
  The {{{Session}}} object this stream will be part of.
675
  [[BR]]direction:[[BR]]
676
  {{{"incoming"}}} if the stream was created because of a received proposal and {{{"outgoing"}}} if a proposal was sent. Note that this need not be the same as the initial direction of the {{{Session}}} since streams can be proposed in either way using re-INVITEs.
677 1 Adrian Georgescu
 '''start'''(''self'', ''local_sdp'', ''remote_sdp'', ''stream_index'')::
678 65 Luci Stanescu
  Starts the stream. This method will be called as soon is known to be used in the {{{Session}}} (eg. only called for an incoming proposal if the local party accepts the proposed stream). If starting succeeds, the stream must send a {{{MediaStreamDidStart}}} notification or a {{{MediaStreamDidFail}}} notification otherwise.
679
  [[BR]]local_sdp:[[BR]]
680
  The {{{FrozenSDPSession}}} which is used by the local endpoint.
681
  [[BR]]remote_sdp:[[BR]]
682
  The {{{FrozenSDPSession}}} which is used by the remote endpoint.
683
  [[BR]]stream_index:[[BR]]
684
  An integer representing the index within the list of media streams within the whole SDP which this stream is represented by. 
685 1 Adrian Georgescu
 '''validate_update'''(''self'', ''remote_sdp'', ''stream_index'')::
686 65 Luci Stanescu
  This method will be called when a re-INVITE is received which changes the parameters of the stream within the SDP. The stream must return {{{True}}} if the changes are acceptable or {{{False}}} otherwise. If any changed streams return {{{False}}} for a re-INVITE, the re-INVITE will be refused with a negative response. This means that streams must not changed any internal data when this method is called as the update is not guaranteed to be applied even if the stream returns {{{True}}}. 
687
  [[BR]]remote_sdp:[[BR]]
688
  The {{{FrozenSDPSession}}} which is used by the remote endpoint.
689
  [[BR]]stream_index:[[BR]]
690
  An integer representing the index within the list of media streams within the whole SDP which this stream is represented by. 
691 1 Adrian Georgescu
 '''update'''(''self'', ''local_sdp'', ''remote_sdp'', ''stream_index'')::
692 65 Luci Stanescu
  This method is called when the an SDP negotiation initiated by either the local party or the remote party succeeds. The stream must update its internal state according to the new SDP in use.
693
  [[BR]]local_sdp:[[BR]]
694
  The {{{FrozenSDPSession}}} which is used by the local endpoint.
695
  [[BR]]remote_sdp:[[BR]]
696
  The {{{FrozenSDPSession}}} which is used by the remote endpoint.
697
  [[BR]]stream_index:[[BR]]
698
  An integer representing the index within the list of media streams within the whole SDP which this stream is represented by. 
699 55 Adrian Georgescu
 '''hold'''(''self'')::
700 65 Luci Stanescu
  Puts the stream on hold if supported by the stream. Typically used by audio and video streams. The stream must immediately stop sending/receiving data and calls to {{{get_local_media()}}} following calls to this method must return an SDP which reflects the new hold state.
701 55 Adrian Georgescu
 '''unhold'''(''self'')::
702 65 Luci Stanescu
  Takes the stream off hold. Typically used by audio and video streams. Calls to {{{get_local_media()}}} following calls to this method must return an SDP which reflects the new hold state.
703
 '''deactivate'''(''self'')::
704
  This method is called on a stream just before the stream will be removed from the {{{Session}}} (either as a result of a re-INVITE or a BYE). This method is needed because it avoids a race condition with streams using stateful protocols such as TCP: the stream connection might be terminated before the SIP signalling announces this due to network routing inconsistencies and the other endpoint would not be able to distinguish between this case and an error which caused the stream transport to fail. The stream must not take any action, but must consider that the transport being closed by the other endpoint after this method was called as a normal situation rather than an error condition.
705
 '''end'''(''self'')::
706
  Ends the stream. This must close the underlying transport connection. The stream must send a {{{MediaStreamWillEnd}}} just after this method is called and a {{{MediaStreamDidEnd}}} as soon as the operation is complete. This method is always be called by the {{{Session}}} on the stream if at least the {{{initialize()}}} method has been called. This means that once a stream sends the {{{MediaStreamDidFail}}} notification, the {{{Session}}} will still call this method.
707 55 Adrian Georgescu
708 65 Luci Stanescu
==== atributes ====
709 55 Adrian Georgescu
710 65 Luci Stanescu
 '''type''' (class attribute)::
711
  A string identifying the stream type (eg: {{{"audio"}}}, {{{"video"}}}).
712
 '''priority''' (class attribute)::
713
  An integer value indicating the stream priority relative to the other streams types (higher numbers have higher priority).
714
 '''hold_supported'''::
715
  True if the stream supports hold
716
 '''on_hold_by_local'''::
717
  True if the stream is on hold by the local party
718
 '''on_hold_by_remote'''::
719
  True if the stream is on hold by the remote
720
 '''on_hold'''::
721
  True if either on_hold_by_local or on_hold_by_remote is true
722 55 Adrian Georgescu
723 65 Luci Stanescu
==== notifications ====
724
725
These notifications must be generated by all streams in order for the {{{Session}}} to know the state of the stream.
726
727 55 Adrian Georgescu
 '''MediaStreamDidInitialize'''::
728 65 Luci Stanescu
  Sent when the stream has been successfully initialized.
729 55 Adrian Georgescu
 '''MediaStreamDidStart'''::
730 65 Luci Stanescu
  Sent when the stream has been successfully started.
731 55 Adrian Georgescu
 '''MediaStreamDidFail'''::
732 65 Luci Stanescu
  Sent when the stream has failed either as a result of calling one of its methods, or during the normal operation of the stream (such as the transport connection being closed).
733 55 Adrian Georgescu
 '''MediaStreamWillEnd'''::
734 65 Luci Stanescu
  Sent immediately after the {{{end()}}} method is called.
735 55 Adrian Georgescu
 '''MediaStreamDidEnd'''::
736 65 Luci Stanescu
  Sent when the {{{end()}}} method finished closing the stream.
737 55 Adrian Georgescu
738 66 Luci Stanescu
=== MediaStreamRegistry ===
739 55 Adrian Georgescu
740 66 Luci Stanescu
The MediaStream registry is a collection of classes which implement {{{IMediaStream}}}. This collection is used by the {{{Session}}} to select a stream class for instantiation in the case of an incomming session. The streams are included in the collection in the descending order of their priority. Thus, streams with a higher priority will be tried first by the {{{Session}}}. This object is a Singleton so references to the same object can be obtained by a simple instantiation.
741 1 Adrian Georgescu
742 66 Luci Stanescu
There are several pre-built streams based on the {{{IMediaStream}}} API:
743
 * {{{sipsimple.streams.rtp.AudioStream}}} - Audio stream based on RTP
744 1 Adrian Georgescu
 * {{{sipsimple.streams.msrp.ChatStream}}} - Chat stream based on MSRP 
745
 * {{{sipsimple.streams.msrp.FileTransferStream}}} - File Transfer stream based on MSRP 
746 66 Luci Stanescu
 * {{{sipsimple.streams.msrp.DesktopSharingStream}}} -  Desktop Sharing stream based on VNC over MSRP
747 1 Adrian Georgescu
748 66 Luci Stanescu
Other streams which are created by the application must be registered in this registry. For a simple way of doing this, see [wiki:SipMiddlewareApi#MediaStreamRegistrar MediaStreamRegistrar].
749
750
==== methods ====
751
752
 '''!__init!__'''(''self'')::
753
  Instantiate the MediaStreamRegistry. This will be called just once when first (and only) instance is created.
754
 '''!__iter!__'''(''self'')::
755
  This method allows the registry to be iterated through and will return classes which were registered to it.
756
 '''add'''(''self'', '''cls''')::
757
  Add {{{cls}}} to the registry of streams. The class must implement the {{{IMediaStream}}} interface.
758
759
=== MediaStreamRegistrar ===
760
761
This is a convenience metaclass which automatically registers a defined class with the {{{MediaStreamRegistry}}}. In order to use this class, one simply needs to use it as the metaclass of the new stream.
762
763
{{{
764
from zope.interface import implements
765
766
from sipsimple.streams import IMediaStream, MediaStreamRegistrar
767
768
769
class MyStream(object):
770
  __metaclass__ = MediaStreamRegistrar
771
772
  implements(IMediaStream)
773
  
774
[...] 
775
}}}
776 55 Adrian Georgescu
777 67 Luci Stanescu
=== AudioStream ===
778 55 Adrian Georgescu
779
Implemented in [browser:sipsimple/streams/rtp.py]
780
781 67 Luci Stanescu
The {{{AudioStream}}} is an implementation of {{{IMediaStream}}} which supports audio data using the {{{AudioTransport}}} and {{{RTPTransport}}} of the SIP core. As such, it provides all features of these objects, including ICE negotiation. An example SDP created using the {{{AudioStream}}} is provided below:
782 55 Adrian Georgescu
783
{{{
784
Content-Type: application/sdp
785
Content-Length:  1093
786
787
v=0
788
o=- 3467525278 3467525278 IN IP4 192.168.1.6
789
s=blink-0.10.7-beta
790
c=IN IP4 80.101.96.20
791
t=0 0
792 57 Adrian Georgescu
m=audio 55328 RTP/AVP 104 103 102 3 9 0 8 101
793
a=rtcp:55329 IN IP4 80.101.96.20
794
a=rtpmap:104 speex/32000
795
a=rtpmap:103 speex/16000
796
a=rtpmap:102 speex/8000
797
a=rtpmap:3 GSM/8000
798
a=rtpmap:9 G722/8000
799
a=rtpmap:0 PCMU/8000
800
a=rtpmap:8 PCMA/8000
801
a=rtpmap:101 telephone-event/8000
802
a=fmtp:101 0-15
803
a=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:esI6DbLY1+Aceu0JNswN9Z10DcFx5cZwqJcu91jb
804
a=crypto:2 AES_CM_128_HMAC_SHA1_32 inline:SHuEMm1BYJqOF4udKl73EaCwnsI57pO86bYKsg70
805
a=ice-ufrag:2701ed80
806
a=ice-pwd:6f8f8281
807
a=candidate:S 1 UDP 31 80.101.96.20 55328 typ srflx raddr 192.168.1.6 rport 55328
808
a=candidate:H 1 UDP 23 192.168.1.6 55328 typ host
809
a=candidate:H 1 UDP 23 10.211.55.2 55328 typ host
810
a=candidate:H 1 UDP 23 10.37.129.2 55328 typ host
811
a=candidate:S 2 UDP 30 80.101.96.20 55329 typ srflx raddr 192.168.1.6 rport 55329
812
a=candidate:H 2 UDP 22 192.168.1.6 55329 typ host
813
a=candidate:H 2 UDP 22 10.211.55.2 55329 typ host
814
a=candidate:H 2 UDP 22 10.37.129.2 55329 typ host
815
a=sendrecv
816
}}}
817 1 Adrian Georgescu
818 67 Luci Stanescu
As an implementation of {{{IAudioPort}}}, an {{{AudioStream}}} can be added to an {{{AudioBridge}}} to send or to read audio data to/from other audio objects. It is connected to the voice {{{AudioMixer}}} ({{{SIPApplication.voice_audio_mixer}}}) so it can only be added to bridges using the same {{{AudioMixer}}}. It also contains an {{{AudioBridge}}} on the {{{bridge}}} attribute which always contains an {{{AudioDevice}}} corresponding to the input and output devices; when the stream is active (started and not on hold), the bridge also contains the stream itself and when recording is active, the stream contains a {{{WaveRecorder}}} which records audio data.
819 1 Adrian Georgescu
820 67 Luci Stanescu
==== methods ====
821
822
 '''start_recording'''(''self'', '''filename'''={{{None}}})::
823
  If an audio stream is present within this session, calling this method will record the audio to a {{{.wav}}} file.
824
  Note that when the session is on hold, nothing will be recorded to the file.
825
  Right before starting the recording a {{{SIPSessionWillStartRecordingAudio}}} notification will be emitted, followed by a {{{SIPSessionDidStartRecordingAudio}}}.
826
  This method may only be called while the stream is started.
827
  [[BR]]''filename'':[[BR]]
828
  The name of the {{{.wav}}} file to record to.
829
  If this is set to {{{None}}}, a default file name including the session participants and the timestamp will be generated using the directory defined in the configuration.
830
 '''stop_recording'''(''self'')::
831
  This will stop a previously started recording.
832
  Before stopping, a {{{SIPSessionWillStopRecordingAudio}}} notification will be sent, followed by a {{{SIPSessionDidStopRecordingAudio}}}.
833
 '''send_dtmf'''(''self'', '''digit''')::
834
  If the audio stream is started, sends a DTMF digit to the remote party.
835
  [[BR]]''digit'':[[BR]]
836
  This should a string of length 1, containing a valid DTMF digit value (0-9, A-D, * or #).
837
838
==== attributes ====
839
840 63 Luci Stanescu
 '''sample_rate'''::
841
  If the audio stream was started, this attribute contains the sample rate of the audio negotiated.
842
 '''codec'''::
843 1 Adrian Georgescu
  If the audio stream was started, this attribute contains the name of the audio codec that was negotiated.
844
 '''srtp_active'''::
845
  If the audio stream was started, this boolean attribute indicates if SRTP is currently being used on the stream.
846 67 Luci Stanescu
 '''ice_active'''::
847
  {{{True}}} if the ICE candidates negotiated are being used, {{{False}}} otherwise.
848 1 Adrian Georgescu
 '''local_rtp_address'''::
849
  If an audio stream is present within the session, this attribute contains the local IP address used for the audio stream.
850
 '''local_rtp_port'''::
851
  If an audio stream is present within the session, this attribute contains the local UDP port used for the audio stream.
852
 '''remote_rtp_address_sdp'''::
853
  If the audio stream was started, this attribute contains the IP address that the remote party gave to send audio to.
854
 '''remote_rtp_port_sdp'''::
855
  If the audio stream was started, this attribute contains the UDP port that the remote party gave to send audio to.
856
 '''remote_rtp_address_received'''::
857
  If the audio stream was started, this attribute contains the remote IP address from which the audio stream is being received.
858
 '''remote_rtp_port_received'''::
859
  If the audio stream was started, this attribute contains the remote UDP port from which the audio stream is being received.
860 67 Luci Stanescu
 '''local_rtp_candidate_type'''::
861
  The local ICE candidate type which was selected by the ICE negotiation if it succeeded and {{{None}}} otherwise.
862
 '''remote_rtp_candidate_type'''::
863
  The remote ICE candidate type which was selected by the ICE negotiation if it succeeded and {{{None}}} otherwise.
864
 '''recording_filename'''::
865 63 Luci Stanescu
  If the audio stream is currently being recorded to disk, this property contains the name of the {{{.wav}}} file being recorded to.
866
867 67 Luci Stanescu
==== notifications ====
868 55 Adrian Georgescu
869
 '''AudioStreamDidChangeHoldState'''::
870 67 Luci Stanescu
  Will be sent when the hold state is changed as a result of either a SIP message received on the network or the application calling the {{{hold()/unhold()}}} methods on the {{{Session}}} this stream is part of.
871
  [[BR]]''timestamp'':[[BR]]
872
  A {{{datetime.datetime}}} object indicating when the notification was sent.
873
  [[BR]]originator:[[BR]]
874
  A string representing the party which requested the hold change, {{{"local"}}} or {{{"remote"}}}
875
  [[BR]]on_hold:[[BR]]
876
  A boolean indicating the new hold state from the point of view of the originator.
877 1 Adrian Georgescu
 '''AudioStreamWillStartRecordingAudio''::
878 67 Luci Stanescu
  Will be sent when the application requested that the audio stream be recorded to a {{{.wav}}} file, just before recording starts.
879 63 Luci Stanescu
  [[BR]]''timestamp'':[[BR]]
880
  A {{{datetime.datetime}}} object indicating when the notification was sent.
881 67 Luci Stanescu
  [[BR]]''filename'':[[BR]]
882
  The full path to the {{{.wav}}} file being recorded to.
883 55 Adrian Georgescu
 '''AudioStreamDidStartRecordingAudio'''::
884 67 Luci Stanescu
  Will be sent when the application requested that the audio stream be recorded to a {{{.wav}}} file, just after recording started.
885 63 Luci Stanescu
  [[BR]]''timestamp'':[[BR]]
886
  A {{{datetime.datetime}}} object indicating when the notification was sent.
887 67 Luci Stanescu
  [[BR]]''filename'':[[BR]]
888
  The full path to the {{{.wav}}} file being recorded to.
889 63 Luci Stanescu
 '''AudioStreamWillStopRecordingAudio'''::
890
  Will be sent when the application requested ending the recording to a {{{.wav}}} file, just before recording stops.
891
  [[BR]]''timestamp'':[[BR]]
892
  A {{{datetime.datetime}}} object indicating when the notification was sent.
893 67 Luci Stanescu
  [[BR]]''filename'':[[BR]]
894
  The full path to the {{{.wav}}} file being recorded to.
895 57 Adrian Georgescu
 '''AudioStreamDidStopRecordingAudio'''::
896 67 Luci Stanescu
  Will be sent when the application requested ending the recording to a {{{.wav}}} file, just after recording stoped.
897 63 Luci Stanescu
  [[BR]]''timestamp'':[[BR]]
898
  A {{{datetime.datetime}}} object indicating when the notification was sent.
899 67 Luci Stanescu
  [[BR]]''filename'':[[BR]]
900
  The full path to the {{{.wav}}} file being recorded to.
901
 '''AudioStreamDidChangeRTPParameters'''::
902
  This notification is sent when the RTP parameters are changed, such as codec, sample rate, RTP port etc.
903 63 Luci Stanescu
  [[BR]]''timestamp'':[[BR]]
904 1 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
905 63 Luci Stanescu
 '''AudioStreamGotDTMF'''::
906 1 Adrian Georgescu
  Will be send if there is a DMTF digit received from the remote party on the audio stream. 
907 57 Adrian Georgescu
  [[BR]]''timestamp'':[[BR]]
908 1 Adrian Georgescu
  A {{{datetime.datetime}}} object indicating when the notification was sent.
909 63 Luci Stanescu
  [[BR]]''digit'':[[BR]]
910 1 Adrian Georgescu
  The DTMF digit that was received, in the form of a string of length 1.
911 67 Luci Stanescu
 '''AudioStreamICENegotiationStateDidChange'''::
912
  This notification is proxied from the {{{RTPTransport}}} and as such has the same data as the {{{RTPTransportICENegotiationStateDidChange}}}.
913
 '''AudioStreamICENegotiationDidSucceed'''::
914
  This notification is proxied from the {{{RTPTransport}}} and as such has the same data as the {{{RTPTransportICENegotiationDidSucceed}}}.
915
 '''AudioStreamICENegotiationDidFail'''::
916
  This notification is proxied from the {{{RTPTransport}}} and as such has the same data as the {{{RTPTransportICENegotiationDidFail}}}.
917 1 Adrian Georgescu
 
918 69 Luci Stanescu
=== MSRPStreamBase ===
919 1 Adrian Georgescu
920
Implemented in [browser:sipsimple/streams/msrp.py]
921
922 68 Luci Stanescu
The {{{MSRPStreamBase}}} is used as a base class for streams using the MSRP protocol. Within the SIP SIMPLE middleware, this hold for the {{{ChatStream}}}, {{{FileTransferStream}}} and {{{DesktopSharingStream}}} classes, however the application can also make use of this class to implement some other streams based on the MSRP protocol as a transport.
923 1 Adrian Georgescu
924 68 Luci Stanescu
==== methods ====
925
 
926
Of the methods defined by the {{{IMediaStream}}} interface, only the {{{new_from_sdp}}} method is not implemented in this base class and needs to be provided by the subclasses. Also, the subclasses can defined methods of the form {{{_handle_XXX}}}, where XXX is a MSRP method name in order to handle incoming MSRP requests. Also, since this class registers as an observer for itself, it will receive the notifications it sends so subclasses can define methods having the signature {{{_NH_<notification name>(self, notification)}}} as used throughout the middleware in order to do various things at the different points within the life-cycle of the stream.
927
928 69 Luci Stanescu
==== atributes ====
929 68 Luci Stanescu
930
The attributes defined in the {{{IMediaStream}}} interface which are not provided by this class are:
931
 * type
932
 * priority
933
934
In addition, the following attributes need to be defined in the subclass in order for the {{{MSRPStreamBase}}} class to take the correct decisions
935 1 Adrian Georgescu
 '''media_type'''::
936 68 Luci Stanescu
  The media type as included in the SDP (eg. {{{"message"}}}, {{{"application"}}}).
937 1 Adrian Georgescu
 '''accept_types'''::
938 68 Luci Stanescu
  A list of the MIME types which should be accepted by the stream (this is also sent within the SDP).
939 1 Adrian Georgescu
 '''accept_wrapped_types'''::
940 68 Luci Stanescu
  A list of the MIME types which should be accepted by the stream while wrapped in a {{{message/cpim}}} envelope.
941 1 Adrian Georgescu
 '''use_msrp_session'''::
942 68 Luci Stanescu
  A boolean indicating whether or not an {{{MSRPSession}}} should be used.
943 1 Adrian Georgescu
944 69 Luci Stanescu
==== notifications ====
945 1 Adrian Georgescu
946 68 Luci Stanescu
While not technically notifications of {{{MSRPStreamBase}}}, these notifications are sent from the middleware on behalf of the {{{MSRPTransport}}} used by a stream in the former case, and anonymously in the latter.
947
948 1 Adrian Georgescu
 '''MSRPTransportTrace'''::
949 68 Luci Stanescu
  This notification is sent when an MSRP message is received for logging purposes.
950
  [[BR]]timestamp:[[BR]]
951
  A {{{datetime.datetime}}} object indicating when the notification was sent.
952
  [[BR]]direction:[[BR]]
953
  The direction of the message, {{{"incoming"}}} or {{{"outgoing"}}}.
954
  [[BR]]data:[[BR]]
955
  The MSRP message as a string.
956
 '''MSRPLibraryLog'''::
957
  This notification is sent anonymously whenever the MSRP library needs to log any information.
958
  [[BR]]timestamp:[[BR]]
959
  A {{{datetime.datetime}}} object indicating when the notification was sent.
960
  [[BR]]message:[[BR]]
961
  The log message as a string.
962
  [[BR]]level:[[BR]]
963
  The log level at which the message was written. One of the levels {{{DEBUG}}}, {{{INFO}}}, {{{WARNING}}}, {{{ERROR}}}, {{{CRITICAL}}} from the {{{application.log.level}}} object which is part of the {{{python-application}}} library.
964 1 Adrian Georgescu
965 68 Luci Stanescu
=== ChatStream ===
966 1 Adrian Georgescu
967
Implemented in [browser:sipsimple/streams/msrp.py]
968
969 68 Luci Stanescu
{{{sipsimple.streams.msrp.ChatStream}}} implements session-based Instant Messaging (IM) over MSRP. This class performs the following functions:
970 1 Adrian Georgescu
971
 * automatically wraps outgoing messages with Message/CPIM if that's necessary according to accept-types
972 68 Luci Stanescu
 * unwraps incoming Message/CPIM messages; for each incoming message, the {{{ChatStreamGotMessage}}} notification is posted
973
 * composes iscomposing payloads and reacts to those received by sending the {{{ChatStreamGotComposingIndication}}} notification
974 1 Adrian Georgescu
975 68 Luci Stanescu
An example of an SDP created using this class follows:
976 1 Adrian Georgescu
977
{{{
978
Content-Type: application/sdp
979
Content-Length:   283
980
981
v=0
982
o=- 3467525214 3467525214 IN IP4 192.168.1.6
983
s=blink-0.10.7-beta
984
c=IN IP4 192.168.1.6
985
t=0 0
986
m=message 2855 TCP/TLS/MSRP *
987
a=path:msrps://192.168.1.6:2855/ca7940f12ddef14c3c32;tcp
988
a=accept-types:message/cpim text/* application/im-iscomposing+xml
989
a=accept-wrapped-types:*
990
}}}
991
992 68 Luci Stanescu
==== methods ====
993 1 Adrian Georgescu
994 68 Luci Stanescu
 '''!__init!__'''(''self'', '''account''', '''direction'''={{{'sendrecv'}}})::
995
  Initializes the ChatStream instance.
996 1 Adrian Georgescu
997 68 Luci Stanescu
 '''send_message'''(''self'', '''content''', '''content_type'''={{{'text/plain'}}}, '''recipients'''={{{None}}}, '''courtesy_recipients'''={{{None}}}, '''subject'''={{{None}}}, ''timestamp''={{{None}}}, '''required'''={{{None}}}, '''additional_headers'''={{{None}}})::
998
  Sends an IM message. Prefer Message/CPIM wrapper if it is supported. If called before the connection was established, the messages will be
999
  queued until the stream starts.
1000
  Returns the generated MSRP message ID.
1001
  [[BR]]content:[[BR]]
1002
  The content of the message.
1003
  [[BR]]content_type:[[BR]]
1004
  Content-Type of wrapped message if Message/CPIM is used (Content-Type of MSRP message is always Message/CPIM in that case);
1005
  otherwise, Content-Type of MSRP message.
1006
  [[BR]]recipients:[[BR]]
1007
  The list of {{{CPIMIdentity}}} objects which will be used for the {{{To}}} header of the CPIM wrapper. Used to override the default which depends on the remote identity.
1008
  May only differ from the default one if the remote party supports private messages. If it does not, a {{{ChatStreamError}}} will be raised.
1009
  [[BR]]courtesy_recipients:[[BR]]
1010
  The list of {{{CPIMIdentity}}} objects which will be used for the {{{cc}}} header of the CPIM wrapper.
1011
  May only be specified if the remote party supports private messages and CPIM is supported. If it does not, a {{{ChatStreamError}}} will be raised.
1012
  [[BR]]subject:[[BR]]
1013
  A string or {{{MultilingualText}}} which specifies the subject and its translations to be added to the CPIM message. If CPIM is not supported, a {{{ChatStreamError}}} will be raised.
1014
  [[BR]]required:[[BR]]
1015
  A list of strings describing the required capabilities that the other endpoint must support in order to understand this CPIM message. If CPIM is not supported, a {{{ChatStreamError}}} will be raised.
1016
  [[BR]]additional_headers:[[BR]]
1017
  A list of MSRP header objects which will be added to this CPIM message. If CPIM is not supported, a {{{ChatStreamError}}} will be raised.
1018
  [[BR]]timestamp:[[BR]]
1019 1 Adrian Georgescu
  A {{{datetime.datetime}}} object representing the timestamp to put on the CPIM wrapper of the message.
1020 68 Luci Stanescu
  When set to {{{None}}}, a default one representing the current moment will be added.
1021 1 Adrian Georgescu
1022
 These MSRP headers are used to enable end-to-end success reports and to disable hop-to-hop successful responses:
1023
{{{
1024
Failure-Report: partial
1025
Success-Report: yes
1026
}}}
1027
1028 68 Luci Stanescu
 '''send_composing_indication'''(''self'', ''state'', ''refresh'', ''last_active=None'', ''recipients=None'')::
1029
  Sends an is-composing message to the listed recipients.
1030
  [[BR]]state:[[BR]]
1031
  The state of the endpoint, {{{"active"}}} or {{{"idle"}}}.
1032
  [[BR]]refresh:[[BR]]
1033
  How often the local endpoint will send is-composing indications to keep the state from being reverted to {{{"idle"}}}.
1034
  [[BR]]last_active:[[BR]]
1035
  A {{{datatime.datetime}}} object representing the moment when the local endpoint was last active.
1036
  [[BR]]recipients:[[BR]]
1037
  The list of {{{CPIMIdentity}}} objects which will be used for the {{{To}}} header of the CPIM wrapper. Used to override the default which depends on the remote identity.
1038
  May only differ from the default one if the remote party supports private messages. If it does not, a {{{ChatStreamError}}} will be raised.
1039 1 Adrian Georgescu
1040 68 Luci Stanescu
==== notifications ====
1041 1 Adrian Georgescu
1042
 '''ChatStreamGotMessage'''::
1043 68 Luci Stanescu
  Sent whenever a new incoming message is received,
1044
  [[BR]]timestamp:[[BR]]
1045
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1046
  [[BR]]message:[[BR]]
1047
  A {{{ChatMessage}}} or {{{CPIMMessage}}} instance, depending on whether a CPIM message was received or not.
1048 1 Adrian Georgescu
 '''ChatStreamDidDeliverMessage'''::
1049 68 Luci Stanescu
  Sent when a successful report is received.
1050
  [[BR]]timestamp:[[BR]]
1051
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1052
  [[BR]]message_id:[[BR]]
1053 1 Adrian Georgescu
  Text identifier of the message.
1054 68 Luci Stanescu
  [[BR]]code:[[BR]]
1055
  The status code received. Will always be 200 for this notification.
1056
  [[BR]]reason:[[BR]]
1057
  The status reason received.
1058
  [[BR]]chunk:[[BR]]
1059 1 Adrian Georgescu
  A {{{msrplib.protocol.MSRPData}}} instance providing all the MSRP information about the report.
1060
 '''ChatStreamDidNotDeliverMessage'''::
1061 68 Luci Stanescu
  Sent when a failure report is received.
1062
  [[BR]]timestamp:[[BR]]
1063
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1064
  [[BR]]message_id:[[BR]]
1065 1 Adrian Georgescu
  Text identifier of the message.
1066 68 Luci Stanescu
  [[BR]]code:[[BR]]
1067
  The status code received.
1068
  [[BR]]reason:[[BR]]
1069
  The status reason received.
1070
  [[BR]]chunk:[[BR]]
1071 1 Adrian Georgescu
  A {{{msrplib.protocol.MSRPData}}} instance providing all the MSRP information about the report.
1072
 '''ChatStreamDidSendMessage'''::
1073 68 Luci Stanescu
  Sent when an outgoing message has been sent.
1074
  [[BR]]timestamp:[[BR]]
1075
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1076
  [[BR]]message:[[BR]]
1077
  A {{{msrplib.protocol.MSRPData}}} instance providing all the MSRP information about the sent message.
1078 1 Adrian Georgescu
 '''ChatStreamGotComposingIndication'''::
1079 68 Luci Stanescu
  Sent when a is-composing payload is received.
1080
  [[BR]]timestamp:[[BR]]
1081
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1082
  [[BR]]state:[[BR]]
1083
  The state of the endpoint, {{{"active"}}} or {{{"idle"}}}.
1084
  [[BR]]refresh:[[BR]]
1085
  How often the remote endpoint will send is-composing indications to keep the state from being reverted to {{{"idle"}}}. May be {{{None}}}.
1086
  [[BR]]last_active:[[BR]]
1087
  A {{{datatime.datetime}}} object representing the moment when the remote endpoint was last active. May be {{{None}}}.
1088
  [[BR]]content_type:[[BR]]
1089
  The MIME type of message being composed. May be {{{None}}}.
1090
  [[BR]]sender:[[BR]]
1091
  The {{{ChatIdentity}}} or {{{CPIMIdentity}}} instance which identifies the sender of the is-composing indication.
1092 55 Adrian Georgescu
1093 70 Luci Stanescu
=== FileSelector ===
1094 1 Adrian Georgescu
1095 70 Luci Stanescu
The {{{FileSelector}}} is used to contain information about a file tranfer using the {{{FileTransferStream}}} documented below.
1096
1097
==== methods ====
1098
1099
 '''!__init!__'''(''self'', '''name'''={{{None}}}, '''type'''={{{None}}}, '''size'''={{{None}}}, '''hash'''={{{None}}}, '''fd'''={{{None}}})::
1100
  Instantiate a new {{{FileSelector}}}. All the arguments are also available as attributes.
1101
  [[BR]]name:[[BR]]
1102
  The filename (should be just the base name).
1103
  [[BR]]type:[[BR]]
1104
  The type of the file.
1105
  [[BR]]size:[[BR]]
1106
  The size of the file in bytes.
1107
  [[BR]]hash:[[BR]]
1108
  The hash of the file in the following format: {{{hash:sha-1:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX}}}, where {{{X}}} is a hexadecimal digit. Currently, only SHA1 hashes are supported according to the RFC.
1109
  [[BR]]fd:[[BR]]
1110
  A file descriptor if the application has already opened the file.
1111
 '''parse'''(''cls'', '''string''')::
1112
  Parses a file selector from the SDP {{{file-selector}}} a attribute and returns a {{{FileSelector}}} instance.
1113
 '''for_file'''(''cls'', '''path''', '''content_type''', '''compute_hash'''={{{True}}})::
1114
  Returns a {{{FileSelector}}} instance for the specified file. The file identified by the path must exist. Note that if {{{compute_hash}}} is {{{True}}} this method will block while the hash is computed, a potentially long operation for large files.
1115
  [[BR]]path:[[BR]]
1116
  The full path to the file.
1117
  [[BR]]content_type:[[BR]]
1118
  An optional MIME type which is to be included in the file-selector.
1119
  [[BR]]compute_hash:[[BR]]
1120
  Whether or not this method should compute the hash of the file.
1121
1122
==== attributes ====
1123
1124
 '''sdp_repr'''::
1125
  The SDP representation of the file-selector according to the RFC. This should be the value of the {{{file-selector}}} SDP attribute.
1126
1127
=== FileTransferStream ===
1128
1129 1 Adrian Georgescu
Implemented in [browser:sipsimple/streams/msrp.py]
1130 55 Adrian Georgescu
1131 70 Luci Stanescu
The {{{FileTransferStream}}} supports file transfer over MSRP according to RFC5547. An example of SDP constructed using this stream follows:
1132 55 Adrian Georgescu
1133
{{{
1134
Content-Type: application/sdp
1135
Content-Length:   383
1136
1137
v=0
1138
o=- 3467525166 3467525166 IN IP4 192.168.1.6
1139
s=blink-0.10.7-beta
1140
c=IN IP4 192.168.1.6
1141
t=0 0
1142
m=message 2855 TCP/TLS/MSRP *
1143 64 Luci Stanescu
a=path:msrps://192.168.1.6:2855/e593357dc9abe90754bd;tcp
1144 55 Adrian Georgescu
a=sendonly
1145 64 Luci Stanescu
a=accept-types:*
1146 55 Adrian Georgescu
a=accept-wrapped-types:*
1147 1 Adrian Georgescu
a=file-selector:name:"reblink.pdf" type:com.adobe.pdf size:268759 hash:sha1:60:A1:BE:8D:71:DB:E3:8E:84:C9:2C:62:9E:F2:99:78:9D:68:79:F6
1148
}}}
1149
1150 70 Luci Stanescu
==== methods ====
1151
1152
 '''!__init!__'''(''self'', '''account''', '''file_selector'''={{{None}}})::
1153
  Instantiate a new {{{FileTransferStream}}}. If this is constructed by the application for an outgoing file transfer, the {{{file_selector}}} argument must be present.
1154
  [[BR]]account:[[BR]]
1155
  The {{{sipsimple.account.Account}}} or {{{sipsimple.account.BonjourAccount}}} instance which will be associated with the stream.
1156
  [[BR]]file_selector:[[BR]]
1157
  The {{{FileSelector}}} instance which represents the file which is to be transferred.
1158
1159 71 Luci Stanescu
==== notifications ====
1160 1 Adrian Georgescu
1161
 '''FileTransferStreamDidDeliverChunk'''::
1162 70 Luci Stanescu
  This notification is sent for an outgoing file transfer when a success report is received about part of the file being transferred.
1163
  [[BR]]timestamp:[[BR]]
1164
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1165
  [[BR]]message_id:[[BR]]
1166
  The MSRP message ID of the file transfer session.
1167
  [[BR]]chunk:[[BR]]
1168
  An {{{msrplib.protocol.MSRPData}}} instance represented the received REPORT.
1169
  [[BR]]code:[[BR]]
1170
  The status code received. Will always be 200 for this notification.
1171
  [[BR]]reason:[[BR]]
1172
  The status reason received.
1173
  [[BR]]transferred_bytes:[[BR]]
1174
  The number of bytes which have currently been successfully transferred.
1175
  [[BR]]file_size:[[BR]]
1176
  The size of the file being transferred.
1177 1 Adrian Georgescu
 '''FileTransferStreamDidNotDeliverChunk'''::
1178 70 Luci Stanescu
  [[BR]]timestamp:[[BR]]
1179
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1180
  This notification is sent for an outgoing file transfer when a failure report is received about part of the file being transferred.
1181
  [[BR]]message_id:[[BR]]
1182
  The MSRP message ID of the file transfer session.
1183
  [[BR]]chunk:[[BR]]
1184
  An {{{msrplib.protocol.MSRPData}}} instance represented the received REPORT.
1185
  [[BR]]code:[[BR]]
1186
  The status code received.
1187
  [[BR]]reason:[[BR]]
1188
  The status reason received.
1189
 '''FileTransferStreamDidFinish'''::
1190
  This notification is sent when the incoming or outgoing file transfer is finished.
1191
  [[BR]]timestamp:[[BR]]
1192
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1193 1 Adrian Georgescu
 '''FileTransferStreamGotChunk'''::
1194 70 Luci Stanescu
  This notificaiton is sent for an incoming file transfer when a chunk of file data is received.
1195
  [[BR]]timestamp:[[BR]]
1196
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1197
  [[BR]]content:[[BR]]
1198
  The file part which was received, as a {{{str}}}.
1199
  [[BR]]content_type:[[BR]]
1200
  The MIME type of the file which is being transferred.
1201
  [[BR]]transferred_bytes:[[BR]]
1202
  The number of bytes which have currently been successfully transferred.
1203
  [[BR]]file_size:[[BR]]
1204
  The size of the file being transferred.
1205 1 Adrian Georgescu
1206
1207 71 Luci Stanescu
=== IDesktopSharingHandler ===
1208
1209
This interface is used to describe the interface between a {{{IDesktopSharingHandler}}}, which is responsible for consuming and producing RFB data, and the {{{DesktopSharingStream}}} which is responsible for transporting the RFB data over MSRP. The middleware provides four implementations of this interface:
1210
 * InternalVNCViewerHandler
1211
 * InternalVNCServerHandler
1212
 * ExternalVNCViewerHandler
1213
 * ExternalVNCServerHandler
1214
1215
==== methods ====
1216
 
1217
 '''initialize'''(''self'', '''stream''')::
1218
  This method will be called by the {{{DesktopSharingStream}}} when the stream has been started and RFB data can be transported. The stream has two attributes which are relevant to the {{{IDesktopSharingHandler}}}: incoming_queue and outgoing_queue. These attributes are {{{eventlet.coros.queue}}} instances which are used to transport RFB data between the stream and the handler.
1219
1220
==== attributes ====
1221
1222
 '''type'''::
1223
  {{{"active"}}} or {{{"passive"}}} depending on whether the handler represents a VNC viewer or server respectively.
1224
1225
==== notifications ====
1226
1227
 '''DesktopSharingHandlerDidFail'''::
1228
  This notification must be sent by the handler when an error occurs to notify the stream that it should fail.
1229
  [[BR]]context:[[BR]]
1230
  A string describing when the handler failed, such as {{{"reading"}}}, {{{"sending"}}} or {{{"connecting"}}}.
1231
  [[BR]]failure:[[BR]]
1232
  A {{{twisted.python.failure.Failure}}} instance describing the exception which led to the failure.
1233
  [[BR]]reason:[[BR]]
1234
  A string describing the failure reason.
1235
1236 75 Luci Stanescu
=== InternalVNCViewerHandler ===
1237
1238
These are concrete implementations of the {{{IDesktopSharingHandler}}} interface which can be used for a VNC viewer or server implemented within the application. Since they have exactly the same interface as far as the application is concerned, they are documented together.
1239
1240
==== methods ====
1241
1242
 '''send'''(''self'', '''data''')::
1243
  Sends the specified data to the stream in order for it to be transported over MSRP to the remote endpoint.
1244
  [[BR]]data:[[BR]]
1245
  The RFB data to be transported over MSRP, in the form of a {{{str}}}.
1246
1247
==== notifications ====
1248
1249
 '''DesktopSharingStreamGotData'''::
1250
  This notification is sent when data is received over MSRP.
1251
  [[BR]]data:[[BR]]
1252
  The RFB data from the remote endpoint, in the form of a {{{str}}}.
1253
1254
=== InternalVNCServerHandler ===
1255 71 Luci Stanescu
1256
These are concrete implementations of the {{{IDesktopSharingHandler}}} interface which can be used for a VNC viewer or server implemented within the application. Since they have exactly the same interface as far as the application is concerned, they are documented together.
1257
1258
==== methods ====
1259
1260
 '''send'''(''self'', '''data''')::
1261
  Sends the specified data to the stream in order for it to be transported over MSRP to the remote endpoint.
1262
  [[BR]]data:[[BR]]
1263
  The RFB data to be transported over MSRP, in the form of a {{{str}}}.
1264
1265
==== notifications ====
1266
1267
 '''DesktopSharingStreamGotData'''::
1268
  This notification is sent when data is received over MSRP.
1269
  [[BR]]data:[[BR]]
1270
  The RFB data from the remote endpoint, in the form of a {{{str}}}.
1271
1272
=== ExternalVNCViewerHandler ===
1273
1274
This implementation of {{{IDesktopSharingHandler}}} can be used for an external VNC viewer which connects to a VNC server using TCP.
1275
1276
==== methods ====
1277
1278
 '''!__init!__'''(''self'', '''address'''={{{("localhost", 0)}}}, '''connect_timeout'''={{{3}}})::
1279
  This instantiates a new {{{ExternalVNCViewerHandler}}} which is listening on the provided address, ready for the external VNC viewer to connect to it via TCP. After this method returns, the attribute {{{address}}} can be used to find out exactly on what address and port the handler is listening on. The handler will only accept one conenction on this address.
1280
  [[BR]]address:[[BR]]
1281
  A tuple containing an IP address/hostname and a port on which the handler should listen. Any data received on this socket will then be forwarded to the stream and any data received from the stream will be forwarded to this socket.
1282
1283
==== attribtues ====
1284
1285
 '''address'''::
1286
  A tuple containing an IP address and a port on which the handler is listening.
1287
1288
=== ExternalVNCServerHandler ===
1289
1290
This implementation of {{{IDesktopSharingHandler}}} can be used for an external VNC server to which handler will connect using TCP.
1291
1292
==== methods ====
1293
1294
 '''!__init!__'''(''self'', '''address''', '''connect_timeout'''={{{3}}})::
1295
  This instantiates a new {{{ExternalVNCServerHandler}}} which will connect to the provided address on which a VNC server must be listening before the stream using this handler starts.
1296
  [[BR]]address:[[BR]]
1297
  A tuple containing an IP address/hostname and a port on which the VNC server will be listening. Any data received on this socket will then be forwared to the stream and any data received form the stream will be forwarded to this socket.
1298
  [[BR]]connect_timeout:[[BR]]
1299
  How long to wait to connect to the VNC server before giving up.
1300
1301
1302
=== DesktopSharingStream ===
1303
1304 1 Adrian Georgescu
Implemented in [browser:sipsimple/streams/msrp.py]
1305 64 Luci Stanescu
1306 71 Luci Stanescu
This stream implements desktop sharing using MSRP as a transport protocol for RFB data.
1307 64 Luci Stanescu
1308 71 Luci Stanescu
There is no standard defining this usage but is fairly easy to implement in clients that already support MSRP. To traverse a NAT-ed router, a [http://msrprelay.org MSRP relay] configured for the called party domain is needed. Below is an example of the Session Description Protocol used for establishing a Desktop sharing session:
1309 64 Luci Stanescu
1310
{{{
1311
m=application 2855 TCP/TLS/MSRP *
1312
a=path:msrps://10.0.1.19:2855/b599b22d1b1d6a3324c8;tcp
1313 1 Adrian Georgescu
a=accept-types:application/x-rfb
1314
a=setup:active
1315
}}}
1316
1317
1318 71 Luci Stanescu
==== methods ====
1319 1 Adrian Georgescu
1320 71 Luci Stanescu
 '''!__init!__'''(''self'', '''acount''', '''handler''')::
1321
  Instantiate a new {{{DesktopSharingStream}}}.
1322
  [[BR]]account:[[BR]]
1323
  The {{{sipsimple.account.Account}}} or {{{sipsimple.account.BonjourAccount}}} instance this stream is associated with.
1324
  [[BR]]handler:[[BR]]
1325
  An object implementing the {{{IDesktopSharingHandler}}} interface which will act as the handler for RFB data.
1326 1 Adrian Georgescu
1327 71 Luci Stanescu
==== attributes ====
1328
1329
 '''handler'''::
1330
  This is a writable property which can be used to get or set the object implementing {{{IDesktopSharingHandler}}} which acts as the handler for RFB data. For incoming {{{DesktopSharingStreams}}}, this must be set by the application before the stream starts.
1331
 '''incoming_queue'''::
1332
  A {{{eventlet.coros.queue}}} instance on which incoming RFB data is written. The handler should wait for data on this queue.
1333
 '''outgoing_queue'''::
1334
  A {{{eventlet.coros.queue}}} instance on which outgoing RFB data is written. The handler should write data on this queue.
1335
1336 64 Luci Stanescu
1337 72 Luci Stanescu
== Account management ==
1338 64 Luci Stanescu
1339 72 Luci Stanescu
Account Management is implemented in [browser:sipsimple/account.py] ({{{sipsimple.account}}} module) and offers support for SIP accounts registered at SIP providers and SIP bonjour accounts which are discovered using mDNS.
1340 1 Adrian Georgescu
1341 72 Luci Stanescu
=== Account ===
1342 64 Luci Stanescu
1343 72 Luci Stanescu
The {{{sipsimple.account.Account}}} objects represent the SIP accounts which are registered at SIP providers. It has a dual purpose: it acts as both a container for account-related settings and as a complex object which can be used to interact with various per-account functions, such as presence, registration etc. This page documents the latter case, while the former is explained in the [wiki:SipConfigurationAPI#Account Configuration API].
1344
1345 64 Luci Stanescu
There is exactly one instance of {{{Account}}} per SIP account used and it is uniquely identifiable by its SIP ID, in the form ''user@domain''. It is a singleton, in the sense that instantiating {{{Account}}} using an already used SIP ID will return the same object. However, this is not the recommended way of accessing accounts, as this can lead to creation of new ones; the recommended way is by using the [wiki:SipMiddlewareApi#AccountManager AccountManager]. The next sections will use a lowercase, monospaced {{{account}}} to represent an instance of {{{Account}}}.
1346
1347 72 Luci Stanescu
==== states ====
1348 64 Luci Stanescu
1349
The {{{Account}}} objects have a setting flag called {{{enabled}}} which, if set to {{{False}}} will deactivate it: none of the internal functions will work in this case; in addition, the application using the middleware should not do anything with a disabled account. After changing it's value, the {{{save()}}} method needs to be called, as the flag is a setting and will not be used until this method is called:
1350
{{{
1351
account.enabled = True
1352
account.save()
1353
}}}
1354
1355
The {{{Account}}} objects will activate automatically when they are loaded/created if the {{{enabled}}} flag is set to {{{True}}} and the {{{sipsimple.engine.Engine}}} is running; if it is not running, the accounts will activate after the engine starts.
1356
1357
In order to create a new account, just create a new instance of {{{Account}}} with an id which doesn't belong to any other account.
1358
1359
The other functions of {{{Account}}} which run automatically have other enabled flags as well. They will only be activated when both the global enabled flag is set and the function-specific one. These are:
1360
1361
 '''Account.registration.enabled'''::
1362
  This flag controls the automatic registration of the account. The notifications '''SIPAccountRegistrationDidSucceed''', '''SIPAccountRegistrationDidFail''' and '''SIPAccountRegistrationDidEnd''' are used to inform the status of this registration.
1363
 '''Account.presence.enabled'''::
1364
  This flag controls the automatic subscription to buddies for the ''presence'' event and the publication of data in this event. (Not implemented yet)
1365
 '''Account.dialog_event.enabled'''::
1366
  This flag controls the automatic subscription to buddies for the ''dialog-info'' event and the publication of data in this event. (Not implemented yet)
1367 1 Adrian Georgescu
 '''Account.message_summary.enabled'''::
1368 64 Luci Stanescu
  This flag controls the automatic subscription to the ''message-summary'' event in order to find out about voicemail messages. (Not implemented yet)
1369
1370
The {{{save()}}} method needs to be called after changing these flags in order for them to take effect. The methods available on {{{Account}}} objects are inherited from [wiki:SipConfigurationAPI#SettingsObject SettingsObject].
1371
1372 72 Luci Stanescu
==== attributes ====
1373 64 Luci Stanescu
1374
The following attributes can be used on an Account object and need to be considered read-only.
1375
1376
 '''id'''::
1377
  This attribute is of type {{{sipsimple.configuration.datatypes.SIPAddress}}} (a subclass of {{{str}}}) and contains the SIP id of the account. It can be used as a normal string in the form ''user@domain'', but it also allows access to the components via the attributes {{{username}}} and {{{domain}}}.
1378
  {{{
1379
  account.id # 'alice@example.com'
1380
  account.id.username # 'alice'
1381
  account.id.domain # 'example.com'
1382
  }}}
1383
 '''contact'''::
1384
  This attribute can be used to construct the Contact URI for SIP requests sent on behalf of this account. It's type is {{{sipsimple.account.ContactURI}}} which is a subclass of {{{sipsimple.configuration.datatypes.SIPAddress}}}. In addition to the attributes defined in {{{SIPAddress}}}, it can be indexed by a string representing a transport ({{{'udp'}}}, {{{'tcp'}}} or {{{'tls'}}}) which will return a {{{sipsimple.core.SIPURI}}} object with the appropriate port and transport parameter. The username part is a randomly generated 8 character string consisting of lowercase letters; the domain part is the IP address on which the {{{Engine}}} is listening (as specified by the SIPSimpleSettings.local_ip setting).
1385
  {{{
1386
  account.contact # 'hnfkybrt@10.0.0.1'
1387 1 Adrian Georgescu
  account.contact.username # 'hnfkybrt'
1388
  account.contact.domain # '10.0.0.1'
1389 64 Luci Stanescu
  account.contact['udp'] # <SIPURI "sip:hnfkybrt@10.0.0.1:53024">
1390 1 Adrian Georgescu
  account.contact['tls'] # <SIPURI "sip:hnfkybrt@10.0.0.1:54478;transport=tls">
1391
  }}}
1392
 '''credentials'''::
1393 72 Luci Stanescu
  This attribute is of type {{{sipsimple.core.Credentials}}} which is built from the {{{id.username}}} attribute and the {{{password}}} setting of the Account. Whenever this setting is changed, this attribute is updated.
1394 1 Adrian Georgescu
  {{{
1395 72 Luci Stanescu
  account.credentials # <Credentials for 'alice'>
1396 64 Luci Stanescu
  }}}
1397 72 Luci Stanescu
 '''uri'''::
1398
  This attribute is of type {{{sipsimple.core.SIPURI}}} which can be used to form a {{{FromHeader}}} associated with this account. It contains the SIP ID of the account.
1399
  {{{
1400
  account.uri # <SIPURI "sip:alice@example.com">
1401
  }}}
1402 1 Adrian Georgescu
1403 72 Luci Stanescu
==== notifications ====
1404 1 Adrian Georgescu
1405
 '''CFGSettingsObjectDidChange'''::
1406
  This notification is sent when the {{{save()}}} method is called on the account after some of the settings were changed. As the notification belongs to the {{{SettingsObject}}} class, it is exaplained in detail in [wiki:SipConfigurationAPI#SettingsObjectNotifications SettingsObject Notifications].
1407
 '''SIPAccountDidActivate'''::
1408 72 Luci Stanescu
  This notification is sent when the {{{Account}}} activates. This can happen when the {{{Account}}} is loaded if it's enabled flag is set and the Engine is running, and at any later time when the status of the Engine changes or the enabled flag is modified.
1409
  [[BR]]''timestamp'':[[BR]]
1410
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1411 1 Adrian Georgescu
 '''SIPAccountDidDeactivate'''::
1412 72 Luci Stanescu
  This notification is sent when the {{{Account}}} deactivates. This can happend when the {{{Engine}}} is stopped or when the enabled flag of the account is set to {{{False}}}.
1413
  [[BR]]''timestamp'':[[BR]]
1414
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1415
 '''SIPAccountWillRegister'''
1416
  This notification is sent when the account is about to register for the first time.
1417
  [[BR]]''timestamp'':[[BR]]
1418
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1419
 '''SIPAccountRegistrationWillRefresh'''
1420
  This notification is sent when a registration is about to be refreshed.
1421
  [[BR]]''timestamp'':[[BR]]
1422
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1423 1 Adrian Georgescu
 '''SIPAccountRegistrationDidSucceed'''::
1424
  This notification is sent when a REGISTER request sent for the account succeeds (it is also sent for each refresh of the registration). The data contained in this notification is:
1425 72 Luci Stanescu
  [[BR]]''timestamp'':[[BR]]
1426
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1427
  [[BR]]''contact_header'':[[BR]]
1428
   The Contact header which was registered.
1429
  [[BR]]''contact_header_list'':[[BR]]
1430
   A list containing all the contacts registered for this SIP account.
1431 1 Adrian Georgescu
  [[BR]]''expires'':[[BR]]
1432
   The amount in seconds in which this registration will expire.
1433 72 Luci Stanescu
  [[BR]]''registrar'':[[BR]]
1434
  The {{{sipsimple.util.Route}}} object which was used.
1435 1 Adrian Georgescu
 '''SIPAccountRegistrationDidFail'''::
1436
  This notification is sent when a REGISTER request sent for the account fails. It can fail either because a negative response was returned or because PJSIP considered the request failed (e.g. on timeout). The data contained in this notification is:
1437 72 Luci Stanescu
  [[BR]]''timestamp'':[[BR]]
1438
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1439
  [[BR]]''error'':[[BR]]
1440 1 Adrian Georgescu
   The reason for the failure of the REGISTER request.
1441 72 Luci Stanescu
  [[BR]]''timeout'':[[BR]]
1442
   The amount in seconds as a {{{float}}} after which the registration will be tried again.
1443 1 Adrian Georgescu
 '''SIPAccountRegistrationDidEnd'''::
1444 64 Luci Stanescu
  This notification is sent when a registration is ended (the account is unregistered). The data contained in this notification is:
1445 72 Luci Stanescu
  [[BR]]''timestamp'':[[BR]]
1446
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1447
  [[BR]]''registration'':[[BR]]
1448
   The {{{sipsimple.core.Registration}}} object which ended.
1449
 '''SIPAccountRegistrationDidNotEnd'''::
1450
  This notification is sent when a registration fails to end (the account is not unregistered). The data contained in this notification is:
1451
  [[BR]]''timestamp'':[[BR]]
1452
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1453 1 Adrian Georgescu
  [[BR]]''code'':[[BR]]
1454 72 Luci Stanescu
  The SIP status code received.
1455 64 Luci Stanescu
  [[BR]]''reason'':[[BR]]
1456 72 Luci Stanescu
  The SIP status reason received.
1457 1 Adrian Georgescu
  [[BR]]''registration'':[[BR]]
1458 72 Luci Stanescu
  The {{{sipsimple.core.Registration}}} object which ended.
1459
 '''SIPAccountRegistrationGotAnswer'''::
1460
  This notification is sent whenever a response is received to a sent REGISTER request for this account. The data contained in this notification is:
1461
  [[BR]]''timestamp'':[[BR]]
1462
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1463
  [[BR]]''code'':[[BR]]
1464
  The SIP status code received.
1465
  [[BR]]''reason'':[[BR]]
1466
  The SIP status reason received.
1467
  [[BR]]''registration'':[[BR]]
1468
  The {{{sipsimple.core.Registration}}} object which was used.
1469
  [[BR]]''registrar'':[[BR]]
1470
  The {{{sipsimple.util.Route}}} object which was used.
1471 1 Adrian Georgescu
1472 72 Luci Stanescu
=== BonjourAccount ===
1473 1 Adrian Georgescu
1474 64 Luci Stanescu
The {{{sipsimple.account.BonjourAccount}}} represents the SIP account used for P2P mode; it does not interact with any server. The class is a singleton, as there can only be one such account on a system. Similar to the {{{Account}}}, it is used both as a complex object, which implements the functions for bonjour mode, as well as a container for the related settings.
1475 1 Adrian Georgescu
1476 72 Luci Stanescu
==== states ====
1477 64 Luci Stanescu
1478 72 Luci Stanescu
The {{{BonjourAccount}}} has an {{{enabled}}} flag which controls whether this account will be used or not. If it is set to {{{False}}}, none of the internal functions will be activated and, in addition, the account should not be used by the application. The bonjour account can only activated if the Engine is running; once it is started, if the enabled flag is set, the account will activate. When the {{{BonjourAccount}}} is activated, it will broadcast the contact address on the LAN. (Not implemented yet)
1479 64 Luci Stanescu
1480 72 Luci Stanescu
==== attributes ====
1481 1 Adrian Georgescu
1482 72 Luci Stanescu
The following attributes can be used on a BonjourAccount object and need to be considered read-only.
1483 64 Luci Stanescu
1484
 '''id'''::
1485
  This attribute is of type {{{sipsimple.configuration.datatypes.SIPAddress}}} (a subclass of {{{str}}}) and contains the SIP id of the account, which is {{{'bonjour@local'}}}. It can be used as a normal string, but it also allows access to the components via the attributes {{{username}}} and {{{domain}}}.
1486
  {{{
1487
  bonjour_account.id # 'bonjour@local'
1488
  bonjour_account.id.username # 'bonjour'
1489
  bonjour_account.id.domain # 'local'
1490
  }}}
1491
 '''contact'''::
1492 1 Adrian Georgescu
  This attribute can be used to construct the Contact URI for SIP requests sent on behalf of this account. It's type is {{{sipsimple.account.ContactURI}}} which is a subclass of {{{sipsimple.configuration.datatypes.SIPAddress}}}. In addition to the attributes defined in {{{SIPAddress}}}, it can be indexed by a string representing a transport ({{{'udp'}}}, {{{'tcp'}}} or {{{'tls'}}}) which will return a {{{sipsimple.core.SIPURI}}} object with the appropriate port and transport parameter. The username part is a randomly generated 8 character string consisting of lowercase letters; the domain part is the IP address on which the {{{Engine}}} is listening (as specified by the SIPSimpleSettings.local_ip setting).
1493 64 Luci Stanescu
  {{{
1494 72 Luci Stanescu
  bonjour_account.contact # 'lxzvgack@10.0.0.1'
1495
  bonjour_account.contact.username # 'lxzvgack'
1496
  bonjour_account.contact.domain # '10.0.0.1'
1497
  bonjour_account.contact['udp'] # <SIPURI "sip:lxzvgack@10.0.0.1:53024">
1498
  bonjour_account.contact['tls'] # <SIPURI "sip:lxzvgack@10.0.0.1:54478;transport=tls">
1499 1 Adrian Georgescu
  }}}
1500
 '''credentials'''::
1501 72 Luci Stanescu
  This attribute is of type {{{sipsimple.core.Credentials}}} object which is built from the {{{contact.username}}} attribute; the password is set to the empty string.
1502 1 Adrian Georgescu
  {{{
1503 72 Luci Stanescu
  bonjour_account.credentials # <Credentials for 'alice'>
1504 1 Adrian Georgescu
  }}}
1505 72 Luci Stanescu
 '''uri'''::
1506
  This attribute is of type {{{sipsimple.core.SIPURI}}} which can be used to form a {{{FromHeader}}} associated with this account. It contains the contact address of the bonjour accunt:
1507
  {{{
1508
  bonjour_account.uri # <SIPURI "sip:lxzvgack@10.0.0.1">
1509
  }}}
1510 64 Luci Stanescu
1511 72 Luci Stanescu
==== notifications ====
1512 64 Luci Stanescu
1513
 '''CFGSettingsObjectDidChange'''::
1514
  This notification is sent when the {{{save()}}} method is called on the account after some of the settings were changed. As the notification belongs to the {{{SettingsObject}}} class, it is exaplained in detail in [wiki:SipConfigurationAPI#SettingsObjectNotifications SettingsObject Notifications].
1515
 '''SIPAccountDidActivate'''::
1516 72 Luci Stanescu
  This notification is sent when the {{{BonjourAccount}}} activates. This can happen when the {{{BonjourAccount}}} is loaded if it's enabled flag is set and the Engine is running, and at any later time when the status of the Engine changes or the enabled flag is modified.
1517
  [[BR]]''timestamp'':[[BR]]
1518
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1519 64 Luci Stanescu
 '''SIPAccountDidDeactivate'''::
1520 72 Luci Stanescu
  This notification is sent when the {{{BonjourAccount}}} deactivates. This can happend when the {{{Engine}}} is stopped or when the enabled flag of the account is set to {{{False}}}.
1521
  [[BR]]''timestamp'':[[BR]]
1522
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1523 1 Adrian Georgescu
1524
1525 72 Luci Stanescu
=== AccountManager ===
1526 1 Adrian Georgescu
1527
The {{{sipsimple.account.AccountManager}}} is the entity responsible for loading and keeping track of the existing accounts. It is a singleton and can be instantiated anywhere, obtaining the same instance. It cannot be used until its {{{start}}} method has been called.
1528
1529 72 Luci Stanescu
==== methods ====
1530 1 Adrian Georgescu
1531
 '''!__init!__'''(''self'')::
1532
  The {{{__init__}}} method allows the {{{AccountManager}}} to be instantiated without passing any parameters. A reference to the {{{AccountManager}}} can be obtained anywhere before it is started.
1533
 '''start'''(''self'')::
1534 72 Luci Stanescu
  This method will load all the existing accounts from the configuration. If the Engine is running, the accounts will also activate. This method can only be called after the [wiki:SipConfigurationAPI#ConfigurationManager ConfigurationManager] has been started. A '''SIPAccountManagerDidAddAccount''' will be sent for each account loaded. This method is called automatically by the SIPApplication when it initializes all the components of the middleware.
1535 1 Adrian Georgescu
 '''stop'''(''self'')::
1536 72 Luci Stanescu
  Calling this method will deactivate all accounts managed by the {{{AccountManager}}}. This method is called automatically by the SIPApplication when it stops.
1537 1 Adrian Georgescu
 '''has_account'''(''self'', '''id''')::
1538
  This method returns {{{True}}} if an account which has the specifed SIP ID (must be a string) exists and {{{False}}} otherwise.
1539
 '''get_account'''(''self'', '''id''')::
1540
  Returns the account (either an {{{Account}}} instance or the {{{BonjourAccount}}} instance) with the specified SIP ID. Will raise a {{{KeyError}}} if such an account does not exist.
1541
 '''get_accounts'''(''self'')::
1542
  Returns a list containing all the managed accounts.
1543
 '''iter_accounts'''(''self'')::
1544
  Returns an iterator through all the managed accounts.
1545
 '''find_account'''(''self'', '''contact_uri''')::
1546
  Returns an account with matches the specified {{{contact_uri}}} which must be a {{{sipsimple.core.SIPURI}}} instance. Only the accounts with the enabled flag set will be considered. Returns None if such an account does not exist.
1547
1548 72 Luci Stanescu
==== notifications ====
1549 1 Adrian Georgescu
1550
 '''SIPAccountManagerDidAddAccount'''::
1551 72 Luci Stanescu
  This notification is sent when a new account becomes available to the {{{AccountManager}}}. The notification is also sent when the accounts are loaded from the configuration.
1552
  [[BR]]''timestamp'':[[BR]]
1553
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1554
  [[BR]]''account'':[[BR]]
1555
  The account object which was added.
1556 1 Adrian Georgescu
 '''SIPAccountManagerDidRemoveAccount'''::
1557 72 Luci Stanescu
  This notification is sent when an account is deleted using the {{{delete}}} method.
1558
  [[BR]]''timestamp'':[[BR]]
1559
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1560
  [[BR]]''account'':[[BR]]
1561
  The account object which was deleted.
1562 1 Adrian Georgescu
 '''SIPAccountManagerDidChangeDefaultAccount'''::
1563 72 Luci Stanescu
  This notification is sent when the default account changes.
1564
  [[BR]]''timestamp'':[[BR]]
1565
  A {{{datetime.datetime}}} object indicating when the notification was sent.
1566 1 Adrian Georgescu
  [[BR]]''old_account'':[[BR]]
1567
   This is the account object which used to be the default account.
1568
  [[BR]]''account'':[[BR]]
1569
   This is the account object which is the new default account.
1570 73 Luci Stanescu
1571
== Conference support ==
1572
1573
Conference support is implemented in the {{{sipsimple.conference}}} module. Currently, only audio conferencing is supported.
1574
1575
=== AudioConference ===
1576
1577
This class contains the basic implementation for audio conferencing. It acts as a container for {{{AudioStream}}} objects which it will connect in a full mesh, such that all participants can hear all other participants.
1578
1579
==== methods ====
1580
1581
 '''!__init!__'''(''self'')::
1582
  Instantiates a new {{{AudioConference}}} which is ready to contain {{{AudioStream}}} objects.
1583
 '''add'''(''self'', '''stream''')::
1584
  Add the specified {{{AudioStream}}} object to the conference.
1585
 '''remove'''(''self'', '''stream''')::
1586
  Removes the specified {{{AudioStream}}} object from the conference. Raises a {{{ValueError}}} if the stream is not part of the conference.
1587
 '''hold'''(''self'')::
1588
  Puts the conference "on hold". This means that the audio device will be disconnected from the conference: all the participants will be able to continue the conference, but the local party will no longer contribute any audio data and will not receive any audio data using the input and output devices respectively. This does not affect the hold state of the streams in any way.
1589
 '''unhold'''(''self'')::
1590
  Removes the conference "from hold". This means that the audio device will be reconnected to the conference: all the participants will start to hear the local party and the local party will start to hear all the participants. This does not affect the hold state of the streams in any way.
1591
1592
==== attributes ====
1593
1594
 '''bridge'''::
1595
  An {{{AudioBridge}}} which this conference uses to connect all audio streams. It can be used by the application to play a wav file using a {{{WavePlayer}}} to all the participants or record the whole conference using a {{{WaveRecorder}}}.
1596
 '''on_hold'''::
1597
  A boolean indicating whether or not the conference is "on hold".
1598
 '''streams'''::
1599
  The list of streams which are part of this conference. The application must not manipulate this list in any way.