SipMiddlewareApi
Version 45 (Adrian Georgescu, 11/13/2009 09:58 pm)
1 | 1 | Adrian Georgescu | = Middleware API = |
---|---|---|---|
2 | 1 | Adrian Georgescu | |
3 | 1 | Adrian Georgescu | [[TOC(WikiStart, Sip*, depth=3)]] |
4 | 1 | Adrian Georgescu | |
5 | 21 | Adrian Georgescu | This chapter describes the event driven middleware API that can be used by a developer to build a user interface for SIP SIMPLE client library. |
6 | 14 | Adrian Georgescu | |
7 | 25 | Adrian Georgescu | * To communicate with other sub-systems, the middleware uses the notification system provided by the [http://pypi.python.org/pypi/python-application python-application] package |
8 | 34 | Adrian Georgescu | * The middleware use the [wiki:SipConfigurationAPI configuration API] to access general and SIP account settings |
9 | 1 | Adrian Georgescu | |
10 | 33 | Adrian Georgescu | [[Image(sipsimple-middleware.png)]] |
11 | 1 | Adrian Georgescu | |
12 | 1 | Adrian Georgescu | == Classes == |
13 | 1 | Adrian Georgescu | |
14 | 1 | Adrian Georgescu | === Session === |
15 | 1 | Adrian Georgescu | |
16 | 45 | Adrian Georgescu | Implemented in [browser:sipsimple/session.py] |
17 | 44 | Adrian Georgescu | |
18 | 44 | 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. |
19 | 1 | Adrian Georgescu | |
20 | 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. |
21 | 1 | Adrian Georgescu | State changes are triggered by methods called on the object by the application or by received network events. |
22 | 26 | Luci Stanescu | Every time this attribute changes, a {{{SIPSessionChangedState}}} notification is sent by the object. |
23 | 1 | Adrian Georgescu | These states and their transitions are represented in the following diagram: |
24 | 1 | Adrian Georgescu | |
25 | 2 | Adrian Georgescu | [[Image(sipsimple-session-state-machine.png)]] |
26 | 1 | Adrian Georgescu | |
27 | 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. |
28 | 1 | Adrian Georgescu | |
29 | 1 | Adrian Georgescu | ==== attributes ==== |
30 | 1 | Adrian Georgescu | |
31 | 1 | Adrian Georgescu | '''state''':: |
32 | 1 | Adrian Georgescu | The state the object is currently in, being one of the states from the diagram above. |
33 | 18 | Ruud Klaver | '''account''':: |
34 | 18 | Ruud Klaver | The {{{sipsimple.account.Account}}} or {{{sipsimple.account.BonjourAccount}}} object that the {{{Session}}} is associated with. |
35 | 18 | Ruud Klaver | On an outbound session, this is the account the application specified on object instantiation. |
36 | 1 | Adrian Georgescu | '''direction''':: |
37 | 1 | Adrian Georgescu | A string indicating the direction of the initial negotiation of the session. |
38 | 1 | Adrian Georgescu | This can be either {{{None}}}, "incoming" or "outgoing". |
39 | 1 | Adrian Georgescu | '''start_time''':: |
40 | 1 | Adrian Georgescu | The time the session started as a {{{datetime.datetime}}} object, or {{{None}}} if the session was not yet started. |
41 | 1 | Adrian Georgescu | '''stop_time''':: |
42 | 1 | Adrian Georgescu | The time the session stopped as a {{{datetime.datetime}}} object, or {{{None}}} if the session has not yet terminated. |
43 | 1 | Adrian Georgescu | '''on_hold_by_local''':: |
44 | 1 | Adrian Georgescu | Boolean indicating whether the session was put on hold by the local party. |
45 | 1 | Adrian Georgescu | '''on_hold_by_remote''':: |
46 | 1 | Adrian Georgescu | Boolean indicating whether the session was put on hold by the remote party. |
47 | 1 | Adrian Georgescu | '''on_hold''':: |
48 | 1 | Adrian Georgescu | Boolean indicating whether the session was put on hold, either by the local or the remote party. |
49 | 1 | Adrian Georgescu | '''remote_user_agent''':: |
50 | 1 | Adrian Georgescu | A string indicating the remote user agent, if it provided one. |
51 | 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). |
52 | 1 | Adrian Georgescu | '''local_uri''':: |
53 | 1 | Adrian Georgescu | The {{{sipsimple.core.SIPURI}}} of the local party, if the session is active. |
54 | 1 | Adrian Georgescu | '''remote_uri''':: |
55 | 1 | Adrian Georgescu | The {{{sipsimple.core.SIPURI}}} of the remote party, if the session is active. |
56 | 1 | Adrian Georgescu | '''caller_uri''':: |
57 | 1 | Adrian Georgescu | The {{{sipsimple.core.SIPURI}}} of the calling party, if the session is active. |
58 | 1 | Adrian Georgescu | Depending on the direction, this is either {{{local_uri}}} or {{{remote_uri}}}. |
59 | 1 | Adrian Georgescu | '''callee_uri''':: |
60 | 1 | Adrian Georgescu | The {{{sipsimple.core.SIPURI}}} of the called party, if the session is active. |
61 | 1 | Adrian Georgescu | Depending on the direction, this is either {{{local_uri}}} or {{{remote_uri}}}. |
62 | 1 | Adrian Georgescu | '''route''':: |
63 | 20 | Ruud Klaver | A copy of the {{{sipsimple.core.Route}}} object passed when the {{{connect()}}} method was called. |
64 | 1 | Adrian Georgescu | On incoming or inactive sessions this is {{{None}}}. |
65 | 1 | Adrian Georgescu | '''audio_transport''':: |
66 | 1 | Adrian Georgescu | The {{{sipsimple.core.AudioTransport}}} object used by the session, if it currently contains an audio stream. |
67 | 1 | Adrian Georgescu | Normally the application will not need to access this directly. |
68 | 1 | Adrian Georgescu | '''has_audio''':: |
69 | 23 | Ruud Klaver | A boolean indicating if this {{{Session}}} currently has an active audio stream. |
70 | 1 | Adrian Georgescu | '''audio_sample_rate''':: |
71 | 1 | Adrian Georgescu | If the audio stream was started, this attribute contains the sample rate of the audio negotiated. |
72 | 1 | Adrian Georgescu | '''audio_codec''':: |
73 | 1 | Adrian Georgescu | If the audio stream was started, this attribute contains the name of the audio codec that was negotiated. |
74 | 1 | Adrian Georgescu | '''audio_srtp_active''':: |
75 | 1 | Adrian Georgescu | If the audio stream was started, this boolean attribute indicates if SRTP is currently being used on the stream. |
76 | 1 | Adrian Georgescu | '''audio_local_rtp_address''':: |
77 | 1 | Adrian Georgescu | If an audio stream is present within the session, this attribute contains the local IP address used for the audio stream. |
78 | 1 | Adrian Georgescu | '''audio_local_rtp_port''':: |
79 | 1 | Adrian Georgescu | If an audio stream is present within the session, this attribute contains the local UDP port used for the audio stream. |
80 | 1 | Adrian Georgescu | '''audio_remote_rtp_address_sdp''':: |
81 | 1 | Adrian Georgescu | If the audio stream was started, this attribute contains the IP address that the remote party gave to send audio to. |
82 | 1 | Adrian Georgescu | '''audio_remote_rtp_port_sdp''':: |
83 | 1 | Adrian Georgescu | If the audio stream was started, this attribute contains the UDP port that the remote party gave to send audio to. |
84 | 1 | Adrian Georgescu | '''audio_remote_rtp_address_received''':: |
85 | 1 | Adrian Georgescu | If the audio stream was started, this attribute contains the remote IP address from which the audio stream is being received. |
86 | 1 | Adrian Georgescu | '''audio_remote_rtp_port_received''':: |
87 | 1 | Adrian Georgescu | If the audio stream was started, this attribute contains the remote UDP port from which the audio stream is being received. |
88 | 1 | Adrian Georgescu | '''audio_was_received''':: |
89 | 1 | Adrian Georgescu | This boolean property indicates if audio was actually received on the audio stream contained within this session. |
90 | 1 | Adrian Georgescu | '''audio_recording_file_name''':: |
91 | 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. |
92 | 1 | Adrian Georgescu | '''chat_transport''':: |
93 | 1 | Adrian Georgescu | The {{{sipsimple.msrp.MSRPChat}}} object used by the session as chat transport, if the session currently contains a chat stream. |
94 | 1 | Adrian Georgescu | Normally the application will not need to access this directly. |
95 | 1 | Adrian Georgescu | '''has_chat''':: |
96 | 23 | Ruud Klaver | A boolean property indicating if this {{{Session}}} currently has an active chat stream. |
97 | 1 | Adrian Georgescu | |
98 | 1 | Adrian Georgescu | ==== methods ==== |
99 | 1 | Adrian Georgescu | |
100 | 18 | Ruud Klaver | '''!__init!__'''(''self'', '''account'''):: |
101 | 1 | Adrian Georgescu | Creates a new {{{Session}}} object in the {{{NULL}}} state. |
102 | 19 | Ruud Klaver | [[BR]]''account'':[[BR]] |
103 | 19 | Ruud Klaver | The local account to be associated with this {{{Session}}}. |
104 | 19 | Ruud Klaver | '''connect'''(''self'', '''callee_uri''', '''routes''', '''audio'''={{{False}}}, '''chat'''={{{False}}}):: |
105 | 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. |
106 | 26 | Luci Stanescu | Before contacting the remote party, a {{{SIPSessionNewOutgoing}}} notification will be emitted. |
107 | 26 | Luci Stanescu | If there is a failure or the remote party rejected the offer, a {{{SIPSessionDidFail}}} notification will be sent, followed by a {{{SIPSessionDidEnd}}}. |
108 | 26 | Luci Stanescu | Any time a ringing indication is received from the remote party, a {{{SIPSessionGotRingIndication}}} notification is sent. |
109 | 26 | 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. |
110 | 1 | Adrian Georgescu | This method may only be called while in the {{{NULL}}} state. |
111 | 1 | Adrian Georgescu | [[BR]]''callee_uri'':[[BR]] |
112 | 1 | Adrian Georgescu | A {{{sipsimple.core.SIPURI}}} object representing the remote host to initiate the session to. |
113 | 19 | Ruud Klaver | [[BR]]''routes'':[[BR]] |
114 | 19 | Ruud Klaver | An iterable of {{{sipsimple.core.Route}}} objects, specifying the IP, port and transport to the outbound proxy. |
115 | 19 | Ruud Klaver | These routes will be tried in order, until one of them succeeds. |
116 | 1 | Adrian Georgescu | [[BR]]''audio'':[[BR]] |
117 | 1 | Adrian Georgescu | A boolean indicating whether an audio stream should be initially included in this session. |
118 | 1 | Adrian Georgescu | [[BR]]''chat'':[[BR]] |
119 | 1 | Adrian Georgescu | A boolean indicating whether a chat stream should be initially included in this session. |
120 | 19 | Ruud Klaver | '''accept'''(''self'', '''audio'''={{{False}}}, '''chat'''={{{False}}}):: |
121 | 1 | Adrian Georgescu | Calling this methods will accept an incoming session and move the state machine to the {{{ACCEPTING}}} state. |
122 | 26 | 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. |
123 | 26 | Luci Stanescu | After this method is called, {{{SIPSessionWillStart}}} followed by {{{SIPSessionDidStart}}} will be emitted, or {{{SIPSessionDidFail}}} followed by {{{SIPSessionDidEnd}}} on an error. |
124 | 1 | Adrian Georgescu | This method may only be called while in the {{{INCOMING}}} state. |
125 | 1 | Adrian Georgescu | [[BR]]''audio'':[[BR]] |
126 | 1 | Adrian Georgescu | A boolean indicating whether an audio stream should be accepted for this session. |
127 | 1 | Adrian Georgescu | Note that this may only be set to {{{True}}} if an audio stream was actually proposed by the remote party. |
128 | 1 | Adrian Georgescu | [[BR]]''chat'':[[BR]] |
129 | 1 | Adrian Georgescu | A boolean indicating whether a chat stream should be accepted for this session. |
130 | 1 | Adrian Georgescu | Note that this may only be set to {{{True}}} if a chat stream was actually proposed by the remote party. |
131 | 41 | Ruud Klaver | '''reject'''(''self'', '''is_busy'''={{{False}}}):: |
132 | 1 | Adrian Georgescu | Reject an incoming session and move it to the {{{TERMINATING}}} state, which eventually leads to the {{{TERMINATED}}} state. |
133 | 26 | Luci Stanescu | Calling this method will cause the {{{Session}}} object to emit a {{{SIPSessionWillEnd}}} notification, followed by a {{{SIPSessionDidEnd}}} notification. |
134 | 1 | Adrian Georgescu | This method may only be called while in the {{{INCOMING}}} state. |
135 | 41 | Ruud Klaver | [[BR]]''chat'':[[BR]] |
136 | 41 | Ruud Klaver | A boolean indicating whether the response code sent to the remote party should be 486 (Busy) instead of 603 (Decline). |
137 | 1 | Adrian Georgescu | '''hold'''(''self''):: |
138 | 1 | Adrian Georgescu | Put the session on hold. |
139 | 26 | Luci Stanescu | This will cause a {{{SIPGotHoldRequest}}} notification to be sent. |
140 | 1 | Adrian Georgescu | This method may only be called while in the {{{ESTABLISHED}}} state. |
141 | 1 | Adrian Georgescu | '''unhold'''(''self''):: |
142 | 1 | Adrian Georgescu | Take the session out of hold. |
143 | 26 | Luci Stanescu | This will cause a {{{SIPGotUnholdRequest}}} notification to be sent. |
144 | 1 | Adrian Georgescu | This method may only be called while in the {{{ESTABLISHED}}} state. |
145 | 19 | Ruud Klaver | '''start_recording_audio'''(''self'', '''file_name'''={{{None}}}):: |
146 | 1 | Adrian Georgescu | If an audio stream is present within this session, calling this method will record the audio to a {{{.wav}}} file. |
147 | 1 | Adrian Georgescu | Note that when the session is on hold, nothing will be recorded to the file. |
148 | 26 | Luci Stanescu | Right before starting the recording a {{{SIPSessionWillStartRecordingAudio}}} notification will be emitted, followed by a {{{SIPSessionDidStartRecordingAudio}}}. |
149 | 1 | Adrian Georgescu | This method may only be called while in the {{{ESTABLISHED}}} state. |
150 | 1 | Adrian Georgescu | [[BR]]''file_name'':[[BR]] |
151 | 1 | Adrian Georgescu | The name of the {{{.wav}}} file to record to. |
152 | 1 | Adrian Georgescu | If this is set to {{{None}}}, a default file name including the session participants and the timestamp will be generated. |
153 | 1 | Adrian Georgescu | '''stop_recording_audio'''(''self''):: |
154 | 1 | Adrian Georgescu | This will stop a previously started recording. |
155 | 26 | Luci Stanescu | Before stopping, a {{{SIPSessionWillStopRecordingAudio}}} notification will be sent, followed by a {{{SIPSessionDidStopRecordingAudio}}}. |
156 | 1 | Adrian Georgescu | This method may only be called while in the {{{ESTABLISHED}}} state. |
157 | 1 | Adrian Georgescu | '''send_dtmf'''(''self'', '''digit'''):: |
158 | 1 | Adrian Georgescu | If this session currently has an active audio stream, send a DTMF digit to the remote party over it. |
159 | 23 | Ruud Klaver | This method may only be called while in the {{{ESTABLISHED}}} state and if the session has an active audio stream. |
160 | 1 | Adrian Georgescu | [[BR]]''digit'':[[BR]] |
161 | 1 | Adrian Georgescu | This should a string of length 1, containing a valid DTMF digit value. |
162 | 13 | Luci Stanescu | '''send_message'''(''self'', '''content''', '''content_type'''="text/plain", '''to_uri'''={{{None}}}, '''dt'''={{{None}}}):: |
163 | 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. |
164 | 26 | Luci Stanescu | This will result in either a {{{SIPSessionDidDeliverMessage}}} or a {{{SIPSessionDidNotDeliverMessage}}} notification being sent. |
165 | 1 | Adrian Georgescu | These notifications include a unique ID as data attribute which is also returned by this method. |
166 | 1 | Adrian Georgescu | This method may only be called while in the {{{ESTABLISHED}}} state. |
167 | 1 | Adrian Georgescu | [[BR]]''content'':[[BR]] |
168 | 1 | Adrian Georgescu | The body of the MSRP message as a string. |
169 | 1 | Adrian Georgescu | [[BR]]''content_type'':[[BR]] |
170 | 1 | Adrian Georgescu | The Content-Type of the body as a string |
171 | 22 | Ruud Klaver | [[BR]]''to_uri'':[[BR]] |
172 | 1 | Adrian Georgescu | The {{{sipsimple.core.SIPURI}}} that should be put in the {{{To:}}} header of the CPIM wrapper of the message. |
173 | 1 | Adrian Georgescu | This defaults to the SIP URI of the remote party of the session if the argument is set to {{{None}}} |
174 | 1 | Adrian Georgescu | [[BR]]''dt'':[[BR]] |
175 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object representing the timestamp to put on the CPIM wrapper of the message. |
176 | 1 | Adrian Georgescu | When set to {{{None}}}, this defaults to now. |
177 | 1 | Adrian Georgescu | '''add_audio'''(''self''):: |
178 | 1 | Adrian Georgescu | Propose the remote party to add an audio stream to this session. |
179 | 26 | Luci Stanescu | Calling this method will cause a {{{SIPSessionGotStreamProposal}}} notification to be emitted. |
180 | 26 | Luci Stanescu | After this, the state machine will move into the {{{PROPOSING}}} state until either a {{{SIPSessionAcceptedStreamProposal}}} or {{{SIPSessionRejectedStreamProposal}}} notification is sent, informing the application if the remote party accepted the proposal. |
181 | 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. |
182 | 1 | Adrian Georgescu | '''remove_audio'''(''self''):: |
183 | 1 | Adrian Georgescu | Stop the audio stream currently active within the session and inform the remote party of this. |
184 | 1 | Adrian Georgescu | This method may only be called while in the {{{ESTABLISHED}}} state on a {{{Session}}} object that has an audio stream. |
185 | 1 | Adrian Georgescu | '''add_chat'''(''self''):: |
186 | 1 | Adrian Georgescu | Propose the remote party to add a chat stream to this session. |
187 | 26 | Luci Stanescu | Calling this method will cause a {{{SIPSessionGotStreamProposal}}} notification to be emitted. |
188 | 26 | Luci Stanescu | After this, the state machine will move into the {{{PROPOSING}}} state until either a {{{SIPSessionAcceptedStreamProposal}}} or {{{SIPSessionRejectedStreamProposal}}} notification is sent, informing the application if the remote party accepted the proposal. |
189 | 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. |
190 | 1 | Adrian Georgescu | '''remove_chat'''(''self''):: |
191 | 1 | Adrian Georgescu | Stop the chat stream currently active within the session and inform the remote party of this. |
192 | 1 | Adrian Georgescu | This method may only be called while in the {{{ESTABLISHED}}} state on a {{{Session}}} object that has a chat stream. |
193 | 19 | Ruud Klaver | '''accept_proposal'''(''self'', '''audio'''={{{False}}}, '''chat'''={{{False}}}):: |
194 | 26 | Luci Stanescu | When the remote party proposes to add a new stream, signaled by the {{{SIPSessionGotStreamProposal}}} notification, the application can use this method to accept the stream(s) being proposed. |
195 | 26 | Luci Stanescu | After calling this method a {{{SIPSessionAcceptedStreamProposal}}} notification is sent, unless an error occurs while setting up the new stream, in which case a {{{SIPSessionRejectedStreamProposal}}} notification is sent and a rejection is sent to the remote party. |
196 | 1 | Adrian Georgescu | This method may only be called while in the {{{PROPOSED}}} state. |
197 | 19 | Ruud Klaver | [[BR]]''audio'':[[BR]] |
198 | 19 | Ruud Klaver | A boolean indicating whether an audio stream should be accepted for this proposal. |
199 | 19 | Ruud Klaver | Note that this may only be set to {{{True}}} if an audio stream was actually proposed by the remote party. |
200 | 19 | Ruud Klaver | [[BR]]''chat'':[[BR]] |
201 | 19 | Ruud Klaver | A boolean indicating whether a chat stream should be accepted for this proposal. |
202 | 19 | Ruud Klaver | Note that this may only be set to {{{True}}} if a chat stream was actually proposed by the remote party. |
203 | 26 | Luci Stanescu | '''reject_proposal'''(''self''):: |
204 | 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 {{{SIPSessionRejectedStreamProposal}}} notification is sent. |
205 | 1 | Adrian Georgescu | This method may only be called while in the {{{PROPOSED}}} state. |
206 | 41 | Ruud Klaver | '''end'''(''self'' '''is_busy'''={{{False}}}):: |
207 | 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. |
208 | 1 | Adrian Georgescu | Right before termination a {{{SIPSessionWillEnd}}} notification is sent, after termination {{{SIPSessionDidEnd}}} is sent. |
209 | 41 | Ruud Klaver | [[BR]]''chat'':[[BR]] |
210 | 41 | Ruud Klaver | A boolean indicating whether the response code sent to the remote party should be 486 (Busy) instead of 603 (Decline). |
211 | 1 | Adrian Georgescu | |
212 | 1 | Adrian Georgescu | ==== notifications ==== |
213 | 1 | Adrian Georgescu | |
214 | 26 | Luci Stanescu | '''SIPSessionChangedState''':: |
215 | 1 | Adrian Georgescu | Will be sent whenever the {{{Session}}} object changes its state. |
216 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
217 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
218 | 1 | Adrian Georgescu | [[BR]]''prev_state'':[[BR]] |
219 | 1 | Adrian Georgescu | The previous state state the object was in. |
220 | 1 | Adrian Georgescu | [[BR]]''state'':[[BR]] |
221 | 1 | Adrian Georgescu | The new state the object is in. |
222 | 26 | Luci Stanescu | '''SIPSessionNewIncoming''':: |
223 | 1 | Adrian Georgescu | Will be sent when a new incoming {{{Session}}} is received. |
224 | 1 | Adrian Georgescu | The application should listen for this notification from all objects specifically to get informed of incoming sessions. |
225 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
226 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
227 | 19 | Ruud Klaver | [[BR]]''streams'':[[BR]] |
228 | 19 | Ruud Klaver | A list of strings indicating the streams that were proposed by the remote party. |
229 | 26 | Luci Stanescu | '''SIPSessionNewOutgoing''':: |
230 | 1 | Adrian Georgescu | Will be sent when the applcation requests a new outgoing {{{Session}}}. |
231 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
232 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
233 | 19 | Ruud Klaver | [[BR]]''streams'':[[BR]] |
234 | 32 | Adrian Georgescu | A list of strings indicating the streams that were proposed to the remote party. |
235 | 26 | Luci Stanescu | '''SIPSessionGotRingIndication''':: |
236 | 1 | Adrian Georgescu | Will be sent when an outgoing {{{Session}}} receives an indication that a remote device is ringing. |
237 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
238 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
239 | 26 | Luci Stanescu | '''SIPSessionWillStart''':: |
240 | 1 | Adrian Georgescu | Will be sent just before a {{{Session}}} completes negotiation. |
241 | 1 | Adrian Georgescu | In terms of SIP, this is sent after the final response to the {{{INVITE}}}, but before the {{{ACK}}}. |
242 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
243 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
244 | 26 | Luci Stanescu | '''SIPSessionDidStart''':: |
245 | 1 | Adrian Georgescu | Will be sent when a {{{Session}}} completes negotiation. |
246 | 1 | Adrian Georgescu | In terms of SIP this is sent after the {{{ACK}}} was sent or received. |
247 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
248 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
249 | 26 | Luci Stanescu | '''SIPSessionDidFail''':: |
250 | 1 | Adrian Georgescu | This notification is sent whenever the session fails. |
251 | 1 | Adrian Georgescu | The failure reason is included in the data attributes. |
252 | 26 | Luci Stanescu | This notification is always followed by {{{SIPSessionDidEnd}}}. |
253 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
254 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
255 | 1 | Adrian Georgescu | [[BR]]''originator'':[[BR]] |
256 | 1 | Adrian Georgescu | A string indicating the origin of the failure. |
257 | 1 | Adrian Georgescu | This will either be "local" or "remote". |
258 | 1 | Adrian Georgescu | [[BR]]''code'':[[BR]] |
259 | 1 | Adrian Georgescu | The SIP error code of the failure. |
260 | 1 | Adrian Georgescu | If this is 0, the error was an internal exception. |
261 | 1 | Adrian Georgescu | [[BR]]''reason'':[[BR]] |
262 | 1 | Adrian Georgescu | A string explaining the reason of the failure. |
263 | 26 | Luci Stanescu | '''SIPSessionWillEnd''':: |
264 | 1 | Adrian Georgescu | Will be sent just before terminating a {{{Session}}} at the request of the application. |
265 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
266 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
267 | 26 | Luci Stanescu | '''SIPSessionDidEnd''':: |
268 | 26 | Luci Stanescu | Will be sent always when a {{{Session}}} ends, either because of a failure (in which case it is preceded by {{{SIPSessionDidFail}}}), remote or local session termination. |
269 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
270 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
271 | 1 | Adrian Georgescu | [[BR]]''originator'':[[BR]] |
272 | 1 | Adrian Georgescu | A string indicating who originated the termination. |
273 | 1 | Adrian Georgescu | This will either be "local" or "remote". |
274 | 26 | Luci Stanescu | '''SIPSessionGotHoldRequest''':: |
275 | 1 | Adrian Georgescu | Will be sent when the session got put on hold, either by the local or the remote party. |
276 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
277 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
278 | 1 | Adrian Georgescu | [[BR]]''originator'':[[BR]] |
279 | 1 | Adrian Georgescu | A string indicating who originated the hold request, and consequently in which direction the session got put on hold. |
280 | 26 | Luci Stanescu | '''SIPSessionGotUnholdRequest''':: |
281 | 1 | Adrian Georgescu | Will be sent when the session got taken out of hold, either by the local or the remote party. |
282 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
283 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
284 | 1 | Adrian Georgescu | [[BR]]''originator'':[[BR]] |
285 | 1 | Adrian Georgescu | A string indicating who sent the original hold request, and consequently in which direction the session got taken out of hold. |
286 | 26 | Luci Stanescu | '''SIPSessionWillStartRecordingAudio''':: |
287 | 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. |
288 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
289 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
290 | 1 | Adrian Georgescu | [[BR]]''file_name'':[[BR]] |
291 | 1 | Adrian Georgescu | The name of the recording {{{.wav}}} file, including full path. |
292 | 26 | Luci Stanescu | '''SIPSessionDidStartRecordingAudio''':: |
293 | 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. |
294 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
295 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
296 | 1 | Adrian Georgescu | [[BR]]''file_name'':[[BR]] |
297 | 1 | Adrian Georgescu | The name of the recording {{{.wav}}} file, including full path. |
298 | 26 | Luci Stanescu | '''SIPSessionWillStopRecordingAudio''':: |
299 | 1 | Adrian Georgescu | Will be sent when the application requested ending the recording to a {{{.wav}}} file, just before recording stops. |
300 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
301 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
302 | 1 | Adrian Georgescu | [[BR]]''file_name'':[[BR]] |
303 | 1 | Adrian Georgescu | The name of the recording {{{.wav}}} file, including full path. |
304 | 26 | Luci Stanescu | '''SIPSessionDidStopRecordingAudio''':: |
305 | 1 | Adrian Georgescu | Will be sent when the application requested ending the recording to a {{{.wav}}} file, just before recording stops. |
306 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
307 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
308 | 1 | Adrian Georgescu | [[BR]]''file_name'':[[BR]] |
309 | 1 | Adrian Georgescu | The name of the recording {{{.wav}}} file, including full path. |
310 | 26 | Luci Stanescu | '''SIPSessionGotNoAudio''':: |
311 | 1 | Adrian Georgescu | This notification will be sent if 5 seconds after the audio stream starts, no audio was received from the remote party. |
312 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
313 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
314 | 26 | Luci Stanescu | '''SIPSessionGotDTMF''':: |
315 | 1 | Adrian Georgescu | Will be send if there is a DMTF digit received from the remote party on the audio stream. |
316 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
317 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
318 | 1 | Adrian Georgescu | [[BR]]''digit'':[[BR]] |
319 | 1 | Adrian Georgescu | The DTMF digit that was received, in the form of a string of length 1. |
320 | 26 | Luci Stanescu | '''SIPSessionGotMessage''':: |
321 | 1 | Adrian Georgescu | Will be sent whenever a MSRP message is received on the chat stream of the session. |
322 | 1 | Adrian Georgescu | [[BR]]''content'':[[BR]] |
323 | 1 | Adrian Georgescu | The body of the message. |
324 | 1 | Adrian Georgescu | [[BR]]''content_type'':[[BR]] |
325 | 1 | Adrian Georgescu | The Content-Type of the body. |
326 | 1 | Adrian Georgescu | [[BR]]''cpim_headers'':[[BR]] |
327 | 1 | Adrian Georgescu | A dictionary of headers included in the CPIM wrapper. |
328 | 1 | Adrian Georgescu | [[BR]]''message'':[[BR]] |
329 | 5 | Redmine Admin | Raw MSRP message, an msrplib.protocol.MSRPData instance |
330 | 26 | Luci Stanescu | '''SIPSessionDidDeliverMessage''':: |
331 | 1 | Adrian Georgescu | Will be sent when a previously sent MSRP chat message got delivered to the remote party. |
332 | 1 | Adrian Georgescu | [[BR]]''message_id'':[[BR]] |
333 | 1 | Adrian Georgescu | The unique identifier of this message as a string, as previously returned by the {{{send_message()}}} method. |
334 | 1 | Adrian Georgescu | [[BR]]''code'':[[BR]] |
335 | 1 | Adrian Georgescu | The response code of the confirmation report. |
336 | 1 | Adrian Georgescu | [[BR]]''reason'':[[BR]] |
337 | 5 | Redmine Admin | The reason string of the confirmation report. |
338 | 1 | Adrian Georgescu | [[BR]]''message'':[[BR]] |
339 | 1 | Adrian Georgescu | Raw MSRP message, an msrplib.protocol.MSRPData instance |
340 | 26 | Luci Stanescu | '''SIPSessionDidDeliverMessage''':: |
341 | 1 | Adrian Georgescu | Will be sent when a previously sent MSRP chat message did not get delivered to the remote party. |
342 | 1 | Adrian Georgescu | [[BR]]''message_id'':[[BR]] |
343 | 1 | Adrian Georgescu | The unique identifier of this message as a string, as previously returned by the {{{send_message()}}} method. |
344 | 1 | Adrian Georgescu | [[BR]]''code'':[[BR]] |
345 | 1 | Adrian Georgescu | The response code of the confirmation report. |
346 | 1 | Adrian Georgescu | [[BR]]''reason'':[[BR]] |
347 | 5 | Redmine Admin | The reason string of the confirmation report. |
348 | 1 | Adrian Georgescu | [[BR]]''message'':[[BR]] |
349 | 1 | Adrian Georgescu | Raw MSRP message, an msrplib.protocol.MSRPData instance |
350 | 26 | Luci Stanescu | '''SIPSessionGotStreamProposal''':: |
351 | 1 | Adrian Georgescu | Will be sent when either the local or the remote party proposes to add a stream to the session. |
352 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
353 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
354 | 1 | Adrian Georgescu | [[BR]]''proposer'':[[BR]] |
355 | 1 | Adrian Georgescu | The party that did the stream proposal, can be either "local" or "remote". |
356 | 19 | Ruud Klaver | [[BR]]''streams'':[[BR]] |
357 | 19 | Ruud Klaver | A list of strings indicating the streams that were proposed. |
358 | 26 | Luci Stanescu | '''SIPSessionRejectedStreamProposal''':: |
359 | 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. |
360 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
361 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
362 | 1 | Adrian Georgescu | [[BR]]''proposer'':[[BR]] |
363 | 1 | Adrian Georgescu | The party that did the stream proposal, can be either "local" or "remote". |
364 | 1 | Adrian Georgescu | [[BR]]''reason'':[[BR]] |
365 | 1 | Adrian Georgescu | The reason for rejecting the stream proposal. |
366 | 1 | Adrian Georgescu | '''SIPSessionRejectedStreamProposal''':: |
367 | 26 | Luci Stanescu | Will be sent when either the local or the remote party accepts a proposal to have (a) stream(s) added to the session. |
368 | 1 | Adrian Georgescu | [[BR]]''timestamp'':[[BR]] |
369 | 1 | Adrian Georgescu | A {{{datetime.datetime}}} object indicating when the notification was sent. |
370 | 1 | Adrian Georgescu | [[BR]]''proposer'':[[BR]] |
371 | 1 | Adrian Georgescu | The party that did the stream proposal, can be either "local" or "remote". |
372 | 1 | Adrian Georgescu | '''SIPSessionGotStreamUpdate''':: |
373 | 26 | Luci Stanescu | Will be sent when a media stream is either activated or deactivated. |
374 | 23 | Ruud Klaver | An application should listen to this notification in order to know when a media stream can be used. |
375 | 23 | Ruud Klaver | [[BR]]''timestamp'':[[BR]] |
376 | 23 | Ruud Klaver | A {{{datetime.datetime}}} object indicating when the notification was sent. |
377 | 23 | Ruud Klaver | [[BR]]''streams'':[[BR]] |
378 | 23 | Ruud Klaver | A list indicating which streams are active on the session from this point onwards. |
379 | 23 | Ruud Klaver | |
380 | 30 | Adrian Georgescu | As an example for how to use the {{{Session}}} object, the following provides a basic Python program that initiates an outgoing SIP session request: |
381 | 6 | Ruud Klaver | |
382 | 6 | Ruud Klaver | {{{ |
383 | 24 | Ruud Klaver | import sys |
384 | 6 | Ruud Klaver | from threading import Event |
385 | 6 | Ruud Klaver | from zope.interface import implements |
386 | 6 | Ruud Klaver | from application.notification import IObserver, NotificationCenter |
387 | 1 | Adrian Georgescu | |
388 | 24 | Ruud Klaver | from sipsimple.configuration import ConfigurationManager |
389 | 24 | Ruud Klaver | from sipsimple.account import AccountManager |
390 | 24 | Ruud Klaver | from sipsimple.engine import Engine |
391 | 24 | Ruud Klaver | from sipsimple.session import Session |
392 | 24 | Ruud Klaver | from sipsimple.core import SIPURI, Route |
393 | 24 | Ruud Klaver | |
394 | 1 | Adrian Georgescu | class SimpleOutboundCall(object): |
395 | 1 | Adrian Georgescu | # indicate that we implement the application.notification.IObserver interface |
396 | 1 | Adrian Georgescu | implements(IObserver) |
397 | 1 | Adrian Georgescu | |
398 | 24 | Ruud Klaver | def __init__(self, remote_uri, route): |
399 | 1 | Adrian Georgescu | # setup a threading.Event to signal that the Engine has stopped |
400 | 1 | Adrian Georgescu | self.engine_ended_event = Event() |
401 | 24 | Ruud Klaver | # start the configuration manager |
402 | 24 | Ruud Klaver | ConfigurationManager().start() |
403 | 24 | Ruud Klaver | # start the account manager |
404 | 24 | Ruud Klaver | am = AccountManager() |
405 | 24 | Ruud Klaver | am.start() |
406 | 24 | Ruud Klaver | # start the Engine with configuration framework parameters |
407 | 24 | Ruud Klaver | Engine().start_cfg() |
408 | 24 | Ruud Klaver | # create a new Session using the default account |
409 | 24 | Ruud Klaver | self.session = Session(am.default_account) |
410 | 6 | Ruud Klaver | # listen for the notification that the Engine stopped |
411 | 26 | Luci Stanescu | NotificationCenter().add_observer(self, "SIPEngineDidEnd", Engine()) |
412 | 6 | Ruud Klaver | # listen for the notification that the Session ended |
413 | 26 | Luci Stanescu | NotificationCenter().add_observer(self, "SIPSessionDidEnd", self.session) |
414 | 6 | Ruud Klaver | # start a new outbound session |
415 | 24 | Ruud Klaver | self.session.connect(remote_uri, [route], audio=True) |
416 | 6 | Ruud Klaver | |
417 | 23 | Ruud Klaver | def end(self): |
418 | 6 | Ruud Klaver | # if the Session is still active, terminate it |
419 | 6 | Ruud Klaver | self.session.end() |
420 | 6 | Ruud Klaver | # wait for the engine to stop, processed in handle_notification |
421 | 6 | Ruud Klaver | self.engine_ended_event.wait() |
422 | 6 | Ruud Klaver | # quit the progam, as this can only be done from the main thread |
423 | 6 | Ruud Klaver | sys.exit() |
424 | 6 | Ruud Klaver | |
425 | 1 | Adrian Georgescu | def handle_notification(self, notification): |
426 | 1 | Adrian Georgescu | if notification.name == "SIPSessionDidEnd": |
427 | 1 | Adrian Georgescu | # if for whatever reason the session ended, stop the Engine |
428 | 1 | Adrian Georgescu | print "Session ended" |
429 | 1 | Adrian Georgescu | Engine().stop() |
430 | 1 | Adrian Georgescu | elif notification.name == "SIPEngineDidEnd": |
431 | 1 | Adrian Georgescu | # once the Engine has stopped, signal the (possibly) waiting main |
432 | 1 | Adrian Georgescu | # thread through a threading.Event |
433 | 1 | Adrian Georgescu | self.engine_ended_event.set() |
434 | 1 | Adrian Georgescu | |
435 | 1 | Adrian Georgescu | # place an audio call from the specified account to the specified URI, through |
436 | 1 | Adrian Georgescu | # the specified SIP proxy |
437 | 1 | Adrian Georgescu | # edit this to reflect real settings |
438 | 1 | Adrian Georgescu | call = SimpleOutboundCall(SIPURI(user="bob", host="example.com"), Route("1.2.3.4")) |
439 | 1 | Adrian Georgescu | # block waiting for user input |
440 | 1 | Adrian Georgescu | print "Placing call, press enter to quit program" |
441 | 1 | Adrian Georgescu | raw_input() |
442 | 1 | Adrian Georgescu | # block in end() until the Engine has stopped |
443 | 26 | Luci Stanescu | call.end() |
444 | 6 | Ruud Klaver | }}} |
445 | 30 | Adrian Georgescu | |
446 | 30 | Adrian Georgescu | === SessionManager === |
447 | 30 | Adrian Georgescu | |
448 | 31 | Adrian Georgescu | The {{{sipsimple.session.SessionManager}}} class is a singleton, which acts as the central aggregation point for sessions within the middleware. |
449 | 30 | Adrian Georgescu | Although it is mainly used internally, the application can use it to query information about all active sessions. |
450 | 30 | Adrian Georgescu | The SessionManager is implemented as a singleton, meaning that only one instance of this class exists within the middleware. |
451 | 30 | Adrian Georgescu | Note that, in order to be able to receive calls, the application has to instantiate this object. |
452 | 30 | Adrian Georgescu | |
453 | 30 | Adrian Georgescu | ==== attributes ==== |
454 | 30 | Adrian Georgescu | |
455 | 30 | Adrian Georgescu | '''sessions''':: |
456 | 30 | 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. |
457 | 30 | Adrian Georgescu | |
458 | 30 | Adrian Georgescu | ==== methods ==== |
459 | 30 | Adrian Georgescu | |
460 | 30 | Adrian Georgescu | '''!__init!__'''(''self''):: |
461 | 30 | Adrian Georgescu | This either returns a new {{{SessionManager}}} object with default configuration objects, or returns a copy of the already existing instance. |
462 | 35 | Luci Stanescu | |
463 | 35 | Luci Stanescu | |
464 | 35 | Luci Stanescu | === Account === |
465 | 35 | Luci Stanescu | |
466 | 40 | Luci Stanescu | The {{{sipsimple.account.Account}}} objects represent the SIP accounts which are used by the middleware. 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]. |
467 | 35 | Luci Stanescu | |
468 | 35 | 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}}}. |
469 | 35 | Luci Stanescu | |
470 | 36 | Luci Stanescu | ==== states ==== |
471 | 35 | Luci Stanescu | |
472 | 35 | 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: |
473 | 35 | Luci Stanescu | {{{ |
474 | 35 | Luci Stanescu | account.enabled = True |
475 | 35 | Luci Stanescu | account.save() |
476 | 35 | Luci Stanescu | }}} |
477 | 35 | Luci Stanescu | |
478 | 37 | 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. |
479 | 37 | Luci Stanescu | |
480 | 39 | 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. |
481 | 39 | Luci Stanescu | |
482 | 35 | 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: |
483 | 35 | Luci Stanescu | |
484 | 35 | Luci Stanescu | '''Account.registration.enabled''':: |
485 | 35 | 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. |
486 | 35 | Luci Stanescu | '''Account.presence.enabled''':: |
487 | 35 | 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) |
488 | 35 | Luci Stanescu | '''Account.dialog_event.enabled''':: |
489 | 35 | 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) |
490 | 35 | Luci Stanescu | '''Account.message_summary.enabled''':: |
491 | 35 | Luci Stanescu | This flag controls the automatic subscription to the ''message-summary'' event in order to find out about voicemail messages. (Not implemented yet) |
492 | 1 | Adrian Georgescu | |
493 | 39 | 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]. |
494 | 36 | Luci Stanescu | |
495 | 36 | Luci Stanescu | ==== attributes ==== |
496 | 36 | Luci Stanescu | |
497 | 36 | Luci Stanescu | The following attributes can be used on an Account object and need to be considered read-only. |
498 | 36 | Luci Stanescu | |
499 | 36 | Luci Stanescu | '''id''':: |
500 | 36 | 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}}}. |
501 | 36 | Luci Stanescu | {{{ |
502 | 36 | Luci Stanescu | account.id # 'alice@example.com' |
503 | 36 | Luci Stanescu | account.id.username # 'alice' |
504 | 36 | Luci Stanescu | account.id.domain # 'example.com' |
505 | 36 | Luci Stanescu | }}} |
506 | 36 | Luci Stanescu | '''contact''':: |
507 | 36 | 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). |
508 | 36 | Luci Stanescu | {{{ |
509 | 36 | Luci Stanescu | account.contact # 'hnfkybrt@10.0.0.1' |
510 | 36 | Luci Stanescu | account.contact.username # 'hnfkybrt' |
511 | 36 | Luci Stanescu | account.contact.domain # '10.0.0.1' |
512 | 36 | Luci Stanescu | account.contact['udp'] # <SIPURI "sip:hnfkybrt@10.0.0.1:53024"> |
513 | 36 | Luci Stanescu | account.contact['tls'] # <SIPURI "sip:hnfkybrt@10.0.0.1:54478;transport=tls"> |
514 | 36 | Luci Stanescu | }}} |
515 | 36 | Luci Stanescu | '''credentials''':: |
516 | 36 | Luci Stanescu | This attribute is of type {{{sipsimple.core.Credentials}}} object which is built from the {{{id}}} attribute and {{{display_name}}} and {{{password}}} settings of the Account. Whenever one of these settings are changed, this attribute is updated. |
517 | 36 | Luci Stanescu | {{{ |
518 | 36 | Luci Stanescu | account.credentials # <Credentials for '"Alice" <sip:alice@example.com>'> |
519 | 36 | Luci Stanescu | }}} |
520 | 37 | Luci Stanescu | |
521 | 37 | Luci Stanescu | ==== notifications ==== |
522 | 37 | Luci Stanescu | |
523 | 37 | Luci Stanescu | '''CFGSettingsObjectDidChange''':: |
524 | 37 | 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]. |
525 | 37 | Luci Stanescu | '''SIPAccountDidActivate''':: |
526 | 37 | 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. The notification does not contain any data. |
527 | 37 | Luci Stanescu | '''SIPAccountDidDeactivate''':: |
528 | 37 | 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}}}. The notification does not contain any data. |
529 | 37 | Luci Stanescu | '''SIPAccountRegistrationDidSucceed''':: |
530 | 37 | 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: |
531 | 37 | Luci Stanescu | [[BR]]''code'':[[BR]] |
532 | 37 | Luci Stanescu | The status code of the response for the REGISTER request. |
533 | 37 | Luci Stanescu | [[BR]]''reason'':[[BR]] |
534 | 37 | Luci Stanescu | The reason of the response for the REGISTER request. |
535 | 37 | Luci Stanescu | [[BR]]''contact_uri'':[[BR]] |
536 | 37 | Luci Stanescu | The Contact URI which was registered. |
537 | 37 | Luci Stanescu | [[BR]]''contact_uri_list'':[[BR]] |
538 | 37 | Luci Stanescu | A list containing all the contact URIs registered for this SIP account. |
539 | 37 | Luci Stanescu | [[BR]]''expires'':[[BR]] |
540 | 37 | Luci Stanescu | The amount in seconds in which this registration will expire. |
541 | 37 | Luci Stanescu | [[BR]]''registration'':[[BR]] |
542 | 37 | Luci Stanescu | The {{{sipsimple.core.Registration}}} object used to register this account. |
543 | 37 | Luci Stanescu | '''SIPAccountRegistrationDidFail''':: |
544 | 37 | Luci Stanescu | 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: |
545 | 37 | Luci Stanescu | [[BR]]''code'':[[BR]] |
546 | 37 | Luci Stanescu | The status code of the response for the REGISTER request. This is only present if the notification is sent as a result of a response being received. |
547 | 37 | Luci Stanescu | [[BR]]''reason'':[[BR]] |
548 | 37 | Luci Stanescu | The reason for the failure of the REGISTER request. |
549 | 37 | Luci Stanescu | [[BR]]''registration'':[[BR]] |
550 | 37 | Luci Stanescu | The {{{sipsimple.core.Registration}}} object which failed. |
551 | 37 | Luci Stanescu | [[BR]]''next_route'':[[BR]] |
552 | 37 | Luci Stanescu | A {{{sipsimple.core.Route}}} object which will be tried next for registering the account, or {{{None}}} if a new DNS lookup needs to be performed. |
553 | 37 | Luci Stanescu | [[BR]]''delay'':[[BR]] |
554 | 37 | Luci Stanescu | The amount in seconds as a {{{float}}} after which the next route will be tried for registering the account. |
555 | 37 | Luci Stanescu | '''SIPAccountRegistrationDidEnd''':: |
556 | 37 | Luci Stanescu | This notification is sent when a registration is ended (the account is unregistered). The data contained in this notification is: |
557 | 37 | Luci Stanescu | [[BR]]''code'':[[BR]] |
558 | 37 | Luci Stanescu | The status code of the response for the REGISTER with {{{Expires: 0}}} request. This is only present if a response was received. |
559 | 37 | Luci Stanescu | [[BR]]''reason'':[[BR]] |
560 | 37 | Luci Stanescu | The reason returned in the response for the Register with {{{Expires: 0}}} request. This is only present if a response was received |
561 | 37 | Luci Stanescu | [[BR]]''registration'':[[BR]] |
562 | 37 | Luci Stanescu | The {{{sipsimple.core.Registration}}} object which ended. |
563 | 37 | Luci Stanescu | |
564 | 37 | Luci Stanescu | === BonjourAccount === |
565 | 37 | Luci Stanescu | |
566 | 37 | Luci Stanescu | The {{{sipsimple.account.BonjourAccount}}} represents the SIP account used for P2P mode; it does not interact with any server. The class is a singleton, as there can only be one such account on a system. Similar to the {{{Account}}}, it is used both as a complex object, which implements the functions for bonjour mode, as well as a container for the related settings. |
567 | 37 | Luci Stanescu | |
568 | 37 | Luci Stanescu | ==== states ==== |
569 | 37 | Luci Stanescu | |
570 | 38 | Luci Stanescu | The {{{BonjourAccount}}} has an {{{enabled}}} flags which controls whether this account will be used or not. If it is set to {{{False}}}, none of the internal functions will be activated and, in addition, the account should not be used by the application. The bonjour account can only activated if the Engine is running; once it is started, if the enabled flag is set, the account will activate. When the {{{BonjourAccount}}} is activated, it will broadcast the contact address on the LAN. (Not implemented yet) |
571 | 38 | Luci Stanescu | |
572 | 38 | Luci Stanescu | ==== attributes ==== |
573 | 38 | Luci Stanescu | |
574 | 38 | Luci Stanescu | The following attributes can be used on an BonjourAccount object and need to be considered read-only. |
575 | 38 | Luci Stanescu | |
576 | 38 | Luci Stanescu | '''id''':: |
577 | 38 | Luci Stanescu | 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}}}. |
578 | 38 | Luci Stanescu | {{{ |
579 | 38 | Luci Stanescu | bonjour_account.id # 'bonjour@local' |
580 | 38 | Luci Stanescu | bonjour_account.id.username # 'bonjour' |
581 | 38 | Luci Stanescu | bonjour_account.id.domain # 'local' |
582 | 38 | Luci Stanescu | }}} |
583 | 38 | Luci Stanescu | '''contact''':: |
584 | 38 | 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). |
585 | 38 | Luci Stanescu | {{{ |
586 | 38 | Luci Stanescu | account.contact # 'lxzvgack@10.0.0.1' |
587 | 38 | Luci Stanescu | account.contact.username # 'lxzvgack' |
588 | 38 | Luci Stanescu | account.contact.domain # '10.0.0.1' |
589 | 38 | Luci Stanescu | account.contact['udp'] # <SIPURI "sip:lxzvgack@10.0.0.1:53024"> |
590 | 38 | Luci Stanescu | account.contact['tls'] # <SIPURI "sip:lxzvgack@10.0.0.1:54478;transport=tls"> |
591 | 38 | Luci Stanescu | }}} |
592 | 38 | Luci Stanescu | '''credentials''':: |
593 | 38 | Luci Stanescu | This attribute is of type {{{sipsimple.core.Credentials}}} object which is built from the {{{contact}}} attribute and {{{display_name}}} setting of the BonjourAccount; the password is set to the empty string. Whenever the display_name setting is changed, this attribute is updated. |
594 | 38 | Luci Stanescu | {{{ |
595 | 38 | Luci Stanescu | account.credentials # <Credentials for '"Alice" <sip:lxzvgack@10.0.0.1>'> |
596 | 1 | Adrian Georgescu | }}} |
597 | 39 | Luci Stanescu | |
598 | 39 | Luci Stanescu | ==== notifications ==== |
599 | 39 | Luci Stanescu | |
600 | 39 | Luci Stanescu | '''CFGSettingsObjectDidChange''':: |
601 | 39 | 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]. |
602 | 39 | Luci Stanescu | '''SIPAccountDidActivate''':: |
603 | 39 | Luci Stanescu | This notification is sent when the {{{BonjourAccount}}} activates. This can happen when the {{{BonjourAccount}}} is loaded if it's enabled flag is set and the Engine is running, and at any later time when the status of the Engine changes or the enabled flag is modified. The notification does not contain any data. |
604 | 39 | Luci Stanescu | '''SIPAccountDidDeactivate''':: |
605 | 39 | Luci Stanescu | This notification is sent when the {{{BonjourAccount}}} deactivates. This can happend when the {{{Engine}}} is stopped or when the enabled flag of the account is set to {{{False}}}. The notification does not contain any data. |
606 | 39 | Luci Stanescu | |
607 | 39 | Luci Stanescu | |
608 | 39 | Luci Stanescu | === AccountManager === |
609 | 39 | Luci Stanescu | |
610 | 39 | Luci Stanescu | 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. |
611 | 39 | Luci Stanescu | |
612 | 39 | Luci Stanescu | ==== methods ==== |
613 | 39 | Luci Stanescu | |
614 | 39 | Luci Stanescu | '''!__init!__'''(''self''):: |
615 | 39 | Luci Stanescu | 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. |
616 | 39 | Luci Stanescu | '''start'''(''self''):: |
617 | 39 | Luci Stanescu | This method will load all the existing accounts from the configuration. If the Engine is running, the accounts will also activate. This method can only be called after the [wiki:SipConfigurationAPI#ConfigurationManager ConfigurationManager] has been started. A '''SIPAccountManagerDidAddAccount''' will be sent for each account loaded. |
618 | 39 | Luci Stanescu | '''stop'''(''self''):: |
619 | 39 | Luci Stanescu | Calling this method will deactivate all accounts managed by the {{{AccountManager}}}. |
620 | 39 | Luci Stanescu | '''has_account'''(''self'', '''id'''):: |
621 | 39 | Luci Stanescu | This method returns {{{True}}} if an account which has the specifed SIP ID (must be a string) exists and {{{False}}} otherwise. |
622 | 39 | Luci Stanescu | '''get_account'''(''self'', '''id'''):: |
623 | 39 | Luci Stanescu | 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. |
624 | 39 | Luci Stanescu | '''get_accounts'''(''self''):: |
625 | 39 | Luci Stanescu | Returns a list containing all the managed accounts. |
626 | 39 | Luci Stanescu | '''iter_accounts'''(''self''):: |
627 | 39 | Luci Stanescu | Returns an iterator through all the managed accounts. |
628 | 39 | Luci Stanescu | '''find_account'''(''self'', '''contact_uri'''):: |
629 | 39 | Luci Stanescu | 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. |
630 | 39 | Luci Stanescu | |
631 | 39 | Luci Stanescu | ==== notifications ==== |
632 | 39 | Luci Stanescu | |
633 | 39 | Luci Stanescu | '''SIPAccountManagerDidAddAccount''':: |
634 | 39 | Luci Stanescu | This notification is sent when a new account becomes available to the {{{AccountManager}}}. The notification is also sent when the accounts are loaded from the configuration. The data contains a single attribute, {{{account}}} which is the account object which was added. |
635 | 39 | Luci Stanescu | '''SIPAccountManagerDidRemoveAccount''':: |
636 | 39 | Luci Stanescu | This notification is sent when an account is deleted using the {{{delete}}} method. The data contains a single attribute, {{{account}}} which is the account object which was deleted. |
637 | 39 | Luci Stanescu | '''SIPAccountManagerDidChangeDefaultAccount''':: |
638 | 39 | Luci Stanescu | This notification is sent when the default account changes. The notification contains two attributes: |
639 | 39 | Luci Stanescu | [[BR]]''old_account'':[[BR]] |
640 | 39 | Luci Stanescu | This is the account object which used to be the default account. |
641 | 39 | Luci Stanescu | [[BR]]''account'':[[BR]] |
642 | 39 | Luci Stanescu | This is the account object which is the new default account. |