SipMiddlewareApi
Version 128 (Adrian Georgescu, 11/14/2010 12:38 pm)
1 | 1 | Adrian Georgescu | = Middleware API = |
---|---|---|---|
2 | 1 | Adrian Georgescu | |
3 | 113 | Adrian Georgescu | [[TOC(SipMiddlewareApi, SipConfigurationAPI, SipCoreApiDocumentation, SipMSRPApi, depth=3)]] |
4 | 104 | Adrian Georgescu | |
5 | 102 | Adrian Georgescu | This chapter describes the ''Middleware API'' for SIP SIMPLE client SDK that can be used for developing a user interface (e.g. Graphical User Interface). The Middleware provides a ''non-blocking'' API that communicates with the user interface asynchronously by using ''Notifications''. For its configuration, the Middleware uses the [wiki:SipConfigurationAPI Configuration API]. |
6 | 1 | Adrian Georgescu | |
7 | 101 | Adrian Georgescu | [[Image(sipsimple-middleware.png, align=center, width=700)]] |
8 | 1 | Adrian Georgescu | |
9 | 1 | Adrian Georgescu | == SIPApplication == |
10 | 1 | Adrian Georgescu | |
11 | 62 | Luci Stanescu | Implemented in [browser:sipsimple/application.py] |
12 | 1 | Adrian Georgescu | |
13 | 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: |
14 | 62 | Luci Stanescu | * the twisted thread |
15 | 93 | Adrian Georgescu | * the configuration system, via the [wiki:SipConfigurationAPI#ConfigurationManager ConfigurationManager] |
16 | 62 | Luci Stanescu | * the core [wiki:SipCoreApiDocumentation#Engine Engine] using the settings in the configuration |
17 | 62 | Luci Stanescu | * the [wiki:SipMiddlewareApi#AccountManager AccountManager], using the accounts in the configuration |
18 | 63 | Luci Stanescu | * the [wiki:SipMiddlewareApi#SessionManager SessionManager], in order to handle incoming sessions |
19 | 62 | Luci Stanescu | * two [wiki:SipMiddlewareApi#AudioBridge AudioBridges], using the settings in the configuration |
20 | 1 | Adrian Georgescu | |
21 | 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. |
22 | 1 | Adrian Georgescu | |
23 | 95 | Adrian Georgescu | ==== methods ==== |
24 | 62 | Luci Stanescu | |
25 | 94 | Adrian Georgescu | |
26 | 62 | Luci Stanescu | '''!__init!__'''(''self''):: |
27 | 62 | Luci Stanescu | Instantiates a new SIPApplication. |
28 | 94 | Adrian Georgescu | |
29 | 62 | Luci Stanescu | '''start'''(''self'', '''config_backend'''):: |
30 | 62 | Luci Stanescu | 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. |
31 | 94 | Adrian Georgescu | |
32 | 62 | Luci Stanescu | '''stop'''(''self''):: |
33 | 62 | Luci Stanescu | 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. |
34 | 62 | Luci Stanescu | |
35 | 95 | Adrian Georgescu | ==== attributes ==== |
36 | 1 | Adrian Georgescu | |
37 | 94 | Adrian Georgescu | |
38 | 62 | Luci Stanescu | '''running''':: |
39 | 62 | Luci Stanescu | {{{True}}} if the SIPApplication is running (it has been started and it has not been told to stop), {{{False}}} otherwise. |
40 | 94 | Adrian Georgescu | |
41 | 94 | Adrian Georgescu | |
42 | 62 | Luci Stanescu | '''alert_audio_mixer''':: |
43 | 62 | Luci Stanescu | The {{{AudioMixer}}} object created on the alert audio device as defined by the configuration (by SIPSimpleSettings.audio.alert_device). |
44 | 94 | Adrian Georgescu | |
45 | 62 | Luci Stanescu | '''alert_audio_bridge''':: |
46 | 62 | Luci Stanescu | An {{{AudioBridge}}} where {{{IAudioPort}}} objects can be added to playback sound to the alert device. |
47 | 94 | Adrian Georgescu | |
48 | 62 | Luci Stanescu | '''alert_audio_device''':: |
49 | 62 | Luci Stanescu | An {{{AudioDevice}}} which corresponds to the alert device as defined by the configuration. This will always be part of the alert_audio_bridge. |
50 | 94 | Adrian Georgescu | |
51 | 62 | Luci Stanescu | '''voice_audio_mixer''':: |
52 | 62 | Luci Stanescu | The {{{AudioMixer}}} object created on the voice audio device as defined by the configuration (by SIPSimpleSettings.audio.input_device and SIPSimpleSettings.audio.output_device). |
53 | 94 | Adrian Georgescu | |
54 | 62 | Luci Stanescu | '''voice_audio_bridge''':: |
55 | 62 | Luci Stanescu | An {{{AudioBridge}}} where {{{IAudioPort}}} objects can be added to playback sound to the output device or record sound from the input device. |
56 | 94 | Adrian Georgescu | |
57 | 62 | Luci Stanescu | '''voice_audio_device''':: |
58 | 62 | Luci Stanescu | An {{{AudioDevice}}} which corresponds to the voice device as defined by the configuration. This will always be part of the voice_audio_bridge. |
59 | 1 | Adrian Georgescu | |
60 | 95 | Adrian Georgescu | ==== notifications ==== |
61 | 62 | Luci Stanescu | |
62 | 94 | Adrian Georgescu | |
63 | 62 | Luci Stanescu | '''SIPApplicationWillStart''':: |
64 | 62 | Luci Stanescu | This notification is sent just after the configuration has been loaded and the twisted thread started, but before any other components have been initialized. |
65 | 62 | Luci Stanescu | [[BR]]timestamp:[[BR]] |
66 | 62 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
67 | 94 | Adrian Georgescu | |
68 | 62 | Luci Stanescu | '''SIPApplicationDidStart''':: |
69 | 62 | Luci Stanescu | 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. |
70 | 62 | Luci Stanescu | [[BR]]timestamp:[[BR]] |
71 | 62 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
72 | 94 | Adrian Georgescu | |
73 | 62 | Luci Stanescu | '''SIPApplicationWillEnd''':: |
74 | 62 | Luci Stanescu | This notification is sent as soon as the {{{stop()}}} method has been called. |
75 | 62 | Luci Stanescu | [[BR]]timestamp:[[BR]] |
76 | 62 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
77 | 94 | Adrian Georgescu | |
78 | 62 | Luci Stanescu | '''SIPApplicationDidEnd''':: |
79 | 62 | Luci Stanescu | 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). |
80 | 62 | Luci Stanescu | [[BR]]timestamp:[[BR]] |
81 | 62 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
82 | 94 | Adrian Georgescu | |
83 | 62 | Luci Stanescu | '''SIPApplicationFailedToStartTLS''':: |
84 | 62 | Luci Stanescu | 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. |
85 | 62 | Luci Stanescu | [[BR]]timestamp:[[BR]] |
86 | 62 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
87 | 62 | Luci Stanescu | [[BR]]error:[[BR]] |
88 | 62 | Luci Stanescu | The exception raised by the Engine which identifies the cause for not being able to start the TLS transport. |
89 | 50 | Adrian Georgescu | |
90 | 1 | Adrian Georgescu | |
91 | 63 | Luci Stanescu | == SIP Sessions == |
92 | 1 | Adrian Georgescu | |
93 | 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. |
94 | 63 | Luci Stanescu | |
95 | 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]. |
96 | 65 | Luci Stanescu | |
97 | 91 | Adrian Georgescu | |
98 | 91 | Adrian Georgescu | === SessionManager === |
99 | 91 | Adrian Georgescu | |
100 | 91 | Adrian Georgescu | Implemented in [browser:sipsimple/session.py] |
101 | 91 | Adrian Georgescu | |
102 | 91 | Adrian Georgescu | The {{{sipsimple.session.SessionManager}}} class is a singleton, which acts as the central aggregation point for sessions within the middleware. |
103 | 91 | Adrian Georgescu | Although it is mainly used internally, the application can use it to query information about all active sessions. |
104 | 115 | 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 and closing all sessions when SIPApplication is stopped. |
105 | 91 | Adrian Georgescu | |
106 | 91 | Adrian Georgescu | ==== attributes ==== |
107 | 91 | Adrian Georgescu | |
108 | 94 | Adrian Georgescu | |
109 | 91 | Adrian Georgescu | '''sessions''':: |
110 | 91 | Adrian Georgescu | 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. |
111 | 91 | Adrian Georgescu | |
112 | 91 | Adrian Georgescu | ==== methods ==== |
113 | 91 | Adrian Georgescu | |
114 | 94 | Adrian Georgescu | |
115 | 91 | Adrian Georgescu | '''!__init!__'''(''self''):: |
116 | 91 | Adrian Georgescu | Instantiate a new {{{SessionManager}}} object. |
117 | 91 | Adrian Georgescu | |
118 | 94 | Adrian Georgescu | |
119 | 1 | Adrian Georgescu | '''start'''(''self''):: |
120 | 115 | Luci Stanescu | Start the {{{SessionManager}}} in order to be able to handle incoming sessions. This method is called automatically when SIPApplication is started. The application should not call this method directly. |
121 | 115 | Luci Stanescu | |
122 | 115 | Luci Stanescu | '''stop'''(''self''):: |
123 | 115 | Luci Stanescu | End all connected sessions. This method is called automatically when SIPApplication is stopped. The application should not call this method directly. |
124 | 91 | Adrian Georgescu | |
125 | 44 | Adrian Georgescu | === Session === |
126 | 1 | Adrian Georgescu | |
127 | 1 | Adrian Georgescu | Implemented in [browser:sipsimple/session.py] |
128 | 26 | Luci Stanescu | |
129 | 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. |
130 | 1 | Adrian Georgescu | |
131 | 1 | Adrian Georgescu | 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. |
132 | 2 | Adrian Georgescu | State changes are triggered by methods called on the object by the application or by received network events. |
133 | 1 | Adrian Georgescu | These states and their transitions are represented in the following diagram: |
134 | 63 | Luci Stanescu | |
135 | 105 | Adrian Georgescu | [[Image(/raw-attachment/wiki/SipCoreApiDocumentation/sipsimple-core-invite-state-machine.png)]] |
136 | 105 | Adrian Georgescu | |
137 | 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. |
138 | 63 | Luci Stanescu | |
139 | 63 | Luci Stanescu | 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. |
140 | 63 | Luci Stanescu | |
141 | 63 | Luci Stanescu | ==== methods ==== |
142 | 63 | Luci Stanescu | |
143 | 94 | Adrian Georgescu | |
144 | 63 | Luci Stanescu | '''!__init!__'''(''self'', '''account'''):: |
145 | 63 | Luci Stanescu | Creates a new {{{Session}}} object in the {{{None}}} state. |
146 | 63 | Luci Stanescu | [[BR]]''account'':[[BR]] |
147 | 63 | Luci Stanescu | The local account to be associated with this {{{Session}}}. |
148 | 94 | Adrian Georgescu | |
149 | 63 | Luci Stanescu | '''connect'''(''self'', '''to_header''', '''routes''', '''streams'''):: |
150 | 63 | Luci Stanescu | 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. |
151 | 63 | Luci Stanescu | Before contacting the remote party, a {{{SIPSessionNewOutgoing}}} notification will be emitted. |
152 | 63 | Luci Stanescu | If there is a failure or the remote party rejected the offer, a {{{SIPSessionDidFail}}} notification will be sent. |
153 | 63 | Luci Stanescu | Any time a ringing indication is received from the remote party, a {{{SIPSessionGotRingIndication}}} notification is sent. |
154 | 63 | Luci Stanescu | If the remote party accepted the session, a {{{SIPSessionWillStart}}} notification will be sent, followed by a {{{SIPSessionDidStart}}} notification when the session is actually established. |
155 | 63 | Luci Stanescu | This method may only be called while in the {{{None}}} state. |
156 | 63 | Luci Stanescu | [[BR]]''to_header'':[[BR]] |
157 | 63 | Luci Stanescu | A {{{sipsimple.core.ToHeader}}} object representing the remote identity to initiate the session to. |
158 | 63 | Luci Stanescu | [[BR]]''routes'':[[BR]] |
159 | 63 | Luci Stanescu | An iterable of {{{sipsimple.util.Route}}} objects, specifying the IP, port and transport to the outbound proxy. |
160 | 63 | Luci Stanescu | These routes will be tried in order, until one of them succeeds. |
161 | 63 | Luci Stanescu | [[BR]]''streams'':[[BR]] |
162 | 63 | Luci Stanescu | A list of stream objects which will be offered to the remote endpoint. |
163 | 94 | Adrian Georgescu | |
164 | 63 | Luci Stanescu | '''send_ring_indication'''(''self''):: |
165 | 63 | Luci Stanescu | Sends a 180 provisional response in the case of an incoming session. |
166 | 94 | Adrian Georgescu | |
167 | 63 | Luci Stanescu | '''accept'''(''self'', '''streams'''):: |
168 | 63 | Luci Stanescu | Calling this methods will accept an incoming session and move the state machine to the {{{accepting}}} state. |
169 | 63 | Luci Stanescu | 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. |
170 | 63 | Luci Stanescu | After this method is called, {{{SIPSessionWillStart}}} followed by {{{SIPSessionDidStart}}} will be emitted, or {{{SIPSessionDidFail}}} on an error. |
171 | 63 | Luci Stanescu | This method may only be called while in the {{{incoming}}} state. |
172 | 63 | Luci Stanescu | [[BR]]''streams'':[[BR]] |
173 | 63 | Luci Stanescu | 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. |
174 | 94 | Adrian Georgescu | |
175 | 63 | Luci Stanescu | '''reject'''(''self'', '''code'''={{{603}}}, '''reason'''={{{None}}}):: |
176 | 114 | Adrian Georgescu | Reject an incoming session and move it to the {{{terminating}}} state, which eventually leads to the {{{terminated}}} state. |
177 | 63 | Luci Stanescu | Calling this method will cause the {{{Session}}} object to emit a {{{SIPSessionDidFail}}} notification once the session has been rejected. |
178 | 63 | Luci Stanescu | This method may only be called while in the {{{incoming}}} state. |
179 | 63 | Luci Stanescu | [[BR]]''code'':[[BR]] |
180 | 63 | Luci Stanescu | 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). |
181 | 63 | Luci Stanescu | [[BR]]''reason'':[[BR]] |
182 | 63 | Luci Stanescu | 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. |
183 | 94 | Adrian Georgescu | |
184 | 63 | Luci Stanescu | '''accept_proposal'''(''self'', '''streams'''):: |
185 | 63 | Luci Stanescu | 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. |
186 | 63 | Luci Stanescu | 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. |
187 | 63 | Luci Stanescu | This method may only be called while in the {{{received_proposal}}} state. |
188 | 63 | Luci Stanescu | [[BR]]''streams'':[[BR]] |
189 | 63 | Luci Stanescu | 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. |
190 | 94 | Adrian Georgescu | |
191 | 63 | Luci Stanescu | '''reject_proposal'''(''self'', '''code'''={{{488}}}, '''reason'''={{{None}}}):: |
192 | 63 | Luci Stanescu | 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. |
193 | 63 | Luci Stanescu | This method may only be called while in the {{{received_proposal}}} state. |
194 | 63 | Luci Stanescu | [[BR]]''code'':[[BR]] |
195 | 63 | Luci Stanescu | An integer which represents the SIP status code in the response which is to be sent. Usually, this is 488 (Not Acceptable Here). |
196 | 63 | Luci Stanescu | [[BR]]''reason'':[[BR]] |
197 | 63 | Luci Stanescu | 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. |
198 | 94 | Adrian Georgescu | |
199 | 63 | Luci Stanescu | '''add_stream'''(''self'', '''stream'''):: |
200 | 63 | Luci Stanescu | Proposes a new stream to the remote party. |
201 | 63 | Luci Stanescu | Calling this method will cause a {{{SIPSessionGotProposal}}} notification to be emitted. |
202 | 63 | Luci Stanescu | 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. |
203 | 63 | Luci Stanescu | This method may only be called while in the {{{connected}}} state. |
204 | 94 | Adrian Georgescu | |
205 | 63 | Luci Stanescu | '''remove_stream'''(''self'', '''stream'''):: |
206 | 63 | Luci Stanescu | 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). |
207 | 63 | Luci Stanescu | This method may only be called while in the {{{connected}}} state. |
208 | 94 | Adrian Georgescu | |
209 | 63 | Luci Stanescu | '''cancel_proposal'''(''self''):: |
210 | 63 | Luci Stanescu | 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. |
211 | 94 | Adrian Georgescu | |
212 | 63 | Luci Stanescu | '''hold'''(''self''):: |
213 | 63 | Luci Stanescu | Put the streams of the session which support the notion of hold on hold. |
214 | 63 | Luci Stanescu | This will cause a {{{SIPSessionDidChangeHoldState}}} notification to be sent. |
215 | 63 | Luci Stanescu | This method may be called in any state and will send the re-INVITE as soon as it is possible. |
216 | 94 | Adrian Georgescu | |
217 | 63 | Luci Stanescu | '''unhold'''(''self''):: |
218 | 63 | Luci Stanescu | Take the streams of the session which support the notion of hold out of hold. |
219 | 63 | Luci Stanescu | This will cause a {{{SIPSessionDidChangeHoldState}}} notification to be sent. |
220 | 63 | Luci Stanescu | This method may be called in any state and will send teh re-INVITE as soon as it is possible. |
221 | 94 | Adrian Georgescu | |
222 | 63 | Luci Stanescu | '''end'''(''self''):: |
223 | 63 | Luci Stanescu | This method may be called any time after the {{{Session}}} has started in order to terminate the session by sending a BYE request. |
224 | 1 | Adrian Georgescu | Right before termination a {{{SIPSessionWillEnd}}} notification is sent, after termination {{{SIPSessionDidEnd}}} is sent. |
225 | 1 | Adrian Georgescu | |
226 | 64 | Luci Stanescu | ==== attributes ==== |
227 | 1 | Adrian Georgescu | |
228 | 94 | Adrian Georgescu | |
229 | 1 | Adrian Georgescu | '''state''':: |
230 | 1 | Adrian Georgescu | The state the object is currently in, being one of the states from the diagram above. |
231 | 94 | Adrian Georgescu | |
232 | 1 | Adrian Georgescu | '''account''':: |
233 | 19 | Ruud Klaver | The {{{sipsimple.account.Account}}} or {{{sipsimple.account.BonjourAccount}}} object that the {{{Session}}} is associated with. |
234 | 1 | Adrian Georgescu | On an outbound session, this is the account the application specified on object instantiation. |
235 | 94 | Adrian Georgescu | |
236 | 1 | Adrian Georgescu | '''direction''':: |
237 | 32 | Adrian Georgescu | A string indicating the direction of the initial negotiation of the session. |
238 | 63 | Luci Stanescu | This can be either {{{None}}}, "incoming" or "outgoing". |
239 | 94 | Adrian Georgescu | |
240 | 63 | Luci Stanescu | '''transport''':: |
241 | 1 | Adrian Georgescu | A string representing the transport this {{{Session}}} is using: {{{"udp"}}}, {{{"tcp"}}} or {{{"tls"}}}. |
242 | 94 | Adrian Georgescu | |
243 | 1 | Adrian Georgescu | '''start_time''':: |
244 | 1 | Adrian Georgescu | The time the session started as a {{{datetime.datetime}}} object, or {{{None}}} if the session was not yet started. |
245 | 94 | Adrian Georgescu | |
246 | 1 | Adrian Georgescu | '''stop_time''':: |
247 | 1 | Adrian Georgescu | The time the session stopped as a {{{datetime.datetime}}} object, or {{{None}}} if the session has not yet terminated. |
248 | 94 | Adrian Georgescu | |
249 | 1 | Adrian Georgescu | '''on_hold''':: |
250 | 1 | Adrian Georgescu | Boolean indicating whether the session was put on hold, either by the local or the remote party. |
251 | 94 | Adrian Georgescu | |
252 | 1 | Adrian Georgescu | '''remote_user_agent''':: |
253 | 1 | Adrian Georgescu | A string indicating the remote user agent, if it provided one. |
254 | 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). |
255 | 94 | Adrian Georgescu | |
256 | 63 | Luci Stanescu | '''local_identity''':: |
257 | 63 | Luci Stanescu | The {{{sipsimple.core.FrozenFromHeader}}} or {{{sipsimple.core.FrozenToHeader}}} identifying the local party, if the session is active, {{{None}}} otherwise. |
258 | 94 | Adrian Georgescu | |
259 | 63 | Luci Stanescu | '''remote_identity''':: |
260 | 63 | Luci Stanescu | The {{{sipsimple.core.FrozenFromHeader}}} or {{{sipsimple.core.FrozenToHeader}}} identifying the remote party, if the session is active, {{{None}}} otherwise. |
261 | 94 | Adrian Georgescu | |
262 | 63 | Luci Stanescu | '''streams''':: |
263 | 63 | Luci Stanescu | A list of the currently active streams in the {{{Session}}}. |
264 | 94 | Adrian Georgescu | |
265 | 63 | Luci Stanescu | '''proposed_streams''':: |
266 | 1 | Adrian Georgescu | A list of the currently proposed streams in the {{{Session}}}, or {{{None}}} if there is no proposal in progress. |
267 | 1 | Adrian Georgescu | |
268 | 64 | Luci Stanescu | ==== notifications ==== |
269 | 1 | Adrian Georgescu | |
270 | 94 | Adrian Georgescu | |
271 | 1 | Adrian Georgescu | '''SIPSessionNewIncoming''':: |
272 | 26 | Luci Stanescu | Will be sent when a new incoming {{{Session}}} is received. |
273 | 63 | Luci Stanescu | The application should listen for this notification to get informed of incoming sessions. |
274 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
275 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
276 | 1 | Adrian Georgescu | [[BR]]''streams'':[[BR]] |
277 | 63 | Luci Stanescu | A list of streams that were proposed by the remote party. |
278 | 94 | Adrian Georgescu | |
279 | 1 | Adrian Georgescu | '''SIPSessionNewOutgoing''':: |
280 | 1 | Adrian Georgescu | Will be sent when the applcation requests a new outgoing {{{Session}}}. |
281 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
282 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
283 | 1 | Adrian Georgescu | [[BR]]''streams'':[[BR]] |
284 | 63 | Luci Stanescu | A list of streams that were proposed to the remote party. |
285 | 94 | Adrian Georgescu | |
286 | 1 | Adrian Georgescu | '''SIPSessionGotRingIndication''':: |
287 | 1 | Adrian Georgescu | Will be sent when an outgoing {{{Session}}} receives an indication that a remote device is ringing. |
288 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
289 | 26 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
290 | 94 | Adrian Georgescu | |
291 | 63 | Luci Stanescu | '''SIPSessionGotProvisionalResponse''':: |
292 | 63 | Luci Stanescu | Will be sent whenever the {{{Session}}} receives a provisional response as a result of sending a (re-)INVITE. |
293 | 63 | Luci Stanescu | [[BR]]''timestamp'':[[BR]] |
294 | 63 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
295 | 63 | Luci Stanescu | [[BR]]''code'':[[BR]] |
296 | 63 | Luci Stanescu | The SIP status code received. |
297 | 63 | Luci Stanescu | [[BR]]''reason'':[[BR]] |
298 | 63 | Luci Stanescu | The SIP status reason received. |
299 | 94 | Adrian Georgescu | |
300 | 1 | Adrian Georgescu | '''SIPSessionWillStart''':: |
301 | 1 | Adrian Georgescu | Will be sent just before a {{{Session}}} completes negotiation. |
302 | 1 | Adrian Georgescu | In terms of SIP, this is sent after the final response to the {{{INVITE}}}, but before the {{{ACK}}}. |
303 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
304 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
305 | 94 | Adrian Georgescu | |
306 | 1 | Adrian Georgescu | '''SIPSessionDidStart''':: |
307 | 63 | Luci Stanescu | Will be sent when a {{{Session}}} completes negotiation and all the streams have started. |
308 | 26 | Luci Stanescu | In terms of SIP this is sent after the {{{ACK}}} was sent or received. |
309 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
310 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
311 | 63 | Luci Stanescu | [[BR]]''streams'':[[BR]] |
312 | 63 | Luci Stanescu | The list of streams which now form the active streams of the {{{Session}}}. |
313 | 94 | Adrian Georgescu | |
314 | 1 | Adrian Georgescu | '''SIPSessionDidFail''':: |
315 | 63 | Luci Stanescu | This notification is sent whenever the session fails before it starts. |
316 | 5 | Redmine Admin | The failure reason is included in the data attributes. |
317 | 63 | Luci Stanescu | This notification is never followed by {{{SIPSessionDidEnd}}}. |
318 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
319 | 26 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
320 | 1 | Adrian Georgescu | [[BR]]''originator'':[[BR]] |
321 | 63 | Luci Stanescu | A string indicating the originator of the {{{Session}}}. This will either be "local" or "remote". |
322 | 1 | Adrian Georgescu | [[BR]]''code'':[[BR]] |
323 | 1 | Adrian Georgescu | The SIP error code of the failure. |
324 | 1 | Adrian Georgescu | [[BR]]''reason'':[[BR]] |
325 | 63 | Luci Stanescu | A SIP status reason. |
326 | 63 | Luci Stanescu | [[BR]]''failure_reason'':[[BR]] |
327 | 63 | Luci Stanescu | A string which represents the reason for the failure, such as {{{"user_request"}}}, {{{"missing ACK"}}}, {{{"SIP core error..."}}}. |
328 | 94 | Adrian Georgescu | |
329 | 1 | Adrian Georgescu | '''SIPSessionWillEnd''':: |
330 | 63 | Luci Stanescu | Will be sent just before terminating a {{{Session}}}. |
331 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
332 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
333 | 94 | Adrian Georgescu | |
334 | 1 | Adrian Georgescu | '''SIPSessionDidEnd''':: |
335 | 63 | Luci Stanescu | Will be sent always when a {{{Session}}} ends as a result of remote or local session termination. |
336 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
337 | 19 | Ruud Klaver | A {{{datetime.datetime}}} object indicating when the notification was sent. |
338 | 19 | Ruud Klaver | [[BR]]''originator'':[[BR]] |
339 | 63 | Luci Stanescu | A string indicating who originated the termination. This will either be "local" or "remote". |
340 | 63 | Luci Stanescu | [[BR]]''end_reason'':[[BR]] |
341 | 63 | Luci Stanescu | A string representing the termination reason, such as {{{"user_request"}}}, {{{"SIP core error..."}}}. |
342 | 94 | Adrian Georgescu | |
343 | 63 | Luci Stanescu | '''SIPSessionDidChangeHoldState''':: |
344 | 63 | Luci Stanescu | Will be sent when the session got put on hold or removed from hold, either by the local or the remote party. |
345 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
346 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
347 | 1 | Adrian Georgescu | [[BR]]''originator'':[[BR]] |
348 | 1 | Adrian Georgescu | A string indicating who originated the hold request, and consequently in which direction the session got put on hold. |
349 | 63 | Luci Stanescu | [[BR]]''on_hold'':[[BR]] |
350 | 63 | Luci Stanescu | {{{True}}} if there is at least one stream which is on hold and {{{False}}} otherwise. |
351 | 63 | Luci Stanescu | [[BR]]''partial'':[[BR]] |
352 | 63 | Luci Stanescu | {{{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. |
353 | 94 | Adrian Georgescu | |
354 | 63 | Luci Stanescu | '''SIPSessionGotProposal''':: |
355 | 63 | Luci Stanescu | Will be sent when either the local or the remote party proposes to add streams to the session. |
356 | 26 | Luci Stanescu | [[BR]]''timestamp'':[[BR]] |
357 | 23 | Ruud Klaver | A {{{datetime.datetime}}} object indicating when the notification was sent. |
358 | 23 | Ruud Klaver | [[BR]]''originator'':[[BR]] |
359 | 63 | Luci Stanescu | The party that initiated the stream proposal, can be either "local" or "remote". |
360 | 63 | Luci Stanescu | [[BR]]''streams'':[[BR]] |
361 | 63 | Luci Stanescu | A list of streams that were proposed. |
362 | 94 | Adrian Georgescu | |
363 | 63 | Luci Stanescu | '''SIPSessionGotRejectProposal''':: |
364 | 63 | Luci Stanescu | Will be sent when either the local or the remote party rejects a proposal to have streams added to the session. |
365 | 6 | Ruud Klaver | [[BR]]''timestamp'':[[BR]] |
366 | 6 | Ruud Klaver | A {{{datetime.datetime}}} object indicating when the notification was sent. |
367 | 63 | Luci Stanescu | [[BR]]''originator'':[[BR]] |
368 | 63 | Luci Stanescu | The party that initiated the stream proposal, can be either "local" or "remote". |
369 | 6 | Ruud Klaver | [[BR]]''code'':[[BR]] |
370 | 63 | Luci Stanescu | The code with which the proposal was rejected. |
371 | 1 | Adrian Georgescu | [[BR]]''reason'':[[BR]] |
372 | 63 | Luci Stanescu | The reason for rejecting the stream proposal. |
373 | 63 | Luci Stanescu | [[BR]]''streams'':[[BR]] |
374 | 63 | Luci Stanescu | The list of streams which were rejected. |
375 | 94 | Adrian Georgescu | |
376 | 63 | Luci Stanescu | '''SIPSessionGotAcceptProposal''':: |
377 | 63 | Luci Stanescu | Will be sent when either the local or the remote party accepts a proposal to have stream( added to the session. |
378 | 24 | Ruud Klaver | [[BR]]''timestamp'':[[BR]] |
379 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
380 | 63 | Luci Stanescu | [[BR]]''originator'':[[BR]] |
381 | 63 | Luci Stanescu | The party that initiated the stream proposal, can be either "local" or "remote". |
382 | 1 | Adrian Georgescu | [[BR]]''streams'':[[BR]] |
383 | 63 | Luci Stanescu | The list of streams which were accepted. |
384 | 116 | Luci Stanescu | [[BR]]''proposed_streams'':[[BR]] |
385 | 116 | Luci Stanescu | The list of streams which were originally proposed. |
386 | 94 | Adrian Georgescu | |
387 | 63 | Luci Stanescu | '''SIPSessionHadProposalFailure''':: |
388 | 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). |
389 | 24 | Ruud Klaver | [[BR]]''timestamp'':[[BR]] |
390 | 63 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
391 | 63 | Luci Stanescu | [[BR]]''failure_reason'':[[BR]] |
392 | 63 | Luci Stanescu | The error which caused the proposal to fail. |
393 | 63 | Luci Stanescu | [[BR]]''streams'':[[BR]] |
394 | 108 | Adrian Georgescu | The streams which were part of this proposal. |
395 | 94 | Adrian Georgescu | |
396 | 24 | Ruud Klaver | '''SIPSessionDidRenegotiateStreams''':: |
397 | 6 | Ruud Klaver | Will be sent when a media stream is either activated or deactivated. |
398 | 26 | Luci Stanescu | An application should listen to this notification in order to know when a media stream can be used. |
399 | 63 | Luci Stanescu | [[BR]]''timestamp'':[[BR]] |
400 | 39 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
401 | 39 | Luci Stanescu | [[BR]]''action'':[[BR]] |
402 | 39 | Luci Stanescu | A string which is either {{{"add"}}} or {{{"remove"}}} which specifies what happened to the streams the notificaton referes to |
403 | 1 | Adrian Georgescu | [[BR]]''streams'':[[BR]] |
404 | 50 | Adrian Georgescu | A list with the streams which were added or removed. |
405 | 94 | Adrian Georgescu | |
406 | 39 | Luci Stanescu | '''SIPSessionDidProcessTransaction''':: |
407 | 39 | Luci Stanescu | Will be sent whenever a SIP transaction is complete in order to provide low-level details of the progress of the INVITE dialog. |
408 | 64 | Luci Stanescu | [[BR]]''timestamp'':[[BR]] |
409 | 39 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
410 | 39 | Luci Stanescu | [[BR]]''originator'':[[BR]] |
411 | 39 | Luci Stanescu | The initiator of the transaction, {{{"local"}}} or {{{"remote"}}}. |
412 | 39 | Luci Stanescu | [[BR]]''method'':[[BR]] |
413 | 64 | Luci Stanescu | The method of the request. |
414 | 39 | Luci Stanescu | [[BR]]''code'':[[BR]] |
415 | 39 | Luci Stanescu | The SIP status code of the response. |
416 | 39 | Luci Stanescu | [[BR]]''reason'':[[BR]] |
417 | 39 | Luci Stanescu | The SIP status reason of the response. |
418 | 39 | Luci Stanescu | [[BR]]''ack_received'':[[BR]] |
419 | 39 | Luci Stanescu | 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. |
420 | 1 | Adrian Georgescu | |
421 | 65 | 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 see [wiki:SipSessionExample Minimalist Session Example code]. |
422 | 39 | Luci Stanescu | |
423 | 39 | Luci Stanescu | === IMediaStream === |
424 | 1 | Adrian Georgescu | |
425 | 65 | Luci Stanescu | Implemented in [browser:sipsimple/streams/__init__.py] |
426 | 1 | Adrian Georgescu | |
427 | 66 | 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. |
428 | 1 | Adrian Georgescu | |
429 | 1 | Adrian Georgescu | ==== methods ==== |
430 | 65 | Luci Stanescu | |
431 | 94 | Adrian Georgescu | |
432 | 1 | Adrian Georgescu | '''!__init!__'''(''self'', ''account''):: |
433 | 65 | Luci Stanescu | Initializes the generic stream instance. |
434 | 94 | Adrian Georgescu | |
435 | 65 | Luci Stanescu | '''new_from_sdp'''(''cls'', ''account'', ''remote_sdp'', ''stream_index''):: |
436 | 65 | Luci Stanescu | A classmethod which returns an instance of this stream implementation if the sdp is accepted by the stream or None otherwise. |
437 | 65 | Luci Stanescu | [[BR]]account:[[BR]] |
438 | 65 | Luci Stanescu | The {{{sipsimple.account.Account}}} or {{{sipsimple.account.BonjourAccount}}} object the session which this stream would be part of is associated with. |
439 | 65 | Luci Stanescu | [[BR]]remote_sdp:[[BR]] |
440 | 65 | Luci Stanescu | The {{{FrozenSDPSession}}} which was received by the remote offer. |
441 | 1 | Adrian Georgescu | [[BR]]stream_index:[[BR]] |
442 | 65 | Luci Stanescu | An integer representing the index within the list of media streams within the whole SDP which this stream would be instantiated for. |
443 | 94 | Adrian Georgescu | |
444 | 65 | Luci Stanescu | '''get_local_media'''(''self'', ''for_offer''):: |
445 | 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. |
446 | 1 | Adrian Georgescu | [[BR]]for_offer:[[BR]] |
447 | 65 | Luci Stanescu | {{{True}}} if the {{{SDPMediaStream}}} will be used for an SDP proposal and {{{False}}} if for a response. |
448 | 94 | Adrian Georgescu | |
449 | 65 | Luci Stanescu | '''initialize'''(''self'', ''session'', ''direction''):: |
450 | 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. |
451 | 65 | Luci Stanescu | [[BR]]session:[[BR]] |
452 | 65 | Luci Stanescu | The {{{Session}}} object this stream will be part of. |
453 | 1 | Adrian Georgescu | [[BR]]direction:[[BR]] |
454 | 65 | Luci Stanescu | {{{"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. |
455 | 94 | Adrian Georgescu | |
456 | 65 | Luci Stanescu | '''start'''(''self'', ''local_sdp'', ''remote_sdp'', ''stream_index''):: |
457 | 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. |
458 | 65 | Luci Stanescu | [[BR]]local_sdp:[[BR]] |
459 | 65 | Luci Stanescu | The {{{FrozenSDPSession}}} which is used by the local endpoint. |
460 | 65 | Luci Stanescu | [[BR]]remote_sdp:[[BR]] |
461 | 65 | Luci Stanescu | The {{{FrozenSDPSession}}} which is used by the remote endpoint. |
462 | 1 | Adrian Georgescu | [[BR]]stream_index:[[BR]] |
463 | 65 | Luci Stanescu | An integer representing the index within the list of media streams within the whole SDP which this stream is represented by. |
464 | 94 | Adrian Georgescu | |
465 | 65 | Luci Stanescu | '''validate_update'''(''self'', ''remote_sdp'', ''stream_index''):: |
466 | 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}}}. |
467 | 65 | Luci Stanescu | [[BR]]remote_sdp:[[BR]] |
468 | 65 | Luci Stanescu | The {{{FrozenSDPSession}}} which is used by the remote endpoint. |
469 | 1 | Adrian Georgescu | [[BR]]stream_index:[[BR]] |
470 | 65 | Luci Stanescu | An integer representing the index within the list of media streams within the whole SDP which this stream is represented by. |
471 | 94 | Adrian Georgescu | |
472 | 65 | Luci Stanescu | '''update'''(''self'', ''local_sdp'', ''remote_sdp'', ''stream_index''):: |
473 | 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. |
474 | 65 | Luci Stanescu | [[BR]]local_sdp:[[BR]] |
475 | 65 | Luci Stanescu | The {{{FrozenSDPSession}}} which is used by the local endpoint. |
476 | 65 | Luci Stanescu | [[BR]]remote_sdp:[[BR]] |
477 | 65 | Luci Stanescu | The {{{FrozenSDPSession}}} which is used by the remote endpoint. |
478 | 55 | Adrian Georgescu | [[BR]]stream_index:[[BR]] |
479 | 65 | Luci Stanescu | An integer representing the index within the list of media streams within the whole SDP which this stream is represented by. |
480 | 94 | Adrian Georgescu | |
481 | 55 | Adrian Georgescu | '''hold'''(''self''):: |
482 | 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. |
483 | 94 | Adrian Georgescu | |
484 | 65 | Luci Stanescu | '''unhold'''(''self''):: |
485 | 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. |
486 | 94 | Adrian Georgescu | |
487 | 65 | Luci Stanescu | '''deactivate'''(''self''):: |
488 | 65 | Luci Stanescu | 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. |
489 | 94 | Adrian Georgescu | |
490 | 55 | Adrian Georgescu | '''end'''(''self''):: |
491 | 65 | Luci Stanescu | 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. |
492 | 55 | Adrian Georgescu | |
493 | 96 | Adrian Georgescu | ==== attributes ==== |
494 | 65 | Luci Stanescu | |
495 | 94 | Adrian Georgescu | |
496 | 65 | Luci Stanescu | '''type''' (class attribute):: |
497 | 65 | Luci Stanescu | A string identifying the stream type (eg: {{{"audio"}}}, {{{"video"}}}). |
498 | 94 | Adrian Georgescu | |
499 | 65 | Luci Stanescu | '''priority''' (class attribute):: |
500 | 65 | Luci Stanescu | An integer value indicating the stream priority relative to the other streams types (higher numbers have higher priority). |
501 | 94 | Adrian Georgescu | |
502 | 65 | Luci Stanescu | '''hold_supported''':: |
503 | 65 | Luci Stanescu | True if the stream supports hold |
504 | 94 | Adrian Georgescu | |
505 | 65 | Luci Stanescu | '''on_hold_by_local''':: |
506 | 65 | Luci Stanescu | True if the stream is on hold by the local party |
507 | 94 | Adrian Georgescu | |
508 | 65 | Luci Stanescu | '''on_hold_by_remote''':: |
509 | 65 | Luci Stanescu | True if the stream is on hold by the remote |
510 | 94 | Adrian Georgescu | |
511 | 55 | Adrian Georgescu | '''on_hold''':: |
512 | 65 | Luci Stanescu | True if either on_hold_by_local or on_hold_by_remote is true |
513 | 65 | Luci Stanescu | |
514 | 65 | Luci Stanescu | ==== notifications ==== |
515 | 65 | Luci Stanescu | |
516 | 55 | Adrian Georgescu | These notifications must be generated by all streams in order for the {{{Session}}} to know the state of the stream. |
517 | 65 | Luci Stanescu | |
518 | 94 | Adrian Georgescu | |
519 | 55 | Adrian Georgescu | '''MediaStreamDidInitialize''':: |
520 | 65 | Luci Stanescu | Sent when the stream has been successfully initialized. |
521 | 94 | Adrian Georgescu | |
522 | 55 | Adrian Georgescu | '''MediaStreamDidStart''':: |
523 | 65 | Luci Stanescu | Sent when the stream has been successfully started. |
524 | 94 | Adrian Georgescu | |
525 | 55 | Adrian Georgescu | '''MediaStreamDidFail''':: |
526 | 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). |
527 | 94 | Adrian Georgescu | |
528 | 55 | Adrian Georgescu | '''MediaStreamWillEnd''':: |
529 | 65 | Luci Stanescu | Sent immediately after the {{{end()}}} method is called. |
530 | 94 | Adrian Georgescu | |
531 | 55 | Adrian Georgescu | '''MediaStreamDidEnd''':: |
532 | 66 | Luci Stanescu | Sent when the {{{end()}}} method finished closing the stream. |
533 | 55 | Adrian Georgescu | |
534 | 66 | Luci Stanescu | === MediaStreamRegistry === |
535 | 1 | Adrian Georgescu | |
536 | 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. |
537 | 66 | Luci Stanescu | |
538 | 1 | Adrian Georgescu | There are several pre-built streams based on the {{{IMediaStream}}} API: |
539 | 1 | Adrian Georgescu | * {{{sipsimple.streams.rtp.AudioStream}}} - Audio stream based on RTP |
540 | 66 | Luci Stanescu | * {{{sipsimple.streams.msrp.ChatStream}}} - Chat stream based on MSRP |
541 | 1 | Adrian Georgescu | * {{{sipsimple.streams.msrp.FileTransferStream}}} - File Transfer stream based on MSRP |
542 | 66 | Luci Stanescu | * {{{sipsimple.streams.msrp.DesktopSharingStream}}} - Desktop Sharing stream based on VNC over MSRP |
543 | 66 | Luci Stanescu | |
544 | 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]. |
545 | 66 | Luci Stanescu | |
546 | 66 | Luci Stanescu | ==== methods ==== |
547 | 66 | Luci Stanescu | |
548 | 94 | Adrian Georgescu | |
549 | 66 | Luci Stanescu | '''!__init!__'''(''self''):: |
550 | 66 | Luci Stanescu | Instantiate the MediaStreamRegistry. This will be called just once when first (and only) instance is created. |
551 | 94 | Adrian Georgescu | |
552 | 66 | Luci Stanescu | '''!__iter!__'''(''self''):: |
553 | 66 | Luci Stanescu | This method allows the registry to be iterated through and will return classes which were registered to it. |
554 | 94 | Adrian Georgescu | |
555 | 66 | Luci Stanescu | '''add'''(''self'', '''cls'''):: |
556 | 66 | Luci Stanescu | Add {{{cls}}} to the registry of streams. The class must implement the {{{IMediaStream}}} interface. |
557 | 66 | Luci Stanescu | |
558 | 66 | Luci Stanescu | === MediaStreamRegistrar === |
559 | 66 | Luci Stanescu | |
560 | 66 | Luci Stanescu | 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. |
561 | 66 | Luci Stanescu | |
562 | 66 | Luci Stanescu | {{{ |
563 | 66 | Luci Stanescu | from zope.interface import implements |
564 | 66 | Luci Stanescu | |
565 | 66 | Luci Stanescu | from sipsimple.streams import IMediaStream, MediaStreamRegistrar |
566 | 66 | Luci Stanescu | |
567 | 66 | Luci Stanescu | |
568 | 66 | Luci Stanescu | class MyStream(object): |
569 | 66 | Luci Stanescu | __metaclass__ = MediaStreamRegistrar |
570 | 66 | Luci Stanescu | |
571 | 66 | Luci Stanescu | implements(IMediaStream) |
572 | 66 | Luci Stanescu | |
573 | 55 | Adrian Georgescu | [...] |
574 | 67 | Luci Stanescu | }}} |
575 | 55 | Adrian Georgescu | |
576 | 55 | Adrian Georgescu | === AudioStream === |
577 | 55 | Adrian Georgescu | |
578 | 67 | Luci Stanescu | Implemented in [browser:sipsimple/streams/rtp.py] |
579 | 55 | Adrian Georgescu | |
580 | 55 | Adrian Georgescu | 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: |
581 | 55 | Adrian Georgescu | |
582 | 55 | Adrian Georgescu | {{{ |
583 | 55 | Adrian Georgescu | Content-Type: application/sdp |
584 | 55 | Adrian Georgescu | Content-Length: 1093 |
585 | 55 | Adrian Georgescu | |
586 | 55 | Adrian Georgescu | v=0 |
587 | 55 | Adrian Georgescu | o=- 3467525278 3467525278 IN IP4 192.168.1.6 |
588 | 55 | Adrian Georgescu | s=blink-0.10.7-beta |
589 | 57 | Adrian Georgescu | c=IN IP4 80.101.96.20 |
590 | 57 | Adrian Georgescu | t=0 0 |
591 | 57 | Adrian Georgescu | m=audio 55328 RTP/AVP 104 103 102 3 9 0 8 101 |
592 | 57 | Adrian Georgescu | a=rtcp:55329 IN IP4 80.101.96.20 |
593 | 57 | Adrian Georgescu | a=rtpmap:104 speex/32000 |
594 | 57 | Adrian Georgescu | a=rtpmap:103 speex/16000 |
595 | 57 | Adrian Georgescu | a=rtpmap:102 speex/8000 |
596 | 57 | Adrian Georgescu | a=rtpmap:3 GSM/8000 |
597 | 57 | Adrian Georgescu | a=rtpmap:9 G722/8000 |
598 | 57 | Adrian Georgescu | a=rtpmap:0 PCMU/8000 |
599 | 57 | Adrian Georgescu | a=rtpmap:8 PCMA/8000 |
600 | 57 | Adrian Georgescu | a=rtpmap:101 telephone-event/8000 |
601 | 57 | Adrian Georgescu | a=fmtp:101 0-15 |
602 | 57 | Adrian Georgescu | a=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:esI6DbLY1+Aceu0JNswN9Z10DcFx5cZwqJcu91jb |
603 | 57 | Adrian Georgescu | a=crypto:2 AES_CM_128_HMAC_SHA1_32 inline:SHuEMm1BYJqOF4udKl73EaCwnsI57pO86bYKsg70 |
604 | 57 | Adrian Georgescu | a=ice-ufrag:2701ed80 |
605 | 57 | Adrian Georgescu | a=ice-pwd:6f8f8281 |
606 | 57 | Adrian Georgescu | a=candidate:S 1 UDP 31 80.101.96.20 55328 typ srflx raddr 192.168.1.6 rport 55328 |
607 | 57 | Adrian Georgescu | a=candidate:H 1 UDP 23 192.168.1.6 55328 typ host |
608 | 57 | Adrian Georgescu | a=candidate:H 1 UDP 23 10.211.55.2 55328 typ host |
609 | 57 | Adrian Georgescu | a=candidate:H 1 UDP 23 10.37.129.2 55328 typ host |
610 | 57 | Adrian Georgescu | a=candidate:S 2 UDP 30 80.101.96.20 55329 typ srflx raddr 192.168.1.6 rport 55329 |
611 | 57 | Adrian Georgescu | a=candidate:H 2 UDP 22 192.168.1.6 55329 typ host |
612 | 57 | Adrian Georgescu | a=candidate:H 2 UDP 22 10.211.55.2 55329 typ host |
613 | 57 | Adrian Georgescu | a=candidate:H 2 UDP 22 10.37.129.2 55329 typ host |
614 | 1 | Adrian Georgescu | a=sendrecv |
615 | 67 | Luci Stanescu | }}} |
616 | 1 | Adrian Georgescu | |
617 | 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. |
618 | 67 | Luci Stanescu | |
619 | 67 | Luci Stanescu | ==== methods ==== |
620 | 67 | Luci Stanescu | |
621 | 94 | Adrian Georgescu | |
622 | 67 | Luci Stanescu | '''start_recording'''(''self'', '''filename'''={{{None}}}):: |
623 | 67 | Luci Stanescu | If an audio stream is present within this session, calling this method will record the audio to a {{{.wav}}} file. |
624 | 67 | Luci Stanescu | Note that when the session is on hold, nothing will be recorded to the file. |
625 | 67 | Luci Stanescu | Right before starting the recording a {{{SIPSessionWillStartRecordingAudio}}} notification will be emitted, followed by a {{{SIPSessionDidStartRecordingAudio}}}. |
626 | 67 | Luci Stanescu | This method may only be called while the stream is started. |
627 | 67 | Luci Stanescu | [[BR]]''filename'':[[BR]] |
628 | 67 | Luci Stanescu | The name of the {{{.wav}}} file to record to. |
629 | 67 | Luci Stanescu | 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. |
630 | 94 | Adrian Georgescu | |
631 | 67 | Luci Stanescu | '''stop_recording'''(''self''):: |
632 | 67 | Luci Stanescu | This will stop a previously started recording. |
633 | 67 | Luci Stanescu | Before stopping, a {{{SIPSessionWillStopRecordingAudio}}} notification will be sent, followed by a {{{SIPSessionDidStopRecordingAudio}}}. |
634 | 94 | Adrian Georgescu | |
635 | 67 | Luci Stanescu | '''send_dtmf'''(''self'', '''digit'''):: |
636 | 67 | Luci Stanescu | If the audio stream is started, sends a DTMF digit to the remote party. |
637 | 67 | Luci Stanescu | [[BR]]''digit'':[[BR]] |
638 | 67 | Luci Stanescu | This should a string of length 1, containing a valid DTMF digit value (0-9, A-D, * or #). |
639 | 67 | Luci Stanescu | |
640 | 63 | Luci Stanescu | ==== attributes ==== |
641 | 63 | Luci Stanescu | |
642 | 94 | Adrian Georgescu | |
643 | 63 | Luci Stanescu | '''sample_rate''':: |
644 | 1 | Adrian Georgescu | If the audio stream was started, this attribute contains the sample rate of the audio negotiated. |
645 | 94 | Adrian Georgescu | |
646 | 1 | Adrian Georgescu | '''codec''':: |
647 | 1 | Adrian Georgescu | If the audio stream was started, this attribute contains the name of the audio codec that was negotiated. |
648 | 94 | Adrian Georgescu | |
649 | 67 | Luci Stanescu | '''srtp_active''':: |
650 | 67 | Luci Stanescu | If the audio stream was started, this boolean attribute indicates if SRTP is currently being used on the stream. |
651 | 94 | Adrian Georgescu | |
652 | 1 | Adrian Georgescu | '''ice_active''':: |
653 | 1 | Adrian Georgescu | {{{True}}} if the ICE candidates negotiated are being used, {{{False}}} otherwise. |
654 | 94 | Adrian Georgescu | |
655 | 1 | Adrian Georgescu | '''local_rtp_address''':: |
656 | 1 | Adrian Georgescu | If an audio stream is present within the session, this attribute contains the local IP address used for the audio stream. |
657 | 94 | Adrian Georgescu | |
658 | 1 | Adrian Georgescu | '''local_rtp_port''':: |
659 | 1 | Adrian Georgescu | If an audio stream is present within the session, this attribute contains the local UDP port used for the audio stream. |
660 | 94 | Adrian Georgescu | |
661 | 1 | Adrian Georgescu | '''remote_rtp_address_sdp''':: |
662 | 1 | Adrian Georgescu | If the audio stream was started, this attribute contains the IP address that the remote party gave to send audio to. |
663 | 94 | Adrian Georgescu | |
664 | 1 | Adrian Georgescu | '''remote_rtp_port_sdp''':: |
665 | 1 | Adrian Georgescu | If the audio stream was started, this attribute contains the UDP port that the remote party gave to send audio to. |
666 | 94 | Adrian Georgescu | |
667 | 1 | Adrian Georgescu | '''remote_rtp_address_received''':: |
668 | 1 | Adrian Georgescu | If the audio stream was started, this attribute contains the remote IP address from which the audio stream is being received. |
669 | 94 | Adrian Georgescu | |
670 | 67 | Luci Stanescu | '''remote_rtp_port_received''':: |
671 | 67 | Luci Stanescu | If the audio stream was started, this attribute contains the remote UDP port from which the audio stream is being received. |
672 | 94 | Adrian Georgescu | |
673 | 67 | Luci Stanescu | '''local_rtp_candidate_type''':: |
674 | 67 | Luci Stanescu | The local ICE candidate type which was selected by the ICE negotiation if it succeeded and {{{None}}} otherwise. |
675 | 94 | Adrian Georgescu | |
676 | 67 | Luci Stanescu | '''remote_rtp_candidate_type''':: |
677 | 63 | Luci Stanescu | The remote ICE candidate type which was selected by the ICE negotiation if it succeeded and {{{None}}} otherwise. |
678 | 94 | Adrian Georgescu | |
679 | 63 | Luci Stanescu | '''recording_filename''':: |
680 | 67 | Luci Stanescu | If the audio stream is currently being recorded to disk, this property contains the name of the {{{.wav}}} file being recorded to. |
681 | 55 | Adrian Georgescu | |
682 | 55 | Adrian Georgescu | ==== notifications ==== |
683 | 67 | Luci Stanescu | |
684 | 94 | Adrian Georgescu | |
685 | 67 | Luci Stanescu | '''AudioStreamDidChangeHoldState''':: |
686 | 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. |
687 | 67 | Luci Stanescu | [[BR]]''timestamp'':[[BR]] |
688 | 67 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
689 | 67 | Luci Stanescu | [[BR]]originator:[[BR]] |
690 | 67 | Luci Stanescu | A string representing the party which requested the hold change, {{{"local"}}} or {{{"remote"}}} |
691 | 1 | Adrian Georgescu | [[BR]]on_hold:[[BR]] |
692 | 67 | Luci Stanescu | A boolean indicating the new hold state from the point of view of the originator. |
693 | 94 | Adrian Georgescu | |
694 | 63 | Luci Stanescu | '''AudioStreamWillStartRecordingAudio'':: |
695 | 63 | Luci Stanescu | Will be sent when the application requested that the audio stream be recorded to a {{{.wav}}} file, just before recording starts. |
696 | 67 | Luci Stanescu | [[BR]]''timestamp'':[[BR]] |
697 | 67 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
698 | 55 | Adrian Georgescu | [[BR]]''filename'':[[BR]] |
699 | 67 | Luci Stanescu | The full path to the {{{.wav}}} file being recorded to. |
700 | 94 | Adrian Georgescu | |
701 | 63 | Luci Stanescu | '''AudioStreamDidStartRecordingAudio''':: |
702 | 63 | Luci Stanescu | Will be sent when the application requested that the audio stream be recorded to a {{{.wav}}} file, just after recording started. |
703 | 67 | Luci Stanescu | [[BR]]''timestamp'':[[BR]] |
704 | 67 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
705 | 63 | Luci Stanescu | [[BR]]''filename'':[[BR]] |
706 | 63 | Luci Stanescu | The full path to the {{{.wav}}} file being recorded to. |
707 | 94 | Adrian Georgescu | |
708 | 63 | Luci Stanescu | '''AudioStreamWillStopRecordingAudio''':: |
709 | 63 | Luci Stanescu | Will be sent when the application requested ending the recording to a {{{.wav}}} file, just before recording stops. |
710 | 67 | Luci Stanescu | [[BR]]''timestamp'':[[BR]] |
711 | 67 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
712 | 57 | Adrian Georgescu | [[BR]]''filename'':[[BR]] |
713 | 67 | Luci Stanescu | The full path to the {{{.wav}}} file being recorded to. |
714 | 94 | Adrian Georgescu | |
715 | 63 | Luci Stanescu | '''AudioStreamDidStopRecordingAudio''':: |
716 | 63 | Luci Stanescu | Will be sent when the application requested ending the recording to a {{{.wav}}} file, just after recording stoped. |
717 | 67 | Luci Stanescu | [[BR]]''timestamp'':[[BR]] |
718 | 67 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
719 | 67 | Luci Stanescu | [[BR]]''filename'':[[BR]] |
720 | 67 | Luci Stanescu | The full path to the {{{.wav}}} file being recorded to. |
721 | 94 | Adrian Georgescu | |
722 | 63 | Luci Stanescu | '''AudioStreamDidChangeRTPParameters''':: |
723 | 1 | Adrian Georgescu | This notification is sent when the RTP parameters are changed, such as codec, sample rate, RTP port etc. |
724 | 63 | Luci Stanescu | [[BR]]''timestamp'':[[BR]] |
725 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
726 | 94 | Adrian Georgescu | |
727 | 57 | Adrian Georgescu | '''AudioStreamGotDTMF''':: |
728 | 1 | Adrian Georgescu | Will be send if there is a DMTF digit received from the remote party on the audio stream. |
729 | 63 | Luci Stanescu | [[BR]]''timestamp'':[[BR]] |
730 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
731 | 67 | Luci Stanescu | [[BR]]''digit'':[[BR]] |
732 | 67 | Luci Stanescu | The DTMF digit that was received, in the form of a string of length 1. |
733 | 94 | Adrian Georgescu | |
734 | 67 | Luci Stanescu | '''AudioStreamICENegotiationStateDidChange''':: |
735 | 67 | Luci Stanescu | This notification is proxied from the {{{RTPTransport}}} and as such has the same data as the {{{RTPTransportICENegotiationStateDidChange}}}. |
736 | 94 | Adrian Georgescu | |
737 | 67 | Luci Stanescu | '''AudioStreamICENegotiationDidSucceed''':: |
738 | 67 | Luci Stanescu | This notification is proxied from the {{{RTPTransport}}} and as such has the same data as the {{{RTPTransportICENegotiationDidSucceed}}}. |
739 | 94 | Adrian Georgescu | |
740 | 1 | Adrian Georgescu | '''AudioStreamICENegotiationDidFail''':: |
741 | 69 | Luci Stanescu | This notification is proxied from the {{{RTPTransport}}} and as such has the same data as the {{{RTPTransportICENegotiationDidFail}}}. |
742 | 1 | Adrian Georgescu | |
743 | 1 | Adrian Georgescu | === MSRPStreamBase === |
744 | 1 | Adrian Georgescu | |
745 | 68 | Luci Stanescu | Implemented in [browser:sipsimple/streams/msrp.py] |
746 | 1 | Adrian Georgescu | |
747 | 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. |
748 | 68 | Luci Stanescu | |
749 | 68 | Luci Stanescu | ==== methods ==== |
750 | 68 | Luci Stanescu | |
751 | 69 | Luci Stanescu | 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. |
752 | 68 | Luci Stanescu | |
753 | 96 | Adrian Georgescu | ==== attributes ==== |
754 | 68 | Luci Stanescu | |
755 | 68 | Luci Stanescu | The attributes defined in the {{{IMediaStream}}} interface which are not provided by this class are: |
756 | 68 | Luci Stanescu | * type |
757 | 68 | Luci Stanescu | * priority |
758 | 1 | Adrian Georgescu | |
759 | 68 | Luci Stanescu | In addition, the following attributes need to be defined in the subclass in order for the {{{MSRPStreamBase}}} class to take the correct decisions |
760 | 94 | Adrian Georgescu | |
761 | 1 | Adrian Georgescu | '''media_type''':: |
762 | 68 | Luci Stanescu | The media type as included in the SDP (eg. {{{"message"}}}, {{{"application"}}}). |
763 | 94 | Adrian Georgescu | |
764 | 1 | Adrian Georgescu | '''accept_types''':: |
765 | 68 | Luci Stanescu | A list of the MIME types which should be accepted by the stream (this is also sent within the SDP). |
766 | 94 | Adrian Georgescu | |
767 | 1 | Adrian Georgescu | '''accept_wrapped_types''':: |
768 | 68 | Luci Stanescu | A list of the MIME types which should be accepted by the stream while wrapped in a {{{message/cpim}}} envelope. |
769 | 94 | Adrian Georgescu | |
770 | 1 | Adrian Georgescu | '''use_msrp_session''':: |
771 | 69 | Luci Stanescu | A boolean indicating whether or not an {{{MSRPSession}}} should be used. |
772 | 1 | Adrian Georgescu | |
773 | 68 | Luci Stanescu | ==== notifications ==== |
774 | 68 | Luci Stanescu | |
775 | 1 | Adrian Georgescu | 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. |
776 | 68 | Luci Stanescu | |
777 | 94 | Adrian Georgescu | |
778 | 68 | Luci Stanescu | '''MSRPTransportTrace''':: |
779 | 68 | Luci Stanescu | This notification is sent when an MSRP message is received for logging purposes. |
780 | 68 | Luci Stanescu | [[BR]]timestamp:[[BR]] |
781 | 68 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
782 | 68 | Luci Stanescu | [[BR]]direction:[[BR]] |
783 | 68 | Luci Stanescu | The direction of the message, {{{"incoming"}}} or {{{"outgoing"}}}. |
784 | 68 | Luci Stanescu | [[BR]]data:[[BR]] |
785 | 68 | Luci Stanescu | The MSRP message as a string. |
786 | 94 | Adrian Georgescu | |
787 | 68 | Luci Stanescu | '''MSRPLibraryLog''':: |
788 | 68 | Luci Stanescu | This notification is sent anonymously whenever the MSRP library needs to log any information. |
789 | 68 | Luci Stanescu | [[BR]]timestamp:[[BR]] |
790 | 68 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
791 | 68 | Luci Stanescu | [[BR]]message:[[BR]] |
792 | 68 | Luci Stanescu | The log message as a string. |
793 | 1 | Adrian Georgescu | [[BR]]level:[[BR]] |
794 | 68 | Luci Stanescu | 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. |
795 | 1 | Adrian Georgescu | |
796 | 1 | Adrian Georgescu | === ChatStream === |
797 | 1 | Adrian Georgescu | |
798 | 68 | Luci Stanescu | Implemented in [browser:sipsimple/streams/msrp.py] |
799 | 1 | Adrian Georgescu | |
800 | 1 | Adrian Georgescu | {{{sipsimple.streams.msrp.ChatStream}}} implements session-based Instant Messaging (IM) over MSRP. This class performs the following functions: |
801 | 68 | Luci Stanescu | |
802 | 68 | Luci Stanescu | * automatically wraps outgoing messages with Message/CPIM if that's necessary according to accept-types |
803 | 1 | Adrian Georgescu | * unwraps incoming Message/CPIM messages; for each incoming message, the {{{ChatStreamGotMessage}}} notification is posted |
804 | 68 | Luci Stanescu | * composes iscomposing payloads and reacts to those received by sending the {{{ChatStreamGotComposingIndication}}} notification |
805 | 1 | Adrian Georgescu | |
806 | 1 | Adrian Georgescu | An example of an SDP created using this class follows: |
807 | 1 | Adrian Georgescu | |
808 | 1 | Adrian Georgescu | {{{ |
809 | 1 | Adrian Georgescu | Content-Type: application/sdp |
810 | 1 | Adrian Georgescu | Content-Length: 283 |
811 | 1 | Adrian Georgescu | |
812 | 1 | Adrian Georgescu | v=0 |
813 | 1 | Adrian Georgescu | o=- 3467525214 3467525214 IN IP4 192.168.1.6 |
814 | 1 | Adrian Georgescu | s=blink-0.10.7-beta |
815 | 1 | Adrian Georgescu | c=IN IP4 192.168.1.6 |
816 | 1 | Adrian Georgescu | t=0 0 |
817 | 1 | Adrian Georgescu | m=message 2855 TCP/TLS/MSRP * |
818 | 1 | Adrian Georgescu | a=path:msrps://192.168.1.6:2855/ca7940f12ddef14c3c32;tcp |
819 | 1 | Adrian Georgescu | a=accept-types:message/cpim text/* application/im-iscomposing+xml |
820 | 1 | Adrian Georgescu | a=accept-wrapped-types:* |
821 | 68 | Luci Stanescu | }}} |
822 | 1 | Adrian Georgescu | |
823 | 68 | Luci Stanescu | ==== methods ==== |
824 | 68 | Luci Stanescu | |
825 | 94 | Adrian Georgescu | |
826 | 1 | Adrian Georgescu | '''!__init!__'''(''self'', '''account''', '''direction'''={{{'sendrecv'}}}):: |
827 | 68 | Luci Stanescu | Initializes the ChatStream instance. |
828 | 68 | Luci Stanescu | |
829 | 94 | Adrian Georgescu | |
830 | 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}}}):: |
831 | 68 | Luci Stanescu | Sends an IM message. Prefer Message/CPIM wrapper if it is supported. If called before the connection was established, the messages will be |
832 | 68 | Luci Stanescu | queued until the stream starts. |
833 | 68 | Luci Stanescu | Returns the generated MSRP message ID. |
834 | 68 | Luci Stanescu | [[BR]]content:[[BR]] |
835 | 68 | Luci Stanescu | The content of the message. |
836 | 68 | Luci Stanescu | [[BR]]content_type:[[BR]] |
837 | 68 | Luci Stanescu | Content-Type of wrapped message if Message/CPIM is used (Content-Type of MSRP message is always Message/CPIM in that case); |
838 | 68 | Luci Stanescu | otherwise, Content-Type of MSRP message. |
839 | 68 | Luci Stanescu | [[BR]]recipients:[[BR]] |
840 | 68 | Luci Stanescu | 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. |
841 | 68 | Luci Stanescu | May only differ from the default one if the remote party supports private messages. If it does not, a {{{ChatStreamError}}} will be raised. |
842 | 68 | Luci Stanescu | [[BR]]courtesy_recipients:[[BR]] |
843 | 68 | Luci Stanescu | The list of {{{CPIMIdentity}}} objects which will be used for the {{{cc}}} header of the CPIM wrapper. |
844 | 68 | Luci Stanescu | May only be specified if the remote party supports private messages and CPIM is supported. If it does not, a {{{ChatStreamError}}} will be raised. |
845 | 68 | Luci Stanescu | [[BR]]subject:[[BR]] |
846 | 68 | Luci Stanescu | 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. |
847 | 68 | Luci Stanescu | [[BR]]required:[[BR]] |
848 | 68 | Luci Stanescu | 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. |
849 | 68 | Luci Stanescu | [[BR]]additional_headers:[[BR]] |
850 | 1 | Adrian Georgescu | A list of MSRP header objects which will be added to this CPIM message. If CPIM is not supported, a {{{ChatStreamError}}} will be raised. |
851 | 68 | Luci Stanescu | [[BR]]timestamp:[[BR]] |
852 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object representing the timestamp to put on the CPIM wrapper of the message. |
853 | 1 | Adrian Georgescu | When set to {{{None}}}, a default one representing the current moment will be added. |
854 | 1 | Adrian Georgescu | |
855 | 1 | Adrian Georgescu | These MSRP headers are used to enable end-to-end success reports and to disable hop-to-hop successful responses: |
856 | 1 | Adrian Georgescu | {{{ |
857 | 1 | Adrian Georgescu | Failure-Report: partial |
858 | 1 | Adrian Georgescu | Success-Report: yes |
859 | 68 | Luci Stanescu | }}} |
860 | 68 | Luci Stanescu | |
861 | 94 | Adrian Georgescu | |
862 | 68 | Luci Stanescu | '''send_composing_indication'''(''self'', ''state'', ''refresh'', ''last_active=None'', ''recipients=None''):: |
863 | 68 | Luci Stanescu | Sends an is-composing message to the listed recipients. |
864 | 68 | Luci Stanescu | [[BR]]state:[[BR]] |
865 | 68 | Luci Stanescu | The state of the endpoint, {{{"active"}}} or {{{"idle"}}}. |
866 | 68 | Luci Stanescu | [[BR]]refresh:[[BR]] |
867 | 68 | Luci Stanescu | How often the local endpoint will send is-composing indications to keep the state from being reverted to {{{"idle"}}}. |
868 | 68 | Luci Stanescu | [[BR]]last_active:[[BR]] |
869 | 68 | Luci Stanescu | A {{{datatime.datetime}}} object representing the moment when the local endpoint was last active. |
870 | 68 | Luci Stanescu | [[BR]]recipients:[[BR]] |
871 | 1 | Adrian Georgescu | 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. |
872 | 68 | Luci Stanescu | May only differ from the default one if the remote party supports private messages. If it does not, a {{{ChatStreamError}}} will be raised. |
873 | 1 | Adrian Georgescu | |
874 | 1 | Adrian Georgescu | ==== notifications ==== |
875 | 68 | Luci Stanescu | |
876 | 94 | Adrian Georgescu | |
877 | 68 | Luci Stanescu | '''ChatStreamGotMessage''':: |
878 | 68 | Luci Stanescu | Sent whenever a new incoming message is received, |
879 | 68 | Luci Stanescu | [[BR]]timestamp:[[BR]] |
880 | 68 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
881 | 1 | Adrian Georgescu | [[BR]]message:[[BR]] |
882 | 68 | Luci Stanescu | A {{{ChatMessage}}} or {{{CPIMMessage}}} instance, depending on whether a CPIM message was received or not. |
883 | 94 | Adrian Georgescu | |
884 | 68 | Luci Stanescu | '''ChatStreamDidDeliverMessage''':: |
885 | 68 | Luci Stanescu | Sent when a successful report is received. |
886 | 68 | Luci Stanescu | [[BR]]timestamp:[[BR]] |
887 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
888 | 68 | Luci Stanescu | [[BR]]message_id:[[BR]] |
889 | 68 | Luci Stanescu | Text identifier of the message. |
890 | 68 | Luci Stanescu | [[BR]]code:[[BR]] |
891 | 68 | Luci Stanescu | The status code received. Will always be 200 for this notification. |
892 | 68 | Luci Stanescu | [[BR]]reason:[[BR]] |
893 | 1 | Adrian Georgescu | The status reason received. |
894 | 1 | Adrian Georgescu | [[BR]]chunk:[[BR]] |
895 | 68 | Luci Stanescu | A {{{msrplib.protocol.MSRPData}}} instance providing all the MSRP information about the report. |
896 | 94 | Adrian Georgescu | |
897 | 68 | Luci Stanescu | '''ChatStreamDidNotDeliverMessage''':: |
898 | 68 | Luci Stanescu | Sent when a failure report is received. |
899 | 68 | Luci Stanescu | [[BR]]timestamp:[[BR]] |
900 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
901 | 68 | Luci Stanescu | [[BR]]message_id:[[BR]] |
902 | 68 | Luci Stanescu | Text identifier of the message. |
903 | 68 | Luci Stanescu | [[BR]]code:[[BR]] |
904 | 68 | Luci Stanescu | The status code received. |
905 | 68 | Luci Stanescu | [[BR]]reason:[[BR]] |
906 | 1 | Adrian Georgescu | The status reason received. |
907 | 1 | Adrian Georgescu | [[BR]]chunk:[[BR]] |
908 | 68 | Luci Stanescu | A {{{msrplib.protocol.MSRPData}}} instance providing all the MSRP information about the report. |
909 | 94 | Adrian Georgescu | |
910 | 68 | Luci Stanescu | '''ChatStreamDidSendMessage''':: |
911 | 68 | Luci Stanescu | Sent when an outgoing message has been sent. |
912 | 68 | Luci Stanescu | [[BR]]timestamp:[[BR]] |
913 | 68 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
914 | 1 | Adrian Georgescu | [[BR]]message:[[BR]] |
915 | 68 | Luci Stanescu | A {{{msrplib.protocol.MSRPData}}} instance providing all the MSRP information about the sent message. |
916 | 94 | Adrian Georgescu | |
917 | 68 | Luci Stanescu | '''ChatStreamGotComposingIndication''':: |
918 | 68 | Luci Stanescu | Sent when a is-composing payload is received. |
919 | 68 | Luci Stanescu | [[BR]]timestamp:[[BR]] |
920 | 68 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
921 | 68 | Luci Stanescu | [[BR]]state:[[BR]] |
922 | 68 | Luci Stanescu | The state of the endpoint, {{{"active"}}} or {{{"idle"}}}. |
923 | 68 | Luci Stanescu | [[BR]]refresh:[[BR]] |
924 | 68 | Luci Stanescu | How often the remote endpoint will send is-composing indications to keep the state from being reverted to {{{"idle"}}}. May be {{{None}}}. |
925 | 68 | Luci Stanescu | [[BR]]last_active:[[BR]] |
926 | 68 | Luci Stanescu | A {{{datatime.datetime}}} object representing the moment when the remote endpoint was last active. May be {{{None}}}. |
927 | 68 | Luci Stanescu | [[BR]]content_type:[[BR]] |
928 | 68 | Luci Stanescu | The MIME type of message being composed. May be {{{None}}}. |
929 | 55 | Adrian Georgescu | [[BR]]sender:[[BR]] |
930 | 70 | Luci Stanescu | The {{{ChatIdentity}}} or {{{CPIMIdentity}}} instance which identifies the sender of the is-composing indication. |
931 | 1 | Adrian Georgescu | |
932 | 70 | Luci Stanescu | === FileSelector === |
933 | 70 | Luci Stanescu | |
934 | 70 | Luci Stanescu | The {{{FileSelector}}} is used to contain information about a file tranfer using the {{{FileTransferStream}}} documented below. |
935 | 70 | Luci Stanescu | |
936 | 70 | Luci Stanescu | ==== methods ==== |
937 | 70 | Luci Stanescu | |
938 | 94 | Adrian Georgescu | |
939 | 70 | Luci Stanescu | '''!__init!__'''(''self'', '''name'''={{{None}}}, '''type'''={{{None}}}, '''size'''={{{None}}}, '''hash'''={{{None}}}, '''fd'''={{{None}}}):: |
940 | 70 | Luci Stanescu | Instantiate a new {{{FileSelector}}}. All the arguments are also available as attributes. |
941 | 70 | Luci Stanescu | [[BR]]name:[[BR]] |
942 | 70 | Luci Stanescu | The filename (should be just the base name). |
943 | 1 | Adrian Georgescu | [[BR]]type:[[BR]] |
944 | 1 | Adrian Georgescu | The type of the file. |
945 | 1 | Adrian Georgescu | [[BR]]size:[[BR]] |
946 | 1 | Adrian Georgescu | The size of the file in bytes. |
947 | 1 | Adrian Georgescu | [[BR]]hash:[[BR]] |
948 | 1 | Adrian Georgescu | 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. |
949 | 1 | Adrian Georgescu | [[BR]]fd:[[BR]] |
950 | 1 | Adrian Georgescu | A file descriptor if the application has already opened the file. |
951 | 94 | Adrian Georgescu | |
952 | 1 | Adrian Georgescu | '''parse'''(''cls'', '''string'''):: |
953 | 1 | Adrian Georgescu | Parses a file selector from the SDP {{{file-selector}}} a attribute and returns a {{{FileSelector}}} instance. |
954 | 94 | Adrian Georgescu | |
955 | 1 | Adrian Georgescu | '''for_file'''(''cls'', '''path''', '''content_type''', '''compute_hash'''={{{True}}}):: |
956 | 1 | Adrian Georgescu | 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. |
957 | 1 | Adrian Georgescu | [[BR]]path:[[BR]] |
958 | 1 | Adrian Georgescu | The full path to the file. |
959 | 1 | Adrian Georgescu | [[BR]]content_type:[[BR]] |
960 | 1 | Adrian Georgescu | An optional MIME type which is to be included in the file-selector. |
961 | 1 | Adrian Georgescu | [[BR]]compute_hash:[[BR]] |
962 | 1 | Adrian Georgescu | Whether or not this method should compute the hash of the file. |
963 | 1 | Adrian Georgescu | |
964 | 1 | Adrian Georgescu | ==== attributes ==== |
965 | 1 | Adrian Georgescu | |
966 | 94 | Adrian Georgescu | |
967 | 1 | Adrian Georgescu | '''sdp_repr''':: |
968 | 1 | Adrian Georgescu | The SDP representation of the file-selector according to the RFC. This should be the value of the {{{file-selector}}} SDP attribute. |
969 | 1 | Adrian Georgescu | |
970 | 1 | Adrian Georgescu | === FileTransferStream === |
971 | 1 | Adrian Georgescu | |
972 | 1 | Adrian Georgescu | Implemented in [browser:sipsimple/streams/msrp.py] |
973 | 1 | Adrian Georgescu | |
974 | 1 | Adrian Georgescu | The {{{FileTransferStream}}} supports file transfer over MSRP according to RFC5547. An example of SDP constructed using this stream follows: |
975 | 1 | Adrian Georgescu | |
976 | 1 | Adrian Georgescu | {{{ |
977 | 1 | Adrian Georgescu | Content-Type: application/sdp |
978 | 1 | Adrian Georgescu | Content-Length: 383 |
979 | 1 | Adrian Georgescu | |
980 | 1 | Adrian Georgescu | v=0 |
981 | 1 | Adrian Georgescu | o=- 3467525166 3467525166 IN IP4 192.168.1.6 |
982 | 1 | Adrian Georgescu | s=blink-0.10.7-beta |
983 | 1 | Adrian Georgescu | c=IN IP4 192.168.1.6 |
984 | 1 | Adrian Georgescu | t=0 0 |
985 | 1 | Adrian Georgescu | m=message 2855 TCP/TLS/MSRP * |
986 | 1 | Adrian Georgescu | a=path:msrps://192.168.1.6:2855/e593357dc9abe90754bd;tcp |
987 | 1 | Adrian Georgescu | a=sendonly |
988 | 1 | Adrian Georgescu | a=accept-types:* |
989 | 1 | Adrian Georgescu | a=accept-wrapped-types:* |
990 | 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 |
991 | 1 | Adrian Georgescu | }}} |
992 | 1 | Adrian Georgescu | |
993 | 1 | Adrian Georgescu | ==== methods ==== |
994 | 1 | Adrian Georgescu | |
995 | 94 | Adrian Georgescu | |
996 | 1 | Adrian Georgescu | '''!__init!__'''(''self'', '''account''', '''file_selector'''={{{None}}}):: |
997 | 1 | Adrian Georgescu | Instantiate a new {{{FileTransferStream}}}. If this is constructed by the application for an outgoing file transfer, the {{{file_selector}}} argument must be present. |
998 | 1 | Adrian Georgescu | [[BR]]account:[[BR]] |
999 | 1 | Adrian Georgescu | The {{{sipsimple.account.Account}}} or {{{sipsimple.account.BonjourAccount}}} instance which will be associated with the stream. |
1000 | 1 | Adrian Georgescu | [[BR]]file_selector:[[BR]] |
1001 | 1 | Adrian Georgescu | The {{{FileSelector}}} instance which represents the file which is to be transferred. |
1002 | 1 | Adrian Georgescu | |
1003 | 1 | Adrian Georgescu | ==== notifications ==== |
1004 | 1 | Adrian Georgescu | |
1005 | 94 | Adrian Georgescu | |
1006 | 1 | Adrian Georgescu | '''FileTransferStreamDidDeliverChunk''':: |
1007 | 1 | Adrian Georgescu | This notification is sent for an outgoing file transfer when a success report is received about part of the file being transferred. |
1008 | 1 | Adrian Georgescu | [[BR]]timestamp:[[BR]] |
1009 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1010 | 1 | Adrian Georgescu | [[BR]]message_id:[[BR]] |
1011 | 1 | Adrian Georgescu | The MSRP message ID of the file transfer session. |
1012 | 1 | Adrian Georgescu | [[BR]]chunk:[[BR]] |
1013 | 1 | Adrian Georgescu | An {{{msrplib.protocol.MSRPData}}} instance represented the received REPORT. |
1014 | 1 | Adrian Georgescu | [[BR]]code:[[BR]] |
1015 | 1 | Adrian Georgescu | The status code received. Will always be 200 for this notification. |
1016 | 1 | Adrian Georgescu | [[BR]]reason:[[BR]] |
1017 | 1 | Adrian Georgescu | The status reason received. |
1018 | 1 | Adrian Georgescu | [[BR]]transferred_bytes:[[BR]] |
1019 | 1 | Adrian Georgescu | The number of bytes which have currently been successfully transferred. |
1020 | 1 | Adrian Georgescu | [[BR]]file_size:[[BR]] |
1021 | 1 | Adrian Georgescu | The size of the file being transferred. |
1022 | 94 | Adrian Georgescu | |
1023 | 1 | Adrian Georgescu | '''FileTransferStreamDidNotDeliverChunk''':: |
1024 | 1 | Adrian Georgescu | [[BR]]timestamp:[[BR]] |
1025 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1026 | 1 | Adrian Georgescu | This notification is sent for an outgoing file transfer when a failure report is received about part of the file being transferred. |
1027 | 1 | Adrian Georgescu | [[BR]]message_id:[[BR]] |
1028 | 1 | Adrian Georgescu | The MSRP message ID of the file transfer session. |
1029 | 1 | Adrian Georgescu | [[BR]]chunk:[[BR]] |
1030 | 1 | Adrian Georgescu | An {{{msrplib.protocol.MSRPData}}} instance represented the received REPORT. |
1031 | 1 | Adrian Georgescu | [[BR]]code:[[BR]] |
1032 | 1 | Adrian Georgescu | The status code received. |
1033 | 1 | Adrian Georgescu | [[BR]]reason:[[BR]] |
1034 | 1 | Adrian Georgescu | The status reason received. |
1035 | 94 | Adrian Georgescu | |
1036 | 1 | Adrian Georgescu | '''FileTransferStreamDidFinish''':: |
1037 | 1 | Adrian Georgescu | This notification is sent when the incoming or outgoing file transfer is finished. |
1038 | 1 | Adrian Georgescu | [[BR]]timestamp:[[BR]] |
1039 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1040 | 94 | Adrian Georgescu | |
1041 | 1 | Adrian Georgescu | '''FileTransferStreamGotChunk''':: |
1042 | 1 | Adrian Georgescu | This notificaiton is sent for an incoming file transfer when a chunk of file data is received. |
1043 | 1 | Adrian Georgescu | [[BR]]timestamp:[[BR]] |
1044 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1045 | 1 | Adrian Georgescu | [[BR]]content:[[BR]] |
1046 | 1 | Adrian Georgescu | The file part which was received, as a {{{str}}}. |
1047 | 1 | Adrian Georgescu | [[BR]]content_type:[[BR]] |
1048 | 1 | Adrian Georgescu | The MIME type of the file which is being transferred. |
1049 | 1 | Adrian Georgescu | [[BR]]transferred_bytes:[[BR]] |
1050 | 1 | Adrian Georgescu | The number of bytes which have currently been successfully transferred. |
1051 | 1 | Adrian Georgescu | [[BR]]file_size:[[BR]] |
1052 | 1 | Adrian Georgescu | The size of the file being transferred. |
1053 | 1 | Adrian Georgescu | |
1054 | 1 | Adrian Georgescu | |
1055 | 1 | Adrian Georgescu | === IDesktopSharingHandler === |
1056 | 1 | Adrian Georgescu | |
1057 | 1 | Adrian Georgescu | 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: |
1058 | 1 | Adrian Georgescu | * InternalVNCViewerHandler |
1059 | 1 | Adrian Georgescu | * InternalVNCServerHandler |
1060 | 1 | Adrian Georgescu | * ExternalVNCViewerHandler |
1061 | 1 | Adrian Georgescu | * ExternalVNCServerHandler |
1062 | 1 | Adrian Georgescu | |
1063 | 1 | Adrian Georgescu | ==== methods ==== |
1064 | 1 | Adrian Georgescu | |
1065 | 94 | Adrian Georgescu | |
1066 | 1 | Adrian Georgescu | '''initialize'''(''self'', '''stream'''):: |
1067 | 1 | Adrian Georgescu | 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. |
1068 | 1 | Adrian Georgescu | |
1069 | 1 | Adrian Georgescu | ==== attributes ==== |
1070 | 1 | Adrian Georgescu | |
1071 | 94 | Adrian Georgescu | |
1072 | 1 | Adrian Georgescu | '''type''':: |
1073 | 1 | Adrian Georgescu | {{{"active"}}} or {{{"passive"}}} depending on whether the handler represents a VNC viewer or server respectively. |
1074 | 1 | Adrian Georgescu | |
1075 | 1 | Adrian Georgescu | ==== notifications ==== |
1076 | 1 | Adrian Georgescu | |
1077 | 94 | Adrian Georgescu | |
1078 | 1 | Adrian Georgescu | '''DesktopSharingHandlerDidFail''':: |
1079 | 1 | Adrian Georgescu | This notification must be sent by the handler when an error occurs to notify the stream that it should fail. |
1080 | 1 | Adrian Georgescu | [[BR]]context:[[BR]] |
1081 | 1 | Adrian Georgescu | A string describing when the handler failed, such as {{{"reading"}}}, {{{"sending"}}} or {{{"connecting"}}}. |
1082 | 1 | Adrian Georgescu | [[BR]]failure:[[BR]] |
1083 | 1 | Adrian Georgescu | A {{{twisted.python.failure.Failure}}} instance describing the exception which led to the failure. |
1084 | 1 | Adrian Georgescu | [[BR]]reason:[[BR]] |
1085 | 1 | Adrian Georgescu | A string describing the failure reason. |
1086 | 1 | Adrian Georgescu | |
1087 | 1 | Adrian Georgescu | === InternalVNCViewerHandler === |
1088 | 1 | Adrian Georgescu | |
1089 | 99 | Luci Stanescu | This is a concrete implementation of the {{{IDesktopSharingHandler}}} interface which can be used for a VNC viewer implemented within the application. |
1090 | 1 | Adrian Georgescu | |
1091 | 1 | Adrian Georgescu | ==== methods ==== |
1092 | 1 | Adrian Georgescu | |
1093 | 94 | Adrian Georgescu | |
1094 | 1 | Adrian Georgescu | '''send'''(''self'', '''data'''):: |
1095 | 1 | Adrian Georgescu | Sends the specified data to the stream in order for it to be transported over MSRP to the remote endpoint. |
1096 | 1 | Adrian Georgescu | [[BR]]data:[[BR]] |
1097 | 1 | Adrian Georgescu | The RFB data to be transported over MSRP, in the form of a {{{str}}}. |
1098 | 1 | Adrian Georgescu | |
1099 | 1 | Adrian Georgescu | ==== notifications ==== |
1100 | 1 | Adrian Georgescu | |
1101 | 94 | Adrian Georgescu | |
1102 | 1 | Adrian Georgescu | '''DesktopSharingStreamGotData''':: |
1103 | 1 | Adrian Georgescu | This notification is sent when data is received over MSRP. |
1104 | 1 | Adrian Georgescu | [[BR]]data:[[BR]] |
1105 | 1 | Adrian Georgescu | The RFB data from the remote endpoint, in the form of a {{{str}}}. |
1106 | 1 | Adrian Georgescu | |
1107 | 1 | Adrian Georgescu | === InternalVNCServerHandler === |
1108 | 1 | Adrian Georgescu | |
1109 | 99 | Luci Stanescu | This is a concrete implementation of the {{{IDesktopSharingHandler}}} interface which can be used for a VNC server implemented within the application. |
1110 | 1 | Adrian Georgescu | |
1111 | 1 | Adrian Georgescu | ==== methods ==== |
1112 | 1 | Adrian Georgescu | |
1113 | 94 | Adrian Georgescu | |
1114 | 1 | Adrian Georgescu | '''send'''(''self'', '''data'''):: |
1115 | 1 | Adrian Georgescu | Sends the specified data to the stream in order for it to be transported over MSRP to the remote endpoint. |
1116 | 1 | Adrian Georgescu | [[BR]]data:[[BR]] |
1117 | 1 | Adrian Georgescu | The RFB data to be transported over MSRP, in the form of a {{{str}}}. |
1118 | 1 | Adrian Georgescu | |
1119 | 1 | Adrian Georgescu | ==== notifications ==== |
1120 | 1 | Adrian Georgescu | |
1121 | 94 | Adrian Georgescu | |
1122 | 1 | Adrian Georgescu | '''DesktopSharingStreamGotData''':: |
1123 | 1 | Adrian Georgescu | This notification is sent when data is received over MSRP. |
1124 | 1 | Adrian Georgescu | [[BR]]data:[[BR]] |
1125 | 1 | Adrian Georgescu | The RFB data from the remote endpoint, in the form of a {{{str}}}. |
1126 | 1 | Adrian Georgescu | |
1127 | 1 | Adrian Georgescu | === ExternalVNCViewerHandler === |
1128 | 1 | Adrian Georgescu | |
1129 | 1 | Adrian Georgescu | This implementation of {{{IDesktopSharingHandler}}} can be used for an external VNC viewer which connects to a VNC server using TCP. |
1130 | 1 | Adrian Georgescu | |
1131 | 1 | Adrian Georgescu | ==== methods ==== |
1132 | 1 | Adrian Georgescu | |
1133 | 94 | Adrian Georgescu | |
1134 | 1 | Adrian Georgescu | '''!__init!__'''(''self'', '''address'''={{{("localhost", 0)}}}, '''connect_timeout'''={{{3}}}):: |
1135 | 1 | Adrian Georgescu | 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. |
1136 | 1 | Adrian Georgescu | [[BR]]address:[[BR]] |
1137 | 1 | Adrian Georgescu | 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. |
1138 | 1 | Adrian Georgescu | |
1139 | 109 | Adrian Georgescu | ==== attributes ==== |
1140 | 1 | Adrian Georgescu | |
1141 | 94 | Adrian Georgescu | |
1142 | 1 | Adrian Georgescu | '''address''':: |
1143 | 1 | Adrian Georgescu | A tuple containing an IP address and a port on which the handler is listening. |
1144 | 1 | Adrian Georgescu | |
1145 | 1 | Adrian Georgescu | === ExternalVNCServerHandler === |
1146 | 1 | Adrian Georgescu | |
1147 | 1 | Adrian Georgescu | This implementation of {{{IDesktopSharingHandler}}} can be used for an external VNC server to which handler will connect using TCP. |
1148 | 1 | Adrian Georgescu | |
1149 | 1 | Adrian Georgescu | ==== methods ==== |
1150 | 1 | Adrian Georgescu | |
1151 | 94 | Adrian Georgescu | |
1152 | 1 | Adrian Georgescu | '''!__init!__'''(''self'', '''address''', '''connect_timeout'''={{{3}}}):: |
1153 | 1 | Adrian Georgescu | 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. |
1154 | 1 | Adrian Georgescu | [[BR]]address:[[BR]] |
1155 | 1 | Adrian Georgescu | 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. |
1156 | 1 | Adrian Georgescu | [[BR]]connect_timeout:[[BR]] |
1157 | 1 | Adrian Georgescu | How long to wait to connect to the VNC server before giving up. |
1158 | 1 | Adrian Georgescu | |
1159 | 1 | Adrian Georgescu | |
1160 | 1 | Adrian Georgescu | === DesktopSharingStream === |
1161 | 1 | Adrian Georgescu | |
1162 | 1 | Adrian Georgescu | Implemented in [browser:sipsimple/streams/msrp.py] |
1163 | 1 | Adrian Georgescu | |
1164 | 1 | Adrian Georgescu | This stream implements desktop sharing using MSRP as a transport protocol for RFB data. |
1165 | 1 | Adrian Georgescu | |
1166 | 1 | Adrian Georgescu | 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: |
1167 | 1 | Adrian Georgescu | |
1168 | 1 | Adrian Georgescu | {{{ |
1169 | 1 | Adrian Georgescu | m=application 2855 TCP/TLS/MSRP * |
1170 | 1 | Adrian Georgescu | a=path:msrps://10.0.1.19:2855/b599b22d1b1d6a3324c8;tcp |
1171 | 1 | Adrian Georgescu | a=accept-types:application/x-rfb |
1172 | 118 | Adrian Georgescu | a=rfbsetup:active |
1173 | 1 | Adrian Georgescu | }}} |
1174 | 1 | Adrian Georgescu | |
1175 | 1 | Adrian Georgescu | |
1176 | 1 | Adrian Georgescu | ==== methods ==== |
1177 | 1 | Adrian Georgescu | |
1178 | 94 | Adrian Georgescu | |
1179 | 1 | Adrian Georgescu | '''!__init!__'''(''self'', '''acount''', '''handler'''):: |
1180 | 1 | Adrian Georgescu | Instantiate a new {{{DesktopSharingStream}}}. |
1181 | 1 | Adrian Georgescu | [[BR]]account:[[BR]] |
1182 | 1 | Adrian Georgescu | The {{{sipsimple.account.Account}}} or {{{sipsimple.account.BonjourAccount}}} instance this stream is associated with. |
1183 | 1 | Adrian Georgescu | [[BR]]handler:[[BR]] |
1184 | 1 | Adrian Georgescu | An object implementing the {{{IDesktopSharingHandler}}} interface which will act as the handler for RFB data. |
1185 | 1 | Adrian Georgescu | |
1186 | 1 | Adrian Georgescu | ==== attributes ==== |
1187 | 1 | Adrian Georgescu | |
1188 | 94 | Adrian Georgescu | |
1189 | 1 | Adrian Georgescu | '''handler''':: |
1190 | 1 | Adrian Georgescu | 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. |
1191 | 94 | Adrian Georgescu | |
1192 | 1 | Adrian Georgescu | '''incoming_queue''':: |
1193 | 1 | Adrian Georgescu | A {{{eventlet.coros.queue}}} instance on which incoming RFB data is written. The handler should wait for data on this queue. |
1194 | 94 | Adrian Georgescu | |
1195 | 1 | Adrian Georgescu | '''outgoing_queue''':: |
1196 | 1 | Adrian Georgescu | A {{{eventlet.coros.queue}}} instance on which outgoing RFB data is written. The handler should write data on this queue. |
1197 | 84 | Adrian Georgescu | |
1198 | 85 | Adrian Georgescu | == Address Resolution == |
1199 | 84 | Adrian Georgescu | |
1200 | 84 | Adrian Georgescu | 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. |
1201 | 84 | Adrian Georgescu | |
1202 | 84 | Adrian Georgescu | === DNS Lookup === |
1203 | 84 | Adrian Georgescu | |
1204 | 84 | Adrian Georgescu | 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. |
1205 | 84 | Adrian Georgescu | |
1206 | 84 | Adrian Georgescu | ==== methods ==== |
1207 | 84 | Adrian Georgescu | |
1208 | 94 | Adrian Georgescu | |
1209 | 84 | Adrian Georgescu | '''!__init!__'''(''self''):: |
1210 | 84 | Adrian Georgescu | Instantiate a new DNSLookup object. |
1211 | 94 | Adrian Georgescu | |
1212 | 84 | Adrian Georgescu | '''lookup_service'''(''self'', '''uri''', '''service''', '''timeout'''={{{3.0}}}, '''lifetime'''={{{15.0}}}):: |
1213 | 84 | Adrian Georgescu | 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. |
1214 | 84 | Adrian Georgescu | [[BR]]uri:[[BR]] |
1215 | 84 | Adrian Georgescu | A {{{(Frozen)SIPURI}}} from which the {{{host}}} attribute is used for the query domain. |
1216 | 84 | Adrian Georgescu | [[BR]]service:[[BR]] |
1217 | 84 | Adrian Georgescu | The service to lookup servers for, {{{"msrprelay"}}} or {{{"stun"}}}. |
1218 | 84 | Adrian Georgescu | [[BR]]timeout:[[BR]] |
1219 | 84 | Adrian Georgescu | How many seconds to wait for a response from a nameserver. |
1220 | 84 | Adrian Georgescu | [[BR]]lifetime:[[BR]] |
1221 | 84 | Adrian Georgescu | How many seconds to wait for a response from all nameservers in total. |
1222 | 94 | Adrian Georgescu | |
1223 | 84 | Adrian Georgescu | '''lookup_sip_proxy'''(''self'', '''uri''', '''supported_transports''', '''timeout'''={{{3.0}}}, '''lifetime'''={{{15.0}}}):: |
1224 | 84 | Adrian Georgescu | 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. |
1225 | 84 | Adrian Georgescu | [[BR]]uri:[[BR]] |
1226 | 84 | Adrian Georgescu | A {{{(Frozen)SIPURI}}} from which the {{{host}}}, {{{port}}}, {{{parameters}}} and {{{secure}}} attributes are used. |
1227 | 84 | Adrian Georgescu | [[BR]]supported_transports:[[BR]] |
1228 | 84 | Adrian Georgescu | A sublist of {{{['udp', 'tcp', 'tls']}}} in the application's order of preference. |
1229 | 84 | Adrian Georgescu | [[BR]]timeout:[[BR]] |
1230 | 84 | Adrian Georgescu | How many seconds to wait for a response from a nameserver. |
1231 | 84 | Adrian Georgescu | [[BR]]lifetime:[[BR]] |
1232 | 84 | Adrian Georgescu | How many seconds to wait for a response from all nameservers in total. |
1233 | 84 | Adrian Georgescu | |
1234 | 120 | Luci Stanescu | '''lookup_xcap_server'''(''self'', '''uri''', '''timeout'''={{{3.0}}}, '''lifetime'''={{{15.0}}}):: |
1235 | 120 | Luci Stanescu | Perform a TXT DNS query on xcap.<uri.host> and return all values of the TXT record which are URIs with a scheme of http or https. Only the {{{uri.host}}} attribute is used. The return value is a list of strings representing HTTP URIs. |
1236 | 120 | Luci Stanescu | [[BR]]uri:[[BR]] |
1237 | 120 | Luci Stanescu | A {{{(Frozen)SIPURI}}} from which the {{{host}}} attribute is used for the query domain. |
1238 | 120 | Luci Stanescu | [[BR]]timeout:[[BR]] |
1239 | 120 | Luci Stanescu | How many seconds to wait for a response from a nameserver. |
1240 | 120 | Luci Stanescu | [[BR]]lifetime:[[BR]] |
1241 | 120 | Luci Stanescu | How many seconds to wait for a response from all nameservers in total. |
1242 | 120 | Luci Stanescu | |
1243 | 120 | Luci Stanescu | |
1244 | 84 | Adrian Georgescu | ==== notifications ==== |
1245 | 84 | Adrian Georgescu | |
1246 | 94 | Adrian Georgescu | |
1247 | 84 | Adrian Georgescu | '''DNSLookupDidSucceed''':: |
1248 | 84 | Adrian Georgescu | This notification is sent when one of the lookup methods succeeds in finding a result. |
1249 | 84 | Adrian Georgescu | [[BR]]timestamp:[[BR]] |
1250 | 84 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1251 | 84 | Adrian Georgescu | [[BR]]result:[[BR]] |
1252 | 84 | Adrian Georgescu | The result of the DNS lookup in the format described in each method. |
1253 | 94 | Adrian Georgescu | |
1254 | 84 | Adrian Georgescu | '''DNSLookupDidFail''':: |
1255 | 84 | Adrian Georgescu | This notification is sent when one of the lookup methods fails in finding a result. |
1256 | 84 | Adrian Georgescu | [[BR]]timestamp:[[BR]] |
1257 | 84 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1258 | 84 | Adrian Georgescu | [[BR]]error:[[BR]] |
1259 | 84 | Adrian Georgescu | A {{{str}}} object describing the error which resulted in the DNS lookup failure. |
1260 | 94 | Adrian Georgescu | |
1261 | 84 | Adrian Georgescu | '''DNSLookupTrace''':: |
1262 | 84 | Adrian Georgescu | This notification is sent several times during a lookup process for each individual DNS query. |
1263 | 84 | Adrian Georgescu | [[BR]]timestamp:[[BR]] |
1264 | 84 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1265 | 84 | Adrian Georgescu | [[BR]]query_type:[[BR]] |
1266 | 84 | Adrian Georgescu | The type of the query, {{{"NAPTR"}}}, {{{"SRV"}}}, {{{"A"}}}, {{{"NS"}}} etc. |
1267 | 84 | Adrian Georgescu | [[BR]]query_name:[[BR]] |
1268 | 84 | Adrian Georgescu | The name which was queried. |
1269 | 84 | Adrian Georgescu | [[BR]]answer:[[BR]] |
1270 | 84 | Adrian Georgescu | The answer returned by dnspython, or {{{None}}} if an error occurred. |
1271 | 84 | Adrian Georgescu | [[BR]]error:[[BR]] |
1272 | 84 | Adrian Georgescu | The exception which caused the query to fail, or {{{None}}} if no error occurred. |
1273 | 84 | Adrian Georgescu | [[BR]]context:[[BR]] |
1274 | 84 | Adrian Georgescu | The name of the method which was called on the {{{DNSLookup}}} object. |
1275 | 84 | Adrian Georgescu | [[BR]]service:[[BR]] |
1276 | 84 | Adrian Georgescu | The service which was queried for, only available when context is {{{"lookup_service"}}}. |
1277 | 84 | Adrian Georgescu | [[BR]]uri:[[BR]] |
1278 | 84 | Adrian Georgescu | The uri which was queried for. |
1279 | 84 | Adrian Georgescu | |
1280 | 84 | Adrian Georgescu | === Route === |
1281 | 84 | Adrian Georgescu | |
1282 | 84 | Adrian Georgescu | 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. |
1283 | 84 | Adrian Georgescu | |
1284 | 84 | Adrian Georgescu | ==== methods ==== |
1285 | 84 | Adrian Georgescu | |
1286 | 94 | Adrian Georgescu | |
1287 | 1 | Adrian Georgescu | '''!__init!__'''(''self'', '''address''', '''port'''=None, '''transport'''={{{'udp'}}}):: |
1288 | 1 | Adrian Georgescu | Creates the Route object with the specified parameters as attributes. |
1289 | 1 | Adrian Georgescu | Each of these attributes can be accessed on the object once instanced. |
1290 | 1 | Adrian Georgescu | [[BR]]''address'':[[BR]] |
1291 | 1 | Adrian Georgescu | The IPv4 address that the request in question should be sent to as a string. |
1292 | 1 | Adrian Georgescu | [[BR]]''port'':[[BR]] |
1293 | 1 | Adrian Georgescu | The port to send the requests to, represented as an int, or None if the default port is to be used. |
1294 | 1 | Adrian Georgescu | [[BR]]''transport'':[[BR]] |
1295 | 1 | Adrian Georgescu | The transport to use, this can be a string of either "udp", "tcp" or "tls" (case insensitive). |
1296 | 94 | Adrian Georgescu | |
1297 | 1 | Adrian Georgescu | '''get_uri'''(''self''):: |
1298 | 1 | Adrian Georgescu | Returns a {{{SIPURI}}} object which contains the adress, port and transport as parameter. This can be used to easily construct a {{{RouteHeader}}}: |
1299 | 1 | Adrian Georgescu | {{{ |
1300 | 1 | Adrian Georgescu | route = Route("1.2.3.4", port=1234, transport="tls") |
1301 | 1 | Adrian Georgescu | route_header = RouteHeader(route.get_uri()) |
1302 | 1 | Adrian Georgescu | }}} |
1303 | 1 | Adrian Georgescu | |
1304 | 1 | Adrian Georgescu | |
1305 | 92 | Adrian Georgescu | == SIP Accounts == |
1306 | 1 | Adrian Georgescu | |
1307 | 1 | Adrian Georgescu | 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. |
1308 | 1 | Adrian Georgescu | |
1309 | 91 | Adrian Georgescu | === AccountManager === |
1310 | 91 | Adrian Georgescu | |
1311 | 91 | Adrian Georgescu | 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. |
1312 | 91 | Adrian Georgescu | |
1313 | 91 | Adrian Georgescu | ==== methods ==== |
1314 | 91 | Adrian Georgescu | |
1315 | 94 | Adrian Georgescu | |
1316 | 91 | Adrian Georgescu | '''!__init!__'''(''self''):: |
1317 | 91 | Adrian Georgescu | 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. |
1318 | 94 | Adrian Georgescu | |
1319 | 91 | Adrian Georgescu | '''start'''(''self''):: |
1320 | 91 | Adrian Georgescu | 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. |
1321 | 94 | Adrian Georgescu | |
1322 | 91 | Adrian Georgescu | '''stop'''(''self''):: |
1323 | 91 | Adrian Georgescu | Calling this method will deactivate all accounts managed by the {{{AccountManager}}}. This method is called automatically by the SIPApplication when it stops. |
1324 | 94 | Adrian Georgescu | |
1325 | 91 | Adrian Georgescu | '''has_account'''(''self'', '''id'''):: |
1326 | 91 | Adrian Georgescu | This method returns {{{True}}} if an account which has the specifed SIP ID (must be a string) exists and {{{False}}} otherwise. |
1327 | 94 | Adrian Georgescu | |
1328 | 91 | Adrian Georgescu | '''get_account'''(''self'', '''id'''):: |
1329 | 91 | Adrian Georgescu | 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. |
1330 | 94 | Adrian Georgescu | |
1331 | 91 | Adrian Georgescu | '''get_accounts'''(''self''):: |
1332 | 91 | Adrian Georgescu | Returns a list containing all the managed accounts. |
1333 | 94 | Adrian Georgescu | |
1334 | 91 | Adrian Georgescu | '''iter_accounts'''(''self''):: |
1335 | 91 | Adrian Georgescu | Returns an iterator through all the managed accounts. |
1336 | 94 | Adrian Georgescu | |
1337 | 91 | Adrian Georgescu | '''find_account'''(''self'', '''contact_uri'''):: |
1338 | 91 | Adrian Georgescu | 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. |
1339 | 91 | Adrian Georgescu | |
1340 | 91 | Adrian Georgescu | ==== notifications ==== |
1341 | 91 | Adrian Georgescu | |
1342 | 94 | Adrian Georgescu | |
1343 | 91 | Adrian Georgescu | '''SIPAccountManagerDidAddAccount''':: |
1344 | 91 | Adrian Georgescu | 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. |
1345 | 91 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
1346 | 91 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1347 | 91 | Adrian Georgescu | [[BR]]''account'':[[BR]] |
1348 | 91 | Adrian Georgescu | The account object which was added. |
1349 | 94 | Adrian Georgescu | |
1350 | 91 | Adrian Georgescu | '''SIPAccountManagerDidRemoveAccount''':: |
1351 | 91 | Adrian Georgescu | This notification is sent when an account is deleted using the {{{delete}}} method. |
1352 | 91 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
1353 | 91 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1354 | 91 | Adrian Georgescu | [[BR]]''account'':[[BR]] |
1355 | 91 | Adrian Georgescu | The account object which was deleted. |
1356 | 94 | Adrian Georgescu | |
1357 | 91 | Adrian Georgescu | '''SIPAccountManagerDidChangeDefaultAccount''':: |
1358 | 91 | Adrian Georgescu | This notification is sent when the default account changes. |
1359 | 91 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
1360 | 91 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1361 | 91 | Adrian Georgescu | [[BR]]''old_account'':[[BR]] |
1362 | 91 | Adrian Georgescu | This is the account object which used to be the default account. |
1363 | 91 | Adrian Georgescu | [[BR]]''account'':[[BR]] |
1364 | 91 | Adrian Georgescu | This is the account object which is the new default account. |
1365 | 91 | Adrian Georgescu | |
1366 | 72 | Luci Stanescu | === Account === |
1367 | 72 | Luci Stanescu | |
1368 | 64 | 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]. |
1369 | 64 | Luci Stanescu | |
1370 | 72 | 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}}}. |
1371 | 64 | Luci Stanescu | |
1372 | 64 | Luci Stanescu | ==== states ==== |
1373 | 64 | Luci Stanescu | |
1374 | 64 | Luci Stanescu | 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: |
1375 | 64 | Luci Stanescu | {{{ |
1376 | 64 | Luci Stanescu | account.enabled = True |
1377 | 64 | Luci Stanescu | account.save() |
1378 | 64 | Luci Stanescu | }}} |
1379 | 64 | Luci Stanescu | |
1380 | 64 | Luci Stanescu | 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. |
1381 | 64 | Luci Stanescu | |
1382 | 64 | Luci Stanescu | 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. |
1383 | 64 | Luci Stanescu | |
1384 | 64 | Luci Stanescu | 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: |
1385 | 64 | Luci Stanescu | |
1386 | 94 | Adrian Georgescu | |
1387 | 64 | Luci Stanescu | '''Account.registration.enabled''':: |
1388 | 64 | Luci Stanescu | This flag controls the automatic registration of the account. The notifications '''SIPAccountRegistrationDidSucceed''', '''SIPAccountRegistrationDidFail''' and '''SIPAccountRegistrationDidEnd''' are used to inform the status of this registration. |
1389 | 94 | Adrian Georgescu | |
1390 | 64 | Luci Stanescu | '''Account.presence.enabled''':: |
1391 | 64 | Luci Stanescu | This flag controls the automatic subscription to buddies for the ''presence'' event and the publication of data in this event. (Not implemented yet) |
1392 | 94 | Adrian Georgescu | |
1393 | 1 | Adrian Georgescu | '''Account.dialog_event.enabled''':: |
1394 | 64 | Luci Stanescu | This flag controls the automatic subscription to buddies for the ''dialog-info'' event and the publication of data in this event. (Not implemented yet) |
1395 | 94 | Adrian Georgescu | |
1396 | 64 | Luci Stanescu | '''Account.message_summary.enabled''':: |
1397 | 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) |
1398 | 64 | Luci Stanescu | |
1399 | 72 | Luci Stanescu | 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]. |
1400 | 64 | Luci Stanescu | |
1401 | 64 | Luci Stanescu | ==== attributes ==== |
1402 | 64 | Luci Stanescu | |
1403 | 64 | Luci Stanescu | The following attributes can be used on an Account object and need to be considered read-only. |
1404 | 64 | Luci Stanescu | |
1405 | 94 | Adrian Georgescu | |
1406 | 64 | Luci Stanescu | '''id''':: |
1407 | 64 | Luci Stanescu | 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}}}. |
1408 | 64 | Luci Stanescu | {{{ |
1409 | 64 | Luci Stanescu | account.id # 'alice@example.com' |
1410 | 64 | Luci Stanescu | account.id.username # 'alice' |
1411 | 64 | Luci Stanescu | account.id.domain # 'example.com' |
1412 | 64 | Luci Stanescu | }}} |
1413 | 94 | Adrian Georgescu | |
1414 | 64 | Luci Stanescu | '''contact''':: |
1415 | 64 | Luci Stanescu | 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). |
1416 | 1 | Adrian Georgescu | {{{ |
1417 | 1 | Adrian Georgescu | account.contact # 'hnfkybrt@10.0.0.1' |
1418 | 64 | Luci Stanescu | account.contact.username # 'hnfkybrt' |
1419 | 1 | Adrian Georgescu | account.contact.domain # '10.0.0.1' |
1420 | 1 | Adrian Georgescu | account.contact['udp'] # <SIPURI "sip:hnfkybrt@10.0.0.1:53024"> |
1421 | 1 | Adrian Georgescu | account.contact['tls'] # <SIPURI "sip:hnfkybrt@10.0.0.1:54478;transport=tls"> |
1422 | 72 | Luci Stanescu | }}} |
1423 | 94 | Adrian Georgescu | |
1424 | 1 | Adrian Georgescu | '''credentials''':: |
1425 | 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. |
1426 | 64 | Luci Stanescu | {{{ |
1427 | 72 | Luci Stanescu | account.credentials # <Credentials for 'alice'> |
1428 | 72 | Luci Stanescu | }}} |
1429 | 94 | Adrian Georgescu | |
1430 | 72 | Luci Stanescu | '''uri''':: |
1431 | 72 | Luci Stanescu | 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. |
1432 | 72 | Luci Stanescu | {{{ |
1433 | 1 | Adrian Georgescu | account.uri # <SIPURI "sip:alice@example.com"> |
1434 | 72 | Luci Stanescu | }}} |
1435 | 1 | Adrian Georgescu | |
1436 | 1 | Adrian Georgescu | ==== notifications ==== |
1437 | 1 | Adrian Georgescu | |
1438 | 94 | Adrian Georgescu | |
1439 | 1 | Adrian Georgescu | '''CFGSettingsObjectDidChange''':: |
1440 | 72 | Luci Stanescu | 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]. |
1441 | 94 | Adrian Georgescu | |
1442 | 125 | Adrian Georgescu | '''SIPAccountWillActivate''':: |
1443 | 125 | Adrian Georgescu | This notification is sent when the {{{Account}}} is about to be activated, but before actually performing any activation task. See {{{SIPAccountDidActivate}}} for more detail. |
1444 | 125 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
1445 | 125 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1446 | 125 | Adrian Georgescu | |
1447 | 72 | Luci Stanescu | '''SIPAccountDidActivate''':: |
1448 | 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. |
1449 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
1450 | 72 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1451 | 94 | Adrian Georgescu | |
1452 | 125 | Adrian Georgescu | '''SIPAccountWillDeactivate''':: |
1453 | 125 | Adrian Georgescu | This notification is sent when the {{{Account}}} is about to be deactivated, but before performing any deactivation task. See {{{SIPAccountDidDeactivate}}} for more detail. |
1454 | 125 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
1455 | 125 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1456 | 125 | Adrian Georgescu | |
1457 | 72 | Luci Stanescu | '''SIPAccountDidDeactivate''':: |
1458 | 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}}}. |
1459 | 72 | Luci Stanescu | [[BR]]''timestamp'':[[BR]] |
1460 | 72 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1461 | 94 | Adrian Georgescu | |
1462 | 117 | Adrian Georgescu | '''SIPAccountWillRegister''':: |
1463 | 72 | Luci Stanescu | This notification is sent when the account is about to register for the first time. |
1464 | 72 | Luci Stanescu | [[BR]]''timestamp'':[[BR]] |
1465 | 72 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1466 | 94 | Adrian Georgescu | |
1467 | 117 | Adrian Georgescu | '''SIPAccountRegistrationWillRefresh''':: |
1468 | 72 | Luci Stanescu | This notification is sent when a registration is about to be refreshed. |
1469 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
1470 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1471 | 94 | Adrian Georgescu | |
1472 | 72 | Luci Stanescu | '''SIPAccountRegistrationDidSucceed''':: |
1473 | 72 | Luci Stanescu | 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: |
1474 | 72 | Luci Stanescu | [[BR]]''timestamp'':[[BR]] |
1475 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1476 | 1 | Adrian Georgescu | [[BR]]''contact_header'':[[BR]] |
1477 | 1 | Adrian Georgescu | The Contact header which was registered. |
1478 | 1 | Adrian Georgescu | [[BR]]''contact_header_list'':[[BR]] |
1479 | 1 | Adrian Georgescu | A list containing all the contacts registered for this SIP account. |
1480 | 1 | Adrian Georgescu | [[BR]]''expires'':[[BR]] |
1481 | 1 | Adrian Georgescu | The amount in seconds in which this registration will expire. |
1482 | 1 | Adrian Georgescu | [[BR]]''registrar'':[[BR]] |
1483 | 1 | Adrian Georgescu | The {{{sipsimple.util.Route}}} object which was used. |
1484 | 94 | Adrian Georgescu | |
1485 | 1 | Adrian Georgescu | '''SIPAccountRegistrationDidFail''':: |
1486 | 1 | Adrian Georgescu | 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: |
1487 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
1488 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1489 | 1 | Adrian Georgescu | [[BR]]''error'':[[BR]] |
1490 | 1 | Adrian Georgescu | The reason for the failure of the REGISTER request. |
1491 | 1 | Adrian Georgescu | [[BR]]''timeout'':[[BR]] |
1492 | 1 | Adrian Georgescu | The amount in seconds as a {{{float}}} after which the registration will be tried again. |
1493 | 94 | Adrian Georgescu | |
1494 | 1 | Adrian Georgescu | '''SIPAccountRegistrationDidEnd''':: |
1495 | 1 | Adrian Georgescu | This notification is sent when a registration is ended (the account is unregistered). The data contained in this notification is: |
1496 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
1497 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1498 | 1 | Adrian Georgescu | [[BR]]''registration'':[[BR]] |
1499 | 1 | Adrian Georgescu | The {{{sipsimple.core.Registration}}} object which ended. |
1500 | 94 | Adrian Georgescu | |
1501 | 1 | Adrian Georgescu | '''SIPAccountRegistrationDidNotEnd''':: |
1502 | 1 | Adrian Georgescu | This notification is sent when a registration fails to end (the account is not unregistered). The data contained in this notification is: |
1503 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
1504 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1505 | 1 | Adrian Georgescu | [[BR]]''code'':[[BR]] |
1506 | 1 | Adrian Georgescu | The SIP status code received. |
1507 | 1 | Adrian Georgescu | [[BR]]''reason'':[[BR]] |
1508 | 1 | Adrian Georgescu | The SIP status reason received. |
1509 | 1 | Adrian Georgescu | [[BR]]''registration'':[[BR]] |
1510 | 1 | Adrian Georgescu | The {{{sipsimple.core.Registration}}} object which ended. |
1511 | 94 | Adrian Georgescu | |
1512 | 1 | Adrian Georgescu | '''SIPAccountRegistrationGotAnswer''':: |
1513 | 1 | Adrian Georgescu | This notification is sent whenever a response is received to a sent REGISTER request for this account. The data contained in this notification is: |
1514 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
1515 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1516 | 1 | Adrian Georgescu | [[BR]]''code'':[[BR]] |
1517 | 1 | Adrian Georgescu | The SIP status code received. |
1518 | 1 | Adrian Georgescu | [[BR]]''reason'':[[BR]] |
1519 | 1 | Adrian Georgescu | The SIP status reason received. |
1520 | 1 | Adrian Georgescu | [[BR]]''registration'':[[BR]] |
1521 | 1 | Adrian Georgescu | The {{{sipsimple.core.Registration}}} object which was used. |
1522 | 1 | Adrian Georgescu | [[BR]]''registrar'':[[BR]] |
1523 | 1 | Adrian Georgescu | The {{{sipsimple.util.Route}}} object which was used. |
1524 | 1 | Adrian Georgescu | |
1525 | 122 | Adrian Georgescu | '''SIPAccountMWIDidGetSummary''':: |
1526 | 121 | Adrian Georgescu | This notification is sent when a NOTIFY is received with a message-summary payload. The data contained in this notification is: |
1527 | 122 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
1528 | 121 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1529 | 122 | Adrian Georgescu | [[BR]]''message_summary'':[[BR]] |
1530 | 121 | Adrian Georgescu | A {{{sipsimple.payloads.messagesummary.MessageSummary}}} object with the parsed payload from the NOTIFY request. |
1531 | 121 | Adrian Georgescu | |
1532 | 1 | Adrian Georgescu | === BonjourAccount === |
1533 | 1 | Adrian Georgescu | |
1534 | 1 | Adrian Georgescu | 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. |
1535 | 1 | Adrian Georgescu | |
1536 | 1 | Adrian Georgescu | ==== states ==== |
1537 | 1 | Adrian Georgescu | |
1538 | 112 | 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 and discover its neighbours sending notifications as this happens. |
1539 | 1 | Adrian Georgescu | |
1540 | 1 | Adrian Georgescu | ==== attributes ==== |
1541 | 1 | Adrian Georgescu | |
1542 | 1 | Adrian Georgescu | The following attributes can be used on a BonjourAccount object and need to be considered read-only. |
1543 | 1 | Adrian Georgescu | |
1544 | 94 | Adrian Georgescu | |
1545 | 1 | Adrian Georgescu | '''id''':: |
1546 | 1 | Adrian Georgescu | 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}}}. |
1547 | 1 | Adrian Georgescu | {{{ |
1548 | 1 | Adrian Georgescu | bonjour_account.id # 'bonjour@local' |
1549 | 1 | Adrian Georgescu | bonjour_account.id.username # 'bonjour' |
1550 | 1 | Adrian Georgescu | bonjour_account.id.domain # 'local' |
1551 | 1 | Adrian Georgescu | }}} |
1552 | 94 | Adrian Georgescu | |
1553 | 1 | Adrian Georgescu | '''contact''':: |
1554 | 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). |
1555 | 1 | Adrian Georgescu | {{{ |
1556 | 1 | Adrian Georgescu | bonjour_account.contact # 'lxzvgack@10.0.0.1' |
1557 | 1 | Adrian Georgescu | bonjour_account.contact.username # 'lxzvgack' |
1558 | 1 | Adrian Georgescu | bonjour_account.contact.domain # '10.0.0.1' |
1559 | 1 | Adrian Georgescu | bonjour_account.contact['udp'] # <SIPURI "sip:lxzvgack@10.0.0.1:53024"> |
1560 | 1 | Adrian Georgescu | bonjour_account.contact['tls'] # <SIPURI "sip:lxzvgack@10.0.0.1:54478;transport=tls"> |
1561 | 1 | Adrian Georgescu | }}} |
1562 | 94 | Adrian Georgescu | |
1563 | 1 | Adrian Georgescu | '''credentials''':: |
1564 | 1 | Adrian Georgescu | 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. |
1565 | 1 | Adrian Georgescu | {{{ |
1566 | 1 | Adrian Georgescu | bonjour_account.credentials # <Credentials for 'alice'> |
1567 | 1 | Adrian Georgescu | }}} |
1568 | 94 | Adrian Georgescu | |
1569 | 1 | Adrian Georgescu | '''uri''':: |
1570 | 111 | Adrian Georgescu | 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 account: |
1571 | 1 | Adrian Georgescu | {{{ |
1572 | 1 | Adrian Georgescu | bonjour_account.uri # <SIPURI "sip:lxzvgack@10.0.0.1"> |
1573 | 1 | Adrian Georgescu | }}} |
1574 | 1 | Adrian Georgescu | |
1575 | 1 | Adrian Georgescu | ==== notifications ==== |
1576 | 1 | Adrian Georgescu | |
1577 | 127 | Adrian Georgescu | '''BonjourAccountDidAddNeighbour''':: |
1578 | 127 | Adrian Georgescu | This notification is sent when a new Bonjour neighbour is discovered. |
1579 | 127 | Adrian Georgescu | [[BR]]''display_name'':[[BR]] |
1580 | 127 | Adrian Georgescu | The name of the neighbour as it is published. |
1581 | 127 | Adrian Georgescu | [[BR]]''host'':[[BR]] |
1582 | 127 | Adrian Georgescu | The hostname of the machine from which the Bonjour neighbour registered its contact address. |
1583 | 127 | Adrian Georgescu | [[BR]]''uri'':[[BR]] |
1584 | 127 | Adrian Georgescu | The contact URI of the Bonjour neighbour, as a {{{FrozenSIPURI}}} object. |
1585 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
1586 | 112 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1587 | 112 | Luci Stanescu | |
1588 | 127 | Adrian Georgescu | '''BonjourAccountDidRemoveNeighbour''':: |
1589 | 127 | Adrian Georgescu | This notification is sent when a Bonjour neighbour unregisters. |
1590 | 127 | Adrian Georgescu | [[BR]]''uri'':[[BR]] |
1591 | 127 | Adrian Georgescu | The contact URI of the Bonjour neighbour, as a {{{FrozenSIPURI}}} object. |
1592 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
1593 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1594 | 1 | Adrian Georgescu | |
1595 | 127 | Adrian Georgescu | '''BonjourAccountDiscoveryDidFail''':: |
1596 | 128 | Adrian Georgescu | This notification is sent when the Bonjour account has failed to perform the discovery process. |
1597 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
1598 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1599 | 1 | Adrian Georgescu | |
1600 | 127 | Adrian Georgescu | '''BonjourAccountDiscoveryFailure''':: |
1601 | 128 | Adrian Georgescu | This notification is sent when the Bonjour account has encountered a problem while browsing the list of neighbours. |
1602 | 124 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
1603 | 124 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1604 | 124 | Adrian Georgescu | |
1605 | 127 | Adrian Georgescu | '''BonjourAccountRegistrationDidEnd''':: |
1606 | 127 | Adrian Georgescu | This notification is sent when the Bonjour account unregisters its contact address using mDNS. |
1607 | 124 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
1608 | 124 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1609 | 124 | Adrian Georgescu | |
1610 | 127 | Adrian Georgescu | '''BonjourAccountRegistrationDidFail''':: |
1611 | 127 | Adrian Georgescu | This notification is sent when the Bonjour account fails to register its contact address using mDNS. |
1612 | 127 | Adrian Georgescu | [[BR]]''code'':[[BR]] |
1613 | 127 | Adrian Georgescu | The Bonjour error code for the failure reason. |
1614 | 127 | Adrian Georgescu | [[BR]]''reason'':[[BR]] |
1615 | 127 | Adrian Georgescu | A human readable error message. |
1616 | 127 | Adrian Georgescu | |
1617 | 127 | Adrian Georgescu | '''BonjourAccountRegistrationDidSucceed''':: |
1618 | 127 | Adrian Georgescu | This notification is sent when the Bonjour account successfully registers its contact address using mDNS. |
1619 | 127 | Adrian Georgescu | [[BR]]''name'':[[BR]] |
1620 | 127 | Adrian Georgescu | The contact address registered. |
1621 | 112 | Luci Stanescu | [[BR]]''timestamp'':[[BR]] |
1622 | 112 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1623 | 112 | Luci Stanescu | |
1624 | 127 | Adrian Georgescu | '''BonjourAccountWillInitateDiscovery''':: |
1625 | 127 | Adrian Georgescu | This notification is sent when the Bonjour account is about to start the discovery process. |
1626 | 112 | Luci Stanescu | [[BR]]''timestamp'':[[BR]] |
1627 | 112 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1628 | 112 | Luci Stanescu | |
1629 | 127 | Adrian Georgescu | '''BonjourAccountWillRegister''':: |
1630 | 127 | Adrian Georgescu | This notification is sent just before the Bonjour account starts the registering process. |
1631 | 112 | Luci Stanescu | [[BR]]''timestamp'':[[BR]] |
1632 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1633 | 127 | Adrian Georgescu | |
1634 | 112 | Luci Stanescu | |
1635 | 112 | Luci Stanescu | '''CFGSettingsObjectDidChange''':: |
1636 | 94 | Adrian Georgescu | 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]. |
1637 | 125 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
1638 | 125 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1639 | 125 | Adrian Georgescu | |
1640 | 125 | Adrian Georgescu | '''SIPAccountWillActivate''':: |
1641 | 125 | Adrian Georgescu | This notification is sent when the {{{BonjourAccount}}} is about to be activated, but before actually performing any activation task. See {{{SIPAccountDidActivate}}} for more detail. |
1642 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
1643 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1644 | 125 | Adrian Georgescu | |
1645 | 125 | Adrian Georgescu | '''SIPAccountDidActivate''':: |
1646 | 125 | Adrian Georgescu | 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. |
1647 | 125 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
1648 | 125 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1649 | 1 | Adrian Georgescu | |
1650 | 1 | Adrian Georgescu | '''SIPAccountWillDeactivate''':: |
1651 | 94 | Adrian Georgescu | This notification is sent when the {{{BonjourAccount}}} is about to be deactivated, but before performing any deactivation task. See {{{SIPAccountDidDeactivate}}} for more detail. |
1652 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
1653 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1654 | 1 | Adrian Georgescu | |
1655 | 1 | Adrian Georgescu | '''SIPAccountDidDeactivate''':: |
1656 | 1 | Adrian Georgescu | 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}}}. |
1657 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
1658 | 87 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1659 | 87 | Adrian Georgescu | |
1660 | 87 | Adrian Georgescu | |
1661 | 87 | Adrian Georgescu | == Audio == |
1662 | 87 | Adrian Georgescu | |
1663 | 87 | Adrian Georgescu | 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: |
1664 | 87 | Adrian Georgescu | * IAudioPort: an interface describing an object capable of producing and/or consuming audio data. |
1665 | 87 | Adrian Georgescu | * AudioDevice: an object conforming to the IAudioPort interface which describes a physical audio device. |
1666 | 87 | Adrian Georgescu | * AudioBridge: a collection of objects conforming to IAudioPort which connects all of them in a full mesh. |
1667 | 87 | Adrian Georgescu | * WavePlayer: an object conforming to the IAudioPort interface which can playback the audio data from a {{{.wav}}} file. |
1668 | 87 | Adrian Georgescu | * WaveRecorder: an object conforming to the IAudioPort interface which can record audio data to a {{{.wav}}} file. |
1669 | 87 | Adrian Georgescu | |
1670 | 87 | Adrian Georgescu | === IAudioPort === |
1671 | 87 | Adrian Georgescu | |
1672 | 87 | Adrian Georgescu | 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. |
1673 | 94 | Adrian Georgescu | |
1674 | 87 | Adrian Georgescu | ==== attributes ==== |
1675 | 87 | Adrian Georgescu | |
1676 | 94 | Adrian Georgescu | |
1677 | 87 | Adrian Georgescu | '''mixer''':: |
1678 | 87 | Adrian Georgescu | 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. |
1679 | 94 | Adrian Georgescu | |
1680 | 87 | Adrian Georgescu | '''consumer_slot''':: |
1681 | 87 | Adrian Georgescu | 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. |
1682 | 87 | Adrian Georgescu | |
1683 | 87 | Adrian Georgescu | '''producer_slot''':: |
1684 | 87 | Adrian Georgescu | 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. |
1685 | 94 | Adrian Georgescu | |
1686 | 87 | Adrian Georgescu | ==== notifications ==== |
1687 | 87 | Adrian Georgescu | |
1688 | 87 | Adrian Georgescu | |
1689 | 87 | Adrian Georgescu | '''AudioPortDidChangeSlots''':: |
1690 | 87 | Adrian Georgescu | 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. |
1691 | 87 | Adrian Georgescu | [[BR]]consumer_slot_changed:[[BR]] |
1692 | 87 | Adrian Georgescu | A bool indicating whether the consumer slot was changed. |
1693 | 87 | Adrian Georgescu | [[BR]]producer_slot_changed:[[BR]] |
1694 | 87 | Adrian Georgescu | A bool indicating whether the producer slot was changed. |
1695 | 87 | Adrian Georgescu | [[BR]]old_consumer_slot:[[BR]] |
1696 | 87 | Adrian Georgescu | The old slot for consuming audio data. Only required if consumer_slot_changed is {{{True}}}. |
1697 | 87 | Adrian Georgescu | [[BR]]new_consumer_slot:[[BR]] |
1698 | 87 | Adrian Georgescu | The new slot for consuming audio data. Only required if consumer_slot_changed is {{{True}}}. |
1699 | 87 | Adrian Georgescu | [[BR]]old_producer_slot:[[BR]] |
1700 | 87 | Adrian Georgescu | The old slot for producing audio data. Only required if producer_slot_changed is {{{True}}}. |
1701 | 87 | Adrian Georgescu | [[BR]]new_producer_slot:[[BR]] |
1702 | 87 | Adrian Georgescu | The new slot for producing audio data. Only required if producer_slot_changed is {{{True}}}. |
1703 | 87 | Adrian Georgescu | |
1704 | 87 | Adrian Georgescu | === AudioDevice === |
1705 | 87 | Adrian Georgescu | |
1706 | 87 | Adrian Georgescu | 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. |
1707 | 94 | Adrian Georgescu | |
1708 | 87 | Adrian Georgescu | ==== methods ==== |
1709 | 87 | Adrian Georgescu | |
1710 | 87 | Adrian Georgescu | |
1711 | 87 | Adrian Georgescu | '''!__init!__'''(''self'', '''mixer''', '''input_muted'''={{{False}}}, '''output_muted'''={{{False}}}): |
1712 | 87 | Adrian Georgescu | Instantiates a new AudioDevice which represents the physical device associated with the specified {{{AudioMixer}}}. |
1713 | 87 | Adrian Georgescu | [[BR]]mixer:[[BR]] |
1714 | 87 | Adrian Georgescu | The {{{AudioMixer}}} whose physical device this object represents. |
1715 | 87 | Adrian Georgescu | [[BR]]input_muted:[[BR]] |
1716 | 87 | Adrian Georgescu | A boolean which indicates whether this object should act as a producer of audio data. |
1717 | 87 | Adrian Georgescu | [[BR]]output_muted:[[BR]] |
1718 | 87 | Adrian Georgescu | A boolean which indicates whether this object should act as a consumer of audio data. |
1719 | 94 | Adrian Georgescu | |
1720 | 87 | Adrian Georgescu | ==== attributes ==== |
1721 | 87 | Adrian Georgescu | |
1722 | 94 | Adrian Georgescu | |
1723 | 87 | Adrian Georgescu | '''input_muted''':: |
1724 | 87 | Adrian Georgescu | 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. |
1725 | 87 | Adrian Georgescu | |
1726 | 87 | Adrian Georgescu | '''output_muted''':: |
1727 | 87 | Adrian Georgescu | 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. |
1728 | 87 | Adrian Georgescu | |
1729 | 87 | Adrian Georgescu | === AudioBridge === |
1730 | 87 | Adrian Georgescu | |
1731 | 87 | Adrian Georgescu | 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}}}. |
1732 | 87 | Adrian Georgescu | > Note: although this is not enforced, there should never be any cycles when connecting {{{AudioBridges}}}. |
1733 | 94 | Adrian Georgescu | |
1734 | 87 | Adrian Georgescu | ==== methods ==== |
1735 | 87 | Adrian Georgescu | |
1736 | 94 | Adrian Georgescu | |
1737 | 87 | Adrian Georgescu | '''!__init!__'''(''self'', '''mixer'''):: |
1738 | 87 | Adrian Georgescu | Instantiate a new {{{AudioBridge}}} which uses the specified {{{AudioMixer}}} for mixing. |
1739 | 94 | Adrian Georgescu | |
1740 | 87 | Adrian Georgescu | '''add'''(''self'', '''port'''):: |
1741 | 87 | Adrian Georgescu | 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. |
1742 | 87 | Adrian Georgescu | |
1743 | 87 | Adrian Georgescu | '''remove'''(''self'', '''port'''):: |
1744 | 87 | Adrian Georgescu | Remove a port from this {{{AudioBridge}}}. The port must have previously been added to the {{{AudioBridge}}}, otherwise a {{{ValueError}}} is raised. |
1745 | 87 | Adrian Georgescu | |
1746 | 87 | Adrian Georgescu | === WavePlayer === |
1747 | 87 | Adrian Georgescu | |
1748 | 87 | Adrian Georgescu | 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. |
1749 | 94 | Adrian Georgescu | |
1750 | 87 | Adrian Georgescu | ==== methods ==== |
1751 | 87 | Adrian Georgescu | |
1752 | 87 | Adrian Georgescu | |
1753 | 87 | Adrian Georgescu | '''!__init!__'''(''self'', '''mixer''', '''filename''', '''volume'''={{{100}}}, '''loop_count'''={{{1}}}, '''pause_time'''={{{0}}}, '''initial_play'''={{{True}}}):: |
1754 | 87 | Adrian Georgescu | 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. |
1755 | 87 | Adrian Georgescu | [[BR]]mixer:[[BR]] |
1756 | 87 | Adrian Georgescu | The {{{AudioMixer}}} this object is connected to. |
1757 | 87 | Adrian Georgescu | [[BR]]filename:[[BR]] |
1758 | 87 | Adrian Georgescu | The full path to the {{{.wav}}} file from which audio data is to be read. |
1759 | 87 | Adrian Georgescu | [[BR]]volume:[[BR]] |
1760 | 87 | Adrian Georgescu | The volume at which the file should be played. |
1761 | 87 | Adrian Georgescu | [[BR]]loop_count:[[BR]] |
1762 | 87 | Adrian Georgescu | The number of times the file should be played, or {{{0}}} for infinity. |
1763 | 87 | Adrian Georgescu | [[BR]]pause_time:[[BR]] |
1764 | 94 | Adrian Georgescu | How many seconds to wait between successive plays of the file. |
1765 | 87 | Adrian Georgescu | [[BR]]initial_play:[[BR]] |
1766 | 87 | Adrian Georgescu | Whether or not the file to play once the {{{WavePlayer}}} is started, or to wait {{{pause_time}}} seconds before the first play. |
1767 | 94 | Adrian Georgescu | |
1768 | 87 | Adrian Georgescu | '''start'''(''self''):: |
1769 | 110 | Adrian Georgescu | Start playing the {{{.wav}}} file. |
1770 | 87 | Adrian Georgescu | |
1771 | 87 | Adrian Georgescu | '''stop'''(''self''):: |
1772 | 87 | Adrian Georgescu | Stop playing the {{{.wav}}} file immediately. |
1773 | 94 | Adrian Georgescu | |
1774 | 87 | Adrian Georgescu | ==== attributes ==== |
1775 | 87 | Adrian Georgescu | |
1776 | 87 | Adrian Georgescu | |
1777 | 87 | Adrian Georgescu | '''is_active''':: |
1778 | 87 | Adrian Georgescu | A boolean indicating whether or not this {{{WavePlayer}}} is currently playing. |
1779 | 94 | Adrian Georgescu | |
1780 | 87 | Adrian Georgescu | ==== notifications ==== |
1781 | 87 | Adrian Georgescu | |
1782 | 87 | Adrian Georgescu | |
1783 | 87 | Adrian Georgescu | '''WavePlayerDidStart''':: |
1784 | 94 | Adrian Georgescu | This notification is sent when the {{{WavePlayer}}} starts playing the file the first time after the {{{start()}}} method has been called. |
1785 | 87 | Adrian Georgescu | [[BR]]timestamp:[[BR]] |
1786 | 87 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1787 | 87 | Adrian Georgescu | |
1788 | 87 | Adrian Georgescu | '''WavePlayerDidEnd''':: |
1789 | 94 | Adrian Georgescu | 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. |
1790 | 87 | Adrian Georgescu | [[BR]]timestamp:[[BR]] |
1791 | 87 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1792 | 87 | Adrian Georgescu | |
1793 | 87 | Adrian Georgescu | '''WavePlayerDidFail''':: |
1794 | 87 | Adrian Georgescu | This notification is sent when the {{{WavePlayer}}} is not capable of playing the {{{.wav}}} file. |
1795 | 87 | Adrian Georgescu | [[BR]]timestamp:[[BR]] |
1796 | 87 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
1797 | 87 | Adrian Georgescu | [[BR]]error:[[BR]] |
1798 | 87 | Adrian Georgescu | The exception raised by the {{{WaveFile}}} which identifies the cause for not being able to play the {{{.wav}}} file. |
1799 | 87 | Adrian Georgescu | |
1800 | 87 | Adrian Georgescu | === WaveRecorder === |
1801 | 87 | Adrian Georgescu | |
1802 | 87 | Adrian Georgescu | 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. |
1803 | 94 | Adrian Georgescu | |
1804 | 87 | Adrian Georgescu | ==== methods ==== |
1805 | 87 | Adrian Georgescu | |
1806 | 87 | Adrian Georgescu | |
1807 | 87 | Adrian Georgescu | '''!__init!__'''(''self'', '''mixer''', '''filename'''):: |
1808 | 87 | Adrian Georgescu | Instantiate a new {{{WaveRecorder}}}. |
1809 | 87 | Adrian Georgescu | [[BR]]mixer:[[BR]] |
1810 | 94 | Adrian Georgescu | The {{{AudioMixer}}} this {{{WaveRecorder}}} is connected to. |
1811 | 87 | Adrian Georgescu | [[BR]]filename:[[BR]] |
1812 | 87 | Adrian Georgescu | 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. |
1813 | 94 | Adrian Georgescu | |
1814 | 87 | Adrian Georgescu | '''start'''(''self''):: |
1815 | 87 | Adrian Georgescu | 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. |
1816 | 87 | Adrian Georgescu | |
1817 | 87 | Adrian Georgescu | '''stop'''(''self''):: |
1818 | 87 | Adrian Georgescu | Stop consuming audio data and close the {{{.wav}}} file. |
1819 | 94 | Adrian Georgescu | |
1820 | 87 | Adrian Georgescu | ==== attributes ==== |
1821 | 87 | Adrian Georgescu | |
1822 | 87 | Adrian Georgescu | |
1823 | 73 | Luci Stanescu | '''is_active''':: |
1824 | 86 | Adrian Georgescu | A boolean indicating whether or not this {{{WaveRecorder}}} is currently recording audio data. |
1825 | 73 | Luci Stanescu | |
1826 | 73 | Luci Stanescu | |
1827 | 73 | Luci Stanescu | == Conference == |
1828 | 73 | Luci Stanescu | |
1829 | 73 | Luci Stanescu | Conference support is implemented in the {{{sipsimple.conference}}} module. Currently, only audio conferencing is supported. |
1830 | 73 | Luci Stanescu | |
1831 | 73 | Luci Stanescu | === AudioConference === |
1832 | 73 | Luci Stanescu | |
1833 | 73 | Luci Stanescu | 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. |
1834 | 94 | Adrian Georgescu | |
1835 | 73 | Luci Stanescu | ==== methods ==== |
1836 | 73 | Luci Stanescu | |
1837 | 94 | Adrian Georgescu | |
1838 | 73 | Luci Stanescu | '''!__init!__'''(''self''):: |
1839 | 73 | Luci Stanescu | Instantiates a new {{{AudioConference}}} which is ready to contain {{{AudioStream}}} objects. |
1840 | 94 | Adrian Georgescu | |
1841 | 73 | Luci Stanescu | '''add'''(''self'', '''stream'''):: |
1842 | 73 | Luci Stanescu | Add the specified {{{AudioStream}}} object to the conference. |
1843 | 94 | Adrian Georgescu | |
1844 | 73 | Luci Stanescu | '''remove'''(''self'', '''stream'''):: |
1845 | 73 | Luci Stanescu | Removes the specified {{{AudioStream}}} object from the conference. Raises a {{{ValueError}}} if the stream is not part of the conference. |
1846 | 94 | Adrian Georgescu | |
1847 | 73 | Luci Stanescu | '''hold'''(''self''):: |
1848 | 73 | Luci Stanescu | 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. |
1849 | 73 | Luci Stanescu | |
1850 | 73 | Luci Stanescu | '''unhold'''(''self''):: |
1851 | 73 | Luci Stanescu | 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. |
1852 | 94 | Adrian Georgescu | |
1853 | 73 | Luci Stanescu | ==== attributes ==== |
1854 | 73 | Luci Stanescu | |
1855 | 94 | Adrian Georgescu | |
1856 | 73 | Luci Stanescu | '''bridge''':: |
1857 | 73 | Luci Stanescu | 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}}}. |
1858 | 94 | Adrian Georgescu | |
1859 | 1 | Adrian Georgescu | '''on_hold''':: |
1860 | 1 | Adrian Georgescu | A boolean indicating whether or not the conference is "on hold". |
1861 | 119 | Luci Stanescu | |
1862 | 119 | Luci Stanescu | '''streams''':: |
1863 | 119 | Luci Stanescu | The list of streams which are part of this conference. The application must not manipulate this list in any way. |
1864 | 119 | Luci Stanescu | |
1865 | 119 | Luci Stanescu | |
1866 | 119 | Luci Stanescu | == XCAP support == |
1867 | 119 | Luci Stanescu | |
1868 | 119 | Luci Stanescu | The {{{sipsimple.xcap}}} module offers a high level API for managing XCAP resources to other parts of the middleware or to the applications built on top of the middleware. The XCAP resources |
1869 | 119 | Luci Stanescu | which can be managed by means of this module are: |
1870 | 119 | Luci Stanescu | * '''contact list''', by means of the {{{resource-lists}}} and {{{rls-services}}} XCAP applications |
1871 | 119 | Luci Stanescu | * '''presence policies''', by means of the {{{org.openmobilealliance.pres-rules}}} or {{{pres-rules}}} XCAP applications |
1872 | 119 | Luci Stanescu | * '''dialoginfo policies''', by means of the {{{org.openxcap.dialog-rules}}} XCAP application |
1873 | 119 | Luci Stanescu | * '''status icon''', by means of the {{{org.openmobilealliance.pres-content}}} XCAP application |
1874 | 119 | Luci Stanescu | * '''offline status''', by means of the {{{pidf-manipulation}}} XCAP application |
1875 | 119 | Luci Stanescu | |
1876 | 119 | Luci Stanescu | The module can work with both OMA or IETF-compliant XCAP servers, preferring the OMA variants of the specification if the server supports them. Not all applications need to be available on the |
1877 | 119 | Luci Stanescu | XCAP server, although it is obvious that only those that are will be managed. The central entity for XCAP resource management is the XCAPManager, whose API relies on a series of objects describing |
1878 | 119 | Luci Stanescu | the resources stored on the XCAP server. |
1879 | 119 | Luci Stanescu | |
1880 | 119 | Luci Stanescu | === Contact === |
1881 | 119 | Luci Stanescu | |
1882 | 119 | Luci Stanescu | Implemented in [browser:sipsimple/xcap/__init__.py] |
1883 | 119 | Luci Stanescu | |
1884 | 119 | Luci Stanescu | A {{{Contact}}} is a URI with additional information stored about it, central to the XCAP contact list management. Information about a contact is stored in the {{{resource-lists}}}, {{{rls-services}}}, |
1885 | 119 | Luci Stanescu | {{{org.openmobilealliance.pres-rules}}} or {{{pres-rules}}}, and {{{org.openxcap.dialog-rules}}} applications. The URI associated with the contact is considered a unique identifier. Information |
1886 | 119 | Luci Stanescu | found in various places about the same URI is aggregated into a single {{{Contact}}} instance. More information about the contact is described within the attributes section. |
1887 | 119 | Luci Stanescu | |
1888 | 119 | Luci Stanescu | ==== attributes ==== |
1889 | 119 | Luci Stanescu | |
1890 | 119 | Luci Stanescu | '''name''':: |
1891 | 119 | Luci Stanescu | A human-readable name which can be associated with the contact. This is stored using the {{{display-name}}} standard {{{resource-lists}}} element. |
1892 | 119 | Luci Stanescu | |
1893 | 119 | Luci Stanescu | '''uri''':: |
1894 | 119 | Luci Stanescu | The uniquely identifying URI. |
1895 | 119 | Luci Stanescu | |
1896 | 119 | Luci Stanescu | '''group''':: |
1897 | 119 | Luci Stanescu | A human-readable group name which can be used to group contacts together. If this is not {{{None}}}, the contact will be reachable from the {{{oma_buddylist}}} list within the {{{resource-lists}}} |
1898 | 119 | Luci Stanescu | document, as defined by OMA. The group of a contact is the first {{{display-name}}} of an ancestor list which contains the contact information. |
1899 | 119 | Luci Stanescu | |
1900 | 119 | Luci Stanescu | '''subscribe_to_presence''':: |
1901 | 119 | Luci Stanescu | A boolean flag which indicates whether a subscription to the {{{presence}}} event is desired. If this is {{{True}}}, the contact's URI is referenced from a {{{rls-services}}} service which defines |
1902 | 119 | Luci Stanescu | {{{presence}}} as one of the packages. Thus, a contact with this flag set is guaranteed to be referenced by an RLS service. |
1903 | 119 | Luci Stanescu | |
1904 | 119 | Luci Stanescu | '''subscribe_to_dialoginfo''':: |
1905 | 119 | Luci Stanescu | A boolean flag which indicates whether a subscription to the {{{dialog}}} event is desired. If this is {{{True}}}, the contact's URI is referenced from a {{{rls-services}}} service which defines |
1906 | 119 | Luci Stanescu | {{{dialog}}} as one of the packages. Thus, a contact with this flag set is guaranteed to be refereneced by an RLS service. |
1907 | 119 | Luci Stanescu | |
1908 | 119 | Luci Stanescu | '''presence_policies''':: |
1909 | 119 | Luci Stanescu | Either {{{None}}} or a list of {{{PresencePolicy}}} objects which represent {{{org.openmobilealliance.pres-rules}}} or {{{pres-rules}}} rules which reference this contact's URI either directly |
1910 | 119 | Luci Stanescu | (through an identity condition) or indirectly through resource lists (using the OMA external-list common policy extension). |
1911 | 119 | Luci Stanescu | |
1912 | 119 | Luci Stanescu | '''dialoginfo_policies''':: |
1913 | 119 | Luci Stanescu | Either {{{None}}} or a list of {{{DialoginfoPolicy}}} objects which represent {{{org.openxcap.dialog-rules}}} rules which reference this contact's URI through an identity condition. |
1914 | 119 | Luci Stanescu | |
1915 | 119 | Luci Stanescu | '''attributes''':: |
1916 | 119 | Luci Stanescu | A dictionary containing additional name, value pairs which the middleware or the application can use to store any information regarding this contact. This is stored through a proprietary AG-Projects |
1917 | 119 | Luci Stanescu | extension to resource-lists. |
1918 | 119 | Luci Stanescu | |
1919 | 119 | Luci Stanescu | ==== methods ==== |
1920 | 119 | Luci Stanescu | |
1921 | 119 | Luci Stanescu | '''!__init!__'''(''self'', '''name''', '''uri''', '''group''', '''**attributes'''):: |
1922 | 119 | Luci Stanescu | Initializes a new {{{Contact}}} instance. The policies are by default set to {{{None}}} and the {{{subscribe_to_presence}}} and {{{subscribe_to_dialoginfo}}} flags to {{{True}}}. |
1923 | 119 | Luci Stanescu | |
1924 | 119 | Luci Stanescu | |
1925 | 119 | Luci Stanescu | === Service === |
1926 | 119 | Luci Stanescu | |
1927 | 119 | Luci Stanescu | Implemented in [browser:sipsimple/xcap/__init__.py] |
1928 | 119 | Luci Stanescu | |
1929 | 119 | Luci Stanescu | A {{{Service}}} represents a URI managed by a Resource List Server (RLS). Subscriptions to this URI will be handled by the RLS. |
1930 | 119 | Luci Stanescu | |
1931 | 119 | Luci Stanescu | ==== attributes ==== |
1932 | 119 | Luci Stanescu | |
1933 | 119 | Luci Stanescu | '''uri''':: |
1934 | 119 | Luci Stanescu | The URI which can be used to access a service provided by the RLS. |
1935 | 119 | Luci Stanescu | |
1936 | 119 | Luci Stanescu | '''packages''':: |
1937 | 119 | Luci Stanescu | A list of strings containing the SIP events which can be subscribed for to the URI. |
1938 | 119 | Luci Stanescu | |
1939 | 119 | Luci Stanescu | '''entries''':: |
1940 | 119 | Luci Stanescu | A list of URIs which represent the expanded list of URIs referenced by the service. A subscription to the service's URI for one of packages will result in the RLS subscribing to these URIs. |
1941 | 119 | Luci Stanescu | |
1942 | 119 | Luci Stanescu | ==== methods ==== |
1943 | 119 | Luci Stanescu | |
1944 | 119 | Luci Stanescu | '''!__init!__'''(''self'', '''uri''', '''packages''', '''entries'''={{{None}}}):: |
1945 | 119 | Luci Stanescu | Initializes a new {{{Service}}} instance. |
1946 | 119 | Luci Stanescu | |
1947 | 119 | Luci Stanescu | |
1948 | 119 | Luci Stanescu | === Policy === |
1949 | 119 | Luci Stanescu | |
1950 | 119 | Luci Stanescu | Implemented in [browser:sipsimple/xcap/__init__.py] |
1951 | 119 | Luci Stanescu | |
1952 | 119 | Luci Stanescu | {{{Policy}}} is the base class for {{{PresencePolicy}}} and {{{DialoginfoPolicy}}}. It describes the attributes common to both. |
1953 | 119 | Luci Stanescu | |
1954 | 119 | Luci Stanescu | ==== attributes ==== |
1955 | 119 | Luci Stanescu | |
1956 | 119 | Luci Stanescu | '''id''':: |
1957 | 119 | Luci Stanescu | A string containing the unique identifier of this specific policy. While it should not be considered human readable, OMA does assign specific meanings to some IDs. |
1958 | 119 | Luci Stanescu | |
1959 | 119 | Luci Stanescu | '''action''':: |
1960 | 119 | Luci Stanescu | A string having one of the values {{{"allow"}}}, {{{"confirm"}}}, {{{"polite-block"}}} or {{{"block"}}}. |
1961 | 119 | Luci Stanescu | |
1962 | 119 | Luci Stanescu | '''validity''':: |
1963 | 119 | Luci Stanescu | Either {{{None}}}, or a list of {{{datetime}}} instance 2-tuples representing the intervals when this policy applies. Example valid validity list which represents two intervals, each of two hours: |
1964 | 119 | Luci Stanescu | {{{ |
1965 | 119 | Luci Stanescu | from datetime import datetime, timedelta |
1966 | 119 | Luci Stanescu | now = datetime.now() |
1967 | 119 | Luci Stanescu | one_hour = timedelta(seconds=3600) |
1968 | 119 | Luci Stanescu | one_day = timedelta(days=1) |
1969 | 119 | Luci Stanescu | validity = [(now-one_hour, now+one_hour), (now+one_day-one_hour, now+one_day+one_hour)] |
1970 | 119 | Luci Stanescu | }}} |
1971 | 119 | Luci Stanescu | |
1972 | 119 | Luci Stanescu | '''sphere''':: |
1973 | 119 | Luci Stanescu | Either {{{None}}} or a string representing the sphere of presentity when this policy applies. |
1974 | 119 | Luci Stanescu | |
1975 | 119 | Luci Stanescu | '''multi_identity_conditions''':: |
1976 | 119 | Luci Stanescu | Either {{{None}}} or a list of {{{CatchAllCondition}}} or {{{DomainCondition}}} objects as defined below. This is used to apply this policy to multiple users. |
1977 | 119 | Luci Stanescu | |
1978 | 119 | Luci Stanescu | ==== methods ==== |
1979 | 119 | Luci Stanescu | |
1980 | 119 | Luci Stanescu | '''!__init!__'''(''self'', '''id''', '''action''', '''name'''={{{None}}}, '''validity'''={{{None}}}, '''sphere'''={{{None}}}, '''multi_identity_conditions'''={{{None}}}):: |
1981 | 119 | Luci Stanescu | Initializes a new {{{Policy}}} instance. |
1982 | 119 | Luci Stanescu | |
1983 | 119 | Luci Stanescu | '''check_validity'''(''self'', '''timestamp''', '''sphere'''={{{Any}}}):: |
1984 | 119 | Luci Stanescu | Returns a boolean indicating whether this policy applies at the specific moment given by timestamp (which must be a {{{datetime}}} instance) in the context of the specific sphere. |
1985 | 119 | Luci Stanescu | |
1986 | 119 | Luci Stanescu | |
1987 | 119 | Luci Stanescu | === CatchAllCondition === |
1988 | 119 | Luci Stanescu | |
1989 | 119 | Luci Stanescu | Implemented in [browser:sipsimple/xcap/__init__.py] |
1990 | 119 | Luci Stanescu | |
1991 | 119 | Luci Stanescu | {{{CatchAllCondition}}} represents a condition which matches any user, but which can have some exceptions. |
1992 | 119 | Luci Stanescu | |
1993 | 119 | Luci Stanescu | ==== attributes ==== |
1994 | 119 | Luci Stanescu | |
1995 | 119 | Luci Stanescu | '''exceptions''':: |
1996 | 119 | Luci Stanescu | A list containing {{{DomainException}}} or {{{UserException}}} objects to define when this condition does not apply. |
1997 | 119 | Luci Stanescu | |
1998 | 119 | Luci Stanescu | ==== methods ==== |
1999 | 119 | Luci Stanescu | |
2000 | 119 | Luci Stanescu | '''!__init!__'''(''self'', '''exceptions'''={{{None}}}):: |
2001 | 119 | Luci Stanescu | Initializes a new {{{CatchAllCondition}}} instance. |
2002 | 119 | Luci Stanescu | |
2003 | 119 | Luci Stanescu | |
2004 | 119 | Luci Stanescu | === DomainCondition === |
2005 | 119 | Luci Stanescu | |
2006 | 119 | Luci Stanescu | Implemented in [browser:sipsimple/xcap/__init__.py] |
2007 | 119 | Luci Stanescu | |
2008 | 119 | Luci Stanescu | {{{DomainCondition}}} represents a condition which matches any user within a specified domain, but which can have some exceptions. |
2009 | 119 | Luci Stanescu | |
2010 | 119 | Luci Stanescu | ==== attributes ==== |
2011 | 119 | Luci Stanescu | |
2012 | 119 | Luci Stanescu | '''domain''':: |
2013 | 119 | Luci Stanescu | A string containing the domain for which this condition applies. |
2014 | 119 | Luci Stanescu | |
2015 | 119 | Luci Stanescu | '''exceptions''':: |
2016 | 119 | Luci Stanescu | A list containing {{{UserEception}}} objects to define when this condition does not apply. |
2017 | 119 | Luci Stanescu | |
2018 | 119 | Luci Stanescu | |
2019 | 119 | Luci Stanescu | ==== methods ==== |
2020 | 119 | Luci Stanescu | |
2021 | 119 | Luci Stanescu | '''!__init!__'''(''self'', '''domain''', '''exceptions'''={{{None}}}):: |
2022 | 119 | Luci Stanescu | Initializes a new {{{DomainCondition}}} instance. |
2023 | 119 | Luci Stanescu | |
2024 | 119 | Luci Stanescu | |
2025 | 119 | Luci Stanescu | === DomainException === |
2026 | 119 | Luci Stanescu | |
2027 | 119 | Luci Stanescu | Implemented in [browser:sipsimple/xcap/__init__.py] |
2028 | 119 | Luci Stanescu | |
2029 | 119 | Luci Stanescu | {{{DomainException}}} is used as an exception for a {{{CatchAllCondition}}} which excludes all users within a specified domain. |
2030 | 119 | Luci Stanescu | |
2031 | 119 | Luci Stanescu | ==== attributes ==== |
2032 | 119 | Luci Stanescu | |
2033 | 119 | Luci Stanescu | '''domain''':: |
2034 | 119 | Luci Stanescu | A string containing the domain which is to be excluded from the {{{CatchAllCondition}}} containing this object as an exception. |
2035 | 119 | Luci Stanescu | |
2036 | 119 | Luci Stanescu | |
2037 | 119 | Luci Stanescu | ==== methods ==== |
2038 | 119 | Luci Stanescu | |
2039 | 119 | Luci Stanescu | '''!__init!__'''(''self'', '''domain'''):: |
2040 | 119 | Luci Stanescu | Initializes a new {{{DomainException}}} instance. |
2041 | 119 | Luci Stanescu | |
2042 | 119 | Luci Stanescu | |
2043 | 119 | Luci Stanescu | === UserException === |
2044 | 119 | Luci Stanescu | |
2045 | 119 | Luci Stanescu | Implemented in [browser:sipsimple/xcap/__init__.py] |
2046 | 119 | Luci Stanescu | |
2047 | 119 | Luci Stanescu | {{{UserException}}} is used as an exception for either a {{{CatchAllCondition}}} or a {{{DomainCondition}}} and excludes a user identified by an URI. |
2048 | 119 | Luci Stanescu | |
2049 | 119 | Luci Stanescu | ==== attributes ==== |
2050 | 119 | Luci Stanescu | |
2051 | 119 | Luci Stanescu | '''uri''':: |
2052 | 119 | Luci Stanescu | A string containing the URI which is to be excluded from the {{{CatchAllCondition}}} or {{{DomainCondition}}} containing this object as an exception. |
2053 | 119 | Luci Stanescu | |
2054 | 119 | Luci Stanescu | |
2055 | 119 | Luci Stanescu | ==== methods ==== |
2056 | 119 | Luci Stanescu | |
2057 | 119 | Luci Stanescu | '''!__init!__'''(''self'', '''uri'''):: |
2058 | 119 | Luci Stanescu | Initializes a new {{{UserException}}} instance. |
2059 | 119 | Luci Stanescu | |
2060 | 119 | Luci Stanescu | |
2061 | 119 | Luci Stanescu | === PresencePolicy === |
2062 | 119 | Luci Stanescu | |
2063 | 119 | Luci Stanescu | Implemented in [browser:sipsimple/xcap/__init__.py] |
2064 | 119 | Luci Stanescu | |
2065 | 119 | Luci Stanescu | A {{{PresencePolicy}}} represents either a {{{org.openmobilealliance.pres-rules}}} or {{{pres-rules}}} rule. It subclasses {{{Policy}}} and inherits its attributes, but defines additional |
2066 | 119 | Luci Stanescu | attributes corresponding to the transformations which can be specified in a rule. |
2067 | 119 | Luci Stanescu | |
2068 | 119 | Luci Stanescu | ==== attributes ==== |
2069 | 119 | Luci Stanescu | |
2070 | 119 | Luci Stanescu | All of the following attributes only make sense for a policy having a {{{"allow"}}} action. |
2071 | 119 | Luci Stanescu | |
2072 | 119 | Luci Stanescu | '''provide_devices''':: |
2073 | 119 | Luci Stanescu | Either {{{sipsimple.util.All}}}, or a list of {{{Class}}}, {{{OccurenceID}}} or {{{DeviceID}}} objects as defined below. |
2074 | 119 | Luci Stanescu | |
2075 | 119 | Luci Stanescu | '''provide_persons''':: |
2076 | 119 | Luci Stanescu | Either {{{sipsimple.util.All}}}, or a list of {{{Class}}} or {{{OccurenceID}}} objects as defined below. |
2077 | 119 | Luci Stanescu | |
2078 | 119 | Luci Stanescu | '''provide_services''':: |
2079 | 119 | Luci Stanescu | Either {{{sipsimple.util.All}}}, or a list of {{{Class}}}, {{{OccurenceID}}}, {{{ServiceURI}}} or {{{ServiceURIScheme}}} objects as defined below. |
2080 | 119 | Luci Stanescu | |
2081 | 119 | Luci Stanescu | '''provide_activities''':: |
2082 | 119 | Luci Stanescu | Either {{{None}}} (if the transformation is not be specified) or a boolean. |
2083 | 119 | Luci Stanescu | |
2084 | 119 | Luci Stanescu | '''provide_class''':: |
2085 | 119 | Luci Stanescu | Either {{{None}}} (if the transformation is not be specified) or a boolean. |
2086 | 119 | Luci Stanescu | |
2087 | 119 | Luci Stanescu | '''provide_device_id''':: |
2088 | 119 | Luci Stanescu | Either {{{None}}} (if the transformation is not be specified) or a boolean. |
2089 | 119 | Luci Stanescu | |
2090 | 119 | Luci Stanescu | '''provide_mood''':: |
2091 | 119 | Luci Stanescu | Either {{{None}}} (if the transformation is not be specified) or a boolean. |
2092 | 119 | Luci Stanescu | |
2093 | 119 | Luci Stanescu | '''provide_place_is''':: |
2094 | 119 | Luci Stanescu | Either {{{None}}} (if the transformation is not be specified) or a boolean. |
2095 | 119 | Luci Stanescu | |
2096 | 119 | Luci Stanescu | '''provide_place_type''':: |
2097 | 119 | Luci Stanescu | Either {{{None}}} (if the transformation is not be specified) or a boolean. |
2098 | 119 | Luci Stanescu | |
2099 | 119 | Luci Stanescu | '''provide_privacy''':: |
2100 | 119 | Luci Stanescu | Either {{{None}}} (if the transformation is not be specified) or a boolean. |
2101 | 119 | Luci Stanescu | |
2102 | 119 | Luci Stanescu | '''provide_relationship''':: |
2103 | 119 | Luci Stanescu | Either {{{None}}} (if the transformation is not be specified) or a boolean. |
2104 | 119 | Luci Stanescu | |
2105 | 119 | Luci Stanescu | '''provide_status_icon''':: |
2106 | 119 | Luci Stanescu | Either {{{None}}} (if the transformation is not be specified) or a boolean. |
2107 | 119 | Luci Stanescu | |
2108 | 119 | Luci Stanescu | '''provide_sphere''':: |
2109 | 119 | Luci Stanescu | Either {{{None}}} (if the transformation is not be specified) or a boolean. |
2110 | 119 | Luci Stanescu | |
2111 | 119 | Luci Stanescu | '''provide_time_offset''':: |
2112 | 119 | Luci Stanescu | Either {{{None}}} (if the transformation is not be specified) or a boolean. |
2113 | 119 | Luci Stanescu | |
2114 | 119 | Luci Stanescu | '''provide_user_input''':: |
2115 | 119 | Luci Stanescu | Either {{{None}}} (if the transformation is not be specified) or one of the strings {{{"false"}}}, {{{"bare"}}}, {{{"thresholds"}}}, {{{"full"}}}. |
2116 | 119 | Luci Stanescu | |
2117 | 119 | Luci Stanescu | '''provide_unknown_attributes''':: |
2118 | 119 | Luci Stanescu | Either {{{None}}} (if the transformation is not be specified) or a boolean. The name of the attribute is not a typo, although it maps to the transformation named {{{provide-unknown-attribute}}} (singular form). |
2119 | 119 | Luci Stanescu | |
2120 | 119 | Luci Stanescu | '''provide_all_attributes''':: |
2121 | 119 | Luci Stanescu | Either {{{None}}} (if the transformation is not be specified) or a boolean. |
2122 | 119 | Luci Stanescu | |
2123 | 119 | Luci Stanescu | ==== methods ==== |
2124 | 119 | Luci Stanescu | |
2125 | 119 | Luci Stanescu | '''!__init!__'''(''self'', '''id''', '''action''', '''name'''={{{None}}}, '''validity'''={{{None}}}, '''sphere'''={{{None}}}, '''multi_identity_conditions'''={{{None}}}):: |
2126 | 119 | Luci Stanescu | Initializes a new {{{PresencePolicy}}} instance. The {{{provide_devices}}}, {{{provide_persons}}} and {{{provide_services}}} are initialized to {{{sipsimple.util.All}}}, {{{provide_all_attributes}}} to {{{True}}} and the rest to {{{None}}}. |
2127 | 119 | Luci Stanescu | |
2128 | 119 | Luci Stanescu | |
2129 | 119 | Luci Stanescu | === DialoginfoPolicy === |
2130 | 119 | Luci Stanescu | |
2131 | 119 | Luci Stanescu | Implemented in [browser:sipsimple/xcap/__init__.py] |
2132 | 119 | Luci Stanescu | |
2133 | 119 | Luci Stanescu | A {{{DialoginfoPolicy}}} represents a {{{org.openxcap.dialog-rules}}} rule. It subclasses {{{Policy}}} and inherits all of its attributes. It does not add any other attributes or methods and thus |
2134 | 119 | Luci Stanescu | has an identical API. |
2135 | 119 | Luci Stanescu | |
2136 | 119 | Luci Stanescu | |
2137 | 119 | Luci Stanescu | === Icon === |
2138 | 119 | Luci Stanescu | |
2139 | 119 | Luci Stanescu | Implemented in [browser:sipsimple/xcap/__init__.py] |
2140 | 119 | Luci Stanescu | |
2141 | 119 | Luci Stanescu | An {{{Icon}}} instance represents a status icon stored using the {{{org.openmobilealliance.pres-content}}} application. |
2142 | 119 | Luci Stanescu | |
2143 | 119 | Luci Stanescu | ==== attributes ==== |
2144 | 119 | Luci Stanescu | |
2145 | 119 | Luci Stanescu | '''data''':: |
2146 | 119 | Luci Stanescu | The binary data of the image, as a string. |
2147 | 119 | Luci Stanescu | |
2148 | 119 | Luci Stanescu | '''mime_type''':: |
2149 | 119 | Luci Stanescu | The MIME type of the image, one of {{{image/jpeg}}}, {{{image/gif}}} or {{{image/png}}}. |
2150 | 119 | Luci Stanescu | |
2151 | 119 | Luci Stanescu | '''description''':: |
2152 | 119 | Luci Stanescu | An optional description of the icon. |
2153 | 119 | Luci Stanescu | |
2154 | 119 | Luci Stanescu | '''location''':: |
2155 | 119 | Luci Stanescu | An HTTP(S) URI which can be used by other users to download the status icon of the local user. If the XCAP server returns the proprietary X-AGP-Alternative-Location header in its GET and PUT |
2156 | 119 | Luci Stanescu | responses, that is used otherwise the XCAP URI of the icon is used. |
2157 | 119 | Luci Stanescu | |
2158 | 119 | Luci Stanescu | ==== methods ==== |
2159 | 119 | Luci Stanescu | |
2160 | 119 | Luci Stanescu | '''!__init!__'''(''self'', '''data''', '''mime_type''', '''description'''={{{None}}}, '''location'''={{{None}}}):: |
2161 | 119 | Luci Stanescu | Initializes a new {{{Icon}}} instance. |
2162 | 119 | Luci Stanescu | |
2163 | 119 | Luci Stanescu | |
2164 | 119 | Luci Stanescu | === OfflineStatus === |
2165 | 119 | Luci Stanescu | |
2166 | 119 | Luci Stanescu | Implemented in [browser:sipsimple/xcap/__init__.py] |
2167 | 119 | Luci Stanescu | |
2168 | 119 | Luci Stanescu | An {{{OfflineStatus}}} instance represents data stored using the {{{pidf-manipulation}}} application. |
2169 | 119 | Luci Stanescu | |
2170 | 119 | Luci Stanescu | ==== attributes ==== |
2171 | 119 | Luci Stanescu | |
2172 | 119 | Luci Stanescu | '''activity''':: |
2173 | 119 | Luci Stanescu | A string representing an activity within a {{{person}}} element. |
2174 | 119 | Luci Stanescu | |
2175 | 119 | Luci Stanescu | '''note''':: |
2176 | 119 | Luci Stanescu | A string stored as a note within a {{{person}}} element. |
2177 | 119 | Luci Stanescu | |
2178 | 119 | Luci Stanescu | ==== methods ==== |
2179 | 119 | Luci Stanescu | |
2180 | 119 | Luci Stanescu | '''!__init!__'''(''self'', '''activity'''={{{None}}}, '''note'''={{{Note}}}):: |
2181 | 119 | Luci Stanescu | Initializes a new {{{OfflineStatus}}} instance. |
2182 | 119 | Luci Stanescu | |
2183 | 119 | Luci Stanescu | |
2184 | 119 | Luci Stanescu | === XCAPManager === |
2185 | 119 | Luci Stanescu | |
2186 | 119 | Luci Stanescu | Implemented in [browser:sipsimple/xcap/__init__.py] |
2187 | 119 | Luci Stanescu | |
2188 | 119 | Luci Stanescu | The XCAPManager is the central entity used to manage resource via the XCAP protocol. It is a {{{Singleton}}} per account and has state machine as described in the following diagram: |
2189 | 119 | Luci Stanescu | |
2190 | 119 | Luci Stanescu | [[Image(xcap-manager-state.png, align=center)]] |
2191 | 119 | Luci Stanescu | |
2192 | 119 | Luci Stanescu | The XCAPManager associated with an account can be obtained by instantiating it with the account passed as an argument. The {{{load}}} method needs to be called just once in order to specify the |
2193 | 119 | Luci Stanescu | directory which is used by manager to store its cache and other internal data. Once this is done, the {{{start}}} and {{{stop}}} methods can be called as needed. Initially in the {{{stopped}}} state, |
2194 | 119 | Luci Stanescu | the start method will result in a transition to the {{{initializing}}} state. While in the {{{initializing}}} state, the XCAP manager will try to connect to the XCAP server and retrieve the |
2195 | 119 | Luci Stanescu | capabilities ({{{xcap-caps}}} application). It will then initiate a SUBSCRIBE for the {{{xcap-diff}}} event (if configured) and transition to the {{{fetching}}} state. In the {{{fetching}}} state, it |
2196 | 119 | Luci Stanescu | will try retrieve all the documents from the XCAP server, also specifying the ETag of the last known version. If none of the documents changed and this is not the first fetch, it transitions to the |
2197 | 119 | Luci Stanescu | {{{insync}}} state. Otherwise, it inserts a {{{normalize}}} operation at the beginning of the journal (described below) and transitions to the {{{updating}}} state. In the {{{updating}}} state, it |
2198 | 119 | Luci Stanescu | applies the operations from the journal which were not applied yet on the currently known documents and tries to push the documents, specifying the Etag of the last known version. If an operation |
2199 | 119 | Luci Stanescu | fails due to a document having been modified, it marks all the operations in the journal as not being applied and transitions to the {{{fetching}}} state; if any other error occurs, the update is |
2200 | 119 | Luci Stanescu | retried periodically. If the update succeeds, data is extracted from the documents and the {{{XCAPManagerDidReloadData}}} notification is sent. The XCAPManager then transitions to the {{{insync}}} |
2201 | 119 | Luci Stanescu | state. A call to the {{{stop}}} method will result in a transition to the {{{stopping}}} state, termination of any existing SUBSCRIBE dialog and a transition to the {{{stopped}}} state. |
2202 | 119 | Luci Stanescu | |
2203 | 119 | Luci Stanescu | Modifications to the settings which control the XCAPManager can result in either a transition to the {{{initializing}}} state or the termination of any previous SUBSCRIBE dialog and creation of a new |
2204 | 126 | Adrian Georgescu | one. |
2205 | 119 | Luci Stanescu | |
2206 | 119 | Luci Stanescu | The subscription to the {{{xcap-diff}}} event allows the XCAPManager to be notified when the documents it manages are modified remotely. If the subscription fails, a fetch of all the documents is |
2207 | 119 | Luci Stanescu | tried and the subscription is retried in some time. This allows the XCAPManager to reload the documents when they are modified remotely even if {{{xcap-diff}}} event is not supported by the provider. If subscription for {{{xcap-diff}}} event fails, a fetch of all the documents will be tried every 2 minutes. |
2208 | 119 | Luci Stanescu | |
2209 | 119 | Luci Stanescu | The XCAPManager keeps the documents as they are stored on the XCAP server along with their ETags in an on-disk cache. All operations are made using the conditional {{{If-Match}}} and |
2210 | 119 | Luci Stanescu | {{{If-None-Match}}} headers such that remote modifications the XCAPManager does not know about are not overwritten and bandwidth and processing power are not wasted by GET operations when a document |
2211 | 119 | Luci Stanescu | is not modified. |
2212 | 119 | Luci Stanescu | |
2213 | 119 | Luci Stanescu | Operations which the XCAPManager can be asked to apply to modify the documents are kept in a journal. This journal is saved to disk, such that operations which cannot be applied when requested due |
2214 | 119 | Luci Stanescu | to server problems or lack of connectivity are retried even after application restarts. In addition, the high-level defined operations and the journal allow the modifications to be applied even if the |
2215 | 119 | Luci Stanescu | document stored on the XCAP server are modified. Put differently, operations do depend on a specific version of the documents and the XCAPManager will try to apply them irrespective of the format |
2216 | 119 | Luci Stanescu | of the document. |
2217 | 119 | Luci Stanescu | |
2218 | 126 | Adrian Georgescu | ==== configuration ==== |
2219 | 119 | Luci Stanescu | |
2220 | 119 | Luci Stanescu | '''Account.id''', '''Account.auth.username''', '''Account.auth.password''':: |
2221 | 119 | Luci Stanescu | These are used both for the {{{xcap-diff}}} subscription and the XCAP server connection. |
2222 | 119 | Luci Stanescu | |
2223 | 119 | Luci Stanescu | '''Account.sip.subscribe_interval''':: |
2224 | 119 | Luci Stanescu | This controls the Expires header used for the subscription, although a 423 response from the server can result in a larger Expires value being used. |
2225 | 119 | Luci Stanescu | |
2226 | 119 | Luci Stanescu | '''Account.xcap.xcap_root''':: |
2227 | 119 | Luci Stanescu | This specifies the XCAP root used for contacting the XCAP server and managing the resources. If this setting is {{{None}}}, a TXT DNS query is made for the {{{xcap}}} subdomain of the SIP account's |
2228 | 119 | Luci Stanescu | domain. The result is interpreted as being an XCAP root. Example record for account alice@example.org: |
2229 | 119 | Luci Stanescu | {{{ |
2230 | 119 | Luci Stanescu | xcap.example.org. IN TXT "https://xcap.example.org/xcap-root" |
2231 | 119 | Luci Stanescu | }}} |
2232 | 119 | Luci Stanescu | |
2233 | 119 | Luci Stanescu | '''SIPSimpleSettings.sip.transport_list''':: |
2234 | 119 | Luci Stanescu | This controls the transports which can be used for the subscription. |
2235 | 119 | Luci Stanescu | |
2236 | 119 | Luci Stanescu | ==== methods ==== |
2237 | 119 | Luci Stanescu | |
2238 | 119 | Luci Stanescu | '''!__init!__'''(''self'', '''account'''):: |
2239 | 119 | Luci Stanescu | Initializes an XCAPManager for the specified account. Since XCAPManager is a {{{Singleton}}}, a single reference will be returned when "instantiating" it multiple times for the same account. |
2240 | 119 | Luci Stanescu | |
2241 | 119 | Luci Stanescu | '''load'''(''self'', '''cache_directory'''):: |
2242 | 119 | Luci Stanescu | Allows the XCAPManager to the load its internal data from cache. The directory passed will be used as the root for xcap data: a subdirectory for each account ID will be created within it. Thus, |
2243 | 119 | Luci Stanescu | the account ID should not be part of the directory passed as an argument. |
2244 | 119 | Luci Stanescu | |
2245 | 119 | Luci Stanescu | '''start'''(''self''):: |
2246 | 119 | Luci Stanescu | Starts the XCAPManager. This will result in the subscription being started, the XCAP server being contacted and any operations in the journal being applied. This method must be called in a green |
2247 | 119 | Luci Stanescu | thread. |
2248 | 119 | Luci Stanescu | |
2249 | 119 | Luci Stanescu | '''stop'''(''self''):: |
2250 | 119 | Luci Stanescu | Stops the XCAPManager from performing any tasks. Waits until the {{{xcap-diff}}} subscription, if any, is terminated. This method must be called in a green thread. |
2251 | 119 | Luci Stanescu | |
2252 | 119 | Luci Stanescu | '''start_transaction'''(''self''):: |
2253 | 119 | Luci Stanescu | This allows multiple operations to be queued and not applied immediately. All operations queued after a call to this method will not be applied until the {{{commit_transaction}}} method is called. |
2254 | 119 | Luci Stanescu | This does not have the same meaning as a relational database transaction, since there is no {{{rollback}}} operation. |
2255 | 119 | Luci Stanescu | |
2256 | 119 | Luci Stanescu | '''commit_transaction'''(''self''):: |
2257 | 119 | Luci Stanescu | Applies the modifications queued after a call to {{{start_transaction}}}. This method needs to be called the exact same number of times the {{{start_transaction}}} method was called. Does not have |
2258 | 119 | Luci Stanescu | any effect if {{{start_transaction}}} was not previously called. |
2259 | 119 | Luci Stanescu | |
2260 | 119 | Luci Stanescu | The following methods results in XCAP operations being queued on the journal: |
2261 | 119 | Luci Stanescu | |
2262 | 119 | Luci Stanescu | '''add_group'''(''self'', '''group'''):: |
2263 | 119 | Luci Stanescu | Add a contact group with the specified name. |
2264 | 119 | Luci Stanescu | |
2265 | 119 | Luci Stanescu | '''rename_group'''(''self'', '''old_name''', '''new_name'''):: |
2266 | 119 | Luci Stanescu | Change the name of the contact group {{{old_name}}} to {{{new_name}}}. If such a contact group does not exist, the operation does not do anything. |
2267 | 119 | Luci Stanescu | |
2268 | 119 | Luci Stanescu | '''remove_group'''(''self'', '''group'''):: |
2269 | 119 | Luci Stanescu | Remove the contact group (and any contacts contained in it) with the specified name. If such a contact group does not exist, the operation does not do anything. |
2270 | 119 | Luci Stanescu | |
2271 | 119 | Luci Stanescu | '''add_contact'''(''self'', '''contact'''):: |
2272 | 119 | Luci Stanescu | Adds a new contact, described by a {{{Contact}}} object. If the contact with the same URI and a not-{{{None}}} group already exists, the operation does not do anything. Otherwise, the contact |
2273 | 119 | Luci Stanescu | is added and any reference to the contact's URI is overwritten. Requests to add a contact to some OMA reserved presence policies ({{{wp_prs_unlisted}}}, {{{wp_prs_allow_unlisted}}}, |
2274 | 119 | Luci Stanescu | {{{wp_prs_block_anonymous}}}, {{{wp_prs_allow_own}}}) is ignored. |
2275 | 119 | Luci Stanescu | |
2276 | 119 | Luci Stanescu | '''update_contact'''(''self'', '''contact''', '''**attributes'''):: |
2277 | 119 | Luci Stanescu | Modifies a contact's properties. The keywords can be any of the {{{Contact}}} attributes, with the same meaning. The URI of the contact to be modified is taken from the first argument. If such |
2278 | 119 | Luci Stanescu | a URI does not exist, it is added. Requests to add a contact to some OMA reserved presence policies ({{{wp_prs_unlisted}}}, {{{wp_prs_allow_unlisted}}}, {{{wp_prs_block_anonymous}}}, |
2279 | 119 | Luci Stanescu | {{{wp_prs_allow_own}}}) is ignored. The URI of a contact can be changed by specified the keyword argument {{{uri}}} with the new value. |
2280 | 119 | Luci Stanescu | |
2281 | 119 | Luci Stanescu | '''remove_contact'''(''self'', '''contact'''):: |
2282 | 119 | Luci Stanescu | Removes any reference to the contact's URI from all documents. This also means that the operation will make sure there are no policies which match the contact's URI. |
2283 | 119 | Luci Stanescu | |
2284 | 119 | Luci Stanescu | '''add_presence_policy'''(''self'', '''policy'''):: |
2285 | 119 | Luci Stanescu | Adds a new presence policy, described by a {{{PresencePolicy}}} object. If the id is specified and a policy with the same id exists, the operation does not do anything. Otherwise, if the id is not |
2286 | 119 | Luci Stanescu | specified, one will be automatically generated (recommended). If the id is specified, but it is incompatible with the description of the policy (for example if an OMA defined id is used and there |
2287 | 119 | Luci Stanescu | are some multi_identity_conditions), a new one will be automatically generated. |
2288 | 119 | Luci Stanescu | |
2289 | 119 | Luci Stanescu | '''update_presence_policy'''(''self'', '''policy''', '''**attributes'''):: |
2290 | 119 | Luci Stanescu | Modifies a presence policy's properties. The keywords can be any of the {{{PresencePolicy}}} attributes, with the same meaning. The id of the policy to be modified is taken from the first argument. |
2291 | 119 | Luci Stanescu | If such a policy does not exist and there is sufficient information about the policy, it is added. If the policy to be modified uses the OMA extension to reference resource-lists and |
2292 | 119 | Luci Stanescu | multi_identity_conditions are specified in the keywords, a new policy whose properties are the combination of the existing policy and the keywords is created. |
2293 | 119 | Luci Stanescu | |
2294 | 119 | Luci Stanescu | '''remove_presence_policy'''(''self'', '''policy'''):: |
2295 | 119 | Luci Stanescu | Removes the presence policy identified by the id attribute of the {{{PresencePolicy}}} object specified. If the id is {{{None}}} or does not exist in the document, the operation does not do |
2296 | 119 | Luci Stanescu | anything. Some standard OMA policies ({{{wp_prs_unlisted}}}, {{{wp_prs_allow_unlisted}}}, {{{wp_prs_block_anonymous}}}, {{{wp_prs_allow_own}}}, {{{wp_prs_grantedcontacts}}}, |
2297 | 119 | Luci Stanescu | {{{wp_prs_blockedcontacts}}}) cannot be removed. |
2298 | 119 | Luci Stanescu | |
2299 | 119 | Luci Stanescu | '''add_dialoginfo_policy'''(''self'', '''policy'''):: |
2300 | 119 | Luci Stanescu | Adds a new dialoginfo policy, described by a {{{DialoginfoPolicy}}} object. If the id is specified and a policy with the same id exists, the operation does not do anything. Otherwise, if the id is |
2301 | 119 | Luci Stanescu | not specified, one will be automatically generated (recommended). |
2302 | 119 | Luci Stanescu | |
2303 | 119 | Luci Stanescu | '''update_dialoginfo_policy'''(''self'', '''policy''', '''**attributes'''):: |
2304 | 119 | Luci Stanescu | Modifies a dialoginfo policy's properties. The keywords can be any of the {{{DialoginfoPolicy}}} attributes, with the same meanining. The id of the policy to be modified is taken from the first |
2305 | 119 | Luci Stanescu | argument. If such a policy does not exist and there is sufficient information about the policy, it is added. |
2306 | 119 | Luci Stanescu | |
2307 | 119 | Luci Stanescu | '''remove_dialoginfo_policy'''(''self'', '''policy'''):: |
2308 | 119 | Luci Stanescu | Removes the dialoginfo policy identified by the id attribute of the {{{DialoginfoPolicy}}} object specified. If the id is {{{None}}} or does not exist in the document, the operation does not do |
2309 | 119 | Luci Stanescu | anything. |
2310 | 119 | Luci Stanescu | |
2311 | 119 | Luci Stanescu | '''set_status_icon'''(''self'', '''icon'''):: |
2312 | 119 | Luci Stanescu | Sets the status icon using the information from the {{{Icon}}} object specified. The {{{location}}} attribute is ignored. The MIME type must be one of {{{image/gif}}}, {{{image/png}}} or |
2313 | 119 | Luci Stanescu | {{{image/jpeg}}}. If the argument is {{{None}}}, the status icon is deleted. |
2314 | 119 | Luci Stanescu | |
2315 | 119 | Luci Stanescu | '''set_offline_status'''(''self'', '''status'''):: |
2316 | 119 | Luci Stanescu | Sets the offline status using the information from the {{{OfflineStatus}}} object specified. If the argument is {{{None}}}, the offline status document is deleted. |
2317 | 119 | Luci Stanescu | |
2318 | 119 | Luci Stanescu | ==== notifications ==== |
2319 | 119 | Luci Stanescu | |
2320 | 119 | Luci Stanescu | '''XCAPManagerWillStart''':: |
2321 | 119 | Luci Stanescu | This notification is sent just after calling the {{{start}}} method. |
2322 | 119 | Luci Stanescu | [[BR]]timestamp:[[BR]] |
2323 | 119 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
2324 | 119 | Luci Stanescu | |
2325 | 119 | Luci Stanescu | '''XCAPManagerDidStart''':: |
2326 | 119 | Luci Stanescu | This notification is sent after the XCAPManager has started doing its tasks (contacting the XCAP server, subscribing to {{{xcap-diff}}} event). This notification does not mean that |
2327 | 119 | Luci Stanescu | any of these operations were successful, as the XCAPManager will retry them continuously should they fail. |
2328 | 119 | Luci Stanescu | [[BR]]timestamp:[[BR]] |
2329 | 119 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
2330 | 119 | Luci Stanescu | |
2331 | 119 | Luci Stanescu | '''XCAPManagerWillEnd''':: |
2332 | 119 | Luci Stanescu | This notification is sent just after calling the {{{stop}}} method. |
2333 | 119 | Luci Stanescu | [[BR]]timestamp:[[BR]] |
2334 | 119 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
2335 | 119 | Luci Stanescu | |
2336 | 119 | Luci Stanescu | '''XCAPManagerDidEnd''':: |
2337 | 119 | Luci Stanescu | This notification is sent when the XCAPManager has stopped performing any tasks. This also means that any active {{{xcap-diff}}} subscription has been terminated. |
2338 | 119 | Luci Stanescu | [[BR]]timestamp:[[BR]] |
2339 | 119 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
2340 | 119 | Luci Stanescu | |
2341 | 119 | Luci Stanescu | '''XCAPManagerDidDiscoverServerCapabilities''':: |
2342 | 119 | Luci Stanescu | This notification is sent when the XCAPManager contacts an XCAP server for the first time or after the connection is reset due to configuration changes. The data of the notification contains |
2343 | 119 | Luci Stanescu | information about the server's capabilities (obtained using the {{{xcap-caps}}} application). |
2344 | 119 | Luci Stanescu | [[BR]]contactlist_supported:[[BR]] |
2345 | 119 | Luci Stanescu | A boolean indicating the support of documents needed for contact management ({{{resource-lists}}} and {{{rls-services}}}). |
2346 | 119 | Luci Stanescu | [[BR]]presence_policies_supported:[[BR]] |
2347 | 119 | Luci Stanescu | A boolean indicating the support of documents needed for presence policy management ({{{org.openmobilealliance.pres-rules}}} or {{{pres-rules}}}). |
2348 | 119 | Luci Stanescu | [[BR]]dialoginfo_policies_supported:[[BR]] |
2349 | 119 | Luci Stanescu | A boolean indicating the support of documents needed for dialoginfo policy management ({{{org.openxcap.dialog-rules}}}). |
2350 | 119 | Luci Stanescu | [[BR]]status_icon_supported:[[BR]] |
2351 | 119 | Luci Stanescu | A boolean indicating the support of documents needed for status icon management ({{{org.openmobilealliance.pres-content}}}). |
2352 | 119 | Luci Stanescu | [[BR]]offline_status_supported:[[BR]] |
2353 | 119 | Luci Stanescu | A boolean indicating the support of documents needed for offline status management ({{{pidf-manipulation}}}). |
2354 | 119 | Luci Stanescu | [[BR]]timestamp:[[BR]] |
2355 | 119 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
2356 | 119 | Luci Stanescu | |
2357 | 119 | Luci Stanescu | '''XCAPManagerDidReloadData''':: |
2358 | 119 | Luci Stanescu | This notification is sent when the XCAPManager synchronizes with the XCAP server. The data of the notification contains objects representing the data as it is stored on the XCAP server. |
2359 | 119 | Luci Stanescu | [[BR]]contacts:[[BR]] |
2360 | 119 | Luci Stanescu | A list of {{{Contact}}} objects. |
2361 | 119 | Luci Stanescu | [[BR]]groups:[[BR]] |
2362 | 119 | Luci Stanescu | A list of strings. |
2363 | 119 | Luci Stanescu | [[BR]]services:[[BR]] |
2364 | 119 | Luci Stanescu | A list of {{{Service}}} objects. |
2365 | 119 | Luci Stanescu | [[BR]]presence_policies:[[BR]] |
2366 | 119 | Luci Stanescu | A list of {{{PresencePolicy}}} objects. |
2367 | 119 | Luci Stanescu | [[BR]]dialoginfo_policies:[[BR]] |
2368 | 119 | Luci Stanescu | A list of {{{DialoginfoPolicy}}} objects. |
2369 | 119 | Luci Stanescu | [[BR]]status_icon:[[BR]] |
2370 | 119 | Luci Stanescu | A {{{StatusIcon}}} object if one is stored, {{{None}}} otherwise. |
2371 | 119 | Luci Stanescu | [[BR]]offline_status:[[BR]] |
2372 | 119 | Luci Stanescu | A {{{OfflineStatus}}} object if offline status information is stored, {{{None}}} otherwise. |
2373 | 119 | Luci Stanescu | [[BR]]timestamp:[[BR]] |
2374 | 119 | Luci Stanescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
2375 | 119 | Luci Stanescu | |
2376 | 119 | Luci Stanescu | '''XCAPManagerDidChangeState''':: |
2377 | 119 | Luci Stanescu | This notification is sent when the XCAPManager transitions from one state to another. |
2378 | 119 | Luci Stanescu | [[BR]]prev_state:[[BR]] |
2379 | 119 | Luci Stanescu | The old state of the XCAPManager, a string. |
2380 | 119 | Luci Stanescu | [[BR]]state:[[BR]] |
2381 | 1 | Adrian Georgescu | The new state of the XCAPManager, a string. |
2382 | 1 | Adrian Georgescu | [[BR]]timestamp:[[BR]] |
2383 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |