Project

General

Profile

SipMSRPApi » History » Version 13

Oliver Bril, 03/31/2009 02:46 PM

1 1 Adrian Georgescu
= MSRP API =
2
3
[[TOC(WikiStart, Sip*, depth=3)]]
4
5
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
7
 * MSRP sessions are defined in [http://tools.ietf.org/html/rfc4975 RFC 4975].
8
 * 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
10 5 Oliver Bril
The MSRP protocol is implemented by [http://devel.ag-projects.com/cgi-bin/darcsweb.cgi?r=python-msrplib;a=summary msrplib] Python package. On top of it, {{{sipsimple}}} provides higher level classes integrated into middleware notification and configuration systems:
11 1 Adrian Georgescu
12 4 Oliver Bril
 * {{{sipsimple.msrp.MSRPChat}}}
13
 * {{{sipsimple.msrp.MSRPFileTransfer}}}
14 1 Adrian Georgescu
 * {{{sipsimple.msrp.MSRPDesktopSharing}}}
15
16 11 Adrian Georgescu
These classes are used internally by [wiki:SipMiddlewareApi#Session Session], which provides the necessary methods to access their features. The notifications posted by these classes are also handled internally by [wiki:SipMiddlewareApi#Session Session]. The notifications that are relevant to the user are then reposted by the Session instance. Refer to [wiki:SipMiddlewareApi#Session Session documentation] for details on the Session API. To communicate with the middleware, MSRP high level classes use the notification system provided by the [http://pypi.python.org/pypi/python-application python-application] package.
17 10 Adrian Georgescu
18 12 Adrian Georgescu
== MSRPChat high level API ==
19 1 Adrian Georgescu
20 10 Adrian Georgescu
{{{sipsimple.msrp.MSRPChat}}} implements Instant Messaging over MSRP in the context of SIPSIMPLE middleware. This class
21 1 Adrian Georgescu
22 5 Oliver Bril
 * automatically wraps outgoing messages with Message/CPIM if that's necessary according to accept-types
23 7 Oliver Bril
 * unwraps incoming Message/CPIM messages; for each incoming message, {{{MSRPChatGotMessage}}} is posted.
24 5 Oliver Bril
 * plays notification sounds on received/sent message
25
26
=== methods ===
27
28
 '''!__init!__'''(''self'', ''account'', ''remote_uri'', ''outgoing'')::
29
 Initialize MSRPChat instance.
30
31
 '''initialize'''(''self'')::
32
 Initialize the MSRP connection; connect to the relay if necessary. When done, fire MSRPChatDidInitialize (with 'sdpmedia' attribute, containing the appropriate 'SDPMedia' instance)
33
34
 '''start'''(''self'', ''remote_media'')::
35
 Complete the MSRP connection establishment; this includes binding the MSRP session. [[BR]]
36
 When done, fire MSRPChatDidStart. At this point each incoming message is posted as a {{{MSRPChatGotMessage}}} notification
37
38
 '''end'''(''self'')::
39
 Close the MSRP connection or cleanup after initialize(), whatever is necessary. [[BR]]
40
 Before doing anything post {{{MSRPChatWillEnd}}}.
41 7 Oliver Bril
 When done, post {{{MSRPChatDidEnd}}}. If there was an error, post {{{MSRPChatDidFail}}}. 
42 5 Oliver Bril
 {{{MSRPChatDidEnd}}} will be posted anyway.
43
44 6 Oliver Bril
 '''send_message'''(''self'', ''content'', ''content_type''={{{'text/plain'}}}, ''to_uri''={{{None}}}, ''dt''={{{None}}})::
45
 Send IM message. Prefer Message/CPIM wrapper if it is supported. If called before the connection was established, the messages will be
46
 queued until MSRPChatDidStart notification.
47
48
 Return generated MSRP chunk (MSRPData instance); to get Message-ID use its 'message_id' attribute.
49
50
 ''content'' str:[[BR]]
51
 content of the message
52
53
 ''to_uri'' SIPURI:[[BR]]
54
 "To" header of CPIM wrapper; use to override the default supplied to {{{__init__}}}.
55
 May only differ from the one supplied in __init__ if the remote party supports private messages. If it does not, {{{MSRPChatError}}} will be raised;
56
57
 ''content_type'' str:[[BR]]
58
 Content-Type of wrapped message if Message/CPIM is used (Content-Type of MSRP message is always Message/CPIM in that case);
59
 otherwise, Content-Type of MSRP message.
60
61
 These MSRP headers are used to enable end-to-end success reports and to disable hop-to-hop successful responses:
62
{{{
63
Failure-Report: partial
64
Success-Report: yes
65
}}}
66
67 5 Oliver Bril
68 1 Adrian Georgescu
=== notifications ===
69
70 7 Oliver Bril
 * MSRPChatDidInitialize
71
 * MSRPChatDidStart
72
 * MSRPChatWillEnd
73
 * MSRPChatDidEnd
74
 * MSRPChatDidFail
75
 * MSRPChatGotMessage
76
  - cpim_headers (dict)
77
  - message  (MSRPData)
78
  - content (str) - the actual string that the remote user has typed
79
 * MSRPChatDidDeliverMessage
80
 * MSRPChatDidNotDeliverMessage
81 5 Oliver Bril
82 4 Oliver Bril
== MSRPFileTransfer ==
83
84
== MSRPDesktopSharing ==
85 1 Adrian Georgescu
86 12 Adrian Georgescu
----------------------
87
88
== msrplib low level API ==
89 4 Oliver Bril
90 1 Adrian Georgescu
{{{msrplib}}} is based upon [http://twistedmatrix.com twisted] and [http://devel.ag-projects.com/~denis/eventlet/ eventlet] and provides a set of
91
classes for establishing and managing MSRP connection.
92
93
The library consist of the following modules:
94
95
 '''msrplib.transport'''::
96
 Defines {{{MSRPTransport}}} class, which provides low level control over MSRP connection.
97 2 Redmine Admin
98 1 Adrian Georgescu
 '''msrplib.connect'''::
99
 Defines means to establish a connection, bind it, and provide an initialized {{{MSRPTransport}}} instance.
100
101
 '''msrplib.session'''::
102
 Defines {{{MSRPSession}}} class, which provides high level control over a MSRP connection.
103
104
 '''msrplib.protocol'''::
105
 Provides representation and parsing of MSRP entities - chunks and URIs.
106
107
 '''msrplib.trafficlog'''::
108
 Defines {{{Logger}}} class that is used through out the library to log the connection state.
109
  
110 4 Oliver Bril
=== Usage ===
111 1 Adrian Georgescu
112 4 Oliver Bril
==== Establish a connection ====
113 3 Oliver Bril
114 1 Adrian Georgescu
{{{msrplib.connect}}} provides a number of classes to establish a connection, so the first
115
thing to do is to select which one applies to your situation:
116
117
    1. Calling endpoint, not using a relay ({{{ConnectorDirect}}})
118
    2. Answering endpoint, not using a relay ({{{AcceptorDirect}}})
119
    3. Calling endpoint, using a relay ({{{ConnectorRelay}}})
120
    4. Answering endpoint, using a relay ({{{AcceptorRelay}}})
121
122
The answering endpoint may skip using the relay if sure that it's accessible
123
directly. The calling endpoint is unlikely to need the relay.
124
125
Once you have an instance of the right class (use the convenience functions
126
{{{get_connector()}}} and {{{get_acceptor()}}} to get one), the procedure to establish the
127
connection is the same:
128
129
{{{
130
full_local_path = connector.prepare()
131
try:
132
    ... put full_local_path in SDP 'a:path' attribute
133
    ... get full_remote_path from remote's 'a:path: attribute
134
    ... (the order of the above steps is reversed if you're the
135
    ... answering party, but that does not affect connector's usage)
136
    msrptransport = connector.complete(full_remote_path)
137
finally:
138
    connector.cleanup()
139
}}}
140
141
To customize connection's parameters, create a new {{{protocol.URI}}} object and pass
142
it to prepare() function, e.g.
143
{{{
144
local_uri = protocol.URI(use_tls=False, port=5000)
145
connector.prepare(local_uri)
146
}}}
147
148
{{{prepare()}}} may update {{{local_uri}}} in place with the actual connection parameters
149
used (e.g. if you specified port=0). 'port' attribute of {{{local_uri}}} is currently
150
only respected by {{{AcceptorDirect}}}.
151
152
Note that, acceptors and connectors are one-use only. Which means, that {{{AcceptorDirect}}}
153
will open a port just to handle one incoming connection and close it right after.
154
If your application behaves more like a server, i.e. opens a port and listens on it
155
constantly, use {{{MSRPServer}}} class.
156 3 Oliver Bril
157 4 Oliver Bril
=== Components ===
158 1 Adrian Georgescu
159 4 Oliver Bril
==== a connector or acceptor ====
160 3 Oliver Bril
161 8 Oliver Bril
 {{{msrplib.connect}}} provides 2 connectors (with and without relay) and 2 acceptors (likewise, with or without relay). All of them have the exact same interface,
162
163
 '''prepare'''(''self'', ''local_uri''={{{None}}})::
164
 Depending on type of the connector, use local_uri to prepare the MSRP connection, which means:
165
 * connecting and authenticating at the relay if a relay is used ({{{ConnectorRelay}}} and {{{AcceptorRelay}}})
166
 * start listening on a local port for DirectAcceptor
167
168
 ''local_uri'' is used to specify the connection parameters, e.g. local port and local ip.
169
 If not provided, suitable ''local_uri'' will be generated.
170
 ''local_uri'' maybe updated in place by {{{prepare()}}} method if the real settings used are different from those specified.
171
172
 {{{prepare}}} returns a full local path - list of {{{protocol.URI}}} instances, suitable to be put in SDP {{{'a:path'}}} attribute.
173
 
174
 '''complete'''(''self'', ''full_remote_path'')::
175
 Complete establishing the MSRP connection, which means
176
 * establishing the connection if it wasn't already established ({{{ConnectorDirect}}})
177
 * bind the connection, i.e. exchange empty chunk to verify each other's From-Path and To-Path
178
179
 ''full_remote_path'' should be a list of {{{protocol.URI}}} instances, obtained by parsing {{{'a:path'}}} put in SDP by the remote party.
180
181
 {{{complete}}} returns {{{transport.MSRPTransport}}} instance, ready to read and send chunks.
182 9 Oliver Bril
183
 '''cleanup'''(''self'')::
184
 Call this method to cleanup after {{{initialize()}}} if it's impossible to call {{{complete()}}}
185 8 Oliver Bril
 
186 1 Adrian Georgescu
187 4 Oliver Bril
==== transport.MSRPTransport ====
188 1 Adrian Georgescu
189
Low level access to MSRP connection.
190
191 4 Oliver Bril
===== attributes =====
192 3 Oliver Bril
193 4 Oliver Bril
===== methods =====
194 3 Oliver Bril
195
 '''make_chunk'''(''self'', ''transaction_id''={{{None}}}, ''method''={{{'SEND'}}}, ''code''={{{None}}}, ''comment''={{{None}}}, ''data''={{{''}}}, ''contflag''={{{None}}}, ''start''={{{1}}}, ''end''={{{None}}}, ''length''={{{None}}}, ''message_id''={{{None}}})::
196 1 Adrian Georgescu
 Make a new chunk ({{{protocol.MSRPData}}} instance) with proper {{{From-Path}}}, {{{To-Path}}}, {{{Byte-Range}}} and {{{Message-ID}}} headers set up based on MSRPTransport's state and the parameters provided. Use ''data'' for payload, and ''start''/''end''/''length'' to generate {{{Byte-Range}}} header. Generate new random strings for default values of ''transaction_id'' and ''message_id''. 
197
 [[BR]]''contflag'':[[BR]]
198
 MSRP chunk's continuation flag ({{{'$'}}}, {{{'+'}}} or {{{'#'}}}). Default is {{{'$'}}}, unless you have a partial {{{SEND}}} chunk, in which case it is {{{'+'}}}
199
200 4 Oliver Bril
==== session.MSRPSession ====
201
===== attributes =====
202
===== methods =====
203 1 Adrian Georgescu
204 4 Oliver Bril
==== connect.MSRPServer ====
205 13 Oliver Bril
 Manage listening sockets. Bind incoming requests.
206
    
207
 MSRPServer solves the problem with AcceptorDirect: concurrent using of 2
208
 or more AcceptorDirect instances on the same non-zero port is not possible.
209
 If you initialize() those instances, one after another, one will listen on
210
 the socket and another will get BindError.
211
212
 MSRPServer avoids the problem by sharing the listening socket between multiple connections.
213
 It has a slightly different interface from AcceptorDirect, so it cannot be considered a drop-in
214
 replacement.
215
216
 '''prepare'''(''self'', ''local_uri''={{{None}}}, ''logger''={{{None}}})::
217
 Start a listening port specified by ''local_uri'' if there isn't one on that port/interface already.
218
 Add ''local_uri'' to the list of expected URIs, so that incoming connections featuring this URI won't be rejected.
219
 If ''logger'' is provided use it for this connection instead of the default one.
220
221
 '''complete'''(''self'', ''full_remote_path'')::
222
 Wait until one of the incoming connections binds using provided ''full_remote_path''.
223
 Return connected and bound {{{MSRPTransport}}} instance.
224
        
225
 If no such binding was made within {{{MSRPBindSessionTimeout.seconds}}}, raise {{{MSRPBindSessionTimeout}}}.
226
 ''full_remote_path'' should be a list of {{{protocol.URI}}} instances, obtained by parsing {{{'a:path'}}} put in SDP by the remote party.
227
228
 '''cleanup'''(''self'', ''local_uri'')::
229
 Remove ''local_uri'' from the list of expected URIs.