SipMiddlewareApi
Version 16 (Adrian Georgescu, 03/23/2009 07:41 pm)
1 | 1 | Adrian Georgescu | = Middleware API = |
---|---|---|---|
2 | 1 | Adrian Georgescu | |
3 | 1 | Adrian Georgescu | [[TOC(WikiStart, Sip*, depth=3)]] |
4 | 11 | Adrian Georgescu | [[Image(sipsimple-middleware.png, align=right, 400px)]] |
5 | 1 | Adrian Georgescu | |
6 | 14 | Adrian Georgescu | This chapter describes the middleware API that can be used by a developer to easily build a user interface for SIP SIMPLE client library. By using this Python API you can easily create a desktop graphical client or a server application for real-time communications based on SIP standards. |
7 | 14 | Adrian Georgescu | |
8 | 16 | Adrian Georgescu | The middleware is event driven and uses a [wiki:SipSettingsAPI configuration API] to access settings for the SIP accounts. |
9 | 1 | Adrian Georgescu | |
10 | 1 | Adrian Georgescu | == Classes == |
11 | 1 | Adrian Georgescu | |
12 | 1 | Adrian Georgescu | === SessionManager === |
13 | 1 | Adrian Georgescu | |
14 | 1 | Adrian Georgescu | The {{{sipsimple.session.SessionManager}}} class is a singleton which acts as the central aggregation point for sessions within the middleware. |
15 | 1 | Adrian Georgescu | The application can use it to query information about the active sessions and set global configuration options relevant to sessions, such as transport options and ringtones. |
16 | 1 | Adrian Georgescu | In order to achieve the latter, the {{{SessionManager}}} instance contains three configuration attributes that can be inspected and modified at runtime. |
17 | 1 | Adrian Georgescu | When a {{{Session}}} is created, either as by the application on an outbound session or by the middleware as an inbound session, these configuration attributes will be copied from the {{{SessionManager}}}. |
18 | 1 | Adrian Georgescu | |
19 | 1 | Adrian Georgescu | > The SessionManager will be integrated with both the configuration framework and the accountmanager, meaning that the part of this API regarding configuration is is subject to change. |
20 | 1 | Adrian Georgescu | |
21 | 1 | Adrian Georgescu | ==== attributes ==== |
22 | 1 | Adrian Georgescu | |
23 | 1 | Adrian Georgescu | '''sessions''':: |
24 | 1 | 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. |
25 | 1 | Adrian Georgescu | '''ringtone_config''':: |
26 | 1 | Adrian Georgescu | A {{{RingtoneConfiguration}}} object, which manages the ringtones that should be played on new inbound and outbound sessions. |
27 | 1 | Adrian Georgescu | '''rtp_config''':: |
28 | 1 | Adrian Georgescu | A {{{RTPConfiguration}}} object, which indicates which options should be used when creating a new RTP transport for use by an audio stream. |
29 | 1 | Adrian Georgescu | '''msrp_config''':: |
30 | 1 | Adrian Georgescu | A {{{MSRPConfiguration}}} object, which provides the options that should be used when creating a new MSRP transport used for chat. |
31 | 1 | Adrian Georgescu | |
32 | 1 | Adrian Georgescu | ==== methods ==== |
33 | 1 | Adrian Georgescu | |
34 | 1 | Adrian Georgescu | '''!__init!__'''(''self''):: |
35 | 1 | Adrian Georgescu | This either returns a new {{{SessionManager}}} object with default configuration objects, or returns a copy of the already existing instance. |
36 | 1 | Adrian Georgescu | |
37 | 1 | Adrian Georgescu | === RingtoneConfiguration === |
38 | 1 | Adrian Georgescu | |
39 | 1 | Adrian Georgescu | A {{{sipsimple.session.RingtoneConfiguration}}} object is contained in the {{{SessionManager}}} and acts as a registration point for both default ringtones and ringtones per incoming SIP URI. |
40 | 1 | Adrian Georgescu | |
41 | 1 | Adrian Georgescu | ==== attributes ==== |
42 | 1 | Adrian Georgescu | |
43 | 1 | Adrian Georgescu | '''default_inbound_ringtone''':: |
44 | 1 | Adrian Georgescu | A string pointing to a {{{.wav}}} file on the filesystem that should be played on an incoming session when the remote SIP URI cannot be matched to any of the registered ones. |
45 | 1 | Adrian Georgescu | If this is set to {{{None}}}, no ringtone is played in this situation. |
46 | 1 | Adrian Georgescu | '''outbound_ringtone''':: |
47 | 1 | Adrian Georgescu | A string pointing to a {{{.wav}}} file on the filesystem that should be played when an outbound session receives a ringing indication from the remote party. |
48 | 1 | Adrian Georgescu | If this is set to {{{None}}}, no ringtone is played in this situation. |
49 | 1 | Adrian Georgescu | |
50 | 1 | Adrian Georgescu | ==== methods ==== |
51 | 1 | Adrian Georgescu | |
52 | 1 | Adrian Georgescu | '''!__init!__'''(''self''):: |
53 | 1 | Adrian Georgescu | Creates a new {{{RingtoneConfiguration}}} object with both attributes set to {{{None}}} and no SIP URIs registered. |
54 | 1 | Adrian Georgescu | '''add_ringtone_for_sipuri'''(''self'', '''sipuri''', '''ringtone'''):: |
55 | 1 | Adrian Georgescu | Registers a ringtone, in the form of a string pointing to a {{{.wav}}} file, to be played back when a incoming session is received from a remote party with the specified SIP URI, in the form of a {{{sipsimple.core.SIPURI}}} object. |
56 | 1 | Adrian Georgescu | This will possibly override a previously registered ringtone. |
57 | 1 | Adrian Georgescu | '''remove_sipuri'''(''self'', '''sipuri'''):: |
58 | 1 | Adrian Georgescu | Removes the ringtone of a previously registered SIP URI. |
59 | 1 | Adrian Georgescu | '''get_ringtone_for_sipuri'''(''self'', '''sipuri'''):: |
60 | 1 | Adrian Georgescu | Retrieve the ringtone to use when receiving an inbound session from the specified SIP URI, as a {{{sipsimple.core.SIPURI}}} object. |
61 | 1 | Adrian Georgescu | If no ringtone was registed, this will return {{{default_inbound_ringtone}}}. |
62 | 1 | Adrian Georgescu | |
63 | 1 | Adrian Georgescu | === RTPConfiguration === |
64 | 1 | Adrian Georgescu | |
65 | 1 | Adrian Georgescu | A {{{sipsimple.session.RTPConfiguration}}} object contains parameters that should be used when creating a new RTP transport, used by a {{{Session}}} object for an audio stream. |
66 | 1 | Adrian Georgescu | |
67 | 1 | Adrian Georgescu | ==== attributes ==== |
68 | 1 | Adrian Georgescu | |
69 | 1 | Adrian Georgescu | '''local_rtp_address''':: |
70 | 1 | Adrian Georgescu | The IP address to use for the RTP endpoint. |
71 | 1 | Adrian Georgescu | '''use_srtp''':: |
72 | 1 | Adrian Georgescu | A boolean indicating whether SRTP should be used. |
73 | 1 | Adrian Georgescu | '''srtp_forced''':: |
74 | 1 | Adrian Georgescu | A boolean indicating whether SRTP should be mandatory, if SRTP is to be used. |
75 | 1 | Adrian Georgescu | '''use_ice''':: |
76 | 1 | Adrian Georgescu | A boolean indicating whether ICE should be used. |
77 | 1 | Adrian Georgescu | '''ice_stun_address''':: |
78 | 1 | Adrian Georgescu | The IP adress of the STUN server that should be contacted to retrieve an ICE candidate. |
79 | 1 | Adrian Georgescu | This attribute is only relevant if ICE is used. |
80 | 1 | Adrian Georgescu | If this is the case and this attribute is set to {{{None}}}, no STUN candidate shall be retrieved for ICE. |
81 | 1 | Adrian Georgescu | '''ice_stun_port'':: |
82 | 1 | Adrian Georgescu | The port of the STUN server to be used for retrieving an ICE candidate. |
83 | 1 | Adrian Georgescu | The same condition apply to this attribute as for {{{ice_stun_address}}}. |
84 | 1 | Adrian Georgescu | |
85 | 1 | Adrian Georgescu | ==== methods ==== |
86 | 1 | Adrian Georgescu | |
87 | 1 | Adrian Georgescu | '''!__init!__'''(''self'', '''local_rtp_address'''=<default_host_ip>, '''use_srtp'''={{{False}}}, '''srtp_forced'''={{{False}}}, '''use_ice'''={{{False}}}, '''ice_stun_address'''={{{None}}}, '''ice_stun_port'''=3478):: |
88 | 1 | Adrian Georgescu | This creates a new {{{RTPConfiguration}}} object with sensible defaults, setting all the attributes to the specified values. |
89 | 1 | Adrian Georgescu | The default value for the {{{local_rtp_address}}} attribute is the default outbound IP of this host, detected at application start. |
90 | 1 | Adrian Georgescu | |
91 | 1 | Adrian Georgescu | === MSRPConfiguration === |
92 | 1 | Adrian Georgescu | |
93 | 1 | Adrian Georgescu | A {{{sipsimple.session.MSRPConfiguration}}} object governs the parameters used for creating an MSRP connection when establishing a chat within a session. |
94 | 1 | Adrian Georgescu | |
95 | 1 | Adrian Georgescu | ==== attributes ==== |
96 | 1 | Adrian Georgescu | |
97 | 1 | Adrian Georgescu | '''local_ip''':: |
98 | 1 | Adrian Georgescu | The local IP address to put in the MSRP URI. |
99 | 1 | Adrian Georgescu | If this is set to None, an IP will be automatically detected. |
100 | 1 | Adrian Georgescu | '''local_port''':: |
101 | 1 | Adrian Georgescu | The local port to use for MSRP. |
102 | 1 | Adrian Georgescu | If this is set to None, an a port will be automatically allocated. |
103 | 1 | Adrian Georgescu | '''local_use_tls''':: |
104 | 1 | Adrian Georgescu | A boolean indicating whether to use TLS in the local MSRP URI. |
105 | 1 | Adrian Georgescu | '''use_relay_incoming''':: |
106 | 1 | Adrian Georgescu | A boolean indicating whether to use a MSRP relay for incoming sessions. |
107 | 1 | Adrian Georgescu | '''use_relay_outgoing''':: |
108 | 1 | Adrian Georgescu | A boolean indicating whether to use a MSRP relay for outgoing sessions. |
109 | 1 | Adrian Georgescu | '''relay_host''':: |
110 | 1 | Adrian Georgescu | The IP address of the MSRP relay to use, set by the above conditions. |
111 | 1 | Adrian Georgescu | '''relay_port''':: |
112 | 1 | Adrian Georgescu | The TCP port to use on the MSRP relay. |
113 | 1 | Adrian Georgescu | '''relay_use_tls''':: |
114 | 1 | Adrian Georgescu | A boolean indicating whether the connection to the MSRP relay specified should use TLS. |
115 | 1 | Adrian Georgescu | |
116 | 1 | Adrian Georgescu | ==== methods ==== |
117 | 1 | Adrian Georgescu | |
118 | 1 | Adrian Georgescu | '''!__init!__'''(''self'', '''local_ip'''={{{None}}}, '''local_port'''={{{None}}}, '''local_use_tls'''={{{True}}}, '''use_relay_incoming'''={{{True}}}, '''use_relay_outgoing'''={{{False}}}, '''relay_host'''={{{None}}}, '''relay_port'''={{{None}}}, '''relay_use_tls'''={{{None}}}):: |
119 | 1 | Adrian Georgescu | This creates a new {{{MSRPConfiguration}}} object with sensible defaults, setting all the attributes to the specified values. |
120 | 1 | Adrian Georgescu | |
121 | 1 | Adrian Georgescu | === Session === |
122 | 1 | Adrian Georgescu | |
123 | 1 | Adrian Georgescu | A {{{sipsimple.session.Session}}} object represents a complete SIP session between the local and a remote endpoints, including media streams. |
124 | 1 | Adrian Georgescu | The currently supported media streams are audio and MSRP chat. |
125 | 1 | Adrian Georgescu | Both incoming and outgoing sessions are represented by this class. |
126 | 1 | Adrian Georgescu | |
127 | 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. |
128 | 1 | Adrian Georgescu | State changes are triggered by methods called on the object by the application or by received network events. |
129 | 1 | Adrian Georgescu | Every time this attribute changes, a {{{SCSessionChangedState}}} notification is sent by the object. |
130 | 1 | Adrian Georgescu | These states and their transitions are represented in the following diagram: |
131 | 1 | Adrian Georgescu | |
132 | 2 | Adrian Georgescu | [[Image(sipsimple-session-state-machine.png)]] |
133 | 1 | Adrian Georgescu | |
134 | 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 different set of notifications is also emitted, which provide all the necessary information to the application. |
135 | 1 | Adrian Georgescu | |
136 | 1 | Adrian Georgescu | ==== attributes ==== |
137 | 1 | Adrian Georgescu | |
138 | 1 | Adrian Georgescu | '''state''':: |
139 | 1 | Adrian Georgescu | The state the object is currently in, being one of the states from the diagram above. |
140 | 1 | Adrian Georgescu | '''direction''':: |
141 | 1 | Adrian Georgescu | A string indicating the direction of the initial negotiation of the session. |
142 | 1 | Adrian Georgescu | This can be either {{{None}}}, "incoming" or "outgoing". |
143 | 1 | Adrian Georgescu | '''start_time''':: |
144 | 1 | Adrian Georgescu | The time the session started as a {{{datetime.datetime}}} object, or {{{None}}} if the session was not yet started. |
145 | 1 | Adrian Georgescu | '''stop_time''':: |
146 | 1 | Adrian Georgescu | The time the session stopped as a {{{datetime.datetime}}} object, or {{{None}}} if the session has not yet terminated. |
147 | 1 | Adrian Georgescu | '''on_hold_by_local''':: |
148 | 1 | Adrian Georgescu | Boolean indicating whether the session was put on hold by the local party. |
149 | 1 | Adrian Georgescu | '''on_hold_by_remote''':: |
150 | 1 | Adrian Georgescu | Boolean indicating whether the session was put on hold by the remote party. |
151 | 1 | Adrian Georgescu | '''on_hold''':: |
152 | 1 | Adrian Georgescu | Boolean indicating whether the session was put on hold, either by the local or the remote party. |
153 | 1 | Adrian Georgescu | '''remote_user_agent''':: |
154 | 1 | Adrian Georgescu | A string indicating the remote user agent, if it provided one. |
155 | 1 | Adrian Georgescu | Initially this will be {{{None}}}, it will be set as soon as this information is received from the remote party (which may be never). |
156 | 1 | Adrian Georgescu | '''local_uri''':: |
157 | 1 | Adrian Georgescu | The {{{sipsimple.core.SIPURI}}} of the local party, if the session is active. |
158 | 1 | Adrian Georgescu | '''remote_uri''':: |
159 | 1 | Adrian Georgescu | The {{{sipsimple.core.SIPURI}}} of the remote party, if the session is active. |
160 | 1 | Adrian Georgescu | '''caller_uri''':: |
161 | 1 | Adrian Georgescu | The {{{sipsimple.core.SIPURI}}} of the calling party, if the session is active. |
162 | 1 | Adrian Georgescu | Depending on the direction, this is either {{{local_uri}}} or {{{remote_uri}}}. |
163 | 1 | Adrian Georgescu | '''callee_uri''':: |
164 | 1 | Adrian Georgescu | The {{{sipsimple.core.SIPURI}}} of the called party, if the session is active. |
165 | 1 | Adrian Georgescu | Depending on the direction, this is either {{{local_uri}}} or {{{remote_uri}}}. |
166 | 1 | Adrian Georgescu | '''credentials''':: |
167 | 1 | Adrian Georgescu | A copy of the {{{sipsimple.core.Credentials}}} object passed when the {{{new()}}} method was called. |
168 | 1 | Adrian Georgescu | On incoming or inactive sessions this is {{{None}}}. |
169 | 1 | Adrian Georgescu | '''route''':: |
170 | 1 | Adrian Georgescu | A copy of the {{{sipsimple.core.Route}}} object passed when the {{{new()}}} method was called. |
171 | 1 | Adrian Georgescu | On incoming or inactive sessions this is {{{None}}}. |
172 | 1 | Adrian Georgescu | '''audio_transport''':: |
173 | 1 | Adrian Georgescu | The {{{sipsimple.core.AudioTransport}}} object used by the session, if it currently contains an audio stream. |
174 | 1 | Adrian Georgescu | Normally the application will not need to access this directly. |
175 | 1 | Adrian Georgescu | '''has_audio''':: |
176 | 1 | Adrian Georgescu | A boolean property indicating if this {{{Session}}} currently has an audio stream. |
177 | 1 | Adrian Georgescu | '''audio_sample_rate''':: |
178 | 1 | Adrian Georgescu | If the audio stream was started, this attribute contains the sample rate of the audio negotiated. |
179 | 1 | Adrian Georgescu | '''audio_codec''':: |
180 | 1 | Adrian Georgescu | If the audio stream was started, this attribute contains the name of the audio codec that was negotiated. |
181 | 1 | Adrian Georgescu | '''audio_srtp_active''':: |
182 | 1 | Adrian Georgescu | If the audio stream was started, this boolean attribute indicates if SRTP is currently being used on the stream. |
183 | 1 | Adrian Georgescu | '''audio_local_rtp_address''':: |
184 | 1 | Adrian Georgescu | If an audio stream is present within the session, this attribute contains the local IP address used for the audio stream. |
185 | 1 | Adrian Georgescu | '''audio_local_rtp_port''':: |
186 | 1 | Adrian Georgescu | If an audio stream is present within the session, this attribute contains the local UDP port used for the audio stream. |
187 | 1 | Adrian Georgescu | '''audio_remote_rtp_address_sdp''':: |
188 | 1 | Adrian Georgescu | If the audio stream was started, this attribute contains the IP address that the remote party gave to send audio to. |
189 | 1 | Adrian Georgescu | '''audio_remote_rtp_port_sdp''':: |
190 | 1 | Adrian Georgescu | If the audio stream was started, this attribute contains the UDP port that the remote party gave to send audio to. |
191 | 1 | Adrian Georgescu | '''audio_remote_rtp_address_received''':: |
192 | 1 | Adrian Georgescu | If the audio stream was started, this attribute contains the remote IP address from which the audio stream is being received. |
193 | 1 | Adrian Georgescu | '''audio_remote_rtp_port_received''':: |
194 | 1 | Adrian Georgescu | If the audio stream was started, this attribute contains the remote UDP port from which the audio stream is being received. |
195 | 1 | Adrian Georgescu | '''audio_was_received''':: |
196 | 1 | Adrian Georgescu | This boolean property indicates if audio was actually received on the audio stream contained within this session. |
197 | 1 | Adrian Georgescu | '''audio_recording_file_name''':: |
198 | 1 | Adrian Georgescu | If the audio stream is currently being recorded to disk, this property contains the name of the {{{.wav}}} file being recorded to. |
199 | 1 | Adrian Georgescu | '''chat_transport''':: |
200 | 1 | Adrian Georgescu | The {{{sipsimple.msrp.MSRPChat}}} object used by the session as chat transport, if the session currently contains a chat stream. |
201 | 1 | Adrian Georgescu | Normally the application will not need to access this directly. |
202 | 1 | Adrian Georgescu | '''has_chat''':: |
203 | 1 | Adrian Georgescu | A boolean property indicating if this {{{Session}}} currently has a chat stream. |
204 | 1 | Adrian Georgescu | |
205 | 1 | Adrian Georgescu | ==== methods ==== |
206 | 1 | Adrian Georgescu | |
207 | 1 | Adrian Georgescu | '''!__init!__'''(''self''):: |
208 | 1 | Adrian Georgescu | Creates a new {{{Session}}} object in the {{{NULL}}} state. |
209 | 15 | Oliver Bril | '''connect'''(''self'', '''callee_uri''', '''credentials''', '''route''', '''audio'''={{{False}}}, '''chat'''={{{False}}}):: |
210 | 1 | Adrian Georgescu | Will set up the {{{Session}}} as outbound and propose the new session to the specified remote party and move the state machine to the {{{CALLING}}} state. |
211 | 1 | Adrian Georgescu | Before contacting the remote party, a {{{SCSessionNewOutgoing}}} notification will be emitted. |
212 | 1 | Adrian Georgescu | If there is a failure or the remote party rejected the offer, a {{{SCSessionDidFail}}} notification will be sent, followed by a {{{SCSessionDidEnd}}}. |
213 | 1 | Adrian Georgescu | Any time a ringing indication is received from the remote party, a {{{SCSessionGotRingIndication}}} notification is sent. |
214 | 1 | Adrian Georgescu | If the remote party accepted the session, a {{{SCSessionWillStart}}} notification will be sent, followed by a {{{SCSessionDidStart}}} notification when the session is actually established. |
215 | 1 | Adrian Georgescu | This method may only be called while in the {{{NULL}}} state. |
216 | 1 | Adrian Georgescu | [[BR]]''callee_uri'':[[BR]] |
217 | 1 | Adrian Georgescu | A {{{sipsimple.core.SIPURI}}} object representing the remote host to initiate the session to. |
218 | 1 | Adrian Georgescu | [[BR]]''credentials'':[[BR]] |
219 | 1 | Adrian Georgescu | A {{{sipsimple.core.Credentials}}} object, encapsulating the local SIP URI and the password for it, if set. |
220 | 1 | Adrian Georgescu | [[BR]]''route'':[[BR]] |
221 | 1 | Adrian Georgescu | A {{{sipsimple.core.Route}}} object, specifying the IP, port and transport to the outbound proxy. |
222 | 1 | Adrian Georgescu | [[BR]]''audio'':[[BR]] |
223 | 1 | Adrian Georgescu | A boolean indicating whether an audio stream should be initially included in this session. |
224 | 1 | Adrian Georgescu | [[BR]]''chat'':[[BR]] |
225 | 1 | Adrian Georgescu | A boolean indicating whether a chat stream should be initially included in this session. |
226 | 1 | Adrian Georgescu | '''accept'''(''self'', '''audio'''={{{False}}}, '''chat'''={{{False}}}, '''password'''={{{None}}}):: |
227 | 1 | Adrian Georgescu | Calling this methods will accept an incoming session and move the state machine to the {{{ACCEPTING}}} state. |
228 | 1 | Adrian Georgescu | When there is a new incoming session, a {{{SCSessionNewIncoming}}} notification is sent, after which the application can call this method on the sender of the notification. |
229 | 1 | Adrian Georgescu | After this method is called, {{{SCSessionWillStart}}} followed by {{{SCSessionDidStart}}} will be emitted, or {{{SCSessionDidFail}}} followed by {{{SCSessionDidEnd}}} on an error. |
230 | 1 | Adrian Georgescu | This method may only be called while in the {{{INCOMING}}} state. |
231 | 1 | Adrian Georgescu | [[BR]]''audio'':[[BR]] |
232 | 1 | Adrian Georgescu | A boolean indicating whether an audio stream should be accepted for this session. |
233 | 1 | Adrian Georgescu | Note that this may only be set to {{{True}}} if an audio stream was actually proposed by the remote party. |
234 | 1 | Adrian Georgescu | [[BR]]''chat'':[[BR]] |
235 | 1 | Adrian Georgescu | A boolean indicating whether a chat stream should be accepted for this session. |
236 | 1 | Adrian Georgescu | Note that this may only be set to {{{True}}} if a chat stream was actually proposed by the remote party. |
237 | 1 | Adrian Georgescu | [[BR]]''password'':[[BR]] |
238 | 1 | Adrian Georgescu | The password for the local SIP URI to which the session was proposed. |
239 | 1 | Adrian Georgescu | This is only used for reserving a session at the MSRP relay. |
240 | 1 | Adrian Georgescu | '''reject'''(''self''):: |
241 | 1 | Adrian Georgescu | Reject an incoming session and move it to the {{{TERMINATING}}} state, which eventually leads to the {{{TERMINATED}}} state. |
242 | 1 | Adrian Georgescu | Calling this method will cause the {{{Session}}} object to emit a {{{SCSessionWillEnd}}} notification, followed by a {{{SCSessionDidEnd}}} notification. |
243 | 1 | Adrian Georgescu | This method may only be called while in the {{{INCOMING}}} state. |
244 | 1 | Adrian Georgescu | '''hold'''(''self''):: |
245 | 1 | Adrian Georgescu | Put the session on hold. |
246 | 1 | Adrian Georgescu | This will cause a {{{SCGotHoldRequest}}} notification to be sent. |
247 | 1 | Adrian Georgescu | This method may only be called while in the {{{ESTABLISHED}}} state. |
248 | 1 | Adrian Georgescu | '''unhold'''(''self''):: |
249 | 1 | Adrian Georgescu | Take the session out of hold. |
250 | 1 | Adrian Georgescu | This will cause a {{{SCGotUnholdRequest}}} notification to be sent. |
251 | 1 | Adrian Georgescu | This method may only be called while in the {{{ESTABLISHED}}} state. |
252 | 1 | Adrian Georgescu | '''start_recording_audio'''(''self'', '''path''', '''file_name'''={{{None}}}):: |
253 | 1 | Adrian Georgescu | If an audio stream is present within this session, calling this method will record the audio to a {{{.wav}}} file. |
254 | 1 | Adrian Georgescu | Note that when the session is on hold, nothing will be recorded to the file. |
255 | 1 | Adrian Georgescu | Right before starting the recording a {{{SCSessionWillStartRecordingAudio}}} notification will be emitted, followed by a {{{SCSessionDidStartRecordingAudio}}}. |
256 | 1 | Adrian Georgescu | This method may only be called while in the {{{ESTABLISHED}}} state. |
257 | 1 | Adrian Georgescu | [[BR]]''path'':[[BR]] |
258 | 1 | Adrian Georgescu | The path to the directory to place the {{{.wav}}} file in. |
259 | 1 | Adrian Georgescu | [[BR]]''file_name'':[[BR]] |
260 | 1 | Adrian Georgescu | The name of the {{{.wav}}} file to record to. |
261 | 1 | Adrian Georgescu | If this is set to {{{None}}}, a default file name including the session participants and the timestamp will be generated. |
262 | 1 | Adrian Georgescu | '''stop_recording_audio'''(''self''):: |
263 | 1 | Adrian Georgescu | This will stop a previously started recording. |
264 | 1 | Adrian Georgescu | Before stopping, a {{{SCSessionWillStopRecordingAudio}}} notification will be sent, followed by a {{{SCSessionDidStopRecordingAudio}}}. |
265 | 1 | Adrian Georgescu | This method may only be called while in the {{{ESTABLISHED}}} state. |
266 | 1 | Adrian Georgescu | '''send_dtmf'''(''self'', '''digit'''):: |
267 | 1 | Adrian Georgescu | If this session currently has an active audio stream, send a DTMF digit to the remote party over it. |
268 | 1 | Adrian Georgescu | This method may only be called while in the {{{ESTABLISHED}}} state. |
269 | 1 | Adrian Georgescu | [[BR]]''digit'':[[BR]] |
270 | 1 | Adrian Georgescu | This should a string of length 1, containing a valid DTMF digit value. |
271 | 13 | Luci Stanescu | '''send_message'''(''self'', '''content''', '''content_type'''="text/plain", '''to_uri'''={{{None}}}, '''dt'''={{{None}}}):: |
272 | 1 | Adrian Georgescu | If this session currently has an active MSRP chat with the remote party, send a message over with the with the specified parameters. |
273 | 1 | Adrian Georgescu | This will result in either a {{{SCSessionDidDeliverMessage}}} or a {{{SCSessionDidNotDeliverMessage}}} notification being sent. |
274 | 1 | Adrian Georgescu | These notifications include a unique ID as data attribute which is also returned by this method. |
275 | 1 | Adrian Georgescu | This method may only be called while in the {{{ESTABLISHED}}} state. |
276 | 1 | Adrian Georgescu | [[BR]]''content'':[[BR]] |
277 | 1 | Adrian Georgescu | The body of the MSRP message as a string. |
278 | 1 | Adrian Georgescu | [[BR]]''content_type'':[[BR]] |
279 | 1 | Adrian Georgescu | The Content-Type of the body as a string |
280 | 1 | Adrian Georgescu | [[BR]]''to_uri'':[[BR]]] |
281 | 1 | Adrian Georgescu | The {{{sipsimple.core.SIPURI}}} that should be put in the {{{To:}}} header of the CPIM wrapper of the message. |
282 | 1 | Adrian Georgescu | This defaults to the SIP URI of the remote party of the session if the argument is set to {{{None}}} |
283 | 1 | Adrian Georgescu | [[BR]]''dt'':[[BR]] |
284 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object representing the timestamp to put on the CPIM wrapper of the message. |
285 | 1 | Adrian Georgescu | When set to {{{None}}}, this defaults to now. |
286 | 1 | Adrian Georgescu | '''add_audio'''(''self''):: |
287 | 1 | Adrian Georgescu | Propose the remote party to add an audio stream to this session. |
288 | 1 | Adrian Georgescu | Calling this method will cause a {{{SCSessionGotStreamProposal}}} notification to be emitted. |
289 | 1 | Adrian Georgescu | After this, the state machine will move into the {{{PROPOSING}}} state until either a {{{SCSessionAcceptedStreamProposal}}} or {{{SCSessionRejectedStreamProposal}}} notification is sent, informing the application if the remote party accepted the proposal. |
290 | 1 | Adrian Georgescu | This method may only be called while in the {{{ESTABLISHED}}} state on a {{{Session}}} object that does not currently have an audio stream. |
291 | 1 | Adrian Georgescu | '''remove_audio'''(''self''):: |
292 | 1 | Adrian Georgescu | Stop the audio stream currently active within the session and inform the remote party of this. |
293 | 1 | Adrian Georgescu | This method may only be called while in the {{{ESTABLISHED}}} state on a {{{Session}}} object that has an audio stream. |
294 | 1 | Adrian Georgescu | '''add_chat'''(''self''):: |
295 | 1 | Adrian Georgescu | Propose the remote party to add a chat stream to this session. |
296 | 1 | Adrian Georgescu | Calling this method will cause a {{{SCSessionGotStreamProposal}}} notification to be emitted. |
297 | 1 | Adrian Georgescu | After this, the state machine will move into the {{{PROPOSING}}} state until either a {{{SCSessionAcceptedStreamProposal}}} or {{{SCSessionRejectedStreamProposal}}} notification is sent, informing the application if the remote party accepted the proposal. |
298 | 1 | Adrian Georgescu | This method may only be called while in the {{{ESTABLISHED}}} state on a {{{Session}}} object that does not currently have a chat stream. |
299 | 1 | Adrian Georgescu | '''remove_chat'''(''self''):: |
300 | 1 | Adrian Georgescu | Stop the chat stream currently active within the session and inform the remote party of this. |
301 | 1 | Adrian Georgescu | This method may only be called while in the {{{ESTABLISHED}}} state on a {{{Session}}} object that has a chat stream. |
302 | 1 | Adrian Georgescu | '''accept_proposal'''(''self''):: |
303 | 1 | Adrian Georgescu | When the remote party proposes to add a new stream, signaled by the {{{SCSessionGotStreamProposal}}} notification, the application can use this method to accept the stream(s) being proposed. |
304 | 1 | Adrian Georgescu | After calling this method a {{{SCSessionAcceptedStreamProposal}}} notification is sent, unless an error occurs while setting up the new stream, in which case a {{{SCSessionRejectedStreamProposal}}} notification is sent and a rejection is sent to the remote party. |
305 | 1 | Adrian Georgescu | This method may only be called while in the {{{PROPOSED}}} state. |
306 | 1 | Adrian Georgescu | '''reject_proposal'''(''self''):: |
307 | 1 | Adrian Georgescu | When the remote party proposes (a) stream(s) that the application does not want to accept, this method can be used to reject the proposal, after which a {{{SCSessionRejectedStreamProposal}}} notification is sent. |
308 | 1 | Adrian Georgescu | This method may only be called while in the {{{PROPOSED}}} state. |
309 | 1 | Adrian Georgescu | '''terminate'''(''self''):: |
310 | 1 | Adrian Georgescu | This method may be called any time when the {{{Session}}} object is active (i.e. not in the {{{NULL}}}, {{{TERMINATING}}} or {{{TERMINATED}}} states) in order to terminate the session. |
311 | 1 | Adrian Georgescu | Right before termination a {{{SCSessionWillEnd}}} notification is sent, after termination {{{SCSessionDidEnd}}} is sent. |
312 | 1 | Adrian Georgescu | |
313 | 1 | Adrian Georgescu | ==== notifications ==== |
314 | 1 | Adrian Georgescu | |
315 | 1 | Adrian Georgescu | '''SCSessionChangedState''':: |
316 | 1 | Adrian Georgescu | Will be sent whenever the {{{Session}}} object changes its state. |
317 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
318 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
319 | 1 | Adrian Georgescu | [[BR]]''prev_state'':[[BR]] |
320 | 1 | Adrian Georgescu | The previous state state the object was in. |
321 | 1 | Adrian Georgescu | [[BR]]''state'':[[BR]] |
322 | 1 | Adrian Georgescu | The new state the object is in. |
323 | 1 | Adrian Georgescu | '''SCSessionNewIncoming''':: |
324 | 1 | Adrian Georgescu | Will be sent when a new incoming {{{Session}}} is received. |
325 | 1 | Adrian Georgescu | The application should listen for this notification from all objects specifically to get informed of incoming sessions. |
326 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
327 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
328 | 1 | Adrian Georgescu | [[BR]]''has_audio'':[[BR]] |
329 | 1 | Adrian Georgescu | A boolean indicating if the remote party proposed an audio stream within this session. |
330 | 1 | Adrian Georgescu | [[BR]]''has_chat'':[[BR]] |
331 | 1 | Adrian Georgescu | A boolean indicating if the remote party proposed a chat stream within this session. |
332 | 1 | Adrian Georgescu | '''SCSessionNewOutgoing''':: |
333 | 1 | Adrian Georgescu | Will be sent when the applcation requests a new outgoing {{{Session}}}. |
334 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
335 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
336 | 1 | Adrian Georgescu | '''SCSessionGotRingIndication''':: |
337 | 1 | Adrian Georgescu | Will be sent when an outgoing {{{Session}}} receives an indication that a remote device is ringing. |
338 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
339 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
340 | 1 | Adrian Georgescu | '''SCSessionWillStart''':: |
341 | 1 | Adrian Georgescu | Will be sent just before a {{{Session}}} completes negotiation. |
342 | 1 | Adrian Georgescu | In terms of SIP, this is sent after the final response to the {{{INVITE}}}, but before the {{{ACK}}}. |
343 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
344 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
345 | 1 | Adrian Georgescu | '''SCSessionDidStart''':: |
346 | 1 | Adrian Georgescu | Will be sent when a {{{Session}}} completes negotiation. |
347 | 1 | Adrian Georgescu | In terms of SIP this is sent after the {{{ACK}}} was sent or received. |
348 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
349 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
350 | 1 | Adrian Georgescu | '''SCSessionDidFail''':: |
351 | 1 | Adrian Georgescu | This notification is sent whenever the session fails. |
352 | 1 | Adrian Georgescu | The failure reason is included in the data attributes. |
353 | 1 | Adrian Georgescu | This notification is always followed by {{{SCSessionDidEnd}}}. |
354 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
355 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
356 | 1 | Adrian Georgescu | [[BR]]''originator'':[[BR]] |
357 | 1 | Adrian Georgescu | A string indicating the origin of the failure. |
358 | 1 | Adrian Georgescu | This will either be "local" or "remote". |
359 | 1 | Adrian Georgescu | [[BR]]''code'':[[BR]] |
360 | 1 | Adrian Georgescu | The SIP error code of the failure. |
361 | 1 | Adrian Georgescu | If this is 0, the error was an internal exception. |
362 | 1 | Adrian Georgescu | [[BR]]''reason'':[[BR]] |
363 | 1 | Adrian Georgescu | A string explaining the reason of the failure. |
364 | 1 | Adrian Georgescu | '''SCSessionWillEnd''':: |
365 | 1 | Adrian Georgescu | Will be sent just before terminating a {{{Session}}} at the request of the application. |
366 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
367 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
368 | 1 | Adrian Georgescu | '''SCSessionDidEnd''':: |
369 | 1 | Adrian Georgescu | Will be sent always when a {{{Session}}} ends, either because of a failure (in which case it is preceded by {{{SCSessionDidFail}}}), remote or local session termination. |
370 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
371 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
372 | 1 | Adrian Georgescu | [[BR]]''originator'':[[BR]] |
373 | 1 | Adrian Georgescu | A string indicating who originated the termination. |
374 | 1 | Adrian Georgescu | This will either be "local" or "remote". |
375 | 1 | Adrian Georgescu | '''SCSessionGotHoldRequest''':: |
376 | 1 | Adrian Georgescu | Will be sent when the session got put on hold, either by the local or the remote party. |
377 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
378 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
379 | 1 | Adrian Georgescu | [[BR]]''originator'':[[BR]] |
380 | 1 | Adrian Georgescu | A string indicating who originated the hold request, and consequently in which direction the session got put on hold. |
381 | 1 | Adrian Georgescu | '''SCSessionGotUnholdRequest''':: |
382 | 1 | Adrian Georgescu | Will be sent when the session got taken out of hold, either by the local or the remote party. |
383 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
384 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
385 | 1 | Adrian Georgescu | [[BR]]''originator'':[[BR]] |
386 | 1 | Adrian Georgescu | A string indicating who sent the original hold request, and consequently in which direction the session got taken out of hold. |
387 | 1 | Adrian Georgescu | '''SCSessionWillStartRecordingAudio''':: |
388 | 1 | Adrian Georgescu | Will be sent when the application requested that the audio stream active within the session be record to a {{{.wav}}} file, just before recording starts. |
389 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
390 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
391 | 1 | Adrian Georgescu | [[BR]]''file_name'':[[BR]] |
392 | 1 | Adrian Georgescu | The name of the recording {{{.wav}}} file, including full path. |
393 | 1 | Adrian Georgescu | '''SCSessionDidStartRecordingAudio''':: |
394 | 1 | Adrian Georgescu | Will be sent when the application requested that the audio stream active within the session be record to a {{{.wav}}} file, just after recording starts. |
395 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
396 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
397 | 1 | Adrian Georgescu | [[BR]]''file_name'':[[BR]] |
398 | 1 | Adrian Georgescu | The name of the recording {{{.wav}}} file, including full path. |
399 | 1 | Adrian Georgescu | '''SCSessionWillStopRecordingAudio''':: |
400 | 1 | Adrian Georgescu | Will be sent when the application requested ending the recording to a {{{.wav}}} file, just before recording stops. |
401 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
402 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
403 | 1 | Adrian Georgescu | [[BR]]''file_name'':[[BR]] |
404 | 1 | Adrian Georgescu | The name of the recording {{{.wav}}} file, including full path. |
405 | 1 | Adrian Georgescu | '''SCSessionDidStopRecordingAudio''':: |
406 | 1 | Adrian Georgescu | Will be sent when the application requested ending the recording to a {{{.wav}}} file, just before recording stops. |
407 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
408 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
409 | 1 | Adrian Georgescu | [[BR]]''file_name'':[[BR]] |
410 | 1 | Adrian Georgescu | The name of the recording {{{.wav}}} file, including full path. |
411 | 1 | Adrian Georgescu | '''SCSessionGotNoAudio''':: |
412 | 1 | Adrian Georgescu | This notification will be sent if 5 seconds after the audio stream starts, no audio was received from the remote party. |
413 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
414 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
415 | 1 | Adrian Georgescu | '''SCSessionGotDTMF''':: |
416 | 1 | Adrian Georgescu | Will be send if there is a DMTF digit received from the remote party on the audio stream. |
417 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
418 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
419 | 1 | Adrian Georgescu | [[BR]]''digit'':[[BR]] |
420 | 1 | Adrian Georgescu | The DTMF digit that was received, in the form of a string of length 1. |
421 | 1 | Adrian Georgescu | '''SCSessionGotMessage''':: |
422 | 1 | Adrian Georgescu | Will be sent whenever a MSRP message is received on the chat stream of the session. |
423 | 1 | Adrian Georgescu | [[BR]]''content'':[[BR]] |
424 | 1 | Adrian Georgescu | The body of the message. |
425 | 1 | Adrian Georgescu | [[BR]]''content_type'':[[BR]] |
426 | 1 | Adrian Georgescu | The Content-Type of the body. |
427 | 1 | Adrian Georgescu | [[BR]]''cpim_headers'':[[BR]] |
428 | 1 | Adrian Georgescu | A dictionary of headers included in the CPIM wrapper. |
429 | 1 | Adrian Georgescu | [[BR]]''message'':[[BR]] |
430 | 5 | Redmine Admin | Raw MSRP message, an msrplib.protocol.MSRPData instance |
431 | 1 | Adrian Georgescu | '''SCSessionDidDeliverMessage''':: |
432 | 1 | Adrian Georgescu | Will be sent when a previously sent MSRP chat message got delivered to the remote party. |
433 | 1 | Adrian Georgescu | [[BR]]''message_id'':[[BR]] |
434 | 1 | Adrian Georgescu | The unique identifier of this message as a string, as previously returned by the {{{send_message()}}} method. |
435 | 1 | Adrian Georgescu | [[BR]]''code'':[[BR]] |
436 | 1 | Adrian Georgescu | The response code of the confirmation report. |
437 | 1 | Adrian Georgescu | [[BR]]''reason'':[[BR]] |
438 | 1 | Adrian Georgescu | The reason string of the confirmation report. |
439 | 1 | Adrian Georgescu | [[BR]]''message'':[[BR]] |
440 | 5 | Redmine Admin | Raw MSRP message, an msrplib.protocol.MSRPData instance |
441 | 1 | Adrian Georgescu | '''SCSessionDidDeliverMessage''':: |
442 | 1 | Adrian Georgescu | Will be sent when a previously sent MSRP chat message did not get delivered to the remote party. |
443 | 1 | Adrian Georgescu | [[BR]]''message_id'':[[BR]] |
444 | 1 | Adrian Georgescu | The unique identifier of this message as a string, as previously returned by the {{{send_message()}}} method. |
445 | 1 | Adrian Georgescu | [[BR]]''code'':[[BR]] |
446 | 1 | Adrian Georgescu | The response code of the confirmation report. |
447 | 1 | Adrian Georgescu | [[BR]]''reason'':[[BR]] |
448 | 1 | Adrian Georgescu | The reason string of the confirmation report. |
449 | 1 | Adrian Georgescu | [[BR]]''message'':[[BR]] |
450 | 5 | Redmine Admin | Raw MSRP message, an msrplib.protocol.MSRPData instance |
451 | 1 | Adrian Georgescu | '''SCSessionGotStreamProposal''':: |
452 | 1 | Adrian Georgescu | Will be sent when either the local or the remote party proposes to add a stream to the session. |
453 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
454 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
455 | 1 | Adrian Georgescu | [[BR]]''proposer'':[[BR]] |
456 | 1 | Adrian Georgescu | The party that did the stream proposal, can be either "local" or "remote". |
457 | 1 | Adrian Georgescu | [[BR]]''adds_audio'':[[BR]] |
458 | 1 | Adrian Georgescu | A boolean indicating if the proposal would add an audio stream. |
459 | 1 | Adrian Georgescu | [[BR]]''adds_chat'':[[BR]] |
460 | 1 | Adrian Georgescu | A boolean indicating if the proposal would add a chat stream. |
461 | 1 | Adrian Georgescu | '''SCSessionRejectedStreamProposal''':: |
462 | 1 | Adrian Georgescu | Will be sent when either the local or the remote party rejects a proposal to have (a) stream(s) added to the session. |
463 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
464 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
465 | 1 | Adrian Georgescu | [[BR]]''proposer'':[[BR]] |
466 | 1 | Adrian Georgescu | The party that did the stream proposal, can be either "local" or "remote". |
467 | 1 | Adrian Georgescu | [[BR]]''reason'':[[BR]] |
468 | 1 | Adrian Georgescu | The reason for rejecting the stream proposal. |
469 | 1 | Adrian Georgescu | '''SCSessionRejectedStreamProposal''':: |
470 | 1 | Adrian Georgescu | Will be sent when either the local or the remote party accepts a proposal to have (a) stream(s) added to the session. |
471 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
472 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
473 | 1 | Adrian Georgescu | [[BR]]''proposer'':[[BR]] |
474 | 1 | Adrian Georgescu | The party that did the stream proposal, can be either "local" or "remote". |
475 | 1 | Adrian Georgescu | |
476 | 1 | Adrian Georgescu | ==== examples ==== |
477 | 1 | Adrian Georgescu | |
478 | 6 | Ruud Klaver | As an example of how to use the {{{Session}}} object, the following provides a very basic Python program that places an outbound call: |
479 | 6 | Ruud Klaver | |
480 | 6 | Ruud Klaver | {{{ |
481 | 6 | Ruud Klaver | from threading import Event |
482 | 6 | Ruud Klaver | from zope.interface import implements |
483 | 6 | Ruud Klaver | from application.notification import IObserver, NotificationCenter |
484 | 6 | Ruud Klaver | from sipsimple import * |
485 | 6 | Ruud Klaver | |
486 | 6 | Ruud Klaver | class SimpleOutboundCall(object): |
487 | 6 | Ruud Klaver | # indicate that we implement the application.notification.IObserver interface |
488 | 6 | Ruud Klaver | implements(IObserver) |
489 | 6 | Ruud Klaver | |
490 | 6 | Ruud Klaver | def __init__(self, local_uri, password, remote_uri, route): |
491 | 6 | Ruud Klaver | # setup a threading.Event to signal that the Engine has stopped |
492 | 6 | Ruud Klaver | self.engine_ended_event = Event() |
493 | 6 | Ruud Klaver | # start the Engine with default parameters |
494 | 1 | Adrian Georgescu | Engine().start() |
495 | 7 | Ruud Klaver | # Set up an outbound ringtone on the session manager |
496 | 7 | Ruud Klaver | SessionManager().ringtone_config.outbound_ringtone = "ringtone.wav" |
497 | 6 | Ruud Klaver | # create a new Session |
498 | 6 | Ruud Klaver | self.session = Session() |
499 | 6 | Ruud Klaver | # listen for the notification that the Engine stopped |
500 | 6 | Ruud Klaver | NotificationCenter().add_observer(self, "SCEngineDidEnd", Engine()) |
501 | 6 | Ruud Klaver | # listen for the notification that the Session ended |
502 | 6 | Ruud Klaver | NotificationCenter().add_observer(self, "SCSessionDidEnd", self.session) |
503 | 6 | Ruud Klaver | # setup sipsimple.core.Credentials object |
504 | 6 | Ruud Klaver | cred = Credentials(local_uri, password) |
505 | 6 | Ruud Klaver | # start a new outbound session |
506 | 6 | Ruud Klaver | self.session.new(remote_uri, cred, route, audio=True) |
507 | 6 | Ruud Klaver | |
508 | 6 | Ruud Klaver | def end(self): |
509 | 6 | Ruud Klaver | # if the Session is still active, terminate it |
510 | 6 | Ruud Klaver | self.session.terminate() |
511 | 6 | Ruud Klaver | # wait for the engine to stop, processed in handle_notification |
512 | 6 | Ruud Klaver | self.engine_ended_event.wait() |
513 | 6 | Ruud Klaver | # quit the progam, as this can only be done from the main thread |
514 | 6 | Ruud Klaver | sys.exit() |
515 | 6 | Ruud Klaver | |
516 | 6 | Ruud Klaver | def handle_notification(self, notification): |
517 | 6 | Ruud Klaver | if notification.name == "SCSessionDidEnd": |
518 | 6 | Ruud Klaver | # if for whatever reason the session ended, stop the Engine |
519 | 6 | Ruud Klaver | print "Session ended" |
520 | 6 | Ruud Klaver | Engine().stop() |
521 | 6 | Ruud Klaver | elif notification.name == "SCEngineDidEnd": |
522 | 6 | Ruud Klaver | # once the Engine has stopped, signal the (possibly) waiting main |
523 | 6 | Ruud Klaver | # thread through a threading.Event |
524 | 6 | Ruud Klaver | self.engine_ended_event.set() |
525 | 6 | Ruud Klaver | |
526 | 6 | Ruud Klaver | |
527 | 6 | Ruud Klaver | # place an audio call from the specified account to the specified URI, through |
528 | 6 | Ruud Klaver | # the specified SIP proxy |
529 | 6 | Ruud Klaver | # edit this to reflect real settings |
530 | 6 | Ruud Klaver | call = SimpleOutboundCall(SIPURI(user="alice", host="example.com"), "p4ssw0rd", SIPURI(user="bob", host="example.com"), Route("1.2.3.4")) |
531 | 6 | Ruud Klaver | # block waiting for user input |
532 | 6 | Ruud Klaver | print "Placing call, press enter to quit program" |
533 | 6 | Ruud Klaver | raw_input() |
534 | 6 | Ruud Klaver | # block in end() until the Engine has stopped |
535 | 6 | Ruud Klaver | call.end() |
536 | 6 | Ruud Klaver | }}} |
537 | 6 | Ruud Klaver | |
538 | 6 | Ruud Klaver | |
539 | 1 | Adrian Georgescu | === MSRPChat === |
540 | 1 | Adrian Georgescu | |
541 | 1 | Adrian Georgescu | ==== Methods ==== |
542 | 1 | Adrian Georgescu | ==== Attributes ==== |
543 | 1 | Adrian Georgescu | |
544 | 1 | Adrian Georgescu | === MSRPFileTransfer === |
545 | 1 | Adrian Georgescu | |
546 | 1 | Adrian Georgescu | ==== Methods ==== |
547 | 1 | Adrian Georgescu | ==== Attributes ==== |
548 | 1 | Adrian Georgescu | == Notifications == |
549 | 1 | Adrian Georgescu | |
550 | 1 | Adrian Georgescu | The notifications bus is implemented using [http://pypi.python.org/pypi/python-application/ python-application] notifications system. |
551 | 1 | Adrian Georgescu | |
552 | 1 | Adrian Georgescu | Each software component that needs to communicate with the rest of the system can subscribe to or publish messages. The format of a message on the notification bus is ABClassNameVerbNoun. Attached to each message data can be appended, the data need to be understood by an interested observer. The messages exchanged on the notifications bus and their context are described below. |
553 | 1 | Adrian Georgescu | |
554 | 1 | Adrian Georgescu | === SIP Registration === |
555 | 1 | Adrian Georgescu | |
556 | 1 | Adrian Georgescu | * SCRegistrationDidSucceed |
557 | 1 | Adrian Georgescu | * SCRegistrationDidFail |
558 | 1 | Adrian Georgescu | * SCRegistrationWillEnd |
559 | 1 | Adrian Georgescu | * SCRegistrationDidEnd |
560 | 1 | Adrian Georgescu | |
561 | 1 | Adrian Georgescu | === SIP Subscription === |
562 | 1 | Adrian Georgescu | |
563 | 1 | Adrian Georgescu | * SCSubscriptionDidSucceed |
564 | 1 | Adrian Georgescu | * SCSubscriptionDidFail |
565 | 1 | Adrian Georgescu | * SCSubscriptionWillEnd |
566 | 1 | Adrian Georgescu | * SCSubscriptionDidEnd |
567 | 1 | Adrian Georgescu | * SCSubscriptionGotNotify |
568 | 1 | Adrian Georgescu | |
569 | 1 | Adrian Georgescu | === SIP Publication === |
570 | 1 | Adrian Georgescu | |
571 | 1 | Adrian Georgescu | * SCPublicationDidSucceed |
572 | 1 | Adrian Georgescu | * SCPublicationDidFail |
573 | 1 | Adrian Georgescu | * SCPublicationWillEnd |
574 | 1 | Adrian Georgescu | * SCPublicationDidEnd |
575 | 1 | Adrian Georgescu | |
576 | 1 | Adrian Georgescu | === MSRP IM Chat === |
577 | 1 | Adrian Georgescu | |
578 | 1 | Adrian Georgescu | * MSRPChatDidInitialize |
579 | 1 | Adrian Georgescu | * MSRPChatDidStart |
580 | 1 | Adrian Georgescu | * MSRPChatDidFail |
581 | 1 | Adrian Georgescu | * MSRPChatWillEnd |
582 | 1 | Adrian Georgescu | * MSRPChatDidEnd |
583 | 1 | Adrian Georgescu | * MSRPChatGotMessage |
584 | 1 | Adrian Georgescu | * MSRPChatDidDeliverMessage |
585 | 1 | Adrian Georgescu | * MSRPChatDidNotDeliverMessage |
586 | 1 | Adrian Georgescu | |
587 | 1 | Adrian Georgescu | === MSRP File Transfer === |
588 | 1 | Adrian Georgescu | |
589 | 1 | Adrian Georgescu | * MSRPFileTransferDidInitialize |
590 | 1 | Adrian Georgescu | * MSRPFileTransferDidStart |
591 | 1 | Adrian Georgescu | * MSRPFileTransferDidFail |
592 | 1 | Adrian Georgescu | * MSRPFileTransferGotFile |
593 | 1 | Adrian Georgescu | * MSRPFileTransferDidDeliverFile |
594 | 1 | Adrian Georgescu | * MSRPFileTransferDidNotDeliverFile |
595 | 1 | Adrian Georgescu | * MSRPFileTransferWillEnd |
596 | 1 | Adrian Georgescu | * MSRPFileTransferDidEnd |