SipMSRPApi

Version 55 (Adrian Georgescu, 04/16/2010 09:10 am)

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 54 Adrian Georgescu
 * MSRP relay extension for NAT traversal is defined in [http://tools.ietf.org/html/rfc4976 RFC 4976]
9 1 Adrian Georgescu
10 55 Adrian Georgescu
The MSRP protocol stack is implemented by [http://download.ag-projects.com/SipClient] 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 53 Luci Stanescu
== Headers ==
179 53 Luci Stanescu
180 53 Luci Stanescu
The MSRP headers are represented using objects from the {{{msrplib.protocol module}}}. All MSRP header object provide three properties:
181 53 Luci Stanescu
 ''name'':[[BR]]
182 53 Luci Stanescu
 The name of the header, as it appears in MSRP chunks.
183 53 Luci Stanescu
 [[BR]]''encode'':[[BR]]
184 53 Luci Stanescu
 The MSRP encoded header value, as it appears in MSRP chunks.
185 53 Luci Stanescu
 [[BR]]''decode'':[[BR]]
186 53 Luci Stanescu
 The high-level object representing the header value.
187 53 Luci Stanescu
188 53 Luci Stanescu
All headers can be constructed by passing either the encoded or decoded objects to {{{__init__}}}. The following headers are provided:
189 53 Luci Stanescu
190 53 Luci Stanescu
=== ToPathHeader ===
191 53 Luci Stanescu
192 53 Luci Stanescu
The name of the header is {{{'To-Path'}}} and the decoded value is a deque of {{{URI}}} objects.
193 53 Luci Stanescu
194 53 Luci Stanescu
=== FromPathHeader ===
195 53 Luci Stanescu
196 53 Luci Stanescu
The name of the header is {{{'From-Path'}}} and the decoded value is a deque of {{{URI}}} objects.
197 53 Luci Stanescu
198 53 Luci Stanescu
=== MessageIDHeader ===
199 53 Luci Stanescu
200 53 Luci Stanescu
The name of the header is {{{'Message-ID'}}} and the decoded value is the string containing the message ID.
201 53 Luci Stanescu
202 53 Luci Stanescu
=== SuccessReportHeader ===
203 53 Luci Stanescu
204 53 Luci Stanescu
The name of the header is {{{'Success-Report'}}} and the decoded value is one of {{{'yes'}}} or {{{'no'}}}.
205 53 Luci Stanescu
206 53 Luci Stanescu
=== FailureReportHeader ===
207 53 Luci Stanescu
208 53 Luci Stanescu
The name of the header is {{{'Failure-Report'}}} and the decoded value is one of {{{'yes'}}}, {{{'partial'}}} or {{{'no'}}}.
209 53 Luci Stanescu
210 53 Luci Stanescu
=== ByteRangeHeader ===
211 53 Luci Stanescu
212 53 Luci Stanescu
The name of the header is {{{'Byte-Range'}}} and the decoded value is a 3-tuple containing the start, end and length values.
213 53 Luci Stanescu
214 53 Luci Stanescu
==== attributes ====
215 53 Luci Stanescu
216 53 Luci Stanescu
 '''fro'''::
217 53 Luci Stanescu
  The start value of the header: the index within the whole message payload where a chunk's payload starts.
218 53 Luci Stanescu
 '''end'''::
219 53 Luci Stanescu
  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.
220 53 Luci Stanescu
 '''length'''::
221 53 Luci Stanescu
  The total size of the message payload.
222 53 Luci Stanescu
223 53 Luci Stanescu
=== StatusHeader ===
224 53 Luci Stanescu
225 53 Luci Stanescu
The name of the header is {{{'Status'}}} and the decoded value is a 2-tuple containing the status code and comment.
226 53 Luci Stanescu
227 53 Luci Stanescu
==== attributes ====
228 53 Luci Stanescu
229 53 Luci Stanescu
 '''code'''::
230 53 Luci Stanescu
  The code component of the header.
231 53 Luci Stanescu
 '''comment'''::
232 53 Luci Stanescu
  The comment component of the header.
233 53 Luci Stanescu
234 53 Luci Stanescu
=== ExpiresHeader ===
235 53 Luci Stanescu
236 53 Luci Stanescu
The name of the header is {{{'Expires'}}} and the decoded value is an integer.
237 53 Luci Stanescu
238 53 Luci Stanescu
=== MinExpiresHeader ===
239 53 Luci Stanescu
240 53 Luci Stanescu
The name of the header is {{{'Min-Expires'}}} and the decoded value is an integer.
241 53 Luci Stanescu
242 53 Luci Stanescu
=== MaxExpiresHeader ===
243 53 Luci Stanescu
244 53 Luci Stanescu
The name of the header is {{{'Max-Expires'}}} and the decoded value is an integer.
245 53 Luci Stanescu
246 53 Luci Stanescu
=== UsePathHeader ===
247 53 Luci Stanescu
248 53 Luci Stanescu
The name of the header is {{{'Use-Path'}}} and the decoded value is a deque of {{{URI}}} objects.
249 53 Luci Stanescu
250 53 Luci Stanescu
=== WWWAuthenticateHeader ===
251 53 Luci Stanescu
252 53 Luci Stanescu
The name of the header is {{{'WWW-Authenticate'}}} and the decoded value is a dictionary of the parameters within the header.
253 53 Luci Stanescu
254 53 Luci Stanescu
=== AuthorizationHeader ===
255 53 Luci Stanescu
256 53 Luci Stanescu
The name of the header is {{{'Authorization'}}} and the decoded value is a dictionary of the parameters within the header.
257 53 Luci Stanescu
258 53 Luci Stanescu
=== AuthenticationInfoHeader ===
259 53 Luci Stanescu
260 53 Luci Stanescu
The name of the header is {{{'Authentication-Info'}}} and the decoded value is a dictionary of the parameters within the header.
261 53 Luci Stanescu
262 53 Luci Stanescu
=== ContentTypeHeader ===
263 53 Luci Stanescu
264 53 Luci Stanescu
The name of the header is {{{'Content-Type'}}} and the decoded value is the string representing the MIME type.
265 53 Luci Stanescu
266 53 Luci Stanescu
=== ContentIDHeader ===
267 53 Luci Stanescu
268 53 Luci Stanescu
The name of the header is {{{'Content-ID'}}} and the decoded value is the string with the value of the header.
269 53 Luci Stanescu
270 53 Luci Stanescu
=== ContentDescriptionHeader ===
271 53 Luci Stanescu
272 53 Luci Stanescu
The name of the header is {{{'Content-Description'}}} and the decoded value is the string with the value of the header.
273 53 Luci Stanescu
274 53 Luci Stanescu
=== ContentDispositionHeader ===
275 53 Luci Stanescu
276 53 Luci Stanescu
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.
277 53 Luci Stanescu
278 51 Luci Stanescu
== MSRPData ==
279 51 Luci Stanescu
280 51 Luci Stanescu
This class is implemented in the {{{msrplib.protocol}}} module and represents an MSRP chunk, either a request or a response.
281 51 Luci Stanescu
282 51 Luci Stanescu
==== attributes ====
283 51 Luci Stanescu
284 51 Luci Stanescu
 The following attributes are read-only.
285 51 Luci Stanescu
286 51 Luci Stanescu
 '''content_type'''::
287 51 Luci Stanescu
  The MIME type of the payload carried by this chunk, which is stored in the Content-Type header.
288 51 Luci Stanescu
289 51 Luci Stanescu
 '''message_id'''::
290 51 Luci Stanescu
  The ID of the message this chunk is part of, which is stored in the Message-ID header.
291 51 Luci Stanescu
292 51 Luci Stanescu
 '''byte_range'''::
293 51 Luci Stanescu
  A 3-tuple containing the start, end and length values (in this order) from the Byte-Range header.
294 51 Luci Stanescu
295 51 Luci Stanescu
 '''status'''::
296 51 Luci Stanescu
  The value of the Status header.
297 51 Luci Stanescu
298 51 Luci Stanescu
 '''failure_report'''::
299 51 Luci Stanescu
  The value of the Failure-Report header, whether it exists or it is implied; one of {{{'yes'}}}, {{{'no'}}}, {{{'partial'}}}.
300 51 Luci Stanescu
301 51 Luci Stanescu
 '''success_report'''::
302 51 Luci Stanescu
  The value of the Success-Report header, whether it exists or it is implied; one of {{{'yes'}}} or {{{'no'}}}.
303 51 Luci Stanescu
304 51 Luci Stanescu
 '''size'''::
305 51 Luci Stanescu
  The size of the payload of this chunk, in bytes.
306 51 Luci Stanescu
307 51 Luci Stanescu
==== methods ====
308 51 Luci Stanescu
309 51 Luci Stanescu
 '''!__init!__'''(''self'', '''transaction_id''', '''method'''={{{None}}}, '''code'''={{{None}}}, '''comment'''={{{None}}}, '''headers'''={{{None}}}, '''data'''={{{''}}}, '''contflag'''={{{'$'}}})::
310 51 Luci Stanescu
  Initializes a new MSRPData instance. All the arguments are also available as attributes.
311 51 Luci Stanescu
  [[BR]]''transaction_id'':[[BR]]
312 51 Luci Stanescu
  The transaction identified of this chunk.
313 51 Luci Stanescu
  [[BR]]''method'':[[BR]]
314 51 Luci Stanescu
  The method of this chunk if it a request and {{{None}}} if it is a response.
315 51 Luci Stanescu
  [[BR]]''code'':[[BR]]
316 51 Luci Stanescu
  The status code of this chunk if it is a response and {{{None}}} if it is a request.
317 51 Luci Stanescu
  [[BR]]''comment'':[[BR]]
318 51 Luci Stanescu
  The comment of this chunk if it is a response and {{{None}}} if it is a request.
319 51 Luci Stanescu
  [[BR]]''headers'':[[BR]]
320 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.
321 51 Luci Stanescu
  [[BR]]''data'':[[BR]]
322 51 Luci Stanescu
  The payload of this chunk, or an empty string if no payload is to be added.
323 51 Luci Stanescu
  [[BR]]''contflag'':[[BR]]
324 51 Luci Stanescu
  The MSRP continuation flag of this chunk, one of {{{'$'}}}, {{{'#'}}} or {{{'+'}}}.
325 51 Luci Stanescu
326 51 Luci Stanescu
 '''copy'''(''self'')::
327 51 Luci Stanescu
  Returns a new MSRPData instance with exactly the same attributes as this object.
328 51 Luci Stanescu
329 51 Luci Stanescu
 '''add_header'''(''self'', '''header''')::
330 51 Luci Stanescu
  Add a MSRP header to this chunk.
331 51 Luci Stanescu
  [[BR]]''header'':[[BR]]
332 51 Luci Stanescu
  The header object which is to be added to this chunk.
333 51 Luci Stanescu
334 51 Luci Stanescu
 '''verify_headers'''(''self'')::
335 51 Luci Stanescu
  Verifies that the chunk contains a To-Path and a From-Path header and that all the headers are valid.
336 51 Luci Stanescu
337 51 Luci Stanescu
 '''encode_start'''(''self'')::
338 51 Luci Stanescu
  Returns a string containing the MSRP header of this chunk.
339 51 Luci Stanescu
340 51 Luci Stanescu
 '''encode_end'''(''self'', '''continuation''')::
341 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.
342 51 Luci Stanescu
  [[BR]]''continuation'':[[BR]]
343 51 Luci Stanescu
  The continuation flag which is to be used in the end line.
344 51 Luci Stanescu
345 51 Luci Stanescu
 '''encode'''(''self''):
346 51 Luci Stanescu
  Returns a string containing the whole of this MSRP chunk.
347 51 Luci Stanescu
348 51 Luci Stanescu
349 14 Oliver Bril
== MSRPTransport ==
350 1 Adrian Georgescu
351 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.
352 1 Adrian Georgescu
353 1 Adrian Georgescu
==== methods ====
354 1 Adrian Georgescu
355 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}}})::
356 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.
357 51 Luci Stanescu
 [[BR]]''transaction_id'':[[BR]]
358 51 Luci Stanescu
 The transaction id which will be put in the chunk. If it is not provided, one will be randomly generated.
359 51 Luci Stanescu
 [[BR]]''method'':[[BR]]
360 51 Luci Stanescu
 The method of the new MSRP request, or {{{None}}} if a response is required.
361 51 Luci Stanescu
 [[BR]]''code'':[[BR]]
362 51 Luci Stanescu
 The code of the new MSRP response, or {{{None}}} if a request is required.
363 51 Luci Stanescu
 [[BR]]''code'':[[BR]]
364 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.
365 51 Luci Stanescu
 [[BR]]''data'':[[BR]]
366 51 Luci Stanescu
 The payload of the new chunk, or an empty string if no payload is required.
367 1 Adrian Georgescu
 [[BR]]''contflag'':[[BR]]
368 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.
369 51 Luci Stanescu
 [[BR]]''start'':[[BR]]
370 51 Luci Stanescu
 The first byte's index within the whole message payload this chunk will carry as its own payload.
371 51 Luci Stanescu
 [[BR]]''end'':[[BR]]
372 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}}}.
373 51 Luci Stanescu
 [[BR]]''length'':[[BR]]
374 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.
375 51 Luci Stanescu
 [[BR]]''message_id'':[[BR]]
376 51 Luci Stanescu
 The ID of the message this chunk is part of. If it is not provided, one will be randomly generated.
377 1 Adrian Georgescu
378 51 Luci Stanescu
 '''write_chunk'''(''self'', '''chunk''', '''wait'''={{{True}}})::
379 51 Luci Stanescu
 Writes the chunk provided to the underlying socket.
380 51 Luci Stanescu
 [[BR]]''chunk'':[[BR]]
381 51 Luci Stanescu
 The chunk which is to be written, an instance of {{{MSRPData}}}.
382 51 Luci Stanescu
 [[BR]]''wait'':[[BR]]
383 51 Luci Stanescu
 If {{{True}}}, waits for the operation to complete.
384 1 Adrian Georgescu
385 51 Luci Stanescu
 '''write_response'''(''self'', '''chunk''', '''code''', '''comment''', '''wait'''={{{True}}}):
386 51 Luci Stanescu
 Creates a response which is suitable as a reply to the specified chunk and writes it to the underlying socket.
387 51 Luci Stanescu
 [[BR]]''chunk'':[[BR]]
388 51 Luci Stanescu
 The chunk for which to create a response.
389 51 Luci Stanescu
 [[BR]]''code'':[[BR]]
390 51 Luci Stanescu
 The status code of the response which is to be created.
391 51 Luci Stanescu
 [[BR]]''comment'':[[BR]]
392 51 Luci Stanescu
 The comment of the response which is to be created.
393 51 Luci Stanescu
 [[BR]]''wait'':[[BR]]
394 51 Luci Stanescu
 If {{{True}}}, waits for the operation to complete.
395 51 Luci Stanescu
396 27 Adrian Georgescu
 '''read_chunk'''(''self'', '''size'''={{{None}}})::
397 1 Adrian Georgescu
 Waits for a new chunk and returns it.
398 15 Oliver Bril
 If there was an error, closes the connection and raises {{{ChunkParseError}}}.
399 27 Adrian Georgescu
400 15 Oliver Bril
 In case of unintelligible input, loses the connection and returns {{{None}}}.
401 39 Luci Stanescu
 When the connection is closed, raises the reason of the closure (e.g. {{{ConnectionDone}}}).
402 15 Oliver Bril
403 1 Adrian Georgescu
 If the data already read exceeds ''size'', stops reading the data and returns
404 15 Oliver Bril
 a "virtual" chunk, i.e. the one that does not actually correspond the the real
405 1 Adrian Georgescu
 MSRP chunk. Such chunks have Byte-Range header changed to match the number of
406 48 Luci Stanescu
 bytes read and continuation that is {{{'+'}}}; they also possess {{{segment}}} attribute,
407 15 Oliver Bril
 an integer, starting with 1 and increasing with every new segment of the chunk.
408 1 Adrian Georgescu
409 1 Adrian Georgescu
 Note, that ''size'' only hints when to interrupt the segment but does not affect
410 1 Adrian Georgescu
 how the data is read from socket. You may have segments bigger than ''size'' and it's
411 44 Luci Stanescu
 legal to set ''size'' to zero (which would mean return a chunk as long as you get
412 39 Luci Stanescu
 some data, regardless how small).
413 51 Luci Stanescu
 
414 51 Luci Stanescu
 [[BR]]''size'':[[BR]]
415 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.
416 41 Luci Stanescu
417 1 Adrian Georgescu
 '''check_incoming_SEND_chunk'''(''self'', '''chunk''')::
418 1 Adrian Georgescu
 Checks the 'To-Path' and 'From-Path' of the incoming SEND chunk.
419 1 Adrian Georgescu
 Returns None is the paths are valid for this connection.
420 1 Adrian Georgescu
 If an error is detected an MSRPError is created and returned.
421 1 Adrian Georgescu
422 51 Luci Stanescu
== OutgoingFile ==
423 51 Luci Stanescu
424 51 Luci Stanescu
This class is implemented in the {{{msrplib.session}}} module and represents a file which is to be sent via MSRP.
425 51 Luci Stanescu
426 51 Luci Stanescu
==== attributes ====
427 51 Luci Stanescu
428 51 Luci Stanescu
 '''headers'''::
429 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.
430 51 Luci Stanescu
431 51 Luci Stanescu
==== methods ====
432 51 Luci Stanescu
433 51 Luci Stanescu
 '''!__init!__'''(''self'', '''fileobj''', '''size''', '''content_type'''={{{None}}}, '''position'''={{{0}}}, '''message_id'''={{{None}}})::
434 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.
435 51 Luci Stanescu
  [[BR]]''fileobj'':[[BR]]
436 51 Luci Stanescu
  A file-like object which will be used for reading the data to be sent.
437 51 Luci Stanescu
  [[BR]]''size'':[[BR]]
438 51 Luci Stanescu
  The size of the whole file.
439 51 Luci Stanescu
  [[BR]]''content_type'':[[BR]]
440 51 Luci Stanescu
  The MIME type associated with the file's data. If provided, it will be added as a Content-Type header.
441 51 Luci Stanescu
  [[BR]]''position'':[[BR]]
442 51 Luci Stanescu
  The position within the file from which data will be sent. The file object must already be seeked to this position.
443 51 Luci Stanescu
  [[BR]]''message_id'':[[BR]]
444 51 Luci Stanescu
  The message ID which will be used for sending this file.
445 51 Luci Stanescu
446 1 Adrian Georgescu
== MSRPSession ==
447 1 Adrian Georgescu
448 1 Adrian Georgescu
This class is implemented in the {{{msrplib.session}}} module and provides a high level API for MSRP sessions.
449 1 Adrian Georgescu
450 1 Adrian Georgescu
==== methods ====
451 1 Adrian Georgescu
452 1 Adrian Georgescu
 '''!__init!__'''(''self'', '''msrptransport''', '''accept_types'''={{{['*']}}}, '''on_incoming_cb'''={{{None}}})::
453 51 Luci Stanescu
 Initializes MSRPSession instance over the specified transport. The incoming chunks are reported through the ''on_incoming_cb'' callback.
454 51 Luci Stanescu
 [[BR]]''msrptransport'':[[BR]]
455 51 Luci Stanescu
 An instance of {{{MSRPTransport}}} over which this session will operate.
456 51 Luci Stanescu
 [[BR]]''accept_types'':[[BR]]
457 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.
458 51 Luci Stanescu
 [[BR]]''on_incoming_cb'':[[BR]]
459 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.
460 1 Adrian Georgescu
461 1 Adrian Georgescu
 '''send_chunk'''(''self'', '''chunk''', '''response_cb'''={{{None}}})::
462 51 Luci Stanescu
 Sends the specified chunk and reports the result via the ''response_cb'' callback.
463 1 Adrian Georgescu
464 1 Adrian Georgescu
 When ''response_cb'' argument is present, it will be used to report
465 1 Adrian Georgescu
 the transaction response to the caller. When a response is received or generated
466 1 Adrian Georgescu
 locally, ''response_cb'' is called with one argument. The function must do something
467 38 Adrian Georgescu
 quickly and must not block, because otherwise it would block the reader greenlet.
468 39 Luci Stanescu
469 1 Adrian Georgescu
 If no response was received after {{{RESPONSE_TIMEOUT}}} seconds,
470 1 Adrian Georgescu
 * 408 response is generated if Failure-Report was {{{'yes'}}} or absent
471 1 Adrian Georgescu
 * 200 response is generated if Failure-Report was {{{'partial'}}} or {{{'no'}}}
472 1 Adrian Georgescu
473 1 Adrian Georgescu
 Note that it's rather wasteful to provide ''response_cb'' argument other than {{{None}}}
474 1 Adrian Georgescu
 for chunks with Failure-Report='no' since it will always fire 30 seconds later
475 1 Adrian Georgescu
 with 200 result (unless the other party is broken and ignores Failure-Report header)
476 1 Adrian Georgescu
477 51 Luci Stanescu
 If sending is not possible, {{{MSRPSessionError}}} is raised.
478 1 Adrian Georgescu
479 51 Luci Stanescu
 [[BR]]''chunk'':[[BR]]
480 51 Luci Stanescu
 The chunk which is to be sent. It must be an instance of {{{MSRPData}}} which represents a request.
481 51 Luci Stanescu
 [[BR]]''response_cb'':[[BR]]
482 51 Luci Stanescu
 A function receiving a single argument which will be the response received for the sent chunk.
483 51 Luci Stanescu
484 1 Adrian Georgescu
 '''deliver_chunk'''(''self'', '''chunk''', '''event'''={{{None}}})::
485 51 Luci Stanescu
 Sends the specified chunk and waits for the transaction response (if Failure-Report header is not {{{'no'}}}).
486 51 Luci Stanescu
 Returns the transaction response if it's a success or raise {{{MSRPTransactionError}}} if it's not.
487 1 Adrian Georgescu
488 1 Adrian Georgescu
 If chunk's Failure-Report is {{{'no'}}}, returns {{{None}}} immediately.
489 1 Adrian Georgescu
490 51 Luci Stanescu
 [[BR]]''chunk'':[[BR]]
491 51 Luci Stanescu
 The chunk which is to be sent. It must be an intance of {{{MSRPData}}} which represents a request.
492 51 Luci Stanescu
 [[BR]]''event'':[[BR]]
493 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.
494 51 Luci Stanescu
 
495 51 Luci Stanescu
 '''send_file'''(''self'', '''outgoing_file''')::
496 51 Luci Stanescu
 Adds the specified file to the queue of files to be sent. The method returns immediately.
497 51 Luci Stanescu
 [[BR]]''outgoing_file'':[[BR]]
498 51 Luci Stanescu
 An instance of {{{OutgoingFile}}} which represents the file to be sent.
499 51 Luci Stanescu
500 44 Luci Stanescu
 '''shutdown'''(''self'', '''sync'''={{{True}}})::
501 1 Adrian Georgescu
 Sends the messages already in queue then closes the connection.
502 44 Luci Stanescu
503 44 Luci Stanescu
== MSRPServer ==
504 44 Luci Stanescu
505 1 Adrian Georgescu
This class is implemented in the {{{msrplib.connect}}} module.
506 44 Luci Stanescu
    
507 39 Luci Stanescu
MSRPServer solves the problem with AcceptorDirect: concurrent using of 2
508 39 Luci Stanescu
or more AcceptorDirect instances on the same non-zero port is not possible.
509 49 Adrian Georgescu
If you initialize() those instances, one after another, one will listen on
510 1 Adrian Georgescu
the socket and another will get BindError.
511 1 Adrian Georgescu
512 1 Adrian Georgescu
MSRPServer avoids the problem by sharing the listening socket between multiple connections.
513 39 Luci Stanescu
It has a slightly different interface from AcceptorDirect, so it cannot be considered a drop-in
514 46 Luci Stanescu
replacement.
515 46 Luci Stanescu
516 1 Adrian Georgescu
It manages the listening sockets and binds incoming requests.
517 1 Adrian Georgescu
518 1 Adrian Georgescu
==== methods ====
519 1 Adrian Georgescu
520 1 Adrian Georgescu
 '''!__init!__'''(''self'', '''logger''')::
521 51 Luci Stanescu
 Constructs a new MSRPServer which will be using the specifed logger for its connections.
522 51 Luci Stanescu
 [[BR]]''logger'':[[BR]]
523 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.
524 1 Adrian Georgescu
525 1 Adrian Georgescu
 '''prepare'''(''self'', ''local_uri''={{{None}}}, ''logger''={{{None}}})::
526 1 Adrian Georgescu
 Starts a listening port specified by ''local_uri'' if there isn't one on that port/interface already.
527 1 Adrian Georgescu
 Adds ''local_uri'' to the list of expected URIs, so that incoming connections featuring this URI won't be rejected.
528 51 Luci Stanescu
 If ''logger'' is provided, it uses it for this connection instead of the one specified in {{{__init___}}}.
529 51 Luci Stanescu
 [[BR]]''local_uri'':[[BR]]
530 51 Luci Stanescu
 The URI which will be added to the list of expected URIs. Connections from this URI will be accepted.
531 51 Luci Stanescu
 [[BR]]''logger'':[[BR]]
532 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.
533 15 Oliver Bril
534 1 Adrian Georgescu
 '''complete'''(''self'', ''full_remote_path'')::
535 51 Luci Stanescu
 Waits until one of the incoming connections binds using the provided ''full_remote_path''.
536 51 Luci Stanescu
 Returns the connected and bound {{{MSRPTransport}}} instance.
537 51 Luci Stanescu
 If no such binding was made within {{{MSRPBindSessionTimeout.seconds}}}, {{{MSRPBindSessionTimeout}}} is raised.
538 51 Luci Stanescu
 [[BR]]''full_remote_path'':[[BR]]
539 51 Luci Stanescu
 A list of {{{protocol.URI}}} instances, obtained by parsing {{{'a:path'}}} put in SDP by the remote party.
540 38 Adrian Georgescu
541 38 Adrian Georgescu
 '''cleanup'''(''self'', ''local_uri'')::
542 46 Luci Stanescu
 Removes ''local_uri'' from the list of expected URIs.
543 51 Luci Stanescu
 [[BR]]''local_uri'':[[BR]]
544 51 Luci Stanescu
 The URI which is to be removed from the list of expected URIs.
545 49 Adrian Georgescu
546 46 Luci Stanescu
== Logging ==
547 46 Luci Stanescu
548 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:
549 46 Luci Stanescu
550 46 Luci Stanescu
==== methods ====
551 46 Luci Stanescu
552 46 Luci Stanescu
 '''received_new_chunk'''('''data''', '''transport''', '''chunk''')::
553 46 Luci Stanescu
  This method is called when the start of a new chunk is received.
554 46 Luci Stanescu
  [[BR]]''data'':[[BR]]
555 46 Luci Stanescu
  The data which came along with the start of the chunk.
556 46 Luci Stanescu
  [[BR]]''transport'':[[BR]]
557 46 Luci Stanescu
  The {{{MSRPTransport}}} instance on which the chunk was received.
558 46 Luci Stanescu
  [[BR]]''chunk'':[[BR]]
559 46 Luci Stanescu
  The actual chunk object.
560 46 Luci Stanescu
561 46 Luci Stanescu
 '''received_chunk_data'''('''data''', '''transport''', '''transaction_id''')::
562 46 Luci Stanescu
  This method is called when data is received as part of a chunk previously announced via '''received_new_chunk'''.
563 46 Luci Stanescu
  [[BR]]''data'':[[BR]]
564 46 Luci Stanescu
  The data received as part of the chunk.
565 47 Luci Stanescu
  [[BR]]''transport'':[[BR]]
566 46 Luci Stanescu
  The {{{MSRPTransport}}} instance on which the chunk was received.
567 46 Luci Stanescu
  [[BR]]''transaction_id'':[[BR]]
568 46 Luci Stanescu
  The transaction ID which identifies the chunk for which data was received.
569 46 Luci Stanescu
570 46 Luci Stanescu
 '''received_chunk_end'''('''data''', '''transport''', '''transaction_id''')::
571 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'''.
572 46 Luci Stanescu
  [[BR]]''data'':[[BR]]
573 46 Luci Stanescu
  The last data received as part of the chunk.
574 46 Luci Stanescu
  [[BR]]''transport'':[[BR]]
575 46 Luci Stanescu
  The {{{MSRPTransport}}} instance on which the chunk was received.
576 46 Luci Stanescu
  [[BR]]''transaction_id'':[[BR]]
577 46 Luci Stanescu
  The transaction ID which identifies the chunk which was ended.
578 46 Luci Stanescu
579 46 Luci Stanescu
 '''sent_new_chunk'''('''data''', '''transport''', '''chunk''')::
580 46 Luci Stanescu
  This method is called when the start of a new chunk is sent.
581 46 Luci Stanescu
  [[BR]]''data'':[[BR]]
582 46 Luci Stanescu
  The data which was sent along with the start of the chunk.
583 46 Luci Stanescu
  [[BR]]''transport'':[[BR]]
584 46 Luci Stanescu
  The {{{MSRPTransport}}} instance on which the chunk was sent.
585 46 Luci Stanescu
  [[BR]]''chunk'':[[BR]]
586 46 Luci Stanescu
  The actual chunk object.
587 46 Luci Stanescu
588 46 Luci Stanescu
 '''sent_chunk_data'''('''data''', '''transport''', '''transaction_id''')::
589 46 Luci Stanescu
  This method is called when data is sent as part of a chunk previously announced via '''sent_new_chunk'''.
590 46 Luci Stanescu
  [[BR]]''data'':[[BR]]
591 46 Luci Stanescu
  The data sent as part of the chunk.
592 47 Luci Stanescu
  [[BR]]''transport'':[[BR]]
593 46 Luci Stanescu
  The {{{MSRPTransport}}} instance on which the chunk was sent.
594 46 Luci Stanescu
  [[BR]]''transaction_id'':[[BR]]
595 46 Luci Stanescu
  The transaction ID which identifies the chunk for which data was sent.
596 46 Luci Stanescu
597 46 Luci Stanescu
 '''sent_chunk_end'''('''data''', '''transport''', '''transaction_id''')::
598 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'''.
599 46 Luci Stanescu
  [[BR]]''data'':[[BR]]
600 46 Luci Stanescu
  The last data sent as part of the chunk.
601 46 Luci Stanescu
  [[BR]]''transport'':[[BR]]
602 46 Luci Stanescu
  The {{{MSRPTransport}}} instance on which the chunk was sent.
603 46 Luci Stanescu
  [[BR]]''transaction_id'':[[BR]]
604 46 Luci Stanescu
  The transaction ID which identifies the chunk which was ended.
605 46 Luci Stanescu
606 46 Luci Stanescu
 '''debug'''('''message''')::
607 46 Luci Stanescu
  This method is called when a debug level message is sent by the library.
608 46 Luci Stanescu
609 46 Luci Stanescu
 '''info'''('''message''')::
610 46 Luci Stanescu
  This method is called when a info level message is sent by the library.
611 46 Luci Stanescu
612 46 Luci Stanescu
 '''warn'''('''message''')::
613 46 Luci Stanescu
  This method is called when a warning level message is sent by the library.
614 46 Luci Stanescu
615 38 Adrian Georgescu
 '''error'''('''message''')::
616 39 Luci Stanescu
  This method is called when a error level message is sent by the library.
617 38 Adrian Georgescu
618 38 Adrian Georgescu
 '''fatal'''('''message''')::
619 1 Adrian Georgescu
  This method is called when a fatal level message is sent by the library.
620 1 Adrian Georgescu
621 52 Luci Stanescu
== Examples ==
622 1 Adrian Georgescu
623 52 Luci Stanescu
=== Creating an outbound connection ===
624 1 Adrian Georgescu
625 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:
626 1 Adrian Georgescu
627 52 Luci Stanescu
{{{
628 52 Luci Stanescu
from msrplib.connect import ConnectorDirect
629 52 Luci Stanescu
from msrplib.session import MSRPSession
630 1 Adrian Georgescu
631 52 Luci Stanescu
connector = ConnectorDirect()
632 52 Luci Stanescu
full_local_path = connector.prepare()
633 52 Luci Stanescu
try:
634 52 Luci Stanescu
    # put full_local_path in SDP 'a:path' attribute of offer
635 52 Luci Stanescu
    # get full_remote_path from remote's 'a:path: attribute of reply
636 52 Luci Stanescu
    msrp_transport = connector.complete(full_remote_path)
637 52 Luci Stanescu
except:
638 52 Luci Stanescu
    connector.cleanup()
639 52 Luci Stanescu
    raise
640 1 Adrian Georgescu
641 52 Luci Stanescu
def handle_incoming(chunk=None, error=None):
642 52 Luci Stanescu
    if error is not None:
643 52 Luci Stanescu
       print 'Error: %s' % error
644 52 Luci Stanescu
       session.shutdown()
645 52 Luci Stanescu
    elif chunk is not None:
646 52 Luci Stanescu
       print 'Got data: %s' % chunk.data
647 1 Adrian Georgescu
648 52 Luci Stanescu
session = MSRPSession(msrp_transport, on_incoming_cb=handle_incoming)
649 52 Luci Stanescu
session.send_chunk(msrp_transport.make_chunk(data='Hello world!'))
650 52 Luci Stanescu
}}}
651 38 Adrian Georgescu
652 52 Luci Stanescu
=== Waiting for an inbound connection ===
653 52 Luci Stanescu
654 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:
655 52 Luci Stanescu
656 38 Adrian Georgescu
{{{
657 52 Luci Stanescu
from msrplib.connect import AcceptorRelay, MSRPRelaySettings
658 52 Luci Stanescu
from msrplib.session import MSRPSession
659 52 Luci Stanescu
660 52 Luci Stanescu
relay = MSRPRelaySettings(domain='example.org', username='user', password='pass')
661 52 Luci Stanescu
connector = AcceptorRelay(relay)
662 1 Adrian Georgescu
full_local_path = connector.prepare()
663 1 Adrian Georgescu
try:
664 52 Luci Stanescu
    # get full_remote_path from remote's 'a:path: attribute of offer
665 52 Luci Stanescu
    # put full_local_path in SDP 'a:path' attribute of reply
666 52 Luci Stanescu
    msrp_transport = connector.complete(full_remote_path)
667 52 Luci Stanescu
except:
668 1 Adrian Georgescu
    connector.cleanup()
669 52 Luci Stanescu
    raise
670 1 Adrian Georgescu
671 52 Luci Stanescu
def handle_incoming(chunk=None, error=None):
672 52 Luci Stanescu
    if error is not None:
673 52 Luci Stanescu
       print 'Error: %s' % error
674 52 Luci Stanescu
       session.shutdown()
675 52 Luci Stanescu
    elif chunk is not None:
676 52 Luci Stanescu
       print 'Got data: %s' % chunk.data
677 1 Adrian Georgescu
678 52 Luci Stanescu
session = MSRPSession(msrp_transport, on_incoming_cb=handle_incoming)
679 52 Luci Stanescu
session.send_chunk(msrp_transport.make_chunk(data='Hello world!'))
680 52 Luci Stanescu
}}}