SipMSRPApi

Version 44 (Luci Stanescu, 04/15/2010 01:39 pm)

1 1 Adrian Georgescu
= MSRP API =
2 1 Adrian Georgescu
3 34 Adrian Georgescu
[[TOC(SipMSRPApi, SipDeveloperGuide, depth=3)]]
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 39 Luci Stanescu
== Classes ==
29 3 Oliver Bril
30 39 Luci Stanescu
=== URI ===
31 1 Adrian Georgescu
32 44 Luci Stanescu
This class is implemented in the {{{msrplib.protocol}}} module and is used to represent an MSRP URI.
33 1 Adrian Georgescu
34 39 Luci Stanescu
==== Methods ====
35 1 Adrian Georgescu
36 39 Luci Stanescu
 '''!__init!__'''(''self'', '''host'''={{{None}}}, '''use_tls'''={{{False}}}, '''user'''={{{None}}}, '''port'''={{{None}}}, '''session_id'''={{{None}}}, '''parameters'''={{{None}}}, '''credentials'''={{{None}}})::
37 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.
38 39 Luci Stanescu
  [[BR]]''host'':[[BR]]
39 39 Luci Stanescu
  The hostname or IP address which forms the URI.
40 39 Luci Stanescu
  [[BR]]''use_tls'':[[BR]]
41 39 Luci Stanescu
  Whether this identifies an msrps or msrp URI.
42 39 Luci Stanescu
  [[BR]]''user'':[[BR]]
43 39 Luci Stanescu
  The user part of the URI.
44 39 Luci Stanescu
  [[BR]]''port'':[[BR]]
45 39 Luci Stanescu
  The port in the URI.
46 39 Luci Stanescu
  [[BR]]''session_id'':[[BR]]
47 39 Luci Stanescu
  The session identifier part of the URI.
48 39 Luci Stanescu
  [[BR]]''parameters'':[[BR]]
49 39 Luci Stanescu
  A {{{dict}}} containing the parameters which will be appended to the URI.
50 39 Luci Stanescu
  [[BR]]''credentials'':[[BR]]
51 39 Luci Stanescu
  A {{{gnutls.interfaces.twisted.X509Credentials}}} object which will be used if this identifies a TLS URI to authenticate to the other endpoint.
52 1 Adrian Georgescu
53 39 Luci Stanescu
=== MSRPRelaySettings ===
54 1 Adrian Georgescu
55 43 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).
56 39 Luci Stanescu
57 39 Luci Stanescu
==== Methods ====
58 39 Luci Stanescu
59 39 Luci Stanescu
 '''!__init!__'''(''self'', '''domain''', '''username''', '''password''', '''host'''={{{None}}}, '''use_tls'''={{{False}}}, '''port'''={{{None}}}, '''credentials'''={{{None}}})::
60 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.
61 39 Luci Stanescu
  [[BR]]''domain'':[[BR]]
62 39 Luci Stanescu
  The DNS domain in which to search for a MSRP relay using SRV queries.
63 39 Luci Stanescu
  [[BR]]''username'':[[BR]]
64 39 Luci Stanescu
  The username which will be used to authenticate to the relay.
65 39 Luci Stanescu
  [[BR]]''password'':[[BR]]
66 39 Luci Stanescu
  The password which will be used to authenticate to the relay.
67 39 Luci Stanescu
  [[BR]]''host'':[[BR]]
68 39 Luci Stanescu
  The hostname or IP address of the MSRP relay.
69 39 Luci Stanescu
  [[BR]]''use_tls'':[[BR]]
70 39 Luci Stanescu
  Whether this identifies an msrps or msrp URI.
71 39 Luci Stanescu
  [[BR]]''port'':[[BR]]
72 39 Luci Stanescu
  The port in the URI.
73 39 Luci Stanescu
  [[BR]]''credentials'':[[BR]]
74 39 Luci Stanescu
  A {{{gnutls.interfaces.twisted.X509Credentials}}} object which will be used to authenticate to the relay if TLS is used.
75 39 Luci Stanescu
76 39 Luci Stanescu
=== ConnectorDirect ===
77 39 Luci Stanescu
78 44 Luci Stanescu
This class is implemented in the {{{msrplib.connect}}} module and is used for outbound MSRP connections without a relay.
79 39 Luci Stanescu
80 39 Luci Stanescu
==== Methods ====
81 39 Luci Stanescu
82 39 Luci Stanescu
 '''!__init!__'''(''self'', '''loger'''={{{None}}})::
83 44 Luci Stanescu
 Constructs a new ConnectorDirect.
84 39 Luci Stanescu
 [[BR]]''logger'':[[BR]]
85 39 Luci Stanescu
 The logger which will be used for this MSRP connection. See the [wiki:SipMSRPApi#Logging Logging] section for more information.
86 39 Luci Stanescu
87 39 Luci Stanescu
 '''prepare'''(''self'', '''local_uri'''={{{None}}})::
88 39 Luci Stanescu
 This method returns a full local path - list of {{{protocol.URI}}} instances, suitable to be put in SDP {{{'a:path'}}} attribute.
89 39 Luci Stanescu
 [[BR]]''local_uri'':[[BR]]
90 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
91 39 Luci Stanescu
 will be automatically generated
92 1 Adrian Georgescu
 
93 39 Luci Stanescu
 '''complete'''(''self'', '''full_remote_path''')::
94 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.
95 39 Luci Stanescu
 [[BR]]''full_remote_path'':[[BR]]
96 39 Luci Stanescu
 A list of {{{protocol.URI}}} instances, obtained by parsing {{{'a:path'}}} put in SDP by the remote party.
97 1 Adrian Georgescu
98 39 Luci Stanescu
 '''cleanup'''(''self'')::
99 39 Luci Stanescu
 This method cleans up after {{{prepare()}}}; it should be called if {{{complete()}}} will not be called for whatever reason.
100 1 Adrian Georgescu
101 39 Luci Stanescu
=== ConnectorRelay ===
102 1 Adrian Georgescu
103 44 Luci Stanescu
This class is implemented in the {{{msrplib.connect}}} module and is used for outbound MSRP connections using a relay.
104 1 Adrian Georgescu
105 39 Luci Stanescu
==== Methods ====
106 39 Luci Stanescu
107 39 Luci Stanescu
 '''!__init!__'''(''self'', '''relay''', '''loger'''={{{None}}})::
108 39 Luci Stanescu
 Constructs a new ConnectorRelay.
109 39 Luci Stanescu
 [[BR]]''relay'':[[BR]]
110 39 Luci Stanescu
 An instance of {{{MSRPRelaySettings}}} which identifies the relay which is to be used.
111 39 Luci Stanescu
 [[BR]]''logger'':[[BR]]
112 39 Luci Stanescu
 The logger which will be used for this MSRP connection. See the [wiki:SipMSRPApi#Logging Logging] section for more information.
113 39 Luci Stanescu
114 39 Luci Stanescu
 '''prepare'''(''self'', '''local_uri'''={{{None}}})::
115 39 Luci Stanescu
 This method returns a full local path - list of {{{protocol.URI}}} instances, suitable to be put in SDP {{{'a:path'}}} attribute.
116 39 Luci Stanescu
 [[BR]]''local_uri'':[[BR]]
117 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 ConnectorRelay. If not provided, one
118 39 Luci Stanescu
 will be automatically generated
119 39 Luci Stanescu
 
120 39 Luci Stanescu
 '''complete'''(''self'', '''full_remote_path''')::
121 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.
122 39 Luci Stanescu
 [[BR]]''full_remote_path'':[[BR]]
123 39 Luci Stanescu
 A list of {{{protocol.URI}}} instances, obtained by parsing {{{'a:path'}}} put in SDP by the remote party.
124 39 Luci Stanescu
125 1 Adrian Georgescu
 '''cleanup'''(''self'')::
126 39 Luci Stanescu
 This method cleans up after {{{prepare()}}}; it should be called if {{{complete()}}} will not be called for whatever reason.
127 1 Adrian Georgescu
128 39 Luci Stanescu
=== AcceptorDirect ===
129 1 Adrian Georgescu
130 44 Luci Stanescu
This class is implemented in the {{{msrplib.connect}}} module and is used for inbound MSRP connections without using a relay.
131 1 Adrian Georgescu
132 40 Luci Stanescu
==== Methods ====
133 39 Luci Stanescu
134 39 Luci Stanescu
 '''!__init!__'''(''self'', '''loger'''={{{None}}})::
135 39 Luci Stanescu
  Constructs a new AcceptorDirect.
136 39 Luci Stanescu
 [[BR]]''logger'':[[BR]]
137 39 Luci Stanescu
 The logger which will be used for this MSRP connection. See the [wiki:SipMSRPApi#Logging Logging] section for more information.
138 39 Luci Stanescu
139 39 Luci Stanescu
 '''prepare'''(''self'', '''local_uri'''={{{None}}})::
140 39 Luci Stanescu
 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.
141 39 Luci Stanescu
 [[BR]]''local_uri'':[[BR]]
142 39 Luci Stanescu
 This attribute will be used to construct the local path and to listen for incomming connections. If not provided, one
143 39 Luci Stanescu
 will be automatically generated
144 39 Luci Stanescu
 
145 39 Luci Stanescu
 '''complete'''(''self'', '''full_remote_path''')::
146 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.
147 39 Luci Stanescu
 [[BR]]''full_remote_path'':[[BR]]
148 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.
149 39 Luci Stanescu
150 39 Luci Stanescu
 '''cleanup'''(''self'')::
151 39 Luci Stanescu
 This method cleans up after {{{prepare()}}}; it should be called if {{{complete()}}} will not be called for whatever reason.
152 39 Luci Stanescu
153 39 Luci Stanescu
=== AcceptorRelay ===
154 39 Luci Stanescu
155 44 Luci Stanescu
This class is implemented in the {{{msrplib.connect}}} module and is used for inbound MSRP connections using a relay.
156 39 Luci Stanescu
157 39 Luci Stanescu
==== Methods ====
158 39 Luci Stanescu
159 39 Luci Stanescu
 '''!__init!__'''(''self'', '''relay''', '''loger'''={{{None}}})::
160 39 Luci Stanescu
 Constructs a new AcceptorRelay.
161 39 Luci Stanescu
 [[BR]]''relay'':[[BR]]
162 39 Luci Stanescu
 An instance of {{{MSRPRelaySettings}}} which identifies the relay which is to be used.
163 39 Luci Stanescu
 [[BR]]''logger'':[[BR]]
164 39 Luci Stanescu
 The logger which will be used for this MSRP connection. See the [wiki:SipMSRPApi#Logging Logging] section for more information.
165 39 Luci Stanescu
166 39 Luci Stanescu
 '''prepare'''(''self'', '''local_uri'''={{{None}}})::
167 39 Luci Stanescu
 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.
168 39 Luci Stanescu
 [[BR]]''local_uri'':[[BR]]
169 39 Luci Stanescu
 This attribute will be used to construct the local path. If not provided, one will be automatically generated
170 39 Luci Stanescu
 
171 39 Luci Stanescu
 '''complete'''(''self'', '''full_remote_path''')::
172 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.
173 39 Luci Stanescu
 [[BR]]''full_remote_path'':[[BR]]
174 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.
175 39 Luci Stanescu
176 39 Luci Stanescu
 '''cleanup'''(''self'')::
177 39 Luci Stanescu
 This method cleans up after {{{prepare()}}}; it should be called if {{{complete()}}} will not be called for whatever reason.
178 39 Luci Stanescu
179 39 Luci Stanescu
=== MSRPTransport ===
180 39 Luci Stanescu
181 41 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
182 39 Luci Stanescu
183 39 Luci Stanescu
==== Methods ====
184 39 Luci Stanescu
185 39 Luci Stanescu
 '''make_chunk'''(''self'', '''transaction_id'''={{{None}}}, '''method'''={{{'SEND'}}}, '''code'''={{{None}}}, '''comment'''={{{None}}}, '''data'''={{{''}}}, '''contflag'''={{{None}}}, '''start'''={{{1}}}, '''end'''={{{None}}}, '''length'''={{{None}}}, '''message_id'''={{{None}}})::
186 1 Adrian Georgescu
 Makes 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''. 
187 1 Adrian Georgescu
 [[BR]]''contflag'':[[BR]]
188 1 Adrian Georgescu
 MSRP chunk's continuation flag ({{{'$'}}}, {{{'+'}}} or {{{'#'}}}). Default is {{{'$'}}}, unless you have a partial {{{SEND}}} chunk, in which case it is {{{'+'}}}
189 14 Oliver Bril
190 39 Luci Stanescu
 '''write'''(''self'', '''bytes''', '''sync'''={{{True}}})::
191 1 Adrian Georgescu
 Writes ''bytes'' to the socket. If ''sync'' is true, waits for an operation to complete.
192 1 Adrian Georgescu
193 39 Luci Stanescu
 '''read_chunk'''(''self'', '''size'''={{{None}}})::
194 1 Adrian Georgescu
 Waits for a new chunk and returns it.
195 1 Adrian Georgescu
 If there was an error, closes the connection and raises {{{ChunkParseError}}}.
196 1 Adrian Georgescu
197 15 Oliver Bril
 In case of unintelligible input, loses the connection and returns {{{None}}}.
198 1 Adrian Georgescu
 When the connection is closed, raises the reason of the closure (e.g. {{{ConnectionDone}}}).
199 27 Adrian Georgescu
200 27 Adrian Georgescu
 If the data already read exceeds ''size'', stops reading the data and returns
201 38 Adrian Georgescu
 a "virtual" chunk, i.e. the one that does not actually correspond the the real
202 1 Adrian Georgescu
 MSRP chunk. Such chunks have Byte-Range header changed to match the number of
203 4 Oliver Bril
 bytes read and continuation that is {{{'+'}}}; they also possess {{{segment}}} attribute,
204 1 Adrian Georgescu
 an integer, starting with 1 and increasing with every new segment of the chunk.
205 15 Oliver Bril
206 27 Adrian Georgescu
 Note, that ''size'' only hints when to interrupt the segment but does not affect
207 1 Adrian Georgescu
 how the data is read from socket. You may have segments bigger than ''size'' and it's
208 15 Oliver Bril
 legal to set ''size'' to zero (which would mean return a chunk as long as you get
209 27 Adrian Georgescu
 some data, regardless how small).
210 15 Oliver Bril
211 39 Luci Stanescu
 '''check_incoming_SEND_chunk'''(''self'', '''chunk''')::
212 15 Oliver Bril
 Checks the 'To-Path' and 'From-Path' of the incoming SEND chunk.
213 1 Adrian Georgescu
 Returns None is the paths are valid for this connection.
214 15 Oliver Bril
 If an error is detected an MSRPError is created and returned.
215 1 Adrian Georgescu
216 39 Luci Stanescu
=== MSRPSession ===
217 15 Oliver Bril
218 44 Luci Stanescu
This class is implemented in the {{{msrplib.session}}} module and provides a high level API for MSRP sessions.
219 39 Luci Stanescu
220 39 Luci Stanescu
==== Methods ====
221 39 Luci Stanescu
222 39 Luci Stanescu
 '''!__init!__'''(''self'', '''msrptransport''', '''accept_types'''={{{['*']}}}, '''on_incoming_cb'''={{{None}}})::
223 41 Luci Stanescu
 Initializes MSRPSession instance. The incoming chunks are reported through the ''on_incoming_cb'' callback, which must be a function which receives two arguments, both optional with default values of {{{None}}}: ''chunk'' and ''error''.
224 1 Adrian Georgescu
225 39 Luci Stanescu
 '''send_chunk'''(''self'', '''chunk''', '''response_cb'''={{{None}}})::
226 1 Adrian Georgescu
 Sends ''chunk''. Report the result via ''response_cb''.
227 1 Adrian Georgescu
228 1 Adrian Georgescu
 When ''response_cb'' argument is present, it will be used to report
229 1 Adrian Georgescu
 the transaction response to the caller. When a response is received or generated
230 1 Adrian Georgescu
 locally, ''response_cb'' is called with one argument. The function must do something
231 1 Adrian Georgescu
 quickly and must not block, because otherwise it would block the reader greenlet.
232 1 Adrian Georgescu
233 1 Adrian Georgescu
 If no response was received after {{{RESPONSE_TIMEOUT}}} seconds,
234 1 Adrian Georgescu
 * 408 response is generated if Failure-Report was {{{'yes'}}} or absent
235 1 Adrian Georgescu
 * 200 response is generated if Failure-Report was {{{'partial'}}} or {{{'no'}}}
236 1 Adrian Georgescu
237 1 Adrian Georgescu
 Note that it's rather wasteful to provide ''response_cb'' argument other than {{{None}}}
238 1 Adrian Georgescu
 for chunks with Failure-Report='no' since it will always fire 30 seconds later
239 1 Adrian Georgescu
 with 200 result (unless the other party is broken and ignores Failure-Report header)
240 1 Adrian Georgescu
241 1 Adrian Georgescu
 If sending is impossible raise {{{MSRPSessionError}}}.
242 38 Adrian Georgescu
243 39 Luci Stanescu
 '''deliver_chunk'''(''self'', '''chunk''', '''event'''={{{None}}})::
244 1 Adrian Georgescu
 Sends the chunk, waits for the transaction response (if Failure-Report header is not {{{'no'}}}).
245 1 Adrian Georgescu
 Returns the transaction response if it's a success, raise {{{MSRPTransactionError}}} if it's not.
246 1 Adrian Georgescu
247 1 Adrian Georgescu
 If chunk's Failure-Report is {{{'no'}}}, returns {{{None}}} immediately.
248 1 Adrian Georgescu
249 39 Luci Stanescu
 '''shutdown'''(''self'', '''sync'''={{{True}}})::
250 41 Luci Stanescu
 Sends the messages already in queue then closes the connection.
251 1 Adrian Georgescu
252 39 Luci Stanescu
=== MSRPServer ===
253 38 Adrian Georgescu
254 44 Luci Stanescu
This class is implemented in the {{{msrplib.connect}}} module.
255 1 Adrian Georgescu
    
256 44 Luci Stanescu
MSRPServer solves the problem with AcceptorDirect: concurrent using of 2
257 44 Luci Stanescu
or more AcceptorDirect instances on the same non-zero port is not possible.
258 44 Luci Stanescu
If you initialize() those instances, one after another, one will listen on
259 44 Luci Stanescu
the socket and another will get BindError.
260 1 Adrian Georgescu
261 44 Luci Stanescu
MSRPServer avoids the problem by sharing the listening socket between multiple connections.
262 44 Luci Stanescu
It has a slightly different interface from AcceptorDirect, so it cannot be considered a drop-in
263 44 Luci Stanescu
replacement.
264 1 Adrian Georgescu
265 44 Luci Stanescu
It manages the listening sockets and binds incoming requests.
266 39 Luci Stanescu
267 39 Luci Stanescu
268 39 Luci Stanescu
==== Methods ====
269 39 Luci Stanescu
270 1 Adrian Georgescu
 '''prepare'''(''self'', ''local_uri''={{{None}}}, ''logger''={{{None}}})::
271 1 Adrian Georgescu
 Starts a listening port specified by ''local_uri'' if there isn't one on that port/interface already.
272 1 Adrian Georgescu
 Adds ''local_uri'' to the list of expected URIs, so that incoming connections featuring this URI won't be rejected.
273 1 Adrian Georgescu
 If ''logger'' is provided, it uses it for this connection instead of the default one.
274 1 Adrian Georgescu
275 15 Oliver Bril
 '''complete'''(''self'', ''full_remote_path'')::
276 1 Adrian Georgescu
 Waits until one of the incoming connections binds using provided ''full_remote_path''.
277 15 Oliver Bril
 Returns connected and bounds the {{{MSRPTransport}}} instance.
278 15 Oliver Bril
        
279 15 Oliver Bril
 If no such binding was made within {{{MSRPBindSessionTimeout.seconds}}}, raise {{{MSRPBindSessionTimeout}}}.
280 38 Adrian Georgescu
 ''full_remote_path'' should be a list of {{{protocol.URI}}} instances, obtained by parsing {{{'a:path'}}} put in SDP by the remote party.
281 38 Adrian Georgescu
282 38 Adrian Georgescu
 '''cleanup'''(''self'', ''local_uri'')::
283 38 Adrian Georgescu
 Removes ''local_uri'' from the list of expected URIs.
284 38 Adrian Georgescu
285 39 Luci Stanescu
== Example ==
286 38 Adrian Georgescu
287 38 Adrian Georgescu
=== Establish a connection ===
288 38 Adrian Georgescu
289 38 Adrian Georgescu
{{{msrplib.connect}}} provides a number of classes to establish a connection, so the first
290 38 Adrian Georgescu
thing to do is to select which one applies to your situation:
291 38 Adrian Georgescu
292 38 Adrian Georgescu
    1. Calling endpoint, not using a relay ({{{ConnectorDirect}}})
293 38 Adrian Georgescu
    2. Answering endpoint, not using a relay ({{{AcceptorDirect}}})
294 38 Adrian Georgescu
    3. Calling endpoint, using a relay ({{{ConnectorRelay}}})
295 38 Adrian Georgescu
    4. Answering endpoint, using a relay ({{{AcceptorRelay}}})
296 38 Adrian Georgescu
297 38 Adrian Georgescu
The answering endpoint may skip using the relay if sure that it's accessible directly, e.g is not behind a NAT. To be sure it works in any network topology a called end-point should always use a relay.
298 38 Adrian Georgescu
299 38 Adrian Georgescu
The calling endpoint does not need a relay as the protocol mandates that it is establishing an outbound connection which always work from behind a NAT.
300 38 Adrian Georgescu
301 38 Adrian Georgescu
Once you have an instance of the right class (use the convenience functions
302 38 Adrian Georgescu
{{{get_connector()}}} and {{{get_acceptor()}}} to get one), the procedure to establish the
303 38 Adrian Georgescu
connection is the same:
304 38 Adrian Georgescu
305 38 Adrian Georgescu
{{{
306 38 Adrian Georgescu
full_local_path = connector.prepare()
307 38 Adrian Georgescu
try:
308 38 Adrian Georgescu
    ... put full_local_path in SDP 'a:path' attribute
309 38 Adrian Georgescu
    ... get full_remote_path from remote's 'a:path: attribute
310 38 Adrian Georgescu
    ... (the order of the above steps is reversed if you're the
311 38 Adrian Georgescu
    ... answering party, but that does not affect connector's usage)
312 38 Adrian Georgescu
    msrptransport = connector.complete(full_remote_path)
313 38 Adrian Georgescu
finally:
314 38 Adrian Georgescu
    connector.cleanup()
315 38 Adrian Georgescu
}}}
316 38 Adrian Georgescu
317 38 Adrian Georgescu
To customize connection's parameters, creates a new {{{protocol.URI}}} object and passes
318 38 Adrian Georgescu
it to prepare() function, e.g.
319 38 Adrian Georgescu
{{{
320 38 Adrian Georgescu
local_uri = protocol.URI(use_tls=False, port=5000)
321 38 Adrian Georgescu
connector.prepare(local_uri)
322 38 Adrian Georgescu
}}}
323 38 Adrian Georgescu
324 38 Adrian Georgescu
{{{prepare()}}} may update {{{local_uri}}} in place with the actual connection parameters
325 38 Adrian Georgescu
used (e.g. if you specified port=0). 'port' attribute of {{{local_uri}}} is currently
326 38 Adrian Georgescu
only respected by {{{AcceptorDirect}}}.
327 38 Adrian Georgescu
328 1 Adrian Georgescu
Note that, acceptors and connectors are one-use only. Which means, that {{{AcceptorDirect}}}
329 1 Adrian Georgescu
will open a port just to handle one incoming connection and close it right after.
330 1 Adrian Georgescu
If your application behaves more like a server, i.e. opens a port and listens on it
331 1 Adrian Georgescu
constantly, use {{{MSRPServer}}} class.