SipMSRPApi

Version 61 (Anonymous, 07/05/2010 10:30 am)

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