SipMSRPApi

Version 46 (Luci Stanescu, 04/15/2010 01:51 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 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).
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 46 Luci Stanescu
 '''!__init!__'''(''self'', '''logger''')::
271 46 Luci Stanescu
 Constructs a new MSRPServer which will be using the specifed logger for its connections. See the [wiki:SipMSRPApi#Logging Logging] section for more information.
272 46 Luci Stanescu
273 1 Adrian Georgescu
 '''prepare'''(''self'', ''local_uri''={{{None}}}, ''logger''={{{None}}})::
274 1 Adrian Georgescu
 Starts a listening port specified by ''local_uri'' if there isn't one on that port/interface already.
275 1 Adrian Georgescu
 Adds ''local_uri'' to the list of expected URIs, so that incoming connections featuring this URI won't be rejected.
276 1 Adrian Georgescu
 If ''logger'' is provided, it uses it for this connection instead of the default one.
277 1 Adrian Georgescu
278 15 Oliver Bril
 '''complete'''(''self'', ''full_remote_path'')::
279 1 Adrian Georgescu
 Waits until one of the incoming connections binds using provided ''full_remote_path''.
280 15 Oliver Bril
 Returns connected and bounds the {{{MSRPTransport}}} instance.
281 15 Oliver Bril
        
282 15 Oliver Bril
 If no such binding was made within {{{MSRPBindSessionTimeout.seconds}}}, raise {{{MSRPBindSessionTimeout}}}.
283 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.
284 38 Adrian Georgescu
285 38 Adrian Georgescu
 '''cleanup'''(''self'', ''local_uri'')::
286 38 Adrian Georgescu
 Removes ''local_uri'' from the list of expected URIs.
287 46 Luci Stanescu
288 46 Luci Stanescu
== Logging ==
289 46 Luci Stanescu
290 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:
291 46 Luci Stanescu
292 46 Luci Stanescu
 '''received_new_chunk'''('''data''', '''transport''', '''chunk''')::
293 46 Luci Stanescu
  This method is called when the start of a new chunk is received.
294 46 Luci Stanescu
  [[BR]]''data'':[[BR]]
295 46 Luci Stanescu
  The data which came along with the start of the chunk.
296 46 Luci Stanescu
  [[BR]]''transport'':[[BR]]
297 46 Luci Stanescu
  The {{{MSRPTransport}}} instance on which the chunk was received.
298 46 Luci Stanescu
  [[BR]]''chunk'':[[BR]]
299 46 Luci Stanescu
  The actual chunk object.
300 46 Luci Stanescu
301 46 Luci Stanescu
 '''received_chunk_data'''('''data''', '''transport''', '''transaction_id''')::
302 46 Luci Stanescu
  This method is called when data is received as part of a chunk previously announced via '''received_new_chunk'''.
303 46 Luci Stanescu
  [[BR]]''data'':[[BR]]
304 46 Luci Stanescu
  The data received as part of the chunk.
305 46 Luci Stanescu
  [[BR]]''transport'':[[BR]]
306 46 Luci Stanescu
  The {{{MSRPTransport}}} instance on which the chunk was received.
307 46 Luci Stanescu
  [[BR]]''transaction_id'':[[BR]]
308 46 Luci Stanescu
  The transaction ID which identifies the chunk for which data was received.
309 46 Luci Stanescu
310 46 Luci Stanescu
 '''received_chunk_end'''('''data''', '''transport''', transaction_id''')::
311 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'''.
312 46 Luci Stanescu
  [[BR]]''data'':[[BR]]
313 46 Luci Stanescu
  The last data received as part of the chunk.
314 46 Luci Stanescu
  [[BR]]''transport'':[[BR]]
315 46 Luci Stanescu
  The {{{MSRPTransport}}} instance on which the chunk was received.
316 46 Luci Stanescu
  [[BR]]''transaction_id'':[[BR]]
317 46 Luci Stanescu
  The transaction ID which identifies the chunk which was ended.
318 46 Luci Stanescu
319 46 Luci Stanescu
 '''sent_new_chunk'''('''data''', '''transport''', '''chunk''')::
320 46 Luci Stanescu
  This method is called when the start of a new chunk is sent.
321 46 Luci Stanescu
  [[BR]]''data'':[[BR]]
322 46 Luci Stanescu
  The data which was sent along with the start of the chunk.
323 46 Luci Stanescu
  [[BR]]''transport'':[[BR]]
324 46 Luci Stanescu
  The {{{MSRPTransport}}} instance on which the chunk was sent.
325 46 Luci Stanescu
  [[BR]]''chunk'':[[BR]]
326 46 Luci Stanescu
  The actual chunk object.
327 46 Luci Stanescu
328 46 Luci Stanescu
 '''sent_chunk_data'''('''data''', '''transport''', '''transaction_id''')::
329 46 Luci Stanescu
  This method is called when data is sent as part of a chunk previously announced via '''sent_new_chunk'''.
330 46 Luci Stanescu
  [[BR]]''data'':[[BR]]
331 46 Luci Stanescu
  The data sent as part of the chunk.
332 46 Luci Stanescu
  [[BR]]''transport'':[[BR]]
333 46 Luci Stanescu
  The {{{MSRPTransport}}} instance on which the chunk was sent.
334 46 Luci Stanescu
  [[BR]]''transaction_id'':[[BR]]
335 46 Luci Stanescu
  The transaction ID which identifies the chunk for which data was sent.
336 46 Luci Stanescu
337 46 Luci Stanescu
 '''sent_chunk_end'''('''data''', '''transport''', transaction_id''')::
338 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'''.
339 46 Luci Stanescu
  [[BR]]''data'':[[BR]]
340 46 Luci Stanescu
  The last data sent as part of the chunk.
341 46 Luci Stanescu
  [[BR]]''transport'':[[BR]]
342 46 Luci Stanescu
  The {{{MSRPTransport}}} instance on which the chunk was sent.
343 46 Luci Stanescu
  [[BR]]''transaction_id'':[[BR]]
344 46 Luci Stanescu
  The transaction ID which identifies the chunk which was ended.
345 46 Luci Stanescu
346 46 Luci Stanescu
 '''debug'''('''message''')::
347 46 Luci Stanescu
  This method is called when a debug level message is sent by the library.
348 46 Luci Stanescu
349 46 Luci Stanescu
 '''info'''('''message''')::
350 46 Luci Stanescu
  This method is called when a info level message is sent by the library.
351 46 Luci Stanescu
352 46 Luci Stanescu
 '''warn'''('''message''')::
353 46 Luci Stanescu
  This method is called when a warning level message is sent by the library.
354 46 Luci Stanescu
355 46 Luci Stanescu
 '''error'''('''message''')::
356 46 Luci Stanescu
  This method is called when a error level message is sent by the library.
357 46 Luci Stanescu
358 46 Luci Stanescu
 '''fatal'''('''message''')::
359 46 Luci Stanescu
  This method is called when a fatal level message is sent by the library.
360 38 Adrian Georgescu
361 39 Luci Stanescu
== Example ==
362 38 Adrian Georgescu
363 38 Adrian Georgescu
=== Establish a connection ===
364 38 Adrian Georgescu
365 38 Adrian Georgescu
{{{msrplib.connect}}} provides a number of classes to establish a connection, so the first
366 38 Adrian Georgescu
thing to do is to select which one applies to your situation:
367 38 Adrian Georgescu
368 38 Adrian Georgescu
    1. Calling endpoint, not using a relay ({{{ConnectorDirect}}})
369 38 Adrian Georgescu
    2. Answering endpoint, not using a relay ({{{AcceptorDirect}}})
370 38 Adrian Georgescu
    3. Calling endpoint, using a relay ({{{ConnectorRelay}}})
371 38 Adrian Georgescu
    4. Answering endpoint, using a relay ({{{AcceptorRelay}}})
372 38 Adrian Georgescu
373 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.
374 38 Adrian Georgescu
375 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.
376 38 Adrian Georgescu
377 38 Adrian Georgescu
Once you have an instance of the right class (use the convenience functions
378 38 Adrian Georgescu
{{{get_connector()}}} and {{{get_acceptor()}}} to get one), the procedure to establish the
379 38 Adrian Georgescu
connection is the same:
380 38 Adrian Georgescu
381 38 Adrian Georgescu
{{{
382 38 Adrian Georgescu
full_local_path = connector.prepare()
383 38 Adrian Georgescu
try:
384 38 Adrian Georgescu
    ... put full_local_path in SDP 'a:path' attribute
385 38 Adrian Georgescu
    ... get full_remote_path from remote's 'a:path: attribute
386 38 Adrian Georgescu
    ... (the order of the above steps is reversed if you're the
387 38 Adrian Georgescu
    ... answering party, but that does not affect connector's usage)
388 38 Adrian Georgescu
    msrptransport = connector.complete(full_remote_path)
389 38 Adrian Georgescu
finally:
390 38 Adrian Georgescu
    connector.cleanup()
391 38 Adrian Georgescu
}}}
392 38 Adrian Georgescu
393 38 Adrian Georgescu
To customize connection's parameters, creates a new {{{protocol.URI}}} object and passes
394 38 Adrian Georgescu
it to prepare() function, e.g.
395 38 Adrian Georgescu
{{{
396 38 Adrian Georgescu
local_uri = protocol.URI(use_tls=False, port=5000)
397 38 Adrian Georgescu
connector.prepare(local_uri)
398 38 Adrian Georgescu
}}}
399 38 Adrian Georgescu
400 38 Adrian Georgescu
{{{prepare()}}} may update {{{local_uri}}} in place with the actual connection parameters
401 38 Adrian Georgescu
used (e.g. if you specified port=0). 'port' attribute of {{{local_uri}}} is currently
402 38 Adrian Georgescu
only respected by {{{AcceptorDirect}}}.
403 38 Adrian Georgescu
404 1 Adrian Georgescu
Note that, acceptors and connectors are one-use only. Which means, that {{{AcceptorDirect}}}
405 1 Adrian Georgescu
will open a port just to handle one incoming connection and close it right after.
406 1 Adrian Georgescu
If your application behaves more like a server, i.e. opens a port and listens on it
407 1 Adrian Georgescu
constantly, use {{{MSRPServer}}} class.