SipMSRPApi » History » Version 11
Adrian Georgescu, 03/31/2009 02:29 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 | 4 | Oliver Bril | == MSRPChat == |
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 | |||
86 | == msrplib == |
||
87 | |||
88 | 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 |
89 | classes for establishing and managing MSRP connection. |
||
90 | |||
91 | The library consist of the following modules: |
||
92 | |||
93 | '''msrplib.transport''':: |
||
94 | Defines {{{MSRPTransport}}} class, which provides low level control over MSRP connection. |
||
95 | 2 | Redmine Admin | |
96 | 1 | Adrian Georgescu | '''msrplib.connect''':: |
97 | Defines means to establish a connection, bind it, and provide an initialized {{{MSRPTransport}}} instance. |
||
98 | |||
99 | '''msrplib.session''':: |
||
100 | Defines {{{MSRPSession}}} class, which provides high level control over a MSRP connection. |
||
101 | |||
102 | '''msrplib.protocol''':: |
||
103 | Provides representation and parsing of MSRP entities - chunks and URIs. |
||
104 | |||
105 | '''msrplib.trafficlog''':: |
||
106 | Defines {{{Logger}}} class that is used through out the library to log the connection state. |
||
107 | |||
108 | 4 | Oliver Bril | === Usage === |
109 | 1 | Adrian Georgescu | |
110 | 4 | Oliver Bril | ==== Establish a connection ==== |
111 | 3 | Oliver Bril | |
112 | 1 | Adrian Georgescu | {{{msrplib.connect}}} provides a number of classes to establish a connection, so the first |
113 | thing to do is to select which one applies to your situation: |
||
114 | |||
115 | 1. Calling endpoint, not using a relay ({{{ConnectorDirect}}}) |
||
116 | 2. Answering endpoint, not using a relay ({{{AcceptorDirect}}}) |
||
117 | 3. Calling endpoint, using a relay ({{{ConnectorRelay}}}) |
||
118 | 4. Answering endpoint, using a relay ({{{AcceptorRelay}}}) |
||
119 | |||
120 | The answering endpoint may skip using the relay if sure that it's accessible |
||
121 | directly. The calling endpoint is unlikely to need the relay. |
||
122 | |||
123 | Once you have an instance of the right class (use the convenience functions |
||
124 | {{{get_connector()}}} and {{{get_acceptor()}}} to get one), the procedure to establish the |
||
125 | connection is the same: |
||
126 | |||
127 | {{{ |
||
128 | full_local_path = connector.prepare() |
||
129 | try: |
||
130 | ... put full_local_path in SDP 'a:path' attribute |
||
131 | ... get full_remote_path from remote's 'a:path: attribute |
||
132 | ... (the order of the above steps is reversed if you're the |
||
133 | ... answering party, but that does not affect connector's usage) |
||
134 | msrptransport = connector.complete(full_remote_path) |
||
135 | finally: |
||
136 | connector.cleanup() |
||
137 | }}} |
||
138 | |||
139 | To customize connection's parameters, create a new {{{protocol.URI}}} object and pass |
||
140 | it to prepare() function, e.g. |
||
141 | {{{ |
||
142 | local_uri = protocol.URI(use_tls=False, port=5000) |
||
143 | connector.prepare(local_uri) |
||
144 | }}} |
||
145 | |||
146 | {{{prepare()}}} may update {{{local_uri}}} in place with the actual connection parameters |
||
147 | used (e.g. if you specified port=0). 'port' attribute of {{{local_uri}}} is currently |
||
148 | only respected by {{{AcceptorDirect}}}. |
||
149 | |||
150 | Note that, acceptors and connectors are one-use only. Which means, that {{{AcceptorDirect}}} |
||
151 | will open a port just to handle one incoming connection and close it right after. |
||
152 | If your application behaves more like a server, i.e. opens a port and listens on it |
||
153 | constantly, use {{{MSRPServer}}} class. |
||
154 | 3 | Oliver Bril | |
155 | 4 | Oliver Bril | === Components === |
156 | 1 | Adrian Georgescu | |
157 | 4 | Oliver Bril | ==== a connector or acceptor ==== |
158 | 3 | Oliver Bril | |
159 | 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, |
160 | |||
161 | '''prepare'''(''self'', ''local_uri''={{{None}}}):: |
||
162 | Depending on type of the connector, use local_uri to prepare the MSRP connection, which means: |
||
163 | * connecting and authenticating at the relay if a relay is used ({{{ConnectorRelay}}} and {{{AcceptorRelay}}}) |
||
164 | * start listening on a local port for DirectAcceptor |
||
165 | |||
166 | ''local_uri'' is used to specify the connection parameters, e.g. local port and local ip. |
||
167 | If not provided, suitable ''local_uri'' will be generated. |
||
168 | ''local_uri'' maybe updated in place by {{{prepare()}}} method if the real settings used are different from those specified. |
||
169 | |||
170 | {{{prepare}}} returns a full local path - list of {{{protocol.URI}}} instances, suitable to be put in SDP {{{'a:path'}}} attribute. |
||
171 | |||
172 | '''complete'''(''self'', ''full_remote_path''):: |
||
173 | Complete establishing the MSRP connection, which means |
||
174 | * establishing the connection if it wasn't already established ({{{ConnectorDirect}}}) |
||
175 | * bind the connection, i.e. exchange empty chunk to verify each other's From-Path and To-Path |
||
176 | |||
177 | ''full_remote_path'' should be a list of {{{protocol.URI}}} instances, obtained by parsing {{{'a:path'}}} put in SDP by the remote party. |
||
178 | |||
179 | {{{complete}}} returns {{{transport.MSRPTransport}}} instance, ready to read and send chunks. |
||
180 | 9 | Oliver Bril | |
181 | '''cleanup'''(''self''):: |
||
182 | Call this method to cleanup after {{{initialize()}}} if it's impossible to call {{{complete()}}} |
||
183 | 8 | Oliver Bril | |
184 | 1 | Adrian Georgescu | |
185 | 4 | Oliver Bril | ==== transport.MSRPTransport ==== |
186 | 1 | Adrian Georgescu | |
187 | Low level access to MSRP connection. |
||
188 | |||
189 | 4 | Oliver Bril | ===== attributes ===== |
190 | 3 | Oliver Bril | |
191 | 4 | Oliver Bril | ===== methods ===== |
192 | 3 | Oliver Bril | |
193 | '''make_chunk'''(''self'', ''transaction_id''={{{None}}}, ''method''={{{'SEND'}}}, ''code''={{{None}}}, ''comment''={{{None}}}, ''data''={{{''}}}, ''contflag''={{{None}}}, ''start''={{{1}}}, ''end''={{{None}}}, ''length''={{{None}}}, ''message_id''={{{None}}}):: |
||
194 | 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''. |
195 | [[BR]]''contflag'':[[BR]] |
||
196 | MSRP chunk's continuation flag ({{{'$'}}}, {{{'+'}}} or {{{'#'}}}). Default is {{{'$'}}}, unless you have a partial {{{SEND}}} chunk, in which case it is {{{'+'}}} |
||
197 | |||
198 | 4 | Oliver Bril | ==== session.MSRPSession ==== |
199 | ===== attributes ===== |
||
200 | ===== methods ===== |
||
201 | 1 | Adrian Georgescu | |
202 | 4 | Oliver Bril | ==== connect.MSRPServer ==== |
203 | ===== attributes ===== |
||
204 | ===== methods ===== |