History

« Previous - Version 7/65 (diff) - Next » - Current version
Oliver Bril, 03/31/2009 01:15 pm

= MSRP API =

<acronym title="WikiStart, Sip*, depth=3">TOC</acronym>

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).

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:

  • {{{sipsimple.msrp.MSRPChat}}}
  • {{{sipsimple.msrp.MSRPFileTransfer}}}
  • {{{sipsimple.msrp.MSRPDesktopSharing}}}

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.
Refer to [wiki:SipMiddlewareApi#Session Session documentation] for details on Session API.

MSRPChat

{{{sipsimple.msrp.MSRPChat}}} implements Instance Messaging over MSRP in the context of SIPSIMPLE middleware. This class

  • automatically wraps outgoing messages with Message/CPIM if that's necessary according to accept-types
  • unwraps incoming Message/CPIM messages; for each incoming message, {{{MSRPChatGotMessage}}} is posted.
  • plays notification sounds on received/sent message

=== methods === {{{
Failure-Report: partial
Success-Report: yes
}}}

'''!__init!__'''(''self'', ''account'', ''remote_uri'', ''outgoing'')::
 Initialize MSRPChat instance.
'''initialize'''(''self'')::
 Initialize the MSRP connection; connect to the relay if necessary. When done, fire MSRPChatDidInitialize (with 'sdpmedia' attribute, containing the appropriate 'SDPMedia' instance)
'''start'''(''self'', ''remote_media'')::
 Complete the MSRP connection establishment; this includes binding the MSRP session. [[BR]]
 When done, fire MSRPChatDidStart. At this point each incoming message is posted as a {{{MSRPChatGotMessage}}} notification
'''end'''(''self'')::
 Close the MSRP connection or cleanup after initialize(), whatever is necessary. [[BR]]
 Before doing anything post {{{MSRPChatWillEnd}}}.
 When done, post {{{MSRPChatDidEnd}}}. If there was an error, post {{{MSRPChatDidFail}}}. 
{{{MSRPChatDidEnd}}} will be posted anyway.
'''send_message'''(''self'', ''content'', ''content_type''={{{'text/plain'}}}, ''to_uri''={{{None}}}, ''dt''={{{None}}})::
 Send IM message. Prefer Message/CPIM wrapper if it is supported. If called before the connection was established, the messages will be
 queued until MSRPChatDidStart notification.
Return generated MSRP chunk (MSRPData instance); to get Message-ID use its 'message_id' attribute.
''content'' str:[[BR]]
 content of the message
''to_uri'' SIPURI:[[BR]]
 "To" header of CPIM wrapper; use to override the default supplied to {{{__init__}}}.
 May only differ from the one supplied in init if the remote party supports private messages. If it does not, {{{MSRPChatError}}} will be raised;
''content_type'' str:[[BR]]
 Content-Type of wrapped message if Message/CPIM is used (Content-Type of MSRP message is always Message/CPIM in that case);
 otherwise, Content-Type of MSRP message.
These MSRP headers are used to enable end-to-end success reports and to disable hop-to-hop successful responses:

=== notifications ===

  • MSRPChatDidInitialize
  • MSRPChatDidStart
  • MSRPChatWillEnd
  • MSRPChatDidEnd
  • MSRPChatDidFail
  • MSRPChatGotMessage
    - cpim_headers (dict)
    - message (MSRPData)
    - content (str) - the actual string that the remote user has typed
  • MSRPChatDidDeliverMessage
  • MSRPChatDidNotDeliverMessage
MSRPFileTransfer MSRPDesktopSharing msrplib

{{{msrplib}}} is based upon [http://twistedmatrix.com twisted] and [http://devel.ag-projects.com/~denis/eventlet/ eventlet] and provides a set of
classes for establishing and managing MSRP connection.

The library consist of the following modules:

'''msrplib.transport'''::
 Defines {{{MSRPTransport}}} class, which provides low level control over MSRP connection.
'''msrplib.connect'''::
 Defines means to establish a connection, bind it, and provide an initialized {{{MSRPTransport}}} instance.
'''msrplib.session'''::
 Defines {{{MSRPSession}}} class, which provides high level control over a MSRP connection.
'''msrplib.protocol'''::
 Provides representation and parsing of MSRP entities - chunks and URIs.
'''msrplib.trafficlog'''::
 Defines {{{Logger}}} class that is used through out the library to log the connection state.

=== Usage ===

==== Establish a connection ====

{{{msrplib.connect}}} provides a number of classes to establish a connection, so the first
thing to do is to select which one applies to your situation:

1. Calling endpoint, not using a relay ({{{ConnectorDirect}}})
    2. Answering endpoint, not using a relay ({{{AcceptorDirect}}})
    3. Calling endpoint, using a relay ({{{ConnectorRelay}}})
    4. Answering endpoint, using a relay ({{{AcceptorRelay}}})

The answering endpoint may skip using the relay if sure that it's accessible
directly. The calling endpoint is unlikely to need the relay.

Once you have an instance of the right class (use the convenience functions {{{get_connector()}}} and {{{get_acceptor()}}} to get one), the procedure to establish the
connection is the same:

{{{
full_local_path = connector.prepare()
try:
... put full_local_path in SDP 'a:path' attribute
... get full_remote_path from remote's 'a:path: attribute
... (the order of the above steps is reversed if you're the
... answering party, but that does not affect connector's usage)
msrptransport = connector.complete(full_remote_path)
finally:
connector.cleanup()
}}}

To customize connection's parameters, create a new {{{protocol.URI}}} object and pass
it to prepare() function, e.g. {{{
local_uri = protocol.URI
connector.prepare(local_uri)
}}}

{{{prepare()}}} may update {{{local_uri}}} in place with the actual connection parameters
used (e.g. if you specified port=0). 'port' attribute of {{{local_uri}}} is currently
only respected by {{{AcceptorDirect}}}.

Note that, acceptors and connectors are one-use only. Which means, that {{{AcceptorDirect}}}
will open a port just to handle one incoming connection and close it right after.
If your application behaves more like a server, i.e. opens a port and listens on it
constantly, use {{{MSRPServer}}} class.

=== Components ===

==== a connector or acceptor ====

===== attributes ===== ===== methods =====

==== transport.MSRPTransport ====

Low level access to MSRP connection.

===== attributes =====

===== methods =====

'''make_chunk'''(''self'', ''transaction_id''={{{None}}}, ''method''={{{'SEND'}}}, ''code''={{{None}}}, ''comment''={{{None}}}, ''data''={{{''}}}, ''contflag''={{{None}}}, ''start''={{{1}}}, ''end''={{{None}}}, ''length''={{{None}}}, ''message_id''={{{None}}})::
 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''. 
 [[BR]]''contflag'':[[BR]]
 MSRP chunk's continuation flag ({{{'$'}}}, {{{'+'}}} or {{{'#'}}}). Default is {{{'$'}}}, unless you have a partial {{{SEND}}} chunk, in which case it is {{{'+'}}}

==== session.MSRPSession ==== ===== attributes ===== ===== methods =====

==== connect.MSRPServer ==== ===== attributes ===== ===== methods =====