SipMSRPApi

Version 6 (Oliver Bril, 03/31/2009 12:52 pm)

1 1 Adrian Georgescu
= MSRP API =
2 1 Adrian Georgescu
3 1 Adrian Georgescu
[[TOC(WikiStart, Sip*, depth=3)]]
4 1 Adrian Georgescu
5 1 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 1 Adrian Georgescu
 * MSRP sessions are defined in [http://tools.ietf.org/html/rfc4975 RFC 4975].
8 1 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 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 4 Oliver Bril
 * {{{sipsimple.msrp.MSRPFileTransfer}}}
14 1 Adrian Georgescu
 * {{{sipsimple.msrp.MSRPDesktopSharing}}}
15 1 Adrian Georgescu
16 5 Oliver Bril
Those 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.
17 5 Oliver Bril
Refer to [wiki:SipMiddlewareApi#Session Session documentation] for details on Session API.
18 5 Oliver Bril
19 4 Oliver Bril
== MSRPChat ==
20 1 Adrian Georgescu
21 5 Oliver Bril
{{{sipsimple.msrp.MSRPChat}}} implements Instance Messaging over MSRP in the context of SIPSIMPLE middleware. This class
22 1 Adrian Georgescu
23 5 Oliver Bril
 * automatically wraps outgoing messages with Message/CPIM if that's necessary according to accept-types
24 5 Oliver Bril
 * unwraps incoming Message/CPIM messages
25 5 Oliver Bril
 * plays notification sounds on received/sent message
26 5 Oliver Bril
27 5 Oliver Bril
=== methods ===
28 5 Oliver Bril
29 5 Oliver Bril
 '''!__init!__'''(''self'', ''account'', ''remote_uri'', ''outgoing'')::
30 5 Oliver Bril
 Initialize MSRPChat instance.
31 5 Oliver Bril
32 5 Oliver Bril
 '''initialize'''(''self'')::
33 5 Oliver Bril
 Initialize the MSRP connection; connect to the relay if necessary. When done, fire MSRPChatDidInitialize (with 'sdpmedia' attribute, containing the appropriate 'SDPMedia' instance)
34 5 Oliver Bril
35 5 Oliver Bril
 '''start'''(''self'', ''remote_media'')::
36 5 Oliver Bril
 Complete the MSRP connection establishment; this includes binding the MSRP session. [[BR]]
37 5 Oliver Bril
 When done, fire MSRPChatDidStart. At this point each incoming message is posted as a {{{MSRPChatGotMessage}}} notification
38 5 Oliver Bril
39 5 Oliver Bril
 '''end'''(''self'')::
40 5 Oliver Bril
 Close the MSRP connection or cleanup after initialize(), whatever is necessary. [[BR]]
41 5 Oliver Bril
 Before doing anything post {{{MSRPChatWillEnd}}}.
42 5 Oliver Bril
 When done, post {{{MSRPChatDidEnd}}}. If there was an error, post {{{MSRPChatDidFail}}}.
43 5 Oliver Bril
 {{{MSRPChatDidEnd}}} will be posted anyway.
44 5 Oliver Bril
45 6 Oliver Bril
 '''send_message'''(''self'', ''content'', ''content_type''={{{'text/plain'}}}, ''to_uri''={{{None}}}, ''dt''={{{None}}})::
46 6 Oliver Bril
 Send IM message. Prefer Message/CPIM wrapper if it is supported. If called before the connection was established, the messages will be
47 6 Oliver Bril
 queued until MSRPChatDidStart notification.
48 6 Oliver Bril
49 6 Oliver Bril
 Return generated MSRP chunk (MSRPData instance); to get Message-ID use its 'message_id' attribute.
50 6 Oliver Bril
51 6 Oliver Bril
 ''content'' str:[[BR]]
52 6 Oliver Bril
 content of the message
53 6 Oliver Bril
54 6 Oliver Bril
 ''to_uri'' SIPURI:[[BR]]
55 6 Oliver Bril
 "To" header of CPIM wrapper; use to override the default supplied to {{{__init__}}}.
56 6 Oliver Bril
 May only differ from the one supplied in __init__ if the remote party supports private messages. If it does not, {{{MSRPChatError}}} will be raised;
57 6 Oliver Bril
58 6 Oliver Bril
 ''content_type'' str:[[BR]]
59 6 Oliver Bril
 Content-Type of wrapped message if Message/CPIM is used (Content-Type of MSRP message is always Message/CPIM in that case);
60 6 Oliver Bril
 otherwise, Content-Type of MSRP message.
61 6 Oliver Bril
62 6 Oliver Bril
 These MSRP headers are used to enable end-to-end success reports and to disable hop-to-hop successful responses:
63 6 Oliver Bril
{{{
64 6 Oliver Bril
Failure-Report: partial
65 6 Oliver Bril
Success-Report: yes
66 6 Oliver Bril
}}}
67 6 Oliver Bril
68 5 Oliver Bril
69 5 Oliver Bril
=== notifications ===
70 5 Oliver Bril
71 5 Oliver Bril
 '''MSRPChatGotMessage''':
72 5 Oliver Bril
 Posted for each incoming message with the following attributes:
73 5 Oliver Bril
 - cpim_headers (dict); if cpim wrapper was not used, empty dict
74 5 Oliver Bril
 - message (MSRPData)
75 5 Oliver Bril
 - content (str) - the actual string that the remote user has typed
76 5 Oliver Bril
77 4 Oliver Bril
== MSRPFileTransfer ==
78 4 Oliver Bril
79 4 Oliver Bril
== MSRPDesktopSharing ==
80 4 Oliver Bril
81 4 Oliver Bril
== msrplib ==
82 4 Oliver Bril
83 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
84 1 Adrian Georgescu
classes for establishing and managing MSRP connection.
85 1 Adrian Georgescu
86 1 Adrian Georgescu
The library consist of the following modules:
87 1 Adrian Georgescu
88 1 Adrian Georgescu
 '''msrplib.transport'''::
89 1 Adrian Georgescu
 Defines {{{MSRPTransport}}} class, which provides low level control over MSRP connection.
90 2 Redmine Admin
91 1 Adrian Georgescu
 '''msrplib.connect'''::
92 1 Adrian Georgescu
 Defines means to establish a connection, bind it, and provide an initialized {{{MSRPTransport}}} instance.
93 1 Adrian Georgescu
94 1 Adrian Georgescu
 '''msrplib.session'''::
95 1 Adrian Georgescu
 Defines {{{MSRPSession}}} class, which provides high level control over a MSRP connection.
96 1 Adrian Georgescu
97 1 Adrian Georgescu
 '''msrplib.protocol'''::
98 1 Adrian Georgescu
 Provides representation and parsing of MSRP entities - chunks and URIs.
99 1 Adrian Georgescu
100 1 Adrian Georgescu
 '''msrplib.trafficlog'''::
101 1 Adrian Georgescu
 Defines {{{Logger}}} class that is used through out the library to log the connection state.
102 1 Adrian Georgescu
  
103 4 Oliver Bril
=== Usage ===
104 1 Adrian Georgescu
105 4 Oliver Bril
==== Establish a connection ====
106 3 Oliver Bril
107 1 Adrian Georgescu
{{{msrplib.connect}}} provides a number of classes to establish a connection, so the first
108 1 Adrian Georgescu
thing to do is to select which one applies to your situation:
109 1 Adrian Georgescu
110 1 Adrian Georgescu
    1. Calling endpoint, not using a relay ({{{ConnectorDirect}}})
111 1 Adrian Georgescu
    2. Answering endpoint, not using a relay ({{{AcceptorDirect}}})
112 1 Adrian Georgescu
    3. Calling endpoint, using a relay ({{{ConnectorRelay}}})
113 1 Adrian Georgescu
    4. Answering endpoint, using a relay ({{{AcceptorRelay}}})
114 1 Adrian Georgescu
115 1 Adrian Georgescu
The answering endpoint may skip using the relay if sure that it's accessible
116 1 Adrian Georgescu
directly. The calling endpoint is unlikely to need the relay.
117 1 Adrian Georgescu
118 1 Adrian Georgescu
Once you have an instance of the right class (use the convenience functions
119 1 Adrian Georgescu
{{{get_connector()}}} and {{{get_acceptor()}}} to get one), the procedure to establish the
120 1 Adrian Georgescu
connection is the same:
121 1 Adrian Georgescu
122 1 Adrian Georgescu
{{{
123 1 Adrian Georgescu
full_local_path = connector.prepare()
124 1 Adrian Georgescu
try:
125 1 Adrian Georgescu
    ... put full_local_path in SDP 'a:path' attribute
126 1 Adrian Georgescu
    ... get full_remote_path from remote's 'a:path: attribute
127 1 Adrian Georgescu
    ... (the order of the above steps is reversed if you're the
128 1 Adrian Georgescu
    ... answering party, but that does not affect connector's usage)
129 1 Adrian Georgescu
    msrptransport = connector.complete(full_remote_path)
130 1 Adrian Georgescu
finally:
131 1 Adrian Georgescu
    connector.cleanup()
132 1 Adrian Georgescu
}}}
133 1 Adrian Georgescu
134 1 Adrian Georgescu
To customize connection's parameters, create a new {{{protocol.URI}}} object and pass
135 1 Adrian Georgescu
it to prepare() function, e.g.
136 1 Adrian Georgescu
{{{
137 1 Adrian Georgescu
local_uri = protocol.URI(use_tls=False, port=5000)
138 1 Adrian Georgescu
connector.prepare(local_uri)
139 1 Adrian Georgescu
}}}
140 1 Adrian Georgescu
141 1 Adrian Georgescu
{{{prepare()}}} may update {{{local_uri}}} in place with the actual connection parameters
142 1 Adrian Georgescu
used (e.g. if you specified port=0). 'port' attribute of {{{local_uri}}} is currently
143 1 Adrian Georgescu
only respected by {{{AcceptorDirect}}}.
144 1 Adrian Georgescu
145 1 Adrian Georgescu
Note that, acceptors and connectors are one-use only. Which means, that {{{AcceptorDirect}}}
146 1 Adrian Georgescu
will open a port just to handle one incoming connection and close it right after.
147 1 Adrian Georgescu
If your application behaves more like a server, i.e. opens a port and listens on it
148 1 Adrian Georgescu
constantly, use {{{MSRPServer}}} class.
149 3 Oliver Bril
150 4 Oliver Bril
=== Components ===
151 1 Adrian Georgescu
152 4 Oliver Bril
==== a connector or acceptor ====
153 3 Oliver Bril
154 4 Oliver Bril
===== attributes =====
155 4 Oliver Bril
===== methods =====
156 1 Adrian Georgescu
157 4 Oliver Bril
==== transport.MSRPTransport ====
158 1 Adrian Georgescu
159 1 Adrian Georgescu
Low level access to MSRP connection.
160 1 Adrian Georgescu
161 4 Oliver Bril
===== attributes =====
162 3 Oliver Bril
163 4 Oliver Bril
===== methods =====
164 3 Oliver Bril
165 3 Oliver Bril
 '''make_chunk'''(''self'', ''transaction_id''={{{None}}}, ''method''={{{'SEND'}}}, ''code''={{{None}}}, ''comment''={{{None}}}, ''data''={{{''}}}, ''contflag''={{{None}}}, ''start''={{{1}}}, ''end''={{{None}}}, ''length''={{{None}}}, ''message_id''={{{None}}})::
166 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''. 
167 1 Adrian Georgescu
 [[BR]]''contflag'':[[BR]]
168 1 Adrian Georgescu
 MSRP chunk's continuation flag ({{{'$'}}}, {{{'+'}}} or {{{'#'}}}). Default is {{{'$'}}}, unless you have a partial {{{SEND}}} chunk, in which case it is {{{'+'}}}
169 1 Adrian Georgescu
170 4 Oliver Bril
==== session.MSRPSession ====
171 4 Oliver Bril
===== attributes =====
172 4 Oliver Bril
===== methods =====
173 1 Adrian Georgescu
174 4 Oliver Bril
==== connect.MSRPServer ====
175 4 Oliver Bril
===== attributes =====
176 4 Oliver Bril
===== methods =====