SipMSRPApi

Version 52 (Luci Stanescu, 04/15/2010 05:09 pm)

1 1 Adrian Georgescu
= MSRP API =
2 1 Adrian Georgescu
3 48 Luci Stanescu
[[TOC(SipMSRPApi, SipDeveloperGuide, depth=2)]]
4 1 Adrian Georgescu
5 31 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). 
6 1 Adrian Georgescu
7 25 Adrian Georgescu
 * MSRP sessions are defined in [http://tools.ietf.org/html/rfc4975 RFC 4975]
8 25 Adrian Georgescu
 * MSRP relay extension used for NAT traversal of instant messaging and file transfer sessions is defined in [http://tools.ietf.org/html/rfc4976 RFC 4976]
9 1 Adrian Georgescu
10 32 Adrian Georgescu
The MSRP protocol stack is implemented by [http://devel.ag-projects.com/cgi-bin/darcsweb.cgi?r=python-msrplib;a=summary msrplib] Python package. 
11 4 Oliver Bril
12 33 Adrian Georgescu
{{{msrplib}}} is based upon [http://twistedmatrix.com twisted] and [http://download.ag-projects.com/SipClient/ eventlet] and provides a set of classes for establishing and managing MSRP connections.
13 1 Adrian Georgescu
14 28 Adrian Georgescu
The library consists of the following modules:
15 1 Adrian Georgescu
16 1 Adrian Georgescu
 '''msrplib.transport'''::
17 27 Adrian Georgescu
 Defines {{{MSRPTransport}}} class, which provides low level control over MSRP connections.
18 2 Redmine Admin
19 1 Adrian Georgescu
 '''msrplib.connect'''::
20 1 Adrian Georgescu
 Defines means to establish a connection, bind it, and provide an initialized {{{MSRPTransport}}} instance.
21 1 Adrian Georgescu
22 1 Adrian Georgescu
 '''msrplib.session'''::
23 1 Adrian Georgescu
 Defines {{{MSRPSession}}} class, which provides high level control over a MSRP connection.
24 1 Adrian Georgescu
25 1 Adrian Georgescu
 '''msrplib.protocol'''::
26 42 Luci Stanescu
 Provides representation and parsing of MSRP entities - chunks and MSRP URIs.  
27 1 Adrian Georgescu
28 48 Luci Stanescu
== URI ==
29 39 Luci Stanescu
30 44 Luci Stanescu
This class is implemented in the {{{msrplib.protocol}}} module and is used to represent an MSRP URI.
31 1 Adrian Georgescu
32 49 Adrian Georgescu
==== methods ====
33 1 Adrian Georgescu
34 39 Luci Stanescu
 '''!__init!__'''(''self'', '''host'''={{{None}}}, '''use_tls'''={{{False}}}, '''user'''={{{None}}}, '''port'''={{{None}}}, '''session_id'''={{{None}}}, '''parameters'''={{{None}}}, '''credentials'''={{{None}}})::
35 39 Luci Stanescu
  Constructs a new {{{URI}}}. All the arguments specified here are also attributes on the object. For more information on these attributes, see RFC4975.
36 39 Luci Stanescu
  [[BR]]''host'':[[BR]]
37 39 Luci Stanescu
  The hostname or IP address which forms the URI.
38 39 Luci Stanescu
  [[BR]]''use_tls'':[[BR]]
39 39 Luci Stanescu
  Whether this identifies an msrps or msrp URI.
40 39 Luci Stanescu
  [[BR]]''user'':[[BR]]
41 39 Luci Stanescu
  The user part of the URI.
42 39 Luci Stanescu
  [[BR]]''port'':[[BR]]
43 39 Luci Stanescu
  The port in the URI.
44 39 Luci Stanescu
  [[BR]]''session_id'':[[BR]]
45 39 Luci Stanescu
  The session identifier part of the URI.
46 1 Adrian Georgescu
  [[BR]]''parameters'':[[BR]]
47 39 Luci Stanescu
  A {{{dict}}} containing the parameters which will be appended to the URI.
48 39 Luci Stanescu
  [[BR]]''credentials'':[[BR]]
49 1 Adrian Georgescu
  A {{{gnutls.interfaces.twisted.X509Credentials}}} object which will be used if this identifies a TLS URI to authenticate to the other endpoint.
50 39 Luci Stanescu
51 48 Luci Stanescu
== MSRPRelaySettings ==
52 1 Adrian Georgescu
53 45 Luci Stanescu
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).
54 39 Luci Stanescu
55 49 Adrian Georgescu
==== methods ====
56 39 Luci Stanescu
57 39 Luci Stanescu
 '''!__init!__'''(''self'', '''domain''', '''username''', '''password''', '''host'''={{{None}}}, '''use_tls'''={{{False}}}, '''port'''={{{None}}}, '''credentials'''={{{None}}})::
58 39 Luci Stanescu
  Constructs a new {{{URI}}}. All the arguments specified here are also attributes on the object. For more information on these attributes, see RFC4975.
59 39 Luci Stanescu
  [[BR]]''domain'':[[BR]]
60 39 Luci Stanescu
  The DNS domain in which to search for a MSRP relay using SRV queries.
61 39 Luci Stanescu
  [[BR]]''username'':[[BR]]
62 39 Luci Stanescu
  The username which will be used to authenticate to the relay.
63 39 Luci Stanescu
  [[BR]]''password'':[[BR]]
64 39 Luci Stanescu
  The password which will be used to authenticate to the relay.
65 39 Luci Stanescu
  [[BR]]''host'':[[BR]]
66 39 Luci Stanescu
  The hostname or IP address of the MSRP relay.
67 1 Adrian Georgescu
  [[BR]]''use_tls'':[[BR]]
68 39 Luci Stanescu
  Whether this identifies an msrps or msrp URI.
69 39 Luci Stanescu
  [[BR]]''port'':[[BR]]
70 1 Adrian Georgescu
  The port in the URI.
71 39 Luci Stanescu
  [[BR]]''credentials'':[[BR]]
72 39 Luci Stanescu
  A {{{gnutls.interfaces.twisted.X509Credentials}}} object which will be used to authenticate to the relay if TLS is used.
73 39 Luci Stanescu
74 48 Luci Stanescu
== ConnectorDirect ==
75 39 Luci Stanescu
76 44 Luci Stanescu
This class is implemented in the {{{msrplib.connect}}} module and is used for outbound MSRP connections without a relay.
77 39 Luci Stanescu
78 49 Adrian Georgescu
==== methods ====
79 39 Luci Stanescu
80 39 Luci Stanescu
 '''!__init!__'''(''self'', '''loger'''={{{None}}})::
81 44 Luci Stanescu
 Constructs a new ConnectorDirect.
82 39 Luci Stanescu
 [[BR]]''logger'':[[BR]]
83 39 Luci Stanescu
 The logger which will be used for this MSRP connection. See the [wiki:SipMSRPApi#Logging Logging] section for more information.
84 39 Luci Stanescu
85 39 Luci Stanescu
 '''prepare'''(''self'', '''local_uri'''={{{None}}})::
86 39 Luci Stanescu
 This method returns a full local path - list of {{{protocol.URI}}} instances, suitable to be put in SDP {{{'a:path'}}} attribute.
87 39 Luci Stanescu
 [[BR]]''local_uri'':[[BR]]
88 39 Luci Stanescu
 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
89 39 Luci Stanescu
 will be automatically generated
90 1 Adrian Georgescu
 
91 1 Adrian Georgescu
 '''complete'''(''self'', '''full_remote_path''')::
92 39 Luci Stanescu
 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.
93 1 Adrian Georgescu
 [[BR]]''full_remote_path'':[[BR]]
94 39 Luci Stanescu
 A list of {{{protocol.URI}}} instances, obtained by parsing {{{'a:path'}}} put in SDP by the remote party.
95 1 Adrian Georgescu
96 39 Luci Stanescu
 '''cleanup'''(''self'')::
97 39 Luci Stanescu
 This method cleans up after {{{prepare()}}}; it should be called if {{{complete()}}} will not be called for whatever reason.
98 1 Adrian Georgescu
99 48 Luci Stanescu
== ConnectorRelay ==
100 1 Adrian Georgescu
101 44 Luci Stanescu
This class is implemented in the {{{msrplib.connect}}} module and is used for outbound MSRP connections using a relay.
102 1 Adrian Georgescu
103 49 Adrian Georgescu
==== methods ====
104 39 Luci Stanescu
105 39 Luci Stanescu
 '''!__init!__'''(''self'', '''relay''', '''loger'''={{{None}}})::
106 39 Luci Stanescu
 Constructs a new ConnectorRelay.
107 39 Luci Stanescu
 [[BR]]''relay'':[[BR]]
108 39 Luci Stanescu
 An instance of {{{MSRPRelaySettings}}} which identifies the relay which is to be used.
109 39 Luci Stanescu
 [[BR]]''logger'':[[BR]]
110 39 Luci Stanescu
 The logger which will be used for this MSRP connection. See the [wiki:SipMSRPApi#Logging Logging] section for more information.
111 39 Luci Stanescu
112 39 Luci Stanescu
 '''prepare'''(''self'', '''local_uri'''={{{None}}})::
113 39 Luci Stanescu
 This method returns a full local path - list of {{{protocol.URI}}} instances, suitable to be put in SDP {{{'a:path'}}} attribute.
114 39 Luci Stanescu
 [[BR]]''local_uri'':[[BR]]
115 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
116 39 Luci Stanescu
 will be automatically generated
117 39 Luci Stanescu
 
118 1 Adrian Georgescu
 '''complete'''(''self'', '''full_remote_path''')::
119 39 Luci Stanescu
 This method establishes the connection to the relay 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.
120 39 Luci Stanescu
 [[BR]]''full_remote_path'':[[BR]]
121 39 Luci Stanescu
 A list of {{{protocol.URI}}} instances, obtained by parsing {{{'a:path'}}} put in SDP by the remote party.
122 39 Luci Stanescu
123 1 Adrian Georgescu
 '''cleanup'''(''self'')::
124 39 Luci Stanescu
 This method cleans up after {{{prepare()}}}; it should be called if {{{complete()}}} will not be called for whatever reason.
125 1 Adrian Georgescu
126 48 Luci Stanescu
== AcceptorDirect ==
127 1 Adrian Georgescu
128 44 Luci Stanescu
This class is implemented in the {{{msrplib.connect}}} module and is used for inbound MSRP connections without using a relay.
129 1 Adrian Georgescu
130 49 Adrian Georgescu
==== methods ====
131 39 Luci Stanescu
132 39 Luci Stanescu
 '''!__init!__'''(''self'', '''loger'''={{{None}}})::
133 39 Luci Stanescu
  Constructs a new AcceptorDirect.
134 39 Luci Stanescu
 [[BR]]''logger'':[[BR]]
135 39 Luci Stanescu
 The logger which will be used for this MSRP connection. See the [wiki:SipMSRPApi#Logging Logging] section for more information.
136 39 Luci Stanescu
137 39 Luci Stanescu
 '''prepare'''(''self'', '''local_uri'''={{{None}}})::
138 1 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.
139 39 Luci Stanescu
 [[BR]]''local_uri'':[[BR]]
140 39 Luci Stanescu
 This attribute will be used to construct the local path and to listen for incomming connections. If not provided, one
141 52 Luci Stanescu
 will be automatically generated. Note that the object may be changed in place: for example, if the port specified is 0,
142 52 Luci Stanescu
 a random one will be selected and the object will be updated accordingly.
143 39 Luci Stanescu
 
144 39 Luci Stanescu
 '''complete'''(''self'', '''full_remote_path''')::
145 39 Luci Stanescu
 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.
146 39 Luci Stanescu
 [[BR]]''full_remote_path'':[[BR]]
147 39 Luci Stanescu
 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.
148 39 Luci Stanescu
149 39 Luci Stanescu
 '''cleanup'''(''self'')::
150 39 Luci Stanescu
 This method cleans up after {{{prepare()}}}; it should be called if {{{complete()}}} will not be called for whatever reason.
151 39 Luci Stanescu
152 48 Luci Stanescu
== AcceptorRelay ==
153 39 Luci Stanescu
154 44 Luci Stanescu
This class is implemented in the {{{msrplib.connect}}} module and is used for inbound MSRP connections using a relay.
155 39 Luci Stanescu
156 49 Adrian Georgescu
==== methods ====
157 39 Luci Stanescu
158 39 Luci Stanescu
 '''!__init!__'''(''self'', '''relay''', '''loger'''={{{None}}})::
159 39 Luci Stanescu
 Constructs a new AcceptorRelay.
160 39 Luci Stanescu
 [[BR]]''relay'':[[BR]]
161 39 Luci Stanescu
 An instance of {{{MSRPRelaySettings}}} which identifies the relay which is to be used.
162 39 Luci Stanescu
 [[BR]]''logger'':[[BR]]
163 1 Adrian Georgescu
 The logger which will be used for this MSRP connection. See the [wiki:SipMSRPApi#Logging Logging] section for more information.
164 39 Luci Stanescu
165 39 Luci Stanescu
 '''prepare'''(''self'', '''local_uri'''={{{None}}})::
166 1 Adrian Georgescu
 This method connects to the relay specified in {{{__init__}}}. It returns a full local path - list of {{{protocol.URI}}} instances, suitable to be put in SDP {{{'a:path'}}} attribute.
167 39 Luci Stanescu
 [[BR]]''local_uri'':[[BR]]
168 39 Luci Stanescu
 This attribute will be used to construct the local path. If not provided, one will be automatically generated
169 39 Luci Stanescu
 
170 39 Luci Stanescu
 '''complete'''(''self'', '''full_remote_path''')::
171 39 Luci Stanescu
 This method waits for an incoming chunk sent by the other party. It returns {{{transport.MSRPTransport}}} instance, ready to read and send chunks.
172 39 Luci Stanescu
 [[BR]]''full_remote_path'':[[BR]]
173 39 Luci Stanescu
 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.
174 39 Luci Stanescu
175 39 Luci Stanescu
 '''cleanup'''(''self'')::
176 39 Luci Stanescu
 This method cleans up after {{{prepare()}}}; it should be called if {{{complete()}}} will not be called for whatever reason.
177 39 Luci Stanescu
178 51 Luci Stanescu
== MSRPData ==
179 51 Luci Stanescu
180 51 Luci Stanescu
This class is implemented in the {{{msrplib.protocol}}} module and represents an MSRP chunk, either a request or a response.
181 51 Luci Stanescu
182 51 Luci Stanescu
==== attributes ====
183 51 Luci Stanescu
184 51 Luci Stanescu
 The following attributes are read-only.
185 51 Luci Stanescu
186 51 Luci Stanescu
 '''content_type'''::
187 51 Luci Stanescu
  The MIME type of the payload carried by this chunk, which is stored in the Content-Type header.
188 51 Luci Stanescu
189 51 Luci Stanescu
 '''message_id'''::
190 51 Luci Stanescu
  The ID of the message this chunk is part of, which is stored in the Message-ID header.
191 51 Luci Stanescu
192 51 Luci Stanescu
 '''byte_range'''::
193 51 Luci Stanescu
  A 3-tuple containing the start, end and length values (in this order) from the Byte-Range header.
194 51 Luci Stanescu
195 51 Luci Stanescu
 '''status'''::
196 51 Luci Stanescu
  The value of the Status header.
197 51 Luci Stanescu
198 51 Luci Stanescu
 '''failure_report'''::
199 51 Luci Stanescu
  The value of the Failure-Report header, whether it exists or it is implied; one of {{{'yes'}}}, {{{'no'}}}, {{{'partial'}}}.
200 51 Luci Stanescu
201 51 Luci Stanescu
 '''success_report'''::
202 51 Luci Stanescu
  The value of the Success-Report header, whether it exists or it is implied; one of {{{'yes'}}} or {{{'no'}}}.
203 51 Luci Stanescu
204 51 Luci Stanescu
 '''size'''::
205 51 Luci Stanescu
  The size of the payload of this chunk, in bytes.
206 51 Luci Stanescu
207 51 Luci Stanescu
==== methods ====
208 51 Luci Stanescu
209 51 Luci Stanescu
 '''!__init!__'''(''self'', '''transaction_id''', '''method'''={{{None}}}, '''code'''={{{None}}}, '''comment'''={{{None}}}, '''headers'''={{{None}}}, '''data'''={{{''}}}, '''contflag'''={{{'$'}}})::
210 51 Luci Stanescu
  Initializes a new MSRPData instance. All the arguments are also available as attributes.
211 51 Luci Stanescu
  [[BR]]''transaction_id'':[[BR]]
212 51 Luci Stanescu
  The transaction identified of this chunk.
213 51 Luci Stanescu
  [[BR]]''method'':[[BR]]
214 51 Luci Stanescu
  The method of this chunk if it a request and {{{None}}} if it is a response.
215 51 Luci Stanescu
  [[BR]]''code'':[[BR]]
216 51 Luci Stanescu
  The status code of this chunk if it is a response and {{{None}}} if it is a request.
217 51 Luci Stanescu
  [[BR]]''comment'':[[BR]]
218 51 Luci Stanescu
  The comment of this chunk if it is a response and {{{None}}} if it is a request.
219 51 Luci Stanescu
  [[BR]]''headers'':[[BR]]
220 51 Luci Stanescu
  A dict containing the headers which are to be added to this chunk, or {{{None}}} if no headers are to be added.
221 51 Luci Stanescu
  [[BR]]''data'':[[BR]]
222 51 Luci Stanescu
  The payload of this chunk, or an empty string if no payload is to be added.
223 51 Luci Stanescu
  [[BR]]''contflag'':[[BR]]
224 51 Luci Stanescu
  The MSRP continuation flag of this chunk, one of {{{'$'}}}, {{{'#'}}} or {{{'+'}}}.
225 51 Luci Stanescu
226 51 Luci Stanescu
 '''copy'''(''self'')::
227 51 Luci Stanescu
  Returns a new MSRPData instance with exactly the same attributes as this object.
228 51 Luci Stanescu
229 51 Luci Stanescu
 '''add_header'''(''self'', '''header''')::
230 51 Luci Stanescu
  Add a MSRP header to this chunk.
231 51 Luci Stanescu
  [[BR]]''header'':[[BR]]
232 51 Luci Stanescu
  The header object which is to be added to this chunk.
233 51 Luci Stanescu
234 51 Luci Stanescu
 '''verify_headers'''(''self'')::
235 51 Luci Stanescu
  Verifies that the chunk contains a To-Path and a From-Path header and that all the headers are valid.
236 51 Luci Stanescu
237 51 Luci Stanescu
 '''encode_start'''(''self'')::
238 51 Luci Stanescu
  Returns a string containing the MSRP header of this chunk.
239 51 Luci Stanescu
240 51 Luci Stanescu
 '''encode_end'''(''self'', '''continuation''')::
241 51 Luci Stanescu
  Returns a string containing the MSRP end line of this chunk: 7 commas followed by the transaction identifier and the continuation flag specified.
242 51 Luci Stanescu
  [[BR]]''continuation'':[[BR]]
243 51 Luci Stanescu
  The continuation flag which is to be used in the end line.
244 51 Luci Stanescu
245 51 Luci Stanescu
 '''encode'''(''self''):
246 51 Luci Stanescu
  Returns a string containing the whole of this MSRP chunk.
247 51 Luci Stanescu
248 51 Luci Stanescu
249 14 Oliver Bril
== MSRPTransport ==
250 1 Adrian Georgescu
251 51 Luci Stanescu
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.
252 1 Adrian Georgescu
253 1 Adrian Georgescu
==== methods ====
254 1 Adrian Georgescu
255 1 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}}})::
256 51 Luci Stanescu
 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.
257 51 Luci Stanescu
 [[BR]]''transaction_id'':[[BR]]
258 51 Luci Stanescu
 The transaction id which will be put in the chunk. If it is not provided, one will be randomly generated.
259 51 Luci Stanescu
 [[BR]]''method'':[[BR]]
260 51 Luci Stanescu
 The method of the new MSRP request, or {{{None}}} if a response is required.
261 51 Luci Stanescu
 [[BR]]''code'':[[BR]]
262 51 Luci Stanescu
 The code of the new MSRP response, or {{{None}}} if a request is required.
263 51 Luci Stanescu
 [[BR]]''code'':[[BR]]
264 51 Luci Stanescu
 The comment of the new MSRP response, or {{{None}}} if a request is required or a comment on the response is not.
265 51 Luci Stanescu
 [[BR]]''data'':[[BR]]
266 51 Luci Stanescu
 The payload of the new chunk, or an empty string if no payload is required.
267 1 Adrian Georgescu
 [[BR]]''contflag'':[[BR]]
268 51 Luci Stanescu
 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.
269 51 Luci Stanescu
 [[BR]]''start'':[[BR]]
270 51 Luci Stanescu
 The first byte's index within the whole message payload this chunk will carry as its own payload.
271 51 Luci Stanescu
 [[BR]]''end'':[[BR]]
272 51 Luci Stanescu
 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}}}.
273 51 Luci Stanescu
 [[BR]]''length'':[[BR]]
274 51 Luci Stanescu
 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.
275 51 Luci Stanescu
 [[BR]]''message_id'':[[BR]]
276 51 Luci Stanescu
 The ID of the message this chunk is part of. If it is not provided, one will be randomly generated.
277 1 Adrian Georgescu
278 51 Luci Stanescu
 '''write_chunk'''(''self'', '''chunk''', '''wait'''={{{True}}})::
279 51 Luci Stanescu
 Writes the chunk provided to the underlying socket.
280 51 Luci Stanescu
 [[BR]]''chunk'':[[BR]]
281 51 Luci Stanescu
 The chunk which is to be written, an instance of {{{MSRPData}}}.
282 51 Luci Stanescu
 [[BR]]''wait'':[[BR]]
283 51 Luci Stanescu
 If {{{True}}}, waits for the operation to complete.
284 1 Adrian Georgescu
285 51 Luci Stanescu
 '''write_response'''(''self'', '''chunk''', '''code''', '''comment''', '''wait'''={{{True}}}):
286 51 Luci Stanescu
 Creates a response which is suitable as a reply to the specified chunk and writes it to the underlying socket.
287 51 Luci Stanescu
 [[BR]]''chunk'':[[BR]]
288 51 Luci Stanescu
 The chunk for which to create a response.
289 51 Luci Stanescu
 [[BR]]''code'':[[BR]]
290 51 Luci Stanescu
 The status code of the response which is to be created.
291 51 Luci Stanescu
 [[BR]]''comment'':[[BR]]
292 51 Luci Stanescu
 The comment of the response which is to be created.
293 51 Luci Stanescu
 [[BR]]''wait'':[[BR]]
294 51 Luci Stanescu
 If {{{True}}}, waits for the operation to complete.
295 51 Luci Stanescu
296 27 Adrian Georgescu
 '''read_chunk'''(''self'', '''size'''={{{None}}})::
297 1 Adrian Georgescu
 Waits for a new chunk and returns it.
298 15 Oliver Bril
 If there was an error, closes the connection and raises {{{ChunkParseError}}}.
299 27 Adrian Georgescu
300 15 Oliver Bril
 In case of unintelligible input, loses the connection and returns {{{None}}}.
301 39 Luci Stanescu
 When the connection is closed, raises the reason of the closure (e.g. {{{ConnectionDone}}}).
302 15 Oliver Bril
303 1 Adrian Georgescu
 If the data already read exceeds ''size'', stops reading the data and returns
304 15 Oliver Bril
 a "virtual" chunk, i.e. the one that does not actually correspond the the real
305 1 Adrian Georgescu
 MSRP chunk. Such chunks have Byte-Range header changed to match the number of
306 48 Luci Stanescu
 bytes read and continuation that is {{{'+'}}}; they also possess {{{segment}}} attribute,
307 15 Oliver Bril
 an integer, starting with 1 and increasing with every new segment of the chunk.
308 1 Adrian Georgescu
309 1 Adrian Georgescu
 Note, that ''size'' only hints when to interrupt the segment but does not affect
310 1 Adrian Georgescu
 how the data is read from socket. You may have segments bigger than ''size'' and it's
311 44 Luci Stanescu
 legal to set ''size'' to zero (which would mean return a chunk as long as you get
312 39 Luci Stanescu
 some data, regardless how small).
313 51 Luci Stanescu
 
314 51 Luci Stanescu
 [[BR]]''size'':[[BR]]
315 51 Luci Stanescu
 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.
316 41 Luci Stanescu
317 1 Adrian Georgescu
 '''check_incoming_SEND_chunk'''(''self'', '''chunk''')::
318 1 Adrian Georgescu
 Checks the 'To-Path' and 'From-Path' of the incoming SEND chunk.
319 1 Adrian Georgescu
 Returns None is the paths are valid for this connection.
320 1 Adrian Georgescu
 If an error is detected an MSRPError is created and returned.
321 1 Adrian Georgescu
322 51 Luci Stanescu
== OutgoingFile ==
323 51 Luci Stanescu
324 51 Luci Stanescu
This class is implemented in the {{{msrplib.session}}} module and represents a file which is to be sent via MSRP.
325 51 Luci Stanescu
326 51 Luci Stanescu
==== attributes ====
327 51 Luci Stanescu
328 51 Luci Stanescu
 '''headers'''::
329 51 Luci Stanescu
  A dict which maps header names to header objects. These headers will be sent in the MSRP message used to send the file.
330 51 Luci Stanescu
331 51 Luci Stanescu
==== methods ====
332 51 Luci Stanescu
333 51 Luci Stanescu
 '''!__init!__'''(''self'', '''fileobj''', '''size''', '''content_type'''={{{None}}}, '''position'''={{{0}}}, '''message_id'''={{{None}}})::
334 51 Luci Stanescu
  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.
335 51 Luci Stanescu
  [[BR]]''fileobj'':[[BR]]
336 51 Luci Stanescu
  A file-like object which will be used for reading the data to be sent.
337 51 Luci Stanescu
  [[BR]]''size'':[[BR]]
338 51 Luci Stanescu
  The size of the whole file.
339 51 Luci Stanescu
  [[BR]]''content_type'':[[BR]]
340 51 Luci Stanescu
  The MIME type associated with the file's data. If provided, it will be added as a Content-Type header.
341 51 Luci Stanescu
  [[BR]]''position'':[[BR]]
342 51 Luci Stanescu
  The position within the file from which data will be sent. The file object must already be seeked to this position.
343 51 Luci Stanescu
  [[BR]]''message_id'':[[BR]]
344 51 Luci Stanescu
  The message ID which will be used for sending this file.
345 51 Luci Stanescu
346 1 Adrian Georgescu
== MSRPSession ==
347 1 Adrian Georgescu
348 1 Adrian Georgescu
This class is implemented in the {{{msrplib.session}}} module and provides a high level API for MSRP sessions.
349 1 Adrian Georgescu
350 1 Adrian Georgescu
==== methods ====
351 1 Adrian Georgescu
352 1 Adrian Georgescu
 '''!__init!__'''(''self'', '''msrptransport''', '''accept_types'''={{{['*']}}}, '''on_incoming_cb'''={{{None}}})::
353 51 Luci Stanescu
 Initializes MSRPSession instance over the specified transport. The incoming chunks are reported through the ''on_incoming_cb'' callback.
354 51 Luci Stanescu
 [[BR]]''msrptransport'':[[BR]]
355 51 Luci Stanescu
 An instance of {{{MSRPTransport}}} over which this session will operate.
356 51 Luci Stanescu
 [[BR]]''accept_types'':[[BR]]
357 51 Luci Stanescu
 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.
358 51 Luci Stanescu
 [[BR]]''on_incoming_cb'':[[BR]]
359 51 Luci Stanescu
 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.
360 1 Adrian Georgescu
361 1 Adrian Georgescu
 '''send_chunk'''(''self'', '''chunk''', '''response_cb'''={{{None}}})::
362 51 Luci Stanescu
 Sends the specified chunk and reports the result via the ''response_cb'' callback.
363 1 Adrian Georgescu
364 1 Adrian Georgescu
 When ''response_cb'' argument is present, it will be used to report
365 1 Adrian Georgescu
 the transaction response to the caller. When a response is received or generated
366 1 Adrian Georgescu
 locally, ''response_cb'' is called with one argument. The function must do something
367 38 Adrian Georgescu
 quickly and must not block, because otherwise it would block the reader greenlet.
368 39 Luci Stanescu
369 1 Adrian Georgescu
 If no response was received after {{{RESPONSE_TIMEOUT}}} seconds,
370 1 Adrian Georgescu
 * 408 response is generated if Failure-Report was {{{'yes'}}} or absent
371 1 Adrian Georgescu
 * 200 response is generated if Failure-Report was {{{'partial'}}} or {{{'no'}}}
372 1 Adrian Georgescu
373 1 Adrian Georgescu
 Note that it's rather wasteful to provide ''response_cb'' argument other than {{{None}}}
374 1 Adrian Georgescu
 for chunks with Failure-Report='no' since it will always fire 30 seconds later
375 1 Adrian Georgescu
 with 200 result (unless the other party is broken and ignores Failure-Report header)
376 1 Adrian Georgescu
377 51 Luci Stanescu
 If sending is not possible, {{{MSRPSessionError}}} is raised.
378 1 Adrian Georgescu
379 51 Luci Stanescu
 [[BR]]''chunk'':[[BR]]
380 51 Luci Stanescu
 The chunk which is to be sent. It must be an instance of {{{MSRPData}}} which represents a request.
381 51 Luci Stanescu
 [[BR]]''response_cb'':[[BR]]
382 51 Luci Stanescu
 A function receiving a single argument which will be the response received for the sent chunk.
383 51 Luci Stanescu
384 1 Adrian Georgescu
 '''deliver_chunk'''(''self'', '''chunk''', '''event'''={{{None}}})::
385 51 Luci Stanescu
 Sends the specified chunk and waits for the transaction response (if Failure-Report header is not {{{'no'}}}).
386 51 Luci Stanescu
 Returns the transaction response if it's a success or raise {{{MSRPTransactionError}}} if it's not.
387 1 Adrian Georgescu
388 1 Adrian Georgescu
 If chunk's Failure-Report is {{{'no'}}}, returns {{{None}}} immediately.
389 1 Adrian Georgescu
390 51 Luci Stanescu
 [[BR]]''chunk'':[[BR]]
391 51 Luci Stanescu
 The chunk which is to be sent. It must be an intance of {{{MSRPData}}} which represents a request.
392 51 Luci Stanescu
 [[BR]]''event'':[[BR]]
393 51 Luci Stanescu
 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.
394 51 Luci Stanescu
 
395 51 Luci Stanescu
 '''send_file'''(''self'', '''outgoing_file''')::
396 51 Luci Stanescu
 Adds the specified file to the queue of files to be sent. The method returns immediately.
397 51 Luci Stanescu
 [[BR]]''outgoing_file'':[[BR]]
398 51 Luci Stanescu
 An instance of {{{OutgoingFile}}} which represents the file to be sent.
399 51 Luci Stanescu
400 44 Luci Stanescu
 '''shutdown'''(''self'', '''sync'''={{{True}}})::
401 1 Adrian Georgescu
 Sends the messages already in queue then closes the connection.
402 44 Luci Stanescu
403 44 Luci Stanescu
== MSRPServer ==
404 44 Luci Stanescu
405 1 Adrian Georgescu
This class is implemented in the {{{msrplib.connect}}} module.
406 44 Luci Stanescu
    
407 39 Luci Stanescu
MSRPServer solves the problem with AcceptorDirect: concurrent using of 2
408 39 Luci Stanescu
or more AcceptorDirect instances on the same non-zero port is not possible.
409 49 Adrian Georgescu
If you initialize() those instances, one after another, one will listen on
410 1 Adrian Georgescu
the socket and another will get BindError.
411 1 Adrian Georgescu
412 1 Adrian Georgescu
MSRPServer avoids the problem by sharing the listening socket between multiple connections.
413 39 Luci Stanescu
It has a slightly different interface from AcceptorDirect, so it cannot be considered a drop-in
414 46 Luci Stanescu
replacement.
415 46 Luci Stanescu
416 1 Adrian Georgescu
It manages the listening sockets and binds incoming requests.
417 1 Adrian Georgescu
418 1 Adrian Georgescu
==== methods ====
419 1 Adrian Georgescu
420 1 Adrian Georgescu
 '''!__init!__'''(''self'', '''logger''')::
421 51 Luci Stanescu
 Constructs a new MSRPServer which will be using the specifed logger for its connections.
422 51 Luci Stanescu
 [[BR]]''logger'':[[BR]]
423 51 Luci Stanescu
 The default logger which will be used for this object's MSRP connections. See the [wiki:SipMSRPApi#Logging Logging] section for more information.
424 1 Adrian Georgescu
425 1 Adrian Georgescu
 '''prepare'''(''self'', ''local_uri''={{{None}}}, ''logger''={{{None}}})::
426 1 Adrian Georgescu
 Starts a listening port specified by ''local_uri'' if there isn't one on that port/interface already.
427 1 Adrian Georgescu
 Adds ''local_uri'' to the list of expected URIs, so that incoming connections featuring this URI won't be rejected.
428 51 Luci Stanescu
 If ''logger'' is provided, it uses it for this connection instead of the one specified in {{{__init___}}}.
429 51 Luci Stanescu
 [[BR]]''local_uri'':[[BR]]
430 51 Luci Stanescu
 The URI which will be added to the list of expected URIs. Connections from this URI will be accepted.
431 51 Luci Stanescu
 [[BR]]''logger'':[[BR]]
432 51 Luci Stanescu
 The logger which will be used for connections from the specified URI. See the [wiki:SipMSRPApi#Logging Logging] section for more information.
433 15 Oliver Bril
434 1 Adrian Georgescu
 '''complete'''(''self'', ''full_remote_path'')::
435 51 Luci Stanescu
 Waits until one of the incoming connections binds using the provided ''full_remote_path''.
436 51 Luci Stanescu
 Returns the connected and bound {{{MSRPTransport}}} instance.
437 51 Luci Stanescu
 If no such binding was made within {{{MSRPBindSessionTimeout.seconds}}}, {{{MSRPBindSessionTimeout}}} is raised.
438 51 Luci Stanescu
 [[BR]]''full_remote_path'':[[BR]]
439 51 Luci Stanescu
 A list of {{{protocol.URI}}} instances, obtained by parsing {{{'a:path'}}} put in SDP by the remote party.
440 38 Adrian Georgescu
441 38 Adrian Georgescu
 '''cleanup'''(''self'', ''local_uri'')::
442 46 Luci Stanescu
 Removes ''local_uri'' from the list of expected URIs.
443 51 Luci Stanescu
 [[BR]]''local_uri'':[[BR]]
444 51 Luci Stanescu
 The URI which is to be removed from the list of expected URIs.
445 49 Adrian Georgescu
446 46 Luci Stanescu
== Logging ==
447 46 Luci Stanescu
448 46 Luci Stanescu
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:
449 46 Luci Stanescu
450 46 Luci Stanescu
==== methods ====
451 46 Luci Stanescu
452 46 Luci Stanescu
 '''received_new_chunk'''('''data''', '''transport''', '''chunk''')::
453 46 Luci Stanescu
  This method is called when the start of a new chunk is received.
454 46 Luci Stanescu
  [[BR]]''data'':[[BR]]
455 46 Luci Stanescu
  The data which came along with the start of the chunk.
456 46 Luci Stanescu
  [[BR]]''transport'':[[BR]]
457 46 Luci Stanescu
  The {{{MSRPTransport}}} instance on which the chunk was received.
458 46 Luci Stanescu
  [[BR]]''chunk'':[[BR]]
459 46 Luci Stanescu
  The actual chunk object.
460 46 Luci Stanescu
461 46 Luci Stanescu
 '''received_chunk_data'''('''data''', '''transport''', '''transaction_id''')::
462 46 Luci Stanescu
  This method is called when data is received as part of a chunk previously announced via '''received_new_chunk'''.
463 46 Luci Stanescu
  [[BR]]''data'':[[BR]]
464 46 Luci Stanescu
  The data received as part of the chunk.
465 47 Luci Stanescu
  [[BR]]''transport'':[[BR]]
466 46 Luci Stanescu
  The {{{MSRPTransport}}} instance on which the chunk was received.
467 46 Luci Stanescu
  [[BR]]''transaction_id'':[[BR]]
468 46 Luci Stanescu
  The transaction ID which identifies the chunk for which data was received.
469 46 Luci Stanescu
470 46 Luci Stanescu
 '''received_chunk_end'''('''data''', '''transport''', '''transaction_id''')::
471 46 Luci Stanescu
  This method is called when the last data of a chunk is received. The chunk was previously announced via '''received_new_chunk'''.
472 46 Luci Stanescu
  [[BR]]''data'':[[BR]]
473 46 Luci Stanescu
  The last data received as part of the chunk.
474 46 Luci Stanescu
  [[BR]]''transport'':[[BR]]
475 46 Luci Stanescu
  The {{{MSRPTransport}}} instance on which the chunk was received.
476 46 Luci Stanescu
  [[BR]]''transaction_id'':[[BR]]
477 46 Luci Stanescu
  The transaction ID which identifies the chunk which was ended.
478 46 Luci Stanescu
479 46 Luci Stanescu
 '''sent_new_chunk'''('''data''', '''transport''', '''chunk''')::
480 46 Luci Stanescu
  This method is called when the start of a new chunk is sent.
481 46 Luci Stanescu
  [[BR]]''data'':[[BR]]
482 46 Luci Stanescu
  The data which was sent along with the start of the chunk.
483 46 Luci Stanescu
  [[BR]]''transport'':[[BR]]
484 46 Luci Stanescu
  The {{{MSRPTransport}}} instance on which the chunk was sent.
485 46 Luci Stanescu
  [[BR]]''chunk'':[[BR]]
486 46 Luci Stanescu
  The actual chunk object.
487 46 Luci Stanescu
488 46 Luci Stanescu
 '''sent_chunk_data'''('''data''', '''transport''', '''transaction_id''')::
489 46 Luci Stanescu
  This method is called when data is sent as part of a chunk previously announced via '''sent_new_chunk'''.
490 46 Luci Stanescu
  [[BR]]''data'':[[BR]]
491 46 Luci Stanescu
  The data sent as part of the chunk.
492 47 Luci Stanescu
  [[BR]]''transport'':[[BR]]
493 46 Luci Stanescu
  The {{{MSRPTransport}}} instance on which the chunk was sent.
494 46 Luci Stanescu
  [[BR]]''transaction_id'':[[BR]]
495 46 Luci Stanescu
  The transaction ID which identifies the chunk for which data was sent.
496 46 Luci Stanescu
497 46 Luci Stanescu
 '''sent_chunk_end'''('''data''', '''transport''', '''transaction_id''')::
498 46 Luci Stanescu
  This method is called when the last data of a chunk is sent. The chunk was previously announced via '''sent_new_chunk'''.
499 46 Luci Stanescu
  [[BR]]''data'':[[BR]]
500 46 Luci Stanescu
  The last data sent as part of the chunk.
501 46 Luci Stanescu
  [[BR]]''transport'':[[BR]]
502 46 Luci Stanescu
  The {{{MSRPTransport}}} instance on which the chunk was sent.
503 46 Luci Stanescu
  [[BR]]''transaction_id'':[[BR]]
504 46 Luci Stanescu
  The transaction ID which identifies the chunk which was ended.
505 46 Luci Stanescu
506 46 Luci Stanescu
 '''debug'''('''message''')::
507 46 Luci Stanescu
  This method is called when a debug level message is sent by the library.
508 46 Luci Stanescu
509 46 Luci Stanescu
 '''info'''('''message''')::
510 46 Luci Stanescu
  This method is called when a info level message is sent by the library.
511 46 Luci Stanescu
512 46 Luci Stanescu
 '''warn'''('''message''')::
513 46 Luci Stanescu
  This method is called when a warning level message is sent by the library.
514 46 Luci Stanescu
515 38 Adrian Georgescu
 '''error'''('''message''')::
516 39 Luci Stanescu
  This method is called when a error level message is sent by the library.
517 38 Adrian Georgescu
518 38 Adrian Georgescu
 '''fatal'''('''message''')::
519 1 Adrian Georgescu
  This method is called when a fatal level message is sent by the library.
520 1 Adrian Georgescu
521 52 Luci Stanescu
== Examples ==
522 1 Adrian Georgescu
523 52 Luci Stanescu
=== Creating an outbound connection ===
524 1 Adrian Georgescu
525 52 Luci Stanescu
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:
526 1 Adrian Georgescu
527 52 Luci Stanescu
{{{
528 52 Luci Stanescu
from msrplib.connect import ConnectorDirect
529 52 Luci Stanescu
from msrplib.session import MSRPSession
530 1 Adrian Georgescu
531 52 Luci Stanescu
connector = ConnectorDirect()
532 52 Luci Stanescu
full_local_path = connector.prepare()
533 52 Luci Stanescu
try:
534 52 Luci Stanescu
    # put full_local_path in SDP 'a:path' attribute of offer
535 52 Luci Stanescu
    # get full_remote_path from remote's 'a:path: attribute of reply
536 52 Luci Stanescu
    msrp_transport = connector.complete(full_remote_path)
537 52 Luci Stanescu
except:
538 52 Luci Stanescu
    connector.cleanup()
539 52 Luci Stanescu
    raise
540 1 Adrian Georgescu
541 52 Luci Stanescu
def handle_incoming(chunk=None, error=None):
542 52 Luci Stanescu
    if error is not None:
543 52 Luci Stanescu
       print 'Error: %s' % error
544 52 Luci Stanescu
       session.shutdown()
545 52 Luci Stanescu
    elif chunk is not None:
546 52 Luci Stanescu
       print 'Got data: %s' % chunk.data
547 1 Adrian Georgescu
548 52 Luci Stanescu
session = MSRPSession(msrp_transport, on_incoming_cb=handle_incoming)
549 52 Luci Stanescu
session.send_chunk(msrp_transport.make_chunk(data='Hello world!'))
550 52 Luci Stanescu
}}}
551 38 Adrian Georgescu
552 52 Luci Stanescu
=== Waiting for an inbound connection ===
553 52 Luci Stanescu
554 52 Luci Stanescu
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:
555 52 Luci Stanescu
556 38 Adrian Georgescu
{{{
557 52 Luci Stanescu
from msrplib.connect import AcceptorRelay, MSRPRelaySettings
558 52 Luci Stanescu
from msrplib.session import MSRPSession
559 52 Luci Stanescu
560 52 Luci Stanescu
relay = MSRPRelaySettings(domain='example.org', username='user', password='pass')
561 52 Luci Stanescu
connector = AcceptorRelay(relay)
562 1 Adrian Georgescu
full_local_path = connector.prepare()
563 1 Adrian Georgescu
try:
564 52 Luci Stanescu
    # get full_remote_path from remote's 'a:path: attribute of offer
565 52 Luci Stanescu
    # put full_local_path in SDP 'a:path' attribute of reply
566 52 Luci Stanescu
    msrp_transport = connector.complete(full_remote_path)
567 52 Luci Stanescu
except:
568 1 Adrian Georgescu
    connector.cleanup()
569 52 Luci Stanescu
    raise
570 1 Adrian Georgescu
571 52 Luci Stanescu
def handle_incoming(chunk=None, error=None):
572 52 Luci Stanescu
    if error is not None:
573 52 Luci Stanescu
       print 'Error: %s' % error
574 52 Luci Stanescu
       session.shutdown()
575 52 Luci Stanescu
    elif chunk is not None:
576 52 Luci Stanescu
       print 'Got data: %s' % chunk.data
577 1 Adrian Georgescu
578 52 Luci Stanescu
session = MSRPSession(msrp_transport, on_incoming_cb=handle_incoming)
579 52 Luci Stanescu
session.send_chunk(msrp_transport.make_chunk(data='Hello world!'))
580 52 Luci Stanescu
}}}