SIP SIMPLE Client SDK

= MSRP API =

[[TOC(WikiStart, Sip*, depth=3)]]

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 sessions are defined in [http://tools.ietf.org/html/rfc4975 RFC 4975].

 * 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].

The MSRP protocol is implemented by [http://devel.ag-projects.com/cgi-bin/darcsweb.cgi?r=python-msrplib;a=summary msrplib] Python package.

== Architecture ==

{{{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(use_tls=False, port=5000)

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 ====