SipMSRPApi

Version 24 (Adrian Georgescu, 03/31/2009 05:14 pm)

1 1 Adrian Georgescu
= MSRP API =
2 1 Adrian Georgescu
3 1 Adrian Georgescu
[[TOC(WikiStart, Sip*, depth=3)]]
4 1 Adrian Georgescu
5 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). 
6 1 Adrian Georgescu
7 1 Adrian Georgescu
 * MSRP sessions are defined in [http://tools.ietf.org/html/rfc4975 RFC 4975].
8 1 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 5 Oliver Bril
The MSRP protocol is implemented by [http://devel.ag-projects.com/cgi-bin/darcsweb.cgi?r=python-msrplib;a=summary msrplib] Python package. On top of it, {{{sipsimple}}} provides higher level classes integrated into middleware notification and configuration systems:
11 1 Adrian Georgescu
12 4 Oliver Bril
 * {{{sipsimple.msrp.MSRPChat}}}
13 4 Oliver Bril
 * {{{sipsimple.msrp.MSRPFileTransfer}}}
14 1 Adrian Georgescu
 * {{{sipsimple.msrp.MSRPDesktopSharing}}}
15 1 Adrian Georgescu
16 21 Adrian Georgescu
These classes are used internally by [wiki:SipMiddlewareApi#Session Session], which provides the necessary methods to access their features. The notifications posted by these classes are also handled internally by [wiki:SipMiddlewareApi#Session Session]. The notifications that are relevant to the user are then reposted by the Session instance. Refer to [wiki:SipMiddlewareApi#Session Session documentation] for details on the Session API. 
17 10 Adrian Georgescu
18 23 Adrian Georgescu
== MSRPChat API ==
19 1 Adrian Georgescu
20 20 Adrian Georgescu
{{{sipsimple.msrp.MSRPChat}}} implements instant messaging (IM) over MSRP for the [wiki:SipMiddlewareApi middleware]. This class performs the following functions:
21 1 Adrian Georgescu
22 5 Oliver Bril
 * automatically wraps outgoing messages with Message/CPIM if that's necessary according to accept-types
23 19 Adrian Georgescu
 * unwraps incoming Message/CPIM messages; for each incoming message, {{{MSRPChatGotMessage}}} is posted
24 5 Oliver Bril
 * plays notification sounds on received/sent message
25 5 Oliver Bril
26 17 Oliver Bril
=== Methods ===
27 5 Oliver Bril
28 5 Oliver Bril
 '''!__init!__'''(''self'', ''account'', ''remote_uri'', ''outgoing'')::
29 5 Oliver Bril
 Initialize MSRPChat instance.
30 5 Oliver Bril
31 5 Oliver Bril
 '''initialize'''(''self'')::
32 5 Oliver Bril
 Initialize the MSRP connection; connect to the relay if necessary. When done, fire MSRPChatDidInitialize (with 'sdpmedia' attribute, containing the appropriate 'SDPMedia' instance)
33 5 Oliver Bril
34 5 Oliver Bril
 '''start'''(''self'', ''remote_media'')::
35 5 Oliver Bril
 Complete the MSRP connection establishment; this includes binding the MSRP session. [[BR]]
36 5 Oliver Bril
 When done, fire MSRPChatDidStart. At this point each incoming message is posted as a {{{MSRPChatGotMessage}}} notification
37 5 Oliver Bril
38 5 Oliver Bril
 '''end'''(''self'')::
39 5 Oliver Bril
 Close the MSRP connection or cleanup after initialize(), whatever is necessary. [[BR]]
40 5 Oliver Bril
 Before doing anything post {{{MSRPChatWillEnd}}}.
41 7 Oliver Bril
 When done, post {{{MSRPChatDidEnd}}}. If there was an error, post {{{MSRPChatDidFail}}}. 
42 5 Oliver Bril
 {{{MSRPChatDidEnd}}} will be posted anyway.
43 5 Oliver Bril
44 6 Oliver Bril
 '''send_message'''(''self'', ''content'', ''content_type''={{{'text/plain'}}}, ''to_uri''={{{None}}}, ''dt''={{{None}}})::
45 6 Oliver Bril
 Send IM message. Prefer Message/CPIM wrapper if it is supported. If called before the connection was established, the messages will be
46 6 Oliver Bril
 queued until MSRPChatDidStart notification.
47 6 Oliver Bril
48 6 Oliver Bril
 Return generated MSRP chunk (MSRPData instance); to get Message-ID use its 'message_id' attribute.
49 6 Oliver Bril
50 6 Oliver Bril
 ''content'' str:[[BR]]
51 6 Oliver Bril
 content of the message
52 6 Oliver Bril
53 6 Oliver Bril
 ''to_uri'' SIPURI:[[BR]]
54 6 Oliver Bril
 "To" header of CPIM wrapper; use to override the default supplied to {{{__init__}}}.
55 6 Oliver Bril
 May only differ from the one supplied in __init__ if the remote party supports private messages. If it does not, {{{MSRPChatError}}} will be raised;
56 6 Oliver Bril
57 6 Oliver Bril
 ''content_type'' str:[[BR]]
58 6 Oliver Bril
 Content-Type of wrapped message if Message/CPIM is used (Content-Type of MSRP message is always Message/CPIM in that case);
59 6 Oliver Bril
 otherwise, Content-Type of MSRP message.
60 6 Oliver Bril
61 6 Oliver Bril
 These MSRP headers are used to enable end-to-end success reports and to disable hop-to-hop successful responses:
62 6 Oliver Bril
{{{
63 6 Oliver Bril
Failure-Report: partial
64 6 Oliver Bril
Success-Report: yes
65 6 Oliver Bril
}}}
66 6 Oliver Bril
67 1 Adrian Georgescu
=== Notifications ===
68 21 Adrian Georgescu
69 21 Adrian Georgescu
To communicate with the middleware, MSRPChat class uses the notification system provided by the [http://pypi.python.org/pypi/python-application python-application] package.
70 1 Adrian Georgescu
71 17 Oliver Bril
 '''MSRPChatDidInitialize'''::
72 18 Adrian Georgescu
 Sent when the {{{MSRPChat}}} instance is initialized, it includes the MSRP relay reservation when requested.
73 17 Oliver Bril
 '''MSRPChatDidStart'''::
74 17 Oliver Bril
 Sent when the {{{MSRPChat}}} instance is started.
75 17 Oliver Bril
 '''MSRPChatWillEnd'''::
76 17 Oliver Bril
 Sent when the {{{MSRPChat}}} is entering cleanup procedure initiated by calling end().
77 17 Oliver Bril
 '''MSRPChatDidEnd'''::
78 17 Oliver Bril
 Sent when the {{{MSRPChat}}} has finished the cleanup procedure initiated by end().
79 17 Oliver Bril
 '''MSRPChatDidFail'''::
80 17 Oliver Bril
 Sent whenever the {{{MSRPChat}}} instance fails.
81 17 Oliver Bril
  [[BR]]''context'':[[BR]]
82 17 Oliver Bril
  A text string identifying the context of the failure ('initialize', 'sdp_negotiation', 'start', 'reading').
83 17 Oliver Bril
  [[BR]]''reason'':[[BR]]
84 17 Oliver Bril
  A text string describing the reason of failure.
85 17 Oliver Bril
  [[BR]]''failure'':[[BR]]
86 17 Oliver Bril
  A Failure instance providing detailed traceback information.
87 17 Oliver Bril
 '''MSRPChatGotMessage'''::
88 17 Oliver Bril
 Sent whenever a new incoming message is received,
89 17 Oliver Bril
  [[BR]]''content'':[[BR]]
90 17 Oliver Bril
  The string that the remote user has typed.
91 17 Oliver Bril
  [[BR]]''content_type'':[[BR]]
92 17 Oliver Bril
  Content-Type of the user message.
93 17 Oliver Bril
  [[BR]]''cpim_headers'':[[BR]]
94 17 Oliver Bril
  A dictionary of CPIM headers. (Empty dictionary if no CPIM wrapper was used).
95 17 Oliver Bril
  [[BR]]''message'':[[BR]]
96 17 Oliver Bril
  A {{{msrplib.protocol.MSRPData}}} instance providing all the MSRP information about the chunk.
97 17 Oliver Bril
 '''MSRPChatDidDeliverMessage'''::
98 17 Oliver Bril
 Sent when a successful report is received.
99 17 Oliver Bril
  [[BR]]''message_id'':[[BR]]
100 17 Oliver Bril
  Text identifier of the message.
101 17 Oliver Bril
  [[BR]]''code'':[[BR]]
102 17 Oliver Bril
  Integer result code.
103 17 Oliver Bril
  [[BR]]''reason'':[[BR]]
104 17 Oliver Bril
  Text comment.
105 17 Oliver Bril
  [[BR]]''message'':[[BR]]
106 17 Oliver Bril
  A {{{msrplib.protocol.MSRPData}}} instance providing all the MSRP information about the report.
107 17 Oliver Bril
 '''MSRPChatDidNotDeliverMessage'''::
108 17 Oliver Bril
 Sent when a failure report of failure transaction response is received.
109 17 Oliver Bril
  [[BR]]''message_id'':[[BR]]
110 17 Oliver Bril
  Text identifier of the message.
111 17 Oliver Bril
  [[BR]]''code'':[[BR]]
112 17 Oliver Bril
  Integer result code.
113 17 Oliver Bril
  [[BR]]''reason'':[[BR]]
114 17 Oliver Bril
  Text comment.
115 17 Oliver Bril
  [[BR]]''message'':[[BR]]
116 17 Oliver Bril
  A {{{msrplib.protocol.MSRPData}}} instance providing all the MSRP information about the report.
117 5 Oliver Bril
118 4 Oliver Bril
== MSRPFileTransfer ==
119 1 Adrian Georgescu
120 22 Adrian Georgescu
=== Methods ===
121 22 Adrian Georgescu
=== Notifications ===
122 22 Adrian Georgescu
123 1 Adrian Georgescu
== MSRPDesktopSharing ==
124 22 Adrian Georgescu
125 22 Adrian Georgescu
=== Methods ===
126 22 Adrian Georgescu
=== Notifications ===
127 1 Adrian Georgescu
128 12 Adrian Georgescu
----------------------
129 12 Adrian Georgescu
130 24 Adrian Georgescu
== MSRP library ==
131 4 Oliver Bril
132 1 Adrian Georgescu
{{{msrplib}}} is based upon [http://twistedmatrix.com twisted] and [http://devel.ag-projects.com/~denis/eventlet/ eventlet] and provides a set of
133 1 Adrian Georgescu
classes for establishing and managing MSRP connection.
134 1 Adrian Georgescu
135 1 Adrian Georgescu
The library consist of the following modules:
136 1 Adrian Georgescu
137 1 Adrian Georgescu
 '''msrplib.transport'''::
138 1 Adrian Georgescu
 Defines {{{MSRPTransport}}} class, which provides low level control over MSRP connection.
139 2 Redmine Admin
140 1 Adrian Georgescu
 '''msrplib.connect'''::
141 1 Adrian Georgescu
 Defines means to establish a connection, bind it, and provide an initialized {{{MSRPTransport}}} instance.
142 1 Adrian Georgescu
143 1 Adrian Georgescu
 '''msrplib.session'''::
144 1 Adrian Georgescu
 Defines {{{MSRPSession}}} class, which provides high level control over a MSRP connection.
145 1 Adrian Georgescu
146 1 Adrian Georgescu
 '''msrplib.protocol'''::
147 1 Adrian Georgescu
 Provides representation and parsing of MSRP entities - chunks and URIs.
148 1 Adrian Georgescu
149 1 Adrian Georgescu
 '''msrplib.trafficlog'''::
150 1 Adrian Georgescu
 Defines {{{Logger}}} class that is used through out the library to log the connection state.
151 1 Adrian Georgescu
  
152 4 Oliver Bril
=== Usage ===
153 1 Adrian Georgescu
154 4 Oliver Bril
==== Establish a connection ====
155 3 Oliver Bril
156 1 Adrian Georgescu
{{{msrplib.connect}}} provides a number of classes to establish a connection, so the first
157 1 Adrian Georgescu
thing to do is to select which one applies to your situation:
158 1 Adrian Georgescu
159 1 Adrian Georgescu
    1. Calling endpoint, not using a relay ({{{ConnectorDirect}}})
160 1 Adrian Georgescu
    2. Answering endpoint, not using a relay ({{{AcceptorDirect}}})
161 1 Adrian Georgescu
    3. Calling endpoint, using a relay ({{{ConnectorRelay}}})
162 1 Adrian Georgescu
    4. Answering endpoint, using a relay ({{{AcceptorRelay}}})
163 1 Adrian Georgescu
164 1 Adrian Georgescu
The answering endpoint may skip using the relay if sure that it's accessible
165 1 Adrian Georgescu
directly. The calling endpoint is unlikely to need the relay.
166 1 Adrian Georgescu
167 1 Adrian Georgescu
Once you have an instance of the right class (use the convenience functions
168 1 Adrian Georgescu
{{{get_connector()}}} and {{{get_acceptor()}}} to get one), the procedure to establish the
169 1 Adrian Georgescu
connection is the same:
170 1 Adrian Georgescu
171 1 Adrian Georgescu
{{{
172 1 Adrian Georgescu
full_local_path = connector.prepare()
173 1 Adrian Georgescu
try:
174 1 Adrian Georgescu
    ... put full_local_path in SDP 'a:path' attribute
175 1 Adrian Georgescu
    ... get full_remote_path from remote's 'a:path: attribute
176 1 Adrian Georgescu
    ... (the order of the above steps is reversed if you're the
177 1 Adrian Georgescu
    ... answering party, but that does not affect connector's usage)
178 1 Adrian Georgescu
    msrptransport = connector.complete(full_remote_path)
179 1 Adrian Georgescu
finally:
180 1 Adrian Georgescu
    connector.cleanup()
181 1 Adrian Georgescu
}}}
182 1 Adrian Georgescu
183 1 Adrian Georgescu
To customize connection's parameters, create a new {{{protocol.URI}}} object and pass
184 1 Adrian Georgescu
it to prepare() function, e.g.
185 1 Adrian Georgescu
{{{
186 1 Adrian Georgescu
local_uri = protocol.URI(use_tls=False, port=5000)
187 1 Adrian Georgescu
connector.prepare(local_uri)
188 1 Adrian Georgescu
}}}
189 1 Adrian Georgescu
190 1 Adrian Georgescu
{{{prepare()}}} may update {{{local_uri}}} in place with the actual connection parameters
191 1 Adrian Georgescu
used (e.g. if you specified port=0). 'port' attribute of {{{local_uri}}} is currently
192 1 Adrian Georgescu
only respected by {{{AcceptorDirect}}}.
193 1 Adrian Georgescu
194 1 Adrian Georgescu
Note that, acceptors and connectors are one-use only. Which means, that {{{AcceptorDirect}}}
195 1 Adrian Georgescu
will open a port just to handle one incoming connection and close it right after.
196 1 Adrian Georgescu
If your application behaves more like a server, i.e. opens a port and listens on it
197 1 Adrian Georgescu
constantly, use {{{MSRPServer}}} class.
198 3 Oliver Bril
199 4 Oliver Bril
=== Components ===
200 1 Adrian Georgescu
201 4 Oliver Bril
==== a connector or acceptor ====
202 3 Oliver Bril
203 8 Oliver Bril
 {{{msrplib.connect}}} provides 2 connectors (with and without relay) and 2 acceptors (likewise, with or without relay). All of them have the exact same interface,
204 8 Oliver Bril
205 8 Oliver Bril
 '''prepare'''(''self'', ''local_uri''={{{None}}})::
206 8 Oliver Bril
 Depending on type of the connector, use local_uri to prepare the MSRP connection, which means:
207 8 Oliver Bril
 * connecting and authenticating at the relay if a relay is used ({{{ConnectorRelay}}} and {{{AcceptorRelay}}})
208 8 Oliver Bril
 * start listening on a local port for DirectAcceptor
209 8 Oliver Bril
210 8 Oliver Bril
 ''local_uri'' is used to specify the connection parameters, e.g. local port and local ip.
211 8 Oliver Bril
 If not provided, suitable ''local_uri'' will be generated.
212 8 Oliver Bril
 ''local_uri'' maybe updated in place by {{{prepare()}}} method if the real settings used are different from those specified.
213 8 Oliver Bril
214 8 Oliver Bril
 {{{prepare}}} returns a full local path - list of {{{protocol.URI}}} instances, suitable to be put in SDP {{{'a:path'}}} attribute.
215 8 Oliver Bril
 
216 8 Oliver Bril
 '''complete'''(''self'', ''full_remote_path'')::
217 8 Oliver Bril
 Complete establishing the MSRP connection, which means
218 8 Oliver Bril
 * establishing the connection if it wasn't already established ({{{ConnectorDirect}}})
219 8 Oliver Bril
 * bind the connection, i.e. exchange empty chunk to verify each other's From-Path and To-Path
220 8 Oliver Bril
221 8 Oliver Bril
 ''full_remote_path'' should be a list of {{{protocol.URI}}} instances, obtained by parsing {{{'a:path'}}} put in SDP by the remote party.
222 8 Oliver Bril
223 8 Oliver Bril
 {{{complete}}} returns {{{transport.MSRPTransport}}} instance, ready to read and send chunks.
224 9 Oliver Bril
225 9 Oliver Bril
 '''cleanup'''(''self'')::
226 9 Oliver Bril
 Call this method to cleanup after {{{initialize()}}} if it's impossible to call {{{complete()}}}
227 8 Oliver Bril
 
228 1 Adrian Georgescu
229 4 Oliver Bril
==== transport.MSRPTransport ====
230 1 Adrian Georgescu
231 1 Adrian Georgescu
Low level access to MSRP connection.
232 1 Adrian Georgescu
233 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}}})::
234 1 Adrian Georgescu
 Make a new chunk ({{{protocol.MSRPData}}} instance) with proper {{{From-Path}}}, {{{To-Path}}}, {{{Byte-Range}}} and {{{Message-ID}}} headers set up based on MSRPTransport's state and the parameters provided. Use ''data'' for payload, and ''start''/''end''/''length'' to generate {{{Byte-Range}}} header. Generate new random strings for default values of ''transaction_id'' and ''message_id''. 
235 1 Adrian Georgescu
 [[BR]]''contflag'':[[BR]]
236 1 Adrian Georgescu
 MSRP chunk's continuation flag ({{{'$'}}}, {{{'+'}}} or {{{'#'}}}). Default is {{{'$'}}}, unless you have a partial {{{SEND}}} chunk, in which case it is {{{'+'}}}
237 14 Oliver Bril
238 14 Oliver Bril
 '''write'''(''self'', ''bytes'', ''sync''={{{True}}})::
239 14 Oliver Bril
 Write ''bytes'' to the socket. If ''sync'' is true, wait for an operation to complete.
240 14 Oliver Bril
241 14 Oliver Bril
 '''read_chunk'''(''self'', ''size''={{{None}}})::
242 14 Oliver Bril
 Wait for a new chunk and return it.
243 14 Oliver Bril
 If there was an error, close the connection and raise {{{ChunkParseError}}}.
244 14 Oliver Bril
245 14 Oliver Bril
 In case of unintelligible input, lose the connection and return {{{None}}}.
246 14 Oliver Bril
 When the connection is closed, raise the reason of the closure (e.g. {{{ConnectionDone}}}).
247 14 Oliver Bril
248 14 Oliver Bril
 If the data already read exceeds ''size'', stop reading the data and return
249 14 Oliver Bril
 a "virtual" chunk, i.e. the one that does not actually correspond the the real
250 14 Oliver Bril
 MSRP chunk. Such chunks have Byte-Range header changed to match the number of
251 14 Oliver Bril
 bytes read and continuation that is {{{'+'}}}; they also possess {{{segment}}} attribute,
252 14 Oliver Bril
 an integer, starting with 1 and increasing with every new segment of the chunk.
253 14 Oliver Bril
254 14 Oliver Bril
 Note, that ''size'' only hints when to interrupt the segment but does not affect
255 14 Oliver Bril
 how the data is read from socket. You may have segments bigger than ''size'' and it's
256 14 Oliver Bril
 legal to set ''size'' to zero (which would mean return a chunk as long as you get
257 14 Oliver Bril
 some data, regardless how small).
258 1 Adrian Georgescu
259 15 Oliver Bril
 '''check_incoming_SEND_chunk'''(''self'', ''chunk'')::
260 15 Oliver Bril
 Check the 'To-Path' and 'From-Path' of the incoming SEND chunk.
261 15 Oliver Bril
 Return None is the paths are valid for this connection.
262 15 Oliver Bril
 If an error is detected an MSRPError is created and returned.
263 15 Oliver Bril
264 4 Oliver Bril
==== session.MSRPSession ====
265 15 Oliver Bril
266 15 Oliver Bril
 '''!__init!__'''(''self'', ''msrptransport'', ''accept_types''={{{['*']}}}, ''on_incoming_cb''={{{None}}})::
267 15 Oliver Bril
 Initialize MSRPSession instance. Report the incoming chunks through ''on_incoming_cb'' callback.
268 15 Oliver Bril
269 15 Oliver Bril
 '''send_chunk'''(''self'', ''chunk'', ''response_cb''={{{None}}})::
270 15 Oliver Bril
 Send ''chunk''. Report the result via ''response_cb''.
271 15 Oliver Bril
272 15 Oliver Bril
 When ''response_cb'' argument is present, it will be used to report
273 15 Oliver Bril
 the transaction response to the caller. When a response is received or generated
274 15 Oliver Bril
 locally, ''response_cb'' is called with one argument. The function must do something
275 15 Oliver Bril
 quickly and must not block, because otherwise it would the reader greenlet.
276 15 Oliver Bril
277 15 Oliver Bril
 If no response was received after {{{RESPONSE_TIMEOUT}}} seconds,
278 15 Oliver Bril
 * 408 response is generated if Failure-Report was {{{'yes'}}} or absent
279 15 Oliver Bril
 * 200 response is generated if Failure-Report was {{{'partial'}}} or {{{'no'}}}
280 15 Oliver Bril
281 15 Oliver Bril
 Note that it's rather wasteful to provide ''response_cb'' argument other than {{{None}}}
282 15 Oliver Bril
 for chunks with Failure-Report='no' since it will always fire 30 seconds later
283 15 Oliver Bril
 with 200 result (unless the other party is broken and ignores Failure-Report header)
284 15 Oliver Bril
285 16 Oliver Bril
 If sending is impossible raise {{{MSRPSessionError}}}.
286 1 Adrian Georgescu
287 16 Oliver Bril
 '''deliver_chunk'''(''self'', ''chunk'', ''event''={{{None}}})::
288 16 Oliver Bril
 Send chunk, wait for the transaction response (if Failure-Report header is not {{{'no'}}}).
289 16 Oliver Bril
 Return the transaction response if it's a success, raise {{{MSRPTransactionError}}} if it's not.
290 16 Oliver Bril
291 16 Oliver Bril
 If chunk's Failure-Report is {{{'no'}}}, return {{{None}}} immediately.
292 16 Oliver Bril
293 16 Oliver Bril
 '''shutdown'''(''self'', ''sync''={{{True}}})::
294 16 Oliver Bril
 Send the messages already in queue then close the connection.
295 16 Oliver Bril
296 16 Oliver Bril
==== session.GreenMSRPSession ====
297 16 Oliver Bril
298 16 Oliver Bril
 A subclass of MSRPSession that delivers the incoming messages to the queue.
299 16 Oliver Bril
300 16 Oliver Bril
 '''!__init!__'''(''self'', ''msrptransport'', ''accept_types''={{{['*']}}})::
301 16 Oliver Bril
 Initialize GreenMSRPSession instance. The messages will be delivered to the queue (available as {{{incoming}}} attribute).
302 16 Oliver Bril
303 16 Oliver Bril
 '''receive_chunk'''(''self'')::
304 16 Oliver Bril
 Return a message from the queue.
305 16 Oliver Bril
306 1 Adrian Georgescu
307 4 Oliver Bril
==== connect.MSRPServer ====
308 13 Oliver Bril
 Manage listening sockets. Bind incoming requests.
309 13 Oliver Bril
    
310 13 Oliver Bril
 MSRPServer solves the problem with AcceptorDirect: concurrent using of 2
311 13 Oliver Bril
 or more AcceptorDirect instances on the same non-zero port is not possible.
312 13 Oliver Bril
 If you initialize() those instances, one after another, one will listen on
313 13 Oliver Bril
 the socket and another will get BindError.
314 13 Oliver Bril
315 13 Oliver Bril
 MSRPServer avoids the problem by sharing the listening socket between multiple connections.
316 13 Oliver Bril
 It has a slightly different interface from AcceptorDirect, so it cannot be considered a drop-in
317 13 Oliver Bril
 replacement.
318 13 Oliver Bril
319 13 Oliver Bril
 '''prepare'''(''self'', ''local_uri''={{{None}}}, ''logger''={{{None}}})::
320 13 Oliver Bril
 Start a listening port specified by ''local_uri'' if there isn't one on that port/interface already.
321 13 Oliver Bril
 Add ''local_uri'' to the list of expected URIs, so that incoming connections featuring this URI won't be rejected.
322 13 Oliver Bril
 If ''logger'' is provided use it for this connection instead of the default one.
323 13 Oliver Bril
324 13 Oliver Bril
 '''complete'''(''self'', ''full_remote_path'')::
325 13 Oliver Bril
 Wait until one of the incoming connections binds using provided ''full_remote_path''.
326 13 Oliver Bril
 Return connected and bound {{{MSRPTransport}}} instance.
327 13 Oliver Bril
        
328 13 Oliver Bril
 If no such binding was made within {{{MSRPBindSessionTimeout.seconds}}}, raise {{{MSRPBindSessionTimeout}}}.
329 13 Oliver Bril
 ''full_remote_path'' should be a list of {{{protocol.URI}}} instances, obtained by parsing {{{'a:path'}}} put in SDP by the remote party.
330 13 Oliver Bril
331 13 Oliver Bril
 '''cleanup'''(''self'', ''local_uri'')::
332 13 Oliver Bril
 Remove ''local_uri'' from the list of expected URIs.