SipMSRPApi
Version 64 (Anonymous, 06/28/2011 02:28 pm)
1 | 1 | Adrian Georgescu | |
---|---|---|---|
2 | 64 | Adrian Georgescu | h1. MSRP API |
3 | 1 | Adrian Georgescu | |
4 | 64 | Adrian Georgescu | |
5 | 64 | Adrian Georgescu | |
6 | 64 | Adrian Georgescu | |
7 | 1 | Adrian Georgescu | Message Session Relay Protocol (MSRP) is a protocol for transmitting a series of related Instant Messages in the context of a session. Message sessions are treated like any other media stream when set up via a rendezvous or session creation protocol such as the Session Initiation Protocol (SIP). MSRP can be used for any application that requires a reliable stream of data, for example File Transfer or Desktop Sharing. |
8 | 1 | Adrian Georgescu | |
9 | 64 | Adrian Georgescu | * MSRP sessions are defined in "RFC 4975":http://tools.ietf.org/html/rfc4975 |
10 | 64 | Adrian Georgescu | * MSRP relay extension for NAT traversal is defined in "RFC 4976":http://tools.ietf.org/html/rfc4976 |
11 | 1 | Adrian Georgescu | |
12 | 64 | Adrian Georgescu | The MSRP protocol stack is implemented by "python-msrplib":http://download.ag-projects.com/SipClient package. |
13 | 1 | Adrian Georgescu | |
14 | 64 | Adrian Georgescu | @msrplib@ is based upon "twisted":http://twistedmatrix.com and "eventlet":http://download.ag-projects.com/SipClient/ and provides a set of classes for establishing and managing MSRP connections. |
15 | 1 | Adrian Georgescu | |
16 | 1 | Adrian Georgescu | The library consists of the following modules: |
17 | 1 | Adrian Georgescu | |
18 | 64 | Adrian Georgescu | *msrplib.transport* |
19 | 64 | Adrian Georgescu | Defines @MSRPTransport@ class, which provides low level control over MSRP connections. |
20 | 1 | Adrian Georgescu | |
21 | 64 | Adrian Georgescu | *msrplib.connect* |
22 | 64 | Adrian Georgescu | Defines means to establish a connection, bind it, and provide an initialized @MSRPTransport@ instance. |
23 | 1 | Adrian Georgescu | |
24 | 64 | Adrian Georgescu | *msrplib.session* |
25 | 64 | Adrian Georgescu | Defines @MSRPSession@ class, which provides high level control over a MSRP connection. |
26 | 1 | Adrian Georgescu | |
27 | 64 | Adrian Georgescu | *msrplib.protocol* |
28 | 1 | Adrian Georgescu | Provides representation and parsing of MSRP entities - chunks and MSRP URIs. |
29 | 1 | Adrian Georgescu | |
30 | 1 | Adrian Georgescu | |
31 | 64 | Adrian Georgescu | h2. URI |
32 | 1 | Adrian Georgescu | |
33 | 1 | Adrian Georgescu | |
34 | 64 | Adrian Georgescu | This class is implemented in the @msrplib.protocol@ module and is used to represent an MSRP URI. |
35 | 1 | Adrian Georgescu | |
36 | 1 | Adrian Georgescu | |
37 | 64 | Adrian Georgescu | h4. methods |
38 | 1 | Adrian Georgescu | |
39 | 1 | Adrian Georgescu | |
40 | 64 | Adrian Georgescu | *<notextile>__init__</notextile>*(_self_, *host*=@None@, *use_tls*=@False@, *user*=@None@, *port*=@None@, *session_id*=@None@, *parameters*=@None@, *credentials*=@None@) |
41 | 64 | Adrian Georgescu | >Constructs a new @URI@. All the arguments specified here are also attributes on the object. For more information on these attributes, see RFC4975. |
42 | 64 | Adrian Georgescu | |
43 | 64 | Adrian Georgescu | >+_host_+: |
44 | 1 | Adrian Georgescu | |
45 | 64 | Adrian Georgescu | >The hostname or IP address which forms the URI. |
46 | 64 | Adrian Georgescu | |
47 | 64 | Adrian Georgescu | >+_use_tls_+: |
48 | 1 | Adrian Georgescu | |
49 | 64 | Adrian Georgescu | >Whether this identifies an msrps or msrp URI. |
50 | 64 | Adrian Georgescu | |
51 | 64 | Adrian Georgescu | >+_user_+: |
52 | 1 | Adrian Georgescu | |
53 | 64 | Adrian Georgescu | >The user part of the URI. |
54 | 64 | Adrian Georgescu | |
55 | 64 | Adrian Georgescu | >+_port_+: |
56 | 1 | Adrian Georgescu | |
57 | 64 | Adrian Georgescu | >The port in the URI. |
58 | 64 | Adrian Georgescu | |
59 | 64 | Adrian Georgescu | >+_session_id_+: |
60 | 64 | Adrian Georgescu | |
61 | 64 | Adrian Georgescu | >The session identifier part of the URI. |
62 | 64 | Adrian Georgescu | |
63 | 64 | Adrian Georgescu | >+_parameters_+: |
64 | 64 | Adrian Georgescu | |
65 | 64 | Adrian Georgescu | >A @dict@ containing the parameters which will be appended to the URI. |
66 | 64 | Adrian Georgescu | |
67 | 64 | Adrian Georgescu | >+_credentials_+: |
68 | 64 | Adrian Georgescu | |
69 | 64 | Adrian Georgescu | >A @gnutls.interfaces.twisted.X509Credentials@ object which will be used if this identifies a TLS URI to authenticate to the other endpoint. |
70 | 64 | Adrian Georgescu | |
71 | 64 | Adrian Georgescu | |
72 | 64 | Adrian Georgescu | h2. MSRPRelaySettings |
73 | 64 | Adrian Georgescu | |
74 | 64 | Adrian Georgescu | |
75 | 64 | Adrian Georgescu | This class is implemented in the @msrplib.connect@ module and is used to specify the MSRP relay which will be used when connecting via a relay (using the @ConnectorRelay@ or @AcceptorRelay@ classes). |
76 | 64 | Adrian Georgescu | |
77 | 64 | Adrian Georgescu | |
78 | 64 | Adrian Georgescu | h4. methods |
79 | 64 | Adrian Georgescu | |
80 | 64 | Adrian Georgescu | |
81 | 64 | Adrian Georgescu | *<notextile>__init__</notextile>*(_self_, *domain*, *username*, *password*, *host*=@None@, *use_tls*=@False@, *port*=@None@, *credentials*=@None@) |
82 | 64 | Adrian Georgescu | >Constructs a new @URI@. All the arguments specified here are also attributes on the object. For more information on these attributes, see RFC4975. |
83 | 64 | Adrian Georgescu | |
84 | 64 | Adrian Georgescu | >+_domain_+: |
85 | 64 | Adrian Georgescu | |
86 | 64 | Adrian Georgescu | >The DNS domain in which to search for a MSRP relay using SRV queries. |
87 | 64 | Adrian Georgescu | |
88 | 64 | Adrian Georgescu | >+_username_+: |
89 | 64 | Adrian Georgescu | |
90 | 64 | Adrian Georgescu | >The username which will be used to authenticate to the relay. |
91 | 64 | Adrian Georgescu | |
92 | 64 | Adrian Georgescu | >+_password_+: |
93 | 64 | Adrian Georgescu | |
94 | 64 | Adrian Georgescu | >The password which will be used to authenticate to the relay. |
95 | 64 | Adrian Georgescu | |
96 | 64 | Adrian Georgescu | >+_host_+: |
97 | 64 | Adrian Georgescu | |
98 | 64 | Adrian Georgescu | >The hostname or IP address of the MSRP relay. |
99 | 64 | Adrian Georgescu | |
100 | 64 | Adrian Georgescu | >+_use_tls_+: |
101 | 64 | Adrian Georgescu | |
102 | 64 | Adrian Georgescu | >Whether this identifies an msrps or msrp URI. |
103 | 64 | Adrian Georgescu | |
104 | 64 | Adrian Georgescu | >+_port_+: |
105 | 64 | Adrian Georgescu | |
106 | 64 | Adrian Georgescu | >The port in the URI. |
107 | 64 | Adrian Georgescu | |
108 | 64 | Adrian Georgescu | >+_credentials_+: |
109 | 64 | Adrian Georgescu | |
110 | 64 | Adrian Georgescu | >A @gnutls.interfaces.twisted.X509Credentials@ object which will be used to authenticate to the relay if TLS is used. |
111 | 64 | Adrian Georgescu | |
112 | 64 | Adrian Georgescu | |
113 | 64 | Adrian Georgescu | h2. ConnectorDirect |
114 | 64 | Adrian Georgescu | |
115 | 64 | Adrian Georgescu | |
116 | 64 | Adrian Georgescu | This class is implemented in the @msrplib.connect@ module and is used for outbound MSRP connections without a relay. |
117 | 64 | Adrian Georgescu | |
118 | 64 | Adrian Georgescu | |
119 | 64 | Adrian Georgescu | h4. methods |
120 | 64 | Adrian Georgescu | |
121 | 64 | Adrian Georgescu | |
122 | 64 | Adrian Georgescu | *<notextile>__init__</notextile>*(_self_, *loger*=@None@, *use_sessmatch*=@False@) |
123 | 1 | Adrian Georgescu | Constructs a new ConnectorDirect. |
124 | 64 | Adrian Georgescu | |
125 | 64 | Adrian Georgescu | >+_logger_+: |
126 | 1 | Adrian Georgescu | |
127 | 64 | Adrian Georgescu | The logger which will be used for this MSRP connection. See the [[SipMSRPApi#Logging|Logging]] section for more information. |
128 | 64 | Adrian Georgescu | |
129 | 64 | Adrian Georgescu | >+_use_sessmatch_+: |
130 | 64 | Adrian Georgescu | |
131 | 64 | Adrian Georgescu | Indicates if the connector should use the session matching mechanism defined by the "sessmatch draft version 10":http://tools.ietf.org/html/draft-ietf-simple-msrp-sessmatch-10 |
132 | 64 | Adrian Georgescu | |
133 | 64 | Adrian Georgescu | *prepare*(_self_, *local_uri*=@None@) |
134 | 64 | Adrian Georgescu | This method returns a full local path - list of @protocol.URI@ instances, suitable to be put in SDP @'a:path'@ attribute. |
135 | 64 | Adrian Georgescu | |
136 | 64 | Adrian Georgescu | >+_local_uri_+: |
137 | 64 | Adrian Georgescu | |
138 | 1 | Adrian Georgescu | This attribute will be used to construct the local path, but other than that it is not used anywhere else in case of the ConnectorDirect. If not provided, one |
139 | 1 | Adrian Georgescu | will be automatically generated |
140 | 1 | Adrian Georgescu | |
141 | 64 | Adrian Georgescu | *complete*(_self_, *full_remote_path*) |
142 | 64 | Adrian Georgescu | This method establishes the connection and binds it (sends an empty chunk to verify each other's From-Path and To-Path). It returns @transport.MSRPTransport@ instance, ready to read and send chunks. |
143 | 64 | Adrian Georgescu | |
144 | 64 | Adrian Georgescu | >+_full_remote_path_+: |
145 | 1 | Adrian Georgescu | |
146 | 64 | Adrian Georgescu | A list of @protocol.URI@ instances, obtained by parsing @'a:path'@ put in SDP by the remote party. |
147 | 1 | Adrian Georgescu | |
148 | 64 | Adrian Georgescu | *cleanup*(_self_) |
149 | 64 | Adrian Georgescu | This method cleans up after @prepare()@; it should be called if @complete()@ will not be called for whatever reason. |
150 | 1 | Adrian Georgescu | |
151 | 1 | Adrian Georgescu | |
152 | 64 | Adrian Georgescu | h2. AcceptorDirect |
153 | 1 | Adrian Georgescu | |
154 | 1 | Adrian Georgescu | |
155 | 64 | Adrian Georgescu | This class is implemented in the @msrplib.connect@ module and is used for inbound MSRP connections without using a relay. |
156 | 64 | Adrian Georgescu | |
157 | 64 | Adrian Georgescu | |
158 | 64 | Adrian Georgescu | h4. methods |
159 | 64 | Adrian Georgescu | |
160 | 64 | Adrian Georgescu | |
161 | 64 | Adrian Georgescu | *<notextile>__init__</notextile>*(_self_, *loger*=@None@, *use_sessmatch*=@False@) |
162 | 64 | Adrian Georgescu | >Constructs a new AcceptorDirect. |
163 | 64 | Adrian Georgescu | |
164 | 64 | Adrian Georgescu | >+_logger_+: |
165 | 64 | Adrian Georgescu | |
166 | 64 | Adrian Georgescu | The logger which will be used for this MSRP connection. See the [[SipMSRPApi#Logging|Logging]] section for more information. |
167 | 64 | Adrian Georgescu | |
168 | 64 | Adrian Georgescu | >+_use_sessmatch_+: |
169 | 64 | Adrian Georgescu | |
170 | 64 | Adrian Georgescu | Indicates if the connector should use the session matching mechanism defined by the "sessmatch draft version 10":http://tools.ietf.org/html/draft-ietf-simple-msrp-sessmatch-10 |
171 | 64 | Adrian Georgescu | |
172 | 64 | Adrian Georgescu | *prepare*(_self_, *local_uri*=@None@) |
173 | 64 | Adrian Georgescu | This method starts listening on a socket identified by the parameters in the @local_uri@ argument. It returns a full local path - list of @protocol.URI@ instances, suitable to be put in SDP @'a:path'@ attribute. |
174 | 64 | Adrian Georgescu | |
175 | 64 | Adrian Georgescu | >+_local_uri_+: |
176 | 64 | Adrian Georgescu | |
177 | 1 | Adrian Georgescu | This attribute will be used to construct the local path and to listen for incomming connections. If not provided, one |
178 | 1 | Adrian Georgescu | will be automatically generated. Note that the object may be changed in place: for example, if the port specified is 0, |
179 | 1 | Adrian Georgescu | a random one will be selected and the object will be updated accordingly. |
180 | 1 | Adrian Georgescu | |
181 | 64 | Adrian Georgescu | *complete*(_self_, *full_remote_path*) |
182 | 64 | Adrian Georgescu | This method waits for an incoming connection and a chunk sent by the other party. It returns @transport.MSRPTransport@ instance, ready to read and send chunks. |
183 | 64 | Adrian Georgescu | |
184 | 64 | Adrian Georgescu | >+_full_remote_path_+: |
185 | 1 | Adrian Georgescu | |
186 | 64 | Adrian Georgescu | A list of @protocol.URI@ instances, obtained by parsing @'a:path'@ put in SDP by the remote party. This is checked agains the From-Path header in the binding chunk. |
187 | 1 | Adrian Georgescu | |
188 | 64 | Adrian Georgescu | *cleanup*(_self_) |
189 | 64 | Adrian Georgescu | This method cleans up after @prepare()@; it should be called if @complete()@ will not be called for whatever reason. |
190 | 1 | Adrian Georgescu | |
191 | 1 | Adrian Georgescu | |
192 | 1 | Adrian Georgescu | |
193 | 64 | Adrian Georgescu | h2. RelayConnection |
194 | 1 | Adrian Georgescu | |
195 | 64 | Adrian Georgescu | |
196 | 64 | Adrian Georgescu | This class is implemented in the @msrplib.connect@ module and is used for inbound and outbound MSRP connections using a relay. |
197 | 64 | Adrian Georgescu | |
198 | 64 | Adrian Georgescu | |
199 | 64 | Adrian Georgescu | h4. methods |
200 | 64 | Adrian Georgescu | |
201 | 64 | Adrian Georgescu | |
202 | 64 | Adrian Georgescu | *<notextile>__init__</notextile>*(_self_, *relay*, *mode*, *loger*=@None@, *use_sessmatch*=@False@) |
203 | 1 | Adrian Georgescu | Constructs a new RelayConnection. |
204 | 64 | Adrian Georgescu | |
205 | 64 | Adrian Georgescu | >+_relay_+: |
206 | 1 | Adrian Georgescu | |
207 | 64 | Adrian Georgescu | An instance of @MSRPRelaySettings@ which identifies the relay which is to be used. |
208 | 64 | Adrian Georgescu | |
209 | 64 | Adrian Georgescu | >+_mode_+: |
210 | 64 | Adrian Georgescu | |
211 | 64 | Adrian Georgescu | A string indicating if this connection should be _active_, an empty SEND should be sent when @complete@ is called, or _passive_, where it will wait for one. |
212 | 64 | Adrian Georgescu | |
213 | 64 | Adrian Georgescu | >+_logger_+: |
214 | 64 | Adrian Georgescu | |
215 | 64 | Adrian Georgescu | The logger which will be used for this MSRP connection. See the [[SipMSRPApi#Logging|Logging]] section for more information. |
216 | 64 | Adrian Georgescu | |
217 | 64 | Adrian Georgescu | >+_use_sessmatch_+: |
218 | 64 | Adrian Georgescu | |
219 | 64 | Adrian Georgescu | Indicates if the connector should use the session matching mechanism defined by the "sessmatch draft version 10":http://tools.ietf.org/html/draft-ietf-simple-msrp-sessmatch-10 |
220 | 64 | Adrian Georgescu | |
221 | 64 | Adrian Georgescu | *prepare*(_self_, *local_uri*=@None@) |
222 | 64 | Adrian Georgescu | This method returns a full local path - list of @protocol.URI@ instances, suitable to be put in SDP @'a:path'@ attribute. |
223 | 64 | Adrian Georgescu | |
224 | 64 | Adrian Georgescu | >+_local_uri_+: |
225 | 64 | Adrian Georgescu | |
226 | 1 | Adrian Georgescu | This attribute will be used to construct the local path, but other than that it is not used anywhere else in case of the ConnectorRelay. If not provided, one |
227 | 1 | Adrian Georgescu | will be automatically generated |
228 | 1 | Adrian Georgescu | |
229 | 64 | Adrian Georgescu | *complete*(_self_, *full_remote_path*) |
230 | 64 | Adrian Georgescu | This method establishes the connection to the relay and binds it (sends an empty chunk or waits for one, depending on the mode, to verify each other's From-Path and To-Path). It returns @transport.MSRPTransport@ instance, ready to read and send chunks. |
231 | 64 | Adrian Georgescu | |
232 | 64 | Adrian Georgescu | >+_full_remote_path_+: |
233 | 1 | Adrian Georgescu | |
234 | 64 | Adrian Georgescu | A list of @protocol.URI@ instances, obtained by parsing @'a:path'@ put in SDP by the remote party. |
235 | 1 | Adrian Georgescu | |
236 | 64 | Adrian Georgescu | *cleanup*(_self_) |
237 | 64 | Adrian Georgescu | This method cleans up after @prepare()@; it should be called if @complete()@ will not be called for whatever reason. |
238 | 1 | Adrian Georgescu | |
239 | 1 | Adrian Georgescu | |
240 | 1 | Adrian Georgescu | |
241 | 64 | Adrian Georgescu | h2. MSRPTransport |
242 | 1 | Adrian Georgescu | |
243 | 64 | Adrian Georgescu | |
244 | 64 | Adrian Georgescu | This class is implemented in the @msrplib.transport@ module and provies low level access to the MSRP connection. This class should not be constructed directly, but rather its intances should be obtained by using the various connector/acceptor classes documented above. |
245 | 64 | Adrian Georgescu | |
246 | 64 | Adrian Georgescu | |
247 | 64 | Adrian Georgescu | h4. methods |
248 | 64 | Adrian Georgescu | |
249 | 64 | Adrian Georgescu | |
250 | 64 | Adrian Georgescu | *make_chunk*(_self_, *transaction_id*=@None@, *method*=@'SEND'@, *code*=@None@, *comment*=@None@, *data*=@''@, *contflag*=@None@, *start*=@1@, *end*=@None@, *length*=@None@, *message_id*=@None@) |
251 | 64 | Adrian Georgescu | Creates a new chunk (@protocol.MSRPData@ instance), which is either an MSRP request or a response. Proper @From-Path@, @To-Path@, @Byte-Range@ and @Message-ID@ headers are added based on MSRPTransport's state and the parameters provided. Use _data_ for payload, and _start_/_end_/_length_ to generate the @Byte-Range@ header. |
252 | 64 | Adrian Georgescu | |
253 | 64 | Adrian Georgescu | >+_transaction_id_+: |
254 | 64 | Adrian Georgescu | |
255 | 1 | Adrian Georgescu | The transaction id which will be put in the chunk. If it is not provided, one will be randomly generated. |
256 | 64 | Adrian Georgescu | |
257 | 64 | Adrian Georgescu | >+_method_+: |
258 | 64 | Adrian Georgescu | |
259 | 64 | Adrian Georgescu | The method of the new MSRP request, or @None@ if a response is required. |
260 | 64 | Adrian Georgescu | |
261 | 64 | Adrian Georgescu | >+_code_+: |
262 | 64 | Adrian Georgescu | |
263 | 64 | Adrian Georgescu | The code of the new MSRP response, or @None@ if a request is required. |
264 | 64 | Adrian Georgescu | |
265 | 64 | Adrian Georgescu | >+_code_+: |
266 | 64 | Adrian Georgescu | |
267 | 64 | Adrian Georgescu | The comment of the new MSRP response, or @None@ if a request is required or a comment on the response is not. |
268 | 64 | Adrian Georgescu | |
269 | 64 | Adrian Georgescu | >+_data_+: |
270 | 64 | Adrian Georgescu | |
271 | 1 | Adrian Georgescu | The payload of the new chunk, or an empty string if no payload is required. |
272 | 64 | Adrian Georgescu | |
273 | 64 | Adrian Georgescu | >+_contflag_+: |
274 | 64 | Adrian Georgescu | |
275 | 64 | Adrian Georgescu | MSRP chunk's continuation flag (@'$'@, @'+'@ or @'#'@). Default is @'$'@ for a full message, unless a partial @SEND@ chunk required, in which case it should be set to @'+'@. If @None@ is provided, either @'$'@ or @'+'@ will be used depending on whether this chunk seems to carry the last part of the message data. |
276 | 64 | Adrian Georgescu | |
277 | 64 | Adrian Georgescu | >+_start_+: |
278 | 64 | Adrian Georgescu | |
279 | 1 | Adrian Georgescu | The first byte's index within the whole message payload this chunk will carry as its own payload. |
280 | 64 | Adrian Georgescu | |
281 | 64 | Adrian Georgescu | >+_end_+: |
282 | 64 | Adrian Georgescu | |
283 | 64 | Adrian Georgescu | The last byte's index within the whole message payload this chunk will carry as its own payload. Note that this is an inclusive index. If this is not provided, it's computed based on the number of bytes in data and @start@. |
284 | 64 | Adrian Georgescu | |
285 | 64 | Adrian Georgescu | >+_length_+: |
286 | 64 | Adrian Georgescu | |
287 | 1 | Adrian Georgescu | The total number of bytes of the whole message payload. If this is not provided, it is computed as if this chunk carries that last part of the message payload. |
288 | 64 | Adrian Georgescu | |
289 | 64 | Adrian Georgescu | >+_message_id_+: |
290 | 64 | Adrian Georgescu | |
291 | 1 | Adrian Georgescu | The ID of the message this chunk is part of. If it is not provided, one will be randomly generated. |
292 | 1 | Adrian Georgescu | |
293 | 64 | Adrian Georgescu | *write_chunk*(_self_, *chunk*, *wait*=@True@) |
294 | 1 | Adrian Georgescu | Writes the chunk provided to the underlying socket. |
295 | 64 | Adrian Georgescu | |
296 | 64 | Adrian Georgescu | >+_chunk_+: |
297 | 1 | Adrian Georgescu | |
298 | 64 | Adrian Georgescu | The chunk which is to be written, an instance of @MSRPData@. |
299 | 64 | Adrian Georgescu | |
300 | 64 | Adrian Georgescu | >+_wait_+: |
301 | 64 | Adrian Georgescu | |
302 | 64 | Adrian Georgescu | If @True@, waits for the operation to complete. |
303 | 64 | Adrian Georgescu | |
304 | 64 | Adrian Georgescu | *write_response*(_self_, *chunk*, *code*, *comment*, *wait*=@True@): |
305 | 1 | Adrian Georgescu | Creates a response which is suitable as a reply to the specified chunk and writes it to the underlying socket. |
306 | 64 | Adrian Georgescu | |
307 | 64 | Adrian Georgescu | >+_chunk_+: |
308 | 64 | Adrian Georgescu | |
309 | 1 | Adrian Georgescu | The chunk for which to create a response. |
310 | 64 | Adrian Georgescu | |
311 | 64 | Adrian Georgescu | >+_code_+: |
312 | 64 | Adrian Georgescu | |
313 | 1 | Adrian Georgescu | The status code of the response which is to be created. |
314 | 64 | Adrian Georgescu | |
315 | 64 | Adrian Georgescu | >+_comment_+: |
316 | 64 | Adrian Georgescu | |
317 | 1 | Adrian Georgescu | The comment of the response which is to be created. |
318 | 64 | Adrian Georgescu | |
319 | 64 | Adrian Georgescu | >+_wait_+: |
320 | 1 | Adrian Georgescu | |
321 | 64 | Adrian Georgescu | If @True@, waits for the operation to complete. |
322 | 64 | Adrian Georgescu | |
323 | 64 | Adrian Georgescu | *read_chunk*(_self_, *size*=@None@) |
324 | 1 | Adrian Georgescu | Waits for a new chunk and returns it. |
325 | 64 | Adrian Georgescu | If there was an error, closes the connection and raises @ChunkParseError@. |
326 | 1 | Adrian Georgescu | |
327 | 64 | Adrian Georgescu | In case of unintelligible input, loses the connection and returns @None@. |
328 | 64 | Adrian Georgescu | When the connection is closed, raises the reason of the closure (e.g. @ConnectionDone@). |
329 | 1 | Adrian Georgescu | |
330 | 64 | Adrian Georgescu | If the data already read exceeds _size_, stops reading the data and returns |
331 | 1 | Adrian Georgescu | a "virtual" chunk, i.e. the one that does not actually correspond the the real |
332 | 1 | Adrian Georgescu | MSRP chunk. Such chunks have Byte-Range header changed to match the number of |
333 | 64 | Adrian Georgescu | bytes read and continuation that is @'+'@; they also possess @segment@ attribute, |
334 | 1 | Adrian Georgescu | an integer, starting with 1 and increasing with every new segment of the chunk. |
335 | 1 | Adrian Georgescu | |
336 | 64 | Adrian Georgescu | Note, that _size_ only hints when to interrupt the segment but does not affect |
337 | 64 | Adrian Georgescu | how the data is read from socket. You may have segments bigger than _size_ and it's |
338 | 64 | Adrian Georgescu | legal to set _size_ to zero (which would mean return a chunk as long as you get |
339 | 1 | Adrian Georgescu | some data, regardless how small). |
340 | 1 | Adrian Georgescu | |
341 | 64 | Adrian Georgescu | |
342 | 64 | Adrian Georgescu | >+_size_+: |
343 | 1 | Adrian Georgescu | |
344 | 64 | Adrian Georgescu | The hint towards how much to read from the socket. If the data already read is larger, then all the data will be returned, even if it exceeds @size@ bytes. |
345 | 64 | Adrian Georgescu | |
346 | 64 | Adrian Georgescu | *check_incoming_SEND_chunk*(_self_, *chunk*) |
347 | 1 | Adrian Georgescu | Checks the 'To-Path' and 'From-Path' of the incoming SEND chunk. |
348 | 1 | Adrian Georgescu | Returns None is the paths are valid for this connection. |
349 | 1 | Adrian Georgescu | If an error is detected an MSRPError is created and returned. |
350 | 1 | Adrian Georgescu | |
351 | 1 | Adrian Georgescu | |
352 | 64 | Adrian Georgescu | h2. MSRPData |
353 | 1 | Adrian Georgescu | |
354 | 1 | Adrian Georgescu | |
355 | 64 | Adrian Georgescu | This class is implemented in the @msrplib.protocol@ module and represents an MSRP chunk, either a request or a response. |
356 | 64 | Adrian Georgescu | |
357 | 64 | Adrian Georgescu | |
358 | 64 | Adrian Georgescu | h4. attributes |
359 | 64 | Adrian Georgescu | |
360 | 64 | Adrian Georgescu | |
361 | 1 | Adrian Georgescu | The following attributes are read-only. |
362 | 1 | Adrian Georgescu | |
363 | 64 | Adrian Georgescu | *content_type* |
364 | 64 | Adrian Georgescu | >The MIME type of the payload carried by this chunk, which is stored in the Content-Type header. |
365 | 1 | Adrian Georgescu | |
366 | 64 | Adrian Georgescu | *message_id* |
367 | 64 | Adrian Georgescu | >The ID of the message this chunk is part of, which is stored in the Message-ID header. |
368 | 1 | Adrian Georgescu | |
369 | 64 | Adrian Georgescu | *byte_range* |
370 | 64 | Adrian Georgescu | >A 3-tuple containing the start, end and length values (in this order) from the Byte-Range header. |
371 | 1 | Adrian Georgescu | |
372 | 64 | Adrian Georgescu | *status* |
373 | 64 | Adrian Georgescu | >The value of the Status header. |
374 | 1 | Adrian Georgescu | |
375 | 64 | Adrian Georgescu | *failure_report* |
376 | 64 | Adrian Georgescu | >The value of the Failure-Report header, whether it exists or it is implied; one of @'yes'@, @'no'@, @'partial'@. |
377 | 1 | Adrian Georgescu | |
378 | 64 | Adrian Georgescu | *success_report* |
379 | 64 | Adrian Georgescu | >The value of the Success-Report header, whether it exists or it is implied; one of @'yes'@ or @'no'@. |
380 | 1 | Adrian Georgescu | |
381 | 64 | Adrian Georgescu | *size* |
382 | 64 | Adrian Georgescu | >The size of the payload of this chunk, in bytes. |
383 | 1 | Adrian Georgescu | |
384 | 1 | Adrian Georgescu | |
385 | 64 | Adrian Georgescu | h4. methods |
386 | 1 | Adrian Georgescu | |
387 | 1 | Adrian Georgescu | |
388 | 64 | Adrian Georgescu | *<notextile>__init__</notextile>*(_self_, *transaction_id*, *method*=@None@, *code*=@None@, *comment*=@None@, *headers*=@None@, *data*=@''@, *contflag*=@'$'@) |
389 | 64 | Adrian Georgescu | >Initializes a new MSRPData instance. All the arguments are also available as attributes. |
390 | 64 | Adrian Georgescu | |
391 | 64 | Adrian Georgescu | >+_transaction_id_+: |
392 | 1 | Adrian Georgescu | |
393 | 64 | Adrian Georgescu | >The transaction identified of this chunk. |
394 | 64 | Adrian Georgescu | |
395 | 64 | Adrian Georgescu | >+_method_+: |
396 | 1 | Adrian Georgescu | |
397 | 64 | Adrian Georgescu | >The method of this chunk if it a request and @None@ if it is a response. |
398 | 64 | Adrian Georgescu | |
399 | 64 | Adrian Georgescu | >+_code_+: |
400 | 1 | Adrian Georgescu | |
401 | 64 | Adrian Georgescu | >The status code of this chunk if it is a response and @None@ if it is a request. |
402 | 64 | Adrian Georgescu | |
403 | 64 | Adrian Georgescu | >+_comment_+: |
404 | 1 | Adrian Georgescu | |
405 | 64 | Adrian Georgescu | >The comment of this chunk if it is a response and @None@ if it is a request. |
406 | 64 | Adrian Georgescu | |
407 | 64 | Adrian Georgescu | >+_headers_+: |
408 | 1 | Adrian Georgescu | |
409 | 64 | Adrian Georgescu | >A dict containing the headers which are to be added to this chunk, or @None@ if no headers are to be added. |
410 | 64 | Adrian Georgescu | |
411 | 64 | Adrian Georgescu | >+_data_+: |
412 | 1 | Adrian Georgescu | |
413 | 64 | Adrian Georgescu | >The payload of this chunk, or an empty string if no payload is to be added. |
414 | 64 | Adrian Georgescu | |
415 | 64 | Adrian Georgescu | >+_contflag_+: |
416 | 1 | Adrian Georgescu | |
417 | 64 | Adrian Georgescu | >The MSRP continuation flag of this chunk, one of @'$'@, @'#'@ or @'+'@. |
418 | 1 | Adrian Georgescu | |
419 | 64 | Adrian Georgescu | *copy*(_self_) |
420 | 64 | Adrian Georgescu | >Returns a new MSRPData instance with exactly the same attributes as this object. |
421 | 1 | Adrian Georgescu | |
422 | 64 | Adrian Georgescu | *add_header*(_self_, *header*) |
423 | 64 | Adrian Georgescu | >Add a MSRP header to this chunk. |
424 | 64 | Adrian Georgescu | |
425 | 64 | Adrian Georgescu | >+_header_+: |
426 | 1 | Adrian Georgescu | |
427 | 64 | Adrian Georgescu | >The header object which is to be added to this chunk. |
428 | 1 | Adrian Georgescu | |
429 | 64 | Adrian Georgescu | *verify_headers*(_self_) |
430 | 64 | Adrian Georgescu | >Verifies that the chunk contains a To-Path and a From-Path header and that all the headers are valid. |
431 | 1 | Adrian Georgescu | |
432 | 64 | Adrian Georgescu | *encode_start*(_self_) |
433 | 64 | Adrian Georgescu | >Returns a string containing the MSRP header of this chunk. |
434 | 1 | Adrian Georgescu | |
435 | 64 | Adrian Georgescu | *encode_end*(_self_, *continuation*) |
436 | 64 | Adrian Georgescu | >Returns a string containing the MSRP end line of this chunk: 7 commas followed by the transaction identifier and the continuation flag specified. |
437 | 64 | Adrian Georgescu | |
438 | 64 | Adrian Georgescu | >+_continuation_+: |
439 | 1 | Adrian Georgescu | |
440 | 64 | Adrian Georgescu | >The continuation flag which is to be used in the end line. |
441 | 1 | Adrian Georgescu | |
442 | 64 | Adrian Georgescu | *encode*(_self_): |
443 | 64 | Adrian Georgescu | >Returns a string containing the whole of this MSRP chunk. |
444 | 1 | Adrian Georgescu | |
445 | 1 | Adrian Georgescu | |
446 | 64 | Adrian Georgescu | |
447 | 64 | Adrian Georgescu | h2. OutgoingFile |
448 | 64 | Adrian Georgescu | |
449 | 64 | Adrian Georgescu | |
450 | 64 | Adrian Georgescu | This class is implemented in the @msrplib.session@ module and represents a file which is to be sent via MSRP. |
451 | 64 | Adrian Georgescu | |
452 | 64 | Adrian Georgescu | |
453 | 64 | Adrian Georgescu | h4. attributes |
454 | 64 | Adrian Georgescu | |
455 | 64 | Adrian Georgescu | |
456 | 64 | Adrian Georgescu | *headers* |
457 | 64 | Adrian Georgescu | >A dict which maps header names to header objects. These headers will be sent in the MSRP message used to send the file. |
458 | 64 | Adrian Georgescu | |
459 | 64 | Adrian Georgescu | |
460 | 64 | Adrian Georgescu | h4. methods |
461 | 64 | Adrian Georgescu | |
462 | 64 | Adrian Georgescu | |
463 | 64 | Adrian Georgescu | *<notextile>__init__</notextile>*(_self_, *fileobj*, *size*, *content_type*=@None@, *position*=@0@, *message_id*=@None@) |
464 | 64 | Adrian Georgescu | >Initializes a new OutgoingFile using the specified file object. All arguments are available as attributes, except for @content_type@ which will be part of the @headers@ attribute. |
465 | 64 | Adrian Georgescu | |
466 | 64 | Adrian Georgescu | >+_fileobj_+: |
467 | 64 | Adrian Georgescu | |
468 | 64 | Adrian Georgescu | >A file-like object which will be used for reading the data to be sent. |
469 | 64 | Adrian Georgescu | |
470 | 64 | Adrian Georgescu | >+_size_+: |
471 | 64 | Adrian Georgescu | |
472 | 64 | Adrian Georgescu | >The size of the whole file. |
473 | 64 | Adrian Georgescu | |
474 | 64 | Adrian Georgescu | >+_content_type_+: |
475 | 64 | Adrian Georgescu | |
476 | 64 | Adrian Georgescu | >The MIME type associated with the file's data. If provided, it will be added as a Content-Type header. |
477 | 64 | Adrian Georgescu | |
478 | 64 | Adrian Georgescu | >+_position_+: |
479 | 64 | Adrian Georgescu | |
480 | 64 | Adrian Georgescu | >The position within the file from which data will be sent. The file object must already be seeked to this position. |
481 | 64 | Adrian Georgescu | |
482 | 64 | Adrian Georgescu | >+_message_id_+: |
483 | 64 | Adrian Georgescu | |
484 | 64 | Adrian Georgescu | >The message ID which will be used for sending this file. |
485 | 64 | Adrian Georgescu | |
486 | 64 | Adrian Georgescu | |
487 | 64 | Adrian Georgescu | h2. MSRPSession |
488 | 64 | Adrian Georgescu | |
489 | 64 | Adrian Georgescu | |
490 | 64 | Adrian Georgescu | This class is implemented in the @msrplib.session@ module and provides a high level API for MSRP sessions. |
491 | 64 | Adrian Georgescu | |
492 | 64 | Adrian Georgescu | |
493 | 64 | Adrian Georgescu | h4. methods |
494 | 64 | Adrian Georgescu | |
495 | 64 | Adrian Georgescu | |
496 | 64 | Adrian Georgescu | *<notextile>__init__</notextile>*(_self_, *msrptransport*, *accept_types*=@['*']@, *on_incoming_cb*=@None@) |
497 | 64 | Adrian Georgescu | Initializes MSRPSession instance over the specified transport. The incoming chunks are reported through the _on_incoming_cb_ callback. |
498 | 64 | Adrian Georgescu | |
499 | 64 | Adrian Georgescu | >+_msrptransport_+: |
500 | 64 | Adrian Georgescu | |
501 | 64 | Adrian Georgescu | An instance of @MSRPTransport@ over which this session will operate. |
502 | 64 | Adrian Georgescu | |
503 | 64 | Adrian Georgescu | >+_accept_types_+: |
504 | 64 | Adrian Georgescu | |
505 | 64 | Adrian Georgescu | A list of MIME types which are acceptable over this session. If data is received with a Content-Type header which doesn't match this list, a negative response is sent back and the application does not get the received data. The special strings @'*'@ and @'<type>/*'@ can be used to match multiple MIME types. |
506 | 64 | Adrian Georgescu | |
507 | 64 | Adrian Georgescu | >+_on_incoming_cb_+: |
508 | 64 | Adrian Georgescu | |
509 | 64 | Adrian Georgescu | A function which receives two arguments, both optional with default values of @None@: _chunk_ and _error_. This will be called when a new chunk is received. |
510 | 64 | Adrian Georgescu | |
511 | 64 | Adrian Georgescu | *send_chunk*(_self_, *chunk*, *response_cb*=@None@) |
512 | 64 | Adrian Georgescu | Sends the specified chunk and reports the result via the _response_cb_ callback. |
513 | 64 | Adrian Georgescu | |
514 | 64 | Adrian Georgescu | When _response_cb_ argument is present, it will be used to report |
515 | 1 | Adrian Georgescu | the transaction response to the caller. When a response is received or generated |
516 | 64 | Adrian Georgescu | locally, _response_cb_ is called with one argument. The function must do something |
517 | 1 | Adrian Georgescu | quickly and must not block, because otherwise it would block the reader greenlet. |
518 | 1 | Adrian Georgescu | |
519 | 64 | Adrian Georgescu | If no response was received after @RESPONSE_TIMEOUT@ seconds, |
520 | 64 | Adrian Georgescu | * 408 response is generated if Failure-Report was @'yes'@ or absent |
521 | 64 | Adrian Georgescu | * 200 response is generated if Failure-Report was @'partial'@ or @'no'@ |
522 | 1 | Adrian Georgescu | |
523 | 64 | Adrian Georgescu | Note that it's rather wasteful to provide _response_cb_ argument other than @None@ |
524 | 1 | Adrian Georgescu | for chunks with Failure-Report='no' since it will always fire 30 seconds later |
525 | 1 | Adrian Georgescu | with 200 result (unless the other party is broken and ignores Failure-Report header) |
526 | 1 | Adrian Georgescu | |
527 | 64 | Adrian Georgescu | If sending is not possible, @MSRPSessionError@ is raised. |
528 | 1 | Adrian Georgescu | |
529 | 64 | Adrian Georgescu | |
530 | 64 | Adrian Georgescu | >+_chunk_+: |
531 | 64 | Adrian Georgescu | |
532 | 64 | Adrian Georgescu | The chunk which is to be sent. It must be an instance of @MSRPData@ which represents a request. |
533 | 64 | Adrian Georgescu | |
534 | 64 | Adrian Georgescu | >+_response_cb_+: |
535 | 64 | Adrian Georgescu | |
536 | 1 | Adrian Georgescu | A function receiving a single argument which will be the response received for the sent chunk. |
537 | 1 | Adrian Georgescu | |
538 | 64 | Adrian Georgescu | *deliver_chunk*(_self_, *chunk*, *event*=@None@) |
539 | 64 | Adrian Georgescu | Sends the specified chunk and waits for the transaction response (if Failure-Report header is not @'no'@). |
540 | 64 | Adrian Georgescu | Returns the transaction response if it's a success or raise @MSRPTransactionError@ if it's not. |
541 | 1 | Adrian Georgescu | |
542 | 64 | Adrian Georgescu | If chunk's Failure-Report is @'no'@, returns @None@ immediately. |
543 | 1 | Adrian Georgescu | |
544 | 1 | Adrian Georgescu | |
545 | 64 | Adrian Georgescu | >+_chunk_+: |
546 | 64 | Adrian Georgescu | |
547 | 64 | Adrian Georgescu | The chunk which is to be sent. It must be an intance of @MSRPData@ which represents a request. |
548 | 64 | Adrian Georgescu | |
549 | 64 | Adrian Georgescu | >+_event_+: |
550 | 64 | Adrian Georgescu | |
551 | 64 | Adrian Georgescu | The @eventlet.coros.event@ object which will be used to wait for a response. It's send method will be called when a response is received. If it is not provided, one will be constructed automatically and used. |
552 | 64 | Adrian Georgescu | |
553 | 64 | Adrian Georgescu | *send_file*(_self_, *outgoing_file*) |
554 | 59 | Adrian Georgescu | Adds the specified file to the queue of files to be sent. The method returns immediately. |
555 | 64 | Adrian Georgescu | |
556 | 64 | Adrian Georgescu | >+_outgoing_file_+: |
557 | 59 | Adrian Georgescu | |
558 | 64 | Adrian Georgescu | An instance of @OutgoingFile@ which represents the file to be sent. |
559 | 64 | Adrian Georgescu | |
560 | 64 | Adrian Georgescu | *shutdown*(_self_, *sync*=@True@) |
561 | 59 | Adrian Georgescu | Sends the messages already in queue then closes the connection. |
562 | 59 | Adrian Georgescu | |
563 | 59 | Adrian Georgescu | |
564 | 64 | Adrian Georgescu | h2. MSRPServer |
565 | 64 | Adrian Georgescu | |
566 | 64 | Adrian Georgescu | |
567 | 64 | Adrian Georgescu | This class is implemented in the @msrplib.connect@ module. |
568 | 59 | Adrian Georgescu | |
569 | 59 | Adrian Georgescu | MSRPServer solves the problem with AcceptorDirect: concurrent using of 2 |
570 | 59 | Adrian Georgescu | or more AcceptorDirect instances on the same non-zero port is not possible. |
571 | 59 | Adrian Georgescu | If you initialize() those instances, one after another, one will listen on |
572 | 59 | Adrian Georgescu | the socket and another will get BindError. |
573 | 59 | Adrian Georgescu | |
574 | 59 | Adrian Georgescu | MSRPServer avoids the problem by sharing the listening socket between multiple connections. |
575 | 59 | Adrian Georgescu | It has a slightly different interface from AcceptorDirect, so it cannot be considered a drop-in |
576 | 59 | Adrian Georgescu | replacement. |
577 | 59 | Adrian Georgescu | |
578 | 59 | Adrian Georgescu | It manages the listening sockets and binds incoming requests. |
579 | 59 | Adrian Georgescu | |
580 | 59 | Adrian Georgescu | |
581 | 64 | Adrian Georgescu | h4. methods |
582 | 64 | Adrian Georgescu | |
583 | 64 | Adrian Georgescu | |
584 | 64 | Adrian Georgescu | *<notextile>__init__</notextile>*(_self_, *logger*) |
585 | 59 | Adrian Georgescu | Constructs a new MSRPServer which will be using the specifed logger for its connections. |
586 | 64 | Adrian Georgescu | |
587 | 64 | Adrian Georgescu | >+_logger_+: |
588 | 59 | Adrian Georgescu | |
589 | 64 | Adrian Georgescu | The default logger which will be used for this object's MSRP connections. See the [[SipMSRPApi#Logging|Logging]] section for more information. |
590 | 64 | Adrian Georgescu | |
591 | 64 | Adrian Georgescu | *prepare*(_self_, _local_uri_=@None@, _logger_=@None@) |
592 | 64 | Adrian Georgescu | Starts a listening port specified by _local_uri_ if there isn't one on that port/interface already. |
593 | 64 | Adrian Georgescu | Adds _local_uri_ to the list of expected URIs, so that incoming connections featuring this URI won't be rejected. |
594 | 64 | Adrian Georgescu | If _logger_ is provided, it uses it for this connection instead of the one specified in @__init___@. |
595 | 64 | Adrian Georgescu | |
596 | 64 | Adrian Georgescu | >+_local_uri_+: |
597 | 64 | Adrian Georgescu | |
598 | 59 | Adrian Georgescu | The URI which will be added to the list of expected URIs. Connections from this URI will be accepted. |
599 | 64 | Adrian Georgescu | |
600 | 64 | Adrian Georgescu | >+_logger_+: |
601 | 59 | Adrian Georgescu | |
602 | 64 | Adrian Georgescu | The logger which will be used for connections from the specified URI. See the [[SipMSRPApi#Logging|Logging]] section for more information. |
603 | 59 | Adrian Georgescu | |
604 | 64 | Adrian Georgescu | *complete*(_self_, _full_remote_path_) |
605 | 64 | Adrian Georgescu | Waits until one of the incoming connections binds using the provided _full_remote_path_. |
606 | 64 | Adrian Georgescu | Returns the connected and bound @MSRPTransport@ instance. |
607 | 64 | Adrian Georgescu | If no such binding was made within @MSRPBindSessionTimeout.seconds@, @MSRPBindSessionTimeout@ is raised. |
608 | 64 | Adrian Georgescu | |
609 | 64 | Adrian Georgescu | >+_full_remote_path_+: |
610 | 64 | Adrian Georgescu | |
611 | 64 | Adrian Georgescu | A list of @protocol.URI@ instances, obtained by parsing @'a:path'@ put in SDP by the remote party. |
612 | 64 | Adrian Georgescu | |
613 | 64 | Adrian Georgescu | *cleanup*(_self_, _local_uri_) |
614 | 64 | Adrian Georgescu | Removes _local_uri_ from the list of expected URIs. |
615 | 64 | Adrian Georgescu | |
616 | 64 | Adrian Georgescu | >+_local_uri_+: |
617 | 64 | Adrian Georgescu | |
618 | 59 | Adrian Georgescu | The URI which is to be removed from the list of expected URIs. |
619 | 59 | Adrian Georgescu | |
620 | 59 | Adrian Georgescu | |
621 | 64 | Adrian Georgescu | h2. Headers |
622 | 64 | Adrian Georgescu | |
623 | 64 | Adrian Georgescu | |
624 | 64 | Adrian Georgescu | The MSRP headers are represented using objects from the @msrplib.protocol module@. All MSRP header object provide three properties: |
625 | 64 | Adrian Georgescu | _name_: |
626 | 64 | Adrian Georgescu | |
627 | 59 | Adrian Georgescu | The name of the header, as it appears in MSRP chunks. |
628 | 64 | Adrian Georgescu | |
629 | 64 | Adrian Georgescu | >+_encode_+: |
630 | 64 | Adrian Georgescu | |
631 | 59 | Adrian Georgescu | The MSRP encoded header value, as it appears in MSRP chunks. |
632 | 64 | Adrian Georgescu | |
633 | 64 | Adrian Georgescu | >+_decode_+: |
634 | 64 | Adrian Georgescu | |
635 | 59 | Adrian Georgescu | The high-level object representing the header value. |
636 | 59 | Adrian Georgescu | |
637 | 64 | Adrian Georgescu | All headers can be constructed by passing either the encoded or decoded objects to @__init__@. The following headers are provided: |
638 | 59 | Adrian Georgescu | |
639 | 59 | Adrian Georgescu | |
640 | 64 | Adrian Georgescu | h3. ToPathHeader |
641 | 59 | Adrian Georgescu | |
642 | 59 | Adrian Georgescu | |
643 | 64 | Adrian Georgescu | The name of the header is @'To-Path'@ and the decoded value is a deque of @URI@ objects. |
644 | 59 | Adrian Georgescu | |
645 | 59 | Adrian Georgescu | |
646 | 64 | Adrian Georgescu | h3. FromPathHeader |
647 | 59 | Adrian Georgescu | |
648 | 49 | Adrian Georgescu | |
649 | 64 | Adrian Georgescu | The name of the header is @'From-Path'@ and the decoded value is a deque of @URI@ objects. |
650 | 46 | Luci Stanescu | |
651 | 46 | Luci Stanescu | |
652 | 64 | Adrian Georgescu | h3. MessageIDHeader |
653 | 46 | Luci Stanescu | |
654 | 46 | Luci Stanescu | |
655 | 64 | Adrian Georgescu | The name of the header is @'Message-ID'@ and the decoded value is the string containing the message ID. |
656 | 46 | Luci Stanescu | |
657 | 46 | Luci Stanescu | |
658 | 64 | Adrian Georgescu | h3. SuccessReportHeader |
659 | 46 | Luci Stanescu | |
660 | 46 | Luci Stanescu | |
661 | 64 | Adrian Georgescu | The name of the header is @'Success-Report'@ and the decoded value is one of @'yes'@ or @'no'@. |
662 | 46 | Luci Stanescu | |
663 | 46 | Luci Stanescu | |
664 | 64 | Adrian Georgescu | h3. FailureReportHeader |
665 | 46 | Luci Stanescu | |
666 | 46 | Luci Stanescu | |
667 | 64 | Adrian Georgescu | The name of the header is @'Failure-Report'@ and the decoded value is one of @'yes'@, @'partial'@ or @'no'@. |
668 | 47 | Luci Stanescu | |
669 | 46 | Luci Stanescu | |
670 | 64 | Adrian Georgescu | h3. ByteRangeHeader |
671 | 46 | Luci Stanescu | |
672 | 46 | Luci Stanescu | |
673 | 64 | Adrian Georgescu | The name of the header is @'Byte-Range'@ and the decoded value is a 3-tuple containing the start, end and length values. |
674 | 46 | Luci Stanescu | |
675 | 46 | Luci Stanescu | |
676 | 64 | Adrian Georgescu | h4. attributes |
677 | 46 | Luci Stanescu | |
678 | 46 | Luci Stanescu | |
679 | 64 | Adrian Georgescu | *fro* |
680 | 64 | Adrian Georgescu | >The start value of the header: the index within the whole message payload where a chunk's payload starts. |
681 | 64 | Adrian Georgescu | *end* |
682 | 64 | Adrian Georgescu | >The end value of the header: the index within the whole message payload where a chunk's payload ends. Note that this index is inclusive. |
683 | 64 | Adrian Georgescu | *length* |
684 | 64 | Adrian Georgescu | >The total size of the message payload. |
685 | 46 | Luci Stanescu | |
686 | 46 | Luci Stanescu | |
687 | 64 | Adrian Georgescu | h3. StatusHeader |
688 | 46 | Luci Stanescu | |
689 | 46 | Luci Stanescu | |
690 | 64 | Adrian Georgescu | The name of the header is @'Status'@ and the decoded value is a 2-tuple containing the status code and comment. |
691 | 46 | Luci Stanescu | |
692 | 46 | Luci Stanescu | |
693 | 64 | Adrian Georgescu | h4. attributes |
694 | 46 | Luci Stanescu | |
695 | 47 | Luci Stanescu | |
696 | 64 | Adrian Georgescu | *code* |
697 | 64 | Adrian Georgescu | >The code component of the header. |
698 | 64 | Adrian Georgescu | *comment* |
699 | 64 | Adrian Georgescu | >The comment component of the header. |
700 | 46 | Luci Stanescu | |
701 | 46 | Luci Stanescu | |
702 | 64 | Adrian Georgescu | h3. ExpiresHeader |
703 | 46 | Luci Stanescu | |
704 | 46 | Luci Stanescu | |
705 | 64 | Adrian Georgescu | The name of the header is @'Expires'@ and the decoded value is an integer. |
706 | 46 | Luci Stanescu | |
707 | 46 | Luci Stanescu | |
708 | 64 | Adrian Georgescu | h3. MinExpiresHeader |
709 | 46 | Luci Stanescu | |
710 | 46 | Luci Stanescu | |
711 | 64 | Adrian Georgescu | The name of the header is @'Min-Expires'@ and the decoded value is an integer. |
712 | 46 | Luci Stanescu | |
713 | 46 | Luci Stanescu | |
714 | 64 | Adrian Georgescu | h3. MaxExpiresHeader |
715 | 46 | Luci Stanescu | |
716 | 46 | Luci Stanescu | |
717 | 64 | Adrian Georgescu | The name of the header is @'Max-Expires'@ and the decoded value is an integer. |
718 | 38 | Adrian Georgescu | |
719 | 1 | Adrian Georgescu | |
720 | 64 | Adrian Georgescu | h3. UsePathHeader |
721 | 38 | Adrian Georgescu | |
722 | 1 | Adrian Georgescu | |
723 | 64 | Adrian Georgescu | The name of the header is @'Use-Path'@ and the decoded value is a deque of @URI@ objects. |
724 | 1 | Adrian Georgescu | |
725 | 61 | Adrian Georgescu | |
726 | 64 | Adrian Georgescu | h3. WWWAuthenticateHeader |
727 | 1 | Adrian Georgescu | |
728 | 52 | Luci Stanescu | |
729 | 64 | Adrian Georgescu | The name of the header is @'WWW-Authenticate'@ and the decoded value is a dictionary of the parameters within the header. |
730 | 52 | Luci Stanescu | |
731 | 1 | Adrian Georgescu | |
732 | 64 | Adrian Georgescu | h3. AuthorizationHeader |
733 | 52 | Luci Stanescu | |
734 | 64 | Adrian Georgescu | |
735 | 64 | Adrian Georgescu | The name of the header is @'Authorization'@ and the decoded value is a dictionary of the parameters within the header. |
736 | 64 | Adrian Georgescu | |
737 | 64 | Adrian Georgescu | |
738 | 64 | Adrian Georgescu | h3. AuthenticationInfoHeader |
739 | 64 | Adrian Georgescu | |
740 | 64 | Adrian Georgescu | |
741 | 64 | Adrian Georgescu | The name of the header is @'Authentication-Info'@ and the decoded value is a dictionary of the parameters within the header. |
742 | 64 | Adrian Georgescu | |
743 | 64 | Adrian Georgescu | |
744 | 64 | Adrian Georgescu | h3. ContentTypeHeader |
745 | 64 | Adrian Georgescu | |
746 | 64 | Adrian Georgescu | |
747 | 64 | Adrian Georgescu | The name of the header is @'Content-Type'@ and the decoded value is the string representing the MIME type. |
748 | 64 | Adrian Georgescu | |
749 | 64 | Adrian Georgescu | |
750 | 64 | Adrian Georgescu | h3. ContentIDHeader |
751 | 64 | Adrian Georgescu | |
752 | 64 | Adrian Georgescu | |
753 | 64 | Adrian Georgescu | The name of the header is @'Content-ID'@ and the decoded value is the string with the value of the header. |
754 | 64 | Adrian Georgescu | |
755 | 64 | Adrian Georgescu | |
756 | 64 | Adrian Georgescu | h3. ContentDescriptionHeader |
757 | 64 | Adrian Georgescu | |
758 | 64 | Adrian Georgescu | |
759 | 64 | Adrian Georgescu | The name of the header is @'Content-Description'@ and the decoded value is the string with the value of the header. |
760 | 64 | Adrian Georgescu | |
761 | 64 | Adrian Georgescu | |
762 | 64 | Adrian Georgescu | h3. ContentDispositionHeader |
763 | 64 | Adrian Georgescu | |
764 | 64 | Adrian Georgescu | |
765 | 64 | Adrian Georgescu | The name of the header is @'Content-Disposition'@ and the decoded value is a list with two elements: the disposition and a dict with the parameters. |
766 | 64 | Adrian Georgescu | |
767 | 64 | Adrian Georgescu | |
768 | 64 | Adrian Georgescu | |
769 | 64 | Adrian Georgescu | h2. Logging |
770 | 64 | Adrian Georgescu | |
771 | 64 | Adrian Georgescu | |
772 | 64 | Adrian Georgescu | Logging is done throughout the library using objects defined by the application, called loggers. If logging is not desired, the @application.python.Null@ object of @python-application@ can be used. These loggers must define the following methods: |
773 | 64 | Adrian Georgescu | |
774 | 64 | Adrian Georgescu | |
775 | 64 | Adrian Georgescu | h4. methods |
776 | 64 | Adrian Georgescu | |
777 | 64 | Adrian Georgescu | |
778 | 64 | Adrian Georgescu | *received_new_chunk*(*data*, *transport*, *chunk*) |
779 | 64 | Adrian Georgescu | >This method is called when the start of a new chunk is received. |
780 | 64 | Adrian Georgescu | |
781 | 64 | Adrian Georgescu | >+_data_+: |
782 | 64 | Adrian Georgescu | |
783 | 64 | Adrian Georgescu | >The data which came along with the start of the chunk. |
784 | 64 | Adrian Georgescu | |
785 | 64 | Adrian Georgescu | >+_transport_+: |
786 | 64 | Adrian Georgescu | |
787 | 64 | Adrian Georgescu | >The @MSRPTransport@ instance on which the chunk was received. |
788 | 64 | Adrian Georgescu | |
789 | 64 | Adrian Georgescu | >+_chunk_+: |
790 | 64 | Adrian Georgescu | |
791 | 64 | Adrian Georgescu | >The actual chunk object. |
792 | 64 | Adrian Georgescu | |
793 | 64 | Adrian Georgescu | *received_chunk_data*(*data*, *transport*, *transaction_id*) |
794 | 64 | Adrian Georgescu | >This method is called when data is received as part of a chunk previously announced via *received_new_chunk*. |
795 | 64 | Adrian Georgescu | |
796 | 64 | Adrian Georgescu | >+_data_+: |
797 | 64 | Adrian Georgescu | |
798 | 64 | Adrian Georgescu | >The data received as part of the chunk. |
799 | 64 | Adrian Georgescu | |
800 | 64 | Adrian Georgescu | >+_transport_+: |
801 | 64 | Adrian Georgescu | |
802 | 64 | Adrian Georgescu | >The @MSRPTransport@ instance on which the chunk was received. |
803 | 64 | Adrian Georgescu | |
804 | 64 | Adrian Georgescu | >+_transaction_id_+: |
805 | 64 | Adrian Georgescu | |
806 | 64 | Adrian Georgescu | >The transaction ID which identifies the chunk for which data was received. |
807 | 64 | Adrian Georgescu | |
808 | 64 | Adrian Georgescu | *received_chunk_end*(*data*, *transport*, *transaction_id*) |
809 | 64 | Adrian Georgescu | >This method is called when the last data of a chunk is received. The chunk was previously announced via *received_new_chunk*. |
810 | 64 | Adrian Georgescu | |
811 | 64 | Adrian Georgescu | >+_data_+: |
812 | 64 | Adrian Georgescu | |
813 | 64 | Adrian Georgescu | >The last data received as part of the chunk. |
814 | 64 | Adrian Georgescu | |
815 | 64 | Adrian Georgescu | >+_transport_+: |
816 | 64 | Adrian Georgescu | |
817 | 64 | Adrian Georgescu | >The @MSRPTransport@ instance on which the chunk was received. |
818 | 64 | Adrian Georgescu | |
819 | 64 | Adrian Georgescu | >+_transaction_id_+: |
820 | 64 | Adrian Georgescu | |
821 | 64 | Adrian Georgescu | >The transaction ID which identifies the chunk which was ended. |
822 | 64 | Adrian Georgescu | |
823 | 64 | Adrian Georgescu | *sent_new_chunk*(*data*, *transport*, *chunk*) |
824 | 64 | Adrian Georgescu | >This method is called when the start of a new chunk is sent. |
825 | 64 | Adrian Georgescu | |
826 | 64 | Adrian Georgescu | >+_data_+: |
827 | 64 | Adrian Georgescu | |
828 | 64 | Adrian Georgescu | >The data which was sent along with the start of the chunk. |
829 | 64 | Adrian Georgescu | |
830 | 64 | Adrian Georgescu | >+_transport_+: |
831 | 64 | Adrian Georgescu | |
832 | 64 | Adrian Georgescu | >The @MSRPTransport@ instance on which the chunk was sent. |
833 | 64 | Adrian Georgescu | |
834 | 64 | Adrian Georgescu | >+_chunk_+: |
835 | 64 | Adrian Georgescu | |
836 | 64 | Adrian Georgescu | >The actual chunk object. |
837 | 64 | Adrian Georgescu | |
838 | 64 | Adrian Georgescu | *sent_chunk_data*(*data*, *transport*, *transaction_id*) |
839 | 64 | Adrian Georgescu | >This method is called when data is sent as part of a chunk previously announced via *sent_new_chunk*. |
840 | 64 | Adrian Georgescu | |
841 | 64 | Adrian Georgescu | >+_data_+: |
842 | 64 | Adrian Georgescu | |
843 | 64 | Adrian Georgescu | >The data sent as part of the chunk. |
844 | 64 | Adrian Georgescu | |
845 | 64 | Adrian Georgescu | >+_transport_+: |
846 | 64 | Adrian Georgescu | |
847 | 64 | Adrian Georgescu | >The @MSRPTransport@ instance on which the chunk was sent. |
848 | 64 | Adrian Georgescu | |
849 | 64 | Adrian Georgescu | >+_transaction_id_+: |
850 | 64 | Adrian Georgescu | |
851 | 64 | Adrian Georgescu | >The transaction ID which identifies the chunk for which data was sent. |
852 | 64 | Adrian Georgescu | |
853 | 64 | Adrian Georgescu | *sent_chunk_end*(*data*, *transport*, *transaction_id*) |
854 | 64 | Adrian Georgescu | >This method is called when the last data of a chunk is sent. The chunk was previously announced via *sent_new_chunk*. |
855 | 64 | Adrian Georgescu | |
856 | 64 | Adrian Georgescu | >+_data_+: |
857 | 64 | Adrian Georgescu | |
858 | 64 | Adrian Georgescu | >The last data sent as part of the chunk. |
859 | 64 | Adrian Georgescu | |
860 | 64 | Adrian Georgescu | >+_transport_+: |
861 | 64 | Adrian Georgescu | |
862 | 64 | Adrian Georgescu | >The @MSRPTransport@ instance on which the chunk was sent. |
863 | 64 | Adrian Georgescu | |
864 | 64 | Adrian Georgescu | >+_transaction_id_+: |
865 | 64 | Adrian Georgescu | |
866 | 64 | Adrian Georgescu | >The transaction ID which identifies the chunk which was ended. |
867 | 64 | Adrian Georgescu | |
868 | 64 | Adrian Georgescu | *debug*(*message*) |
869 | 64 | Adrian Georgescu | >This method is called when a debug level message is sent by the library. |
870 | 64 | Adrian Georgescu | |
871 | 64 | Adrian Georgescu | *info*(*message*) |
872 | 64 | Adrian Georgescu | >This method is called when a info level message is sent by the library. |
873 | 64 | Adrian Georgescu | |
874 | 64 | Adrian Georgescu | *warn*(*message*) |
875 | 64 | Adrian Georgescu | >This method is called when a warning level message is sent by the library. |
876 | 64 | Adrian Georgescu | |
877 | 64 | Adrian Georgescu | *error*(*message*) |
878 | 64 | Adrian Georgescu | >This method is called when a error level message is sent by the library. |
879 | 64 | Adrian Georgescu | |
880 | 64 | Adrian Georgescu | *fatal*(*message*) |
881 | 64 | Adrian Georgescu | >This method is called when a fatal level message is sent by the library. |
882 | 64 | Adrian Georgescu | |
883 | 64 | Adrian Georgescu | |
884 | 64 | Adrian Georgescu | h2. Examples |
885 | 64 | Adrian Georgescu | |
886 | 64 | Adrian Georgescu | |
887 | 64 | Adrian Georgescu | |
888 | 64 | Adrian Georgescu | h3. Creating an outbound connection |
889 | 64 | Adrian Georgescu | |
890 | 64 | Adrian Georgescu | |
891 | 64 | Adrian Georgescu | When creating an outbound connection, a relay is not usually used because NAT traversal is not a problem for the endpoing creating the connection. If one is nevertheless desired, a @ConnectorRelay@ can be used instead: |
892 | 64 | Adrian Georgescu | |
893 | 64 | Adrian Georgescu | <pre> |
894 | 1 | Adrian Georgescu | from msrplib.connect import ConnectorDirect |
895 | 1 | Adrian Georgescu | from msrplib.session import MSRPSession |
896 | 1 | Adrian Georgescu | |
897 | 1 | Adrian Georgescu | connector = ConnectorDirect() |
898 | 1 | Adrian Georgescu | full_local_path = connector.prepare() |
899 | 1 | Adrian Georgescu | try: |
900 | 1 | Adrian Georgescu | # put full_local_path in SDP 'a:path' attribute of offer |
901 | 1 | Adrian Georgescu | # get full_remote_path from remote's 'a:path: attribute of reply |
902 | 1 | Adrian Georgescu | msrp_transport = connector.complete(full_remote_path) |
903 | 1 | Adrian Georgescu | except: |
904 | 1 | Adrian Georgescu | connector.cleanup() |
905 | 1 | Adrian Georgescu | raise |
906 | 1 | Adrian Georgescu | |
907 | 1 | Adrian Georgescu | def handle_incoming(chunk=None, error=None): |
908 | 1 | Adrian Georgescu | if error is not None: |
909 | 1 | Adrian Georgescu | print 'Error: %s' % error |
910 | 1 | Adrian Georgescu | session.shutdown() |
911 | 1 | Adrian Georgescu | elif chunk is not None: |
912 | 1 | Adrian Georgescu | print 'Got data: %s' % chunk.data |
913 | 1 | Adrian Georgescu | |
914 | 1 | Adrian Georgescu | session = MSRPSession(msrp_transport, on_incoming_cb=handle_incoming) |
915 | 1 | Adrian Georgescu | session.send_chunk(msrp_transport.make_chunk(data='Hello world!')) |
916 | 64 | Adrian Georgescu | </pre> |
917 | 1 | Adrian Georgescu | |
918 | 1 | Adrian Georgescu | |
919 | 64 | Adrian Georgescu | h3. Waiting for an inbound connection |
920 | 1 | Adrian Georgescu | |
921 | 64 | Adrian Georgescu | |
922 | 64 | Adrian Georgescu | When creating an inbound connection, a relay must be used for NAT traversal. However, if one is not desired, an @AceptorDirect@ can be used instead: |
923 | 64 | Adrian Georgescu | |
924 | 64 | Adrian Georgescu | <pre> |
925 | 1 | Adrian Georgescu | from msrplib.connect import RelayConnection, MSRPRelaySettings |
926 | 1 | Adrian Georgescu | from msrplib.session import MSRPSession |
927 | 1 | Adrian Georgescu | |
928 | 1 | Adrian Georgescu | relay = MSRPRelaySettings(domain='example.org', username='user', password='pass') |
929 | 1 | Adrian Georgescu | connector = RelayConnection(relay, 'passive') |
930 | 1 | Adrian Georgescu | full_local_path = connector.prepare() |
931 | 1 | Adrian Georgescu | try: |
932 | 1 | Adrian Georgescu | # get full_remote_path from remote's 'a:path: attribute of offer |
933 | 1 | Adrian Georgescu | # put full_local_path in SDP 'a:path' attribute of reply |
934 | 1 | Adrian Georgescu | msrp_transport = connector.complete(full_remote_path) |
935 | 1 | Adrian Georgescu | except: |
936 | 1 | Adrian Georgescu | connector.cleanup() |
937 | 1 | Adrian Georgescu | raise |
938 | 1 | Adrian Georgescu | |
939 | 1 | Adrian Georgescu | def handle_incoming(chunk=None, error=None): |
940 | 1 | Adrian Georgescu | if error is not None: |
941 | 1 | Adrian Georgescu | print 'Error: %s' % error |
942 | 1 | Adrian Georgescu | session.shutdown() |
943 | 1 | Adrian Georgescu | elif chunk is not None: |
944 | 1 | Adrian Georgescu | print 'Got data: %s' % chunk.data |
945 | 1 | Adrian Georgescu | |
946 | 1 | Adrian Georgescu | session = MSRPSession(msrp_transport, on_incoming_cb=handle_incoming) |
947 | 1 | Adrian Georgescu | session.send_chunk(msrp_transport.make_chunk(data='Hello world!')) |
948 | 64 | Adrian Georgescu | </pre> |