History

« Previous - Version 64/65 (diff) - Next » - Current version
Anonymous, 06/28/2011 02:28 pm

MSRP API¶

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 can be used for any application that requires a reliable stream of data, for example File Transfer or Desktop Sharing.

MSRP sessions are defined in RFC 4975
MSRP relay extension for NAT traversal is defined in RFC 4976

The MSRP protocol stack is implemented by python-msrplib package.

msrplib is based upon twisted and eventlet and provides a set of classes for establishing and managing MSRP connections.

The library consists of the following modules:

msrplib.transport
Defines MSRPTransport class, which provides low level control over MSRP connections.

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 MSRP URIs.

URI¶

This class is implemented in the msrplib.protocol module and is used to represent an MSRP URI.

methods¶

__init__(self, host=None, use_tls=False, user=None, port=None, session_id=None, parameters=None, credentials=None)

Constructs a new URI. All the arguments specified here are also attributes on the object. For more information on these attributes, see RFC4975.

host:

The hostname or IP address which forms the URI.

use_tls:

Whether this identifies an msrps or msrp URI.

user:

The user part of the URI.

port:

The port in the URI.

session_id:

The session identifier part of the URI.

parameters:

A dict containing the parameters which will be appended to the URI.

credentials:

A gnutls.interfaces.twisted.X509Credentials object which will be used if this identifies a TLS URI to authenticate to the other endpoint.

MSRPRelaySettings¶

This class is implemented in the msrplib.connect module and is used to specify the MSRP relay which will be used when connecting via a relay (using the ConnectorRelay or AcceptorRelay classes).

methods¶

__init__(self, domain, username, password, host=None, use_tls=False, port=None, credentials=None)

Constructs a new URI. All the arguments specified here are also attributes on the object. For more information on these attributes, see RFC4975.

domain:

The DNS domain in which to search for a MSRP relay using SRV queries.

username:

The username which will be used to authenticate to the relay.

password:

The password which will be used to authenticate to the relay.

host:

The hostname or IP address of the MSRP relay.

use_tls:

Whether this identifies an msrps or msrp URI.

port:

The port in the URI.

credentials:

A gnutls.interfaces.twisted.X509Credentials object which will be used to authenticate to the relay if TLS is used.

ConnectorDirect¶

This class is implemented in the msrplib.connect module and is used for outbound MSRP connections without a relay.

methods¶

__init__(self, loger=None, use_sessmatch=False)
Constructs a new ConnectorDirect.

logger:

The logger which will be used for this MSRP connection. See the Logging section for more information.

use_sessmatch:

Indicates if the connector should use the session matching mechanism defined by the sessmatch draft version 10

prepare(self, local_uri=None)
This method returns a full local path - list of protocol.URI instances, suitable to be put in SDP 'a:path' attribute.

local_uri:

This attribute will be used to construct the local path, but other than that it is not used anywhere else in case of the ConnectorDirect. If not provided, one
will be automatically generated

complete(self, full_remote_path)
This method establishes the connection and binds it (sends an empty chunk to verify each other's From-Path and To-Path). It returns transport.MSRPTransport instance, ready to read and send chunks.

full_remote_path:

A list of protocol.URI instances, obtained by parsing 'a:path' put in SDP by the remote party.

cleanup(self)
This method cleans up after prepare(); it should be called if complete() will not be called for whatever reason.

AcceptorDirect¶

This class is implemented in the msrplib.connect module and is used for inbound MSRP connections without using a relay.

methods¶

__init__(self, loger=None, use_sessmatch=False)

Constructs a new AcceptorDirect.

logger:

The logger which will be used for this MSRP connection. See the Logging section for more information.

use_sessmatch:

Indicates if the connector should use the session matching mechanism defined by the sessmatch draft version 10

prepare(self, local_uri=None)
This method starts listening on a socket identified by the parameters in the local_uri argument. It returns a full local path - list of protocol.URI instances, suitable to be put in SDP 'a:path' attribute.

local_uri:

This attribute will be used to construct the local path and to listen for incomming connections. If not provided, one
will be automatically generated. Note that the object may be changed in place: for example, if the port specified is 0,
a random one will be selected and the object will be updated accordingly.

complete(self, full_remote_path)
This method waits for an incoming connection and a chunk sent by the other party. It returns transport.MSRPTransport instance, ready to read and send chunks.

full_remote_path:

A list of protocol.URI instances, obtained by parsing 'a:path' put in SDP by the remote party. This is checked agains the From-Path header in the binding chunk.

cleanup(self)
This method cleans up after prepare(); it should be called if complete() will not be called for whatever reason.

RelayConnection¶

This class is implemented in the msrplib.connect module and is used for inbound and outbound MSRP connections using a relay.

methods¶

__init__(self, relay, mode, loger=None, use_sessmatch=False)
Constructs a new RelayConnection.

relay:

An instance of MSRPRelaySettings which identifies the relay which is to be used.

mode:

A string indicating if this connection should be active, an empty SEND should be sent when complete is called, or passive, where it will wait for one.

logger:

The logger which will be used for this MSRP connection. See the Logging section for more information.

use_sessmatch:

Indicates if the connector should use the session matching mechanism defined by the sessmatch draft version 10

prepare(self, local_uri=None)
This method returns a full local path - list of protocol.URI instances, suitable to be put in SDP 'a:path' attribute.

local_uri:

This attribute will be used to construct the local path, but other than that it is not used anywhere else in case of the ConnectorRelay. If not provided, one
will be automatically generated

complete(self, full_remote_path)
This method establishes the connection to the relay and binds it (sends an empty chunk or waits for one, depending on the mode, to verify each other's From-Path and To-Path). It returns transport.MSRPTransport instance, ready to read and send chunks.

full_remote_path:

A list of protocol.URI instances, obtained by parsing 'a:path' put in SDP by the remote party.

cleanup(self)
This method cleans up after prepare(); it should be called if complete() will not be called for whatever reason.

MSRPTransport¶

This class is implemented in the msrplib.transport module and provies low level access to the MSRP connection. This class should not be constructed directly, but rather its intances should be obtained by using the various connector/acceptor classes documented above.

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)
Creates a new chunk (protocol.MSRPData instance), which is either an MSRP request or a response. Proper From-Path, To-Path, Byte-Range and Message-ID headers are added based on MSRPTransport's state and the parameters provided. Use data for payload, and start/_end_/_length_ to generate the Byte-Range header.

transaction_id:

The transaction id which will be put in the chunk. If it is not provided, one will be randomly generated.

method:

The method of the new MSRP request, or None if a response is required.

code:

The code of the new MSRP response, or None if a request is required.

code:

The comment of the new MSRP response, or None if a request is required or a comment on the response is not.

data:

The payload of the new chunk, or an empty string if no payload is required.

contflag:

MSRP chunk's continuation flag ('$', '+' or '#'). Default is '$' for a full message, unless a partial SEND chunk required, in which case it should be set to '+'. If None is provided, either '$' or '+' will be used depending on whether this chunk seems to carry the last part of the message data.

start:

The first byte's index within the whole message payload this chunk will carry as its own payload.

end:

The last byte's index within the whole message payload this chunk will carry as its own payload. Note that this is an inclusive index. If this is not provided, it's computed based on the number of bytes in data and start.

length:

The total number of bytes of the whole message payload. If this is not provided, it is computed as if this chunk carries that last part of the message payload.

message_id:

The ID of the message this chunk is part of. If it is not provided, one will be randomly generated.

write_chunk(self, chunk, wait=True)
Writes the chunk provided to the underlying socket.

chunk:

The chunk which is to be written, an instance of MSRPData.

wait:

If True, waits for the operation to complete.

write_response(self, chunk, code, comment, wait=True):
Creates a response which is suitable as a reply to the specified chunk and writes it to the underlying socket.

chunk:

The chunk for which to create a response.

code:

The status code of the response which is to be created.

comment:

The comment of the response which is to be created.

wait:

If True, waits for the operation to complete.

read_chunk(self, size=None)
Waits for a new chunk and returns it.
If there was an error, closes the connection and raises ChunkParseError.

In case of unintelligible input, loses the connection and returns None.
When the connection is closed, raises the reason of the closure (e.g. ConnectionDone).

If the data already read exceeds size, stops reading the data and returns
a "virtual" chunk, i.e. the one that does not actually correspond the the real
MSRP chunk. Such chunks have Byte-Range header changed to match the number of
bytes read and continuation that is '+'; they also possess segment attribute,
an integer, starting with 1 and increasing with every new segment of the chunk.

Note, that size only hints when to interrupt the segment but does not affect
how the data is read from socket. You may have segments bigger than size and it's
legal to set size to zero (which would mean return a chunk as long as you get
some data, regardless how small).

size:

The hint towards how much to read from the socket. If the data already read is larger, then all the data will be returned, even if it exceeds size bytes.

check_incoming_SEND_chunk(self, chunk)
Checks the 'To-Path' and 'From-Path' of the incoming SEND chunk.
Returns None is the paths are valid for this connection.
If an error is detected an MSRPError is created and returned.

MSRPData¶

This class is implemented in the msrplib.protocol module and represents an MSRP chunk, either a request or a response.

attributes¶

The following attributes are read-only.

content_type

The MIME type of the payload carried by this chunk, which is stored in the Content-Type header.

message_id

The ID of the message this chunk is part of, which is stored in the Message-ID header.

byte_range

A 3-tuple containing the start, end and length values (in this order) from the Byte-Range header.

status

The value of the Status header.

failure_report

The value of the Failure-Report header, whether it exists or it is implied; one of 'yes', 'no', 'partial'.

success_report

The value of the Success-Report header, whether it exists or it is implied; one of 'yes' or 'no'.

size

The size of the payload of this chunk, in bytes.

methods¶

__init__(self, transaction_id, method=None, code=None, comment=None, headers=None, data='', contflag='$')

Initializes a new MSRPData instance. All the arguments are also available as attributes.

transaction_id:

The transaction identified of this chunk.

method:

The method of this chunk if it a request and None if it is a response.

code:

The status code of this chunk if it is a response and None if it is a request.

comment:

The comment of this chunk if it is a response and None if it is a request.

headers:

A dict containing the headers which are to be added to this chunk, or None if no headers are to be added.

data:

The payload of this chunk, or an empty string if no payload is to be added.

contflag:

The MSRP continuation flag of this chunk, one of '$', '#' or '+'.

copy(self)

Returns a new MSRPData instance with exactly the same attributes as this object.

add_header(self, header)

Add a MSRP header to this chunk.

header:

The header object which is to be added to this chunk.

verify_headers(self)

Verifies that the chunk contains a To-Path and a From-Path header and that all the headers are valid.

encode_start(self)

Returns a string containing the MSRP header of this chunk.

encode_end(self, continuation)

Returns a string containing the MSRP end line of this chunk: 7 commas followed by the transaction identifier and the continuation flag specified.

continuation:

The continuation flag which is to be used in the end line.

encode(self):

Returns a string containing the whole of this MSRP chunk.

OutgoingFile¶

This class is implemented in the msrplib.session module and represents a file which is to be sent via MSRP.

attributes¶

headers

A dict which maps header names to header objects. These headers will be sent in the MSRP message used to send the file.

methods¶

__init__(self, fileobj, size, content_type=None, position=0, message_id=None)

Initializes a new OutgoingFile using the specified file object. All arguments are available as attributes, except for content_type which will be part of the headers attribute.

fileobj:

A file-like object which will be used for reading the data to be sent.

size:

The size of the whole file.

content_type:

The MIME type associated with the file's data. If provided, it will be added as a Content-Type header.

position:

The position within the file from which data will be sent. The file object must already be seeked to this position.

message_id:

The message ID which will be used for sending this file.

MSRPSession¶

This class is implemented in the msrplib.session module and provides a high level API for MSRP sessions.

methods¶

__init__(self, msrptransport, accept_types=['*'], on_incoming_cb=None)
Initializes MSRPSession instance over the specified transport. The incoming chunks are reported through the on_incoming_cb callback.

msrptransport:

An instance of MSRPTransport over which this session will operate.

accept_types:

A list of MIME types which are acceptable over this session. If data is received with a Content-Type header which doesn't match this list, a negative response is sent back and the application does not get the received data. The special strings '*' and '<type>/*' can be used to match multiple MIME types.

on_incoming_cb:

A function which receives two arguments, both optional with default values of None: chunk and error. This will be called when a new chunk is received.

send_chunk(self, chunk, response_cb=None)
Sends the specified chunk and reports the result via the response_cb callback.

When response_cb argument is present, it will be used to report
the transaction response to the caller. When a response is received or generated
locally, response_cb is called with one argument. The function must do something
quickly and must not block, because otherwise it would block the reader greenlet.

If no response was received after RESPONSE_TIMEOUT seconds,

408 response is generated if Failure-Report was 'yes' or absent
200 response is generated if Failure-Report was 'partial' or 'no'
Note that it's rather wasteful to provide response_cb argument other than None
for chunks with Failure-Report='no' since it will always fire 30 seconds later
with 200 result (unless the other party is broken and ignores Failure-Report header)

If sending is not possible, MSRPSessionError is raised.

chunk:

The chunk which is to be sent. It must be an instance of MSRPData which represents a request.

response_cb:

A function receiving a single argument which will be the response received for the sent chunk.

deliver_chunk(self, chunk, event=None)
Sends the specified chunk and waits for the transaction response (if Failure-Report header is not 'no').
Returns the transaction response if it's a success or raise MSRPTransactionError if it's not.

If chunk's Failure-Report is 'no', returns None immediately.

chunk:

The chunk which is to be sent. It must be an intance of MSRPData which represents a request.

event:

The eventlet.coros.event object which will be used to wait for a response. It's send method will be called when a response is received. If it is not provided, one will be constructed automatically and used.

send_file(self, outgoing_file)
Adds the specified file to the queue of files to be sent. The method returns immediately.

outgoing_file:

An instance of OutgoingFile which represents the file to be sent.

shutdown(self, sync=True)
Sends the messages already in queue then closes the connection.

MSRPServer¶

This class is implemented in the msrplib.connect module.

MSRPServer solves the problem with AcceptorDirect: concurrent using of 2
or more AcceptorDirect instances on the same non-zero port is not possible.
If you initialize() those instances, one after another, one will listen on
the socket and another will get BindError.

MSRPServer avoids the problem by sharing the listening socket between multiple connections.
It has a slightly different interface from AcceptorDirect, so it cannot be considered a drop-in
replacement.

It manages the listening sockets and binds incoming requests.

methods¶

__init__(self, logger)
Constructs a new MSRPServer which will be using the specifed logger for its connections.

logger:

The default logger which will be used for this object's MSRP connections. See the Logging section for more information.

prepare(self, local_uri=None, logger=None)
Starts a listening port specified by local_uri if there isn't one on that port/interface already.
Adds local_uri to the list of expected URIs, so that incoming connections featuring this URI won't be rejected.
If logger is provided, it uses it for this connection instead of the one specified in __init___.

local_uri:

The URI which will be added to the list of expected URIs. Connections from this URI will be accepted.

logger:

The logger which will be used for connections from the specified URI. See the Logging section for more information.

complete(self, full_remote_path)
Waits until one of the incoming connections binds using the provided full_remote_path.
Returns the connected and bound MSRPTransport instance.
If no such binding was made within MSRPBindSessionTimeout.seconds, MSRPBindSessionTimeout is raised.

full_remote_path:

A list of protocol.URI instances, obtained by parsing 'a:path' put in SDP by the remote party.

cleanup(self, local_uri)
Removes local_uri from the list of expected URIs.

local_uri:

The URI which is to be removed from the list of expected URIs.

Headers¶

The MSRP headers are represented using objects from the msrplib.protocol module. All MSRP header object provide three properties:
name:

The name of the header, as it appears in MSRP chunks.

encode:

The MSRP encoded header value, as it appears in MSRP chunks.

decode:

The high-level object representing the header value.

All headers can be constructed by passing either the encoded or decoded objects to __init__. The following headers are provided:

ToPathHeader¶

The name of the header is 'To-Path' and the decoded value is a deque of URI objects.

FromPathHeader¶

The name of the header is 'From-Path' and the decoded value is a deque of URI objects.

MessageIDHeader¶

The name of the header is 'Message-ID' and the decoded value is the string containing the message ID.

SuccessReportHeader¶

The name of the header is 'Success-Report' and the decoded value is one of 'yes' or 'no'.

FailureReportHeader¶

The name of the header is 'Failure-Report' and the decoded value is one of 'yes', 'partial' or 'no'.

ByteRangeHeader¶

The name of the header is 'Byte-Range' and the decoded value is a 3-tuple containing the start, end and length values.

attributes¶

fro

The start value of the header: the index within the whole message payload where a chunk's payload starts.

end

The end value of the header: the index within the whole message payload where a chunk's payload ends. Note that this index is inclusive.

length

The total size of the message payload.

StatusHeader¶

The name of the header is 'Status' and the decoded value is a 2-tuple containing the status code and comment.

attributes¶

code

The code component of the header.

comment

The comment component of the header.

ExpiresHeader¶

The name of the header is 'Expires' and the decoded value is an integer.

MinExpiresHeader¶

The name of the header is 'Min-Expires' and the decoded value is an integer.

MaxExpiresHeader¶

The name of the header is 'Max-Expires' and the decoded value is an integer.

UsePathHeader¶

The name of the header is 'Use-Path' and the decoded value is a deque of URI objects.

WWWAuthenticateHeader¶

The name of the header is 'WWW-Authenticate' and the decoded value is a dictionary of the parameters within the header.

AuthorizationHeader¶

The name of the header is 'Authorization' and the decoded value is a dictionary of the parameters within the header.

AuthenticationInfoHeader¶

The name of the header is 'Authentication-Info' and the decoded value is a dictionary of the parameters within the header.

ContentTypeHeader¶

The name of the header is 'Content-Type' and the decoded value is the string representing the MIME type.

ContentIDHeader¶

The name of the header is 'Content-ID' and the decoded value is the string with the value of the header.

ContentDescriptionHeader¶

The name of the header is 'Content-Description' and the decoded value is the string with the value of the header.

ContentDispositionHeader¶

The name of the header is 'Content-Disposition' and the decoded value is a list with two elements: the disposition and a dict with the parameters.

Logging¶

Logging is done throughout the library using objects defined by the application, called loggers. If logging is not desired, the application.python.Null object of python-application can be used. These loggers must define the following methods:

methods¶

received_new_chunk(data, transport, chunk)

This method is called when the start of a new chunk is received.

data:

The data which came along with the start of the chunk.

transport:

The MSRPTransport instance on which the chunk was received.

chunk:

The actual chunk object.

received_chunk_data(data, transport, transaction_id)

This method is called when data is received as part of a chunk previously announced via received_new_chunk.

data:

The data received as part of the chunk.

transport:

The MSRPTransport instance on which the chunk was received.

transaction_id:

The transaction ID which identifies the chunk for which data was received.

received_chunk_end(data, transport, transaction_id)

This method is called when the last data of a chunk is received. The chunk was previously announced via received_new_chunk.

data:

The last data received as part of the chunk.

transport:

The MSRPTransport instance on which the chunk was received.

transaction_id:

The transaction ID which identifies the chunk which was ended.

sent_new_chunk(data, transport, chunk)

This method is called when the start of a new chunk is sent.

data:

The data which was sent along with the start of the chunk.

transport:

The MSRPTransport instance on which the chunk was sent.

chunk:

The actual chunk object.

sent_chunk_data(data, transport, transaction_id)

This method is called when data is sent as part of a chunk previously announced via sent_new_chunk.

data:

The data sent as part of the chunk.

transport:

The MSRPTransport instance on which the chunk was sent.

transaction_id:

The transaction ID which identifies the chunk for which data was sent.

sent_chunk_end(data, transport, transaction_id)

This method is called when the last data of a chunk is sent. The chunk was previously announced via sent_new_chunk.

data:

The last data sent as part of the chunk.

transport:

The MSRPTransport instance on which the chunk was sent.

transaction_id:

The transaction ID which identifies the chunk which was ended.

debug(message)

This method is called when a debug level message is sent by the library.

info(message)

This method is called when a info level message is sent by the library.

warn(message)

This method is called when a warning level message is sent by the library.

error(message)

This method is called when a error level message is sent by the library.

fatal(message)

This method is called when a fatal level message is sent by the library.

Examples¶

Creating an outbound connection¶

When creating an outbound connection, a relay is not usually used because NAT traversal is not a problem for the endpoing creating the connection. If one is nevertheless desired, a ConnectorRelay can be used instead:

from msrplib.connect import ConnectorDirect
from msrplib.session import MSRPSession

connector = ConnectorDirect()
full_local_path = connector.prepare()
try:
    # put full_local_path in SDP 'a:path' attribute of offer
    # get full_remote_path from remote's 'a:path: attribute of reply
    msrp_transport = connector.complete(full_remote_path)
except:
    connector.cleanup()
    raise

def handle_incoming(chunk=None, error=None):
    if error is not None:
       print 'Error: %s' % error
       session.shutdown()
    elif chunk is not None:
       print 'Got data: %s' % chunk.data

session = MSRPSession(msrp_transport, on_incoming_cb=handle_incoming)
session.send_chunk(msrp_transport.make_chunk(data='Hello world!'))

Waiting for an inbound connection¶

When creating an inbound connection, a relay must be used for NAT traversal. However, if one is not desired, an AceptorDirect can be used instead:

from msrplib.connect import RelayConnection, MSRPRelaySettings
from msrplib.session import MSRPSession

relay = MSRPRelaySettings(domain='example.org', username='user', password='pass')
connector = RelayConnection(relay, 'passive')
full_local_path = connector.prepare()
try:
    # get full_remote_path from remote's 'a:path: attribute of offer
    # put full_local_path in SDP 'a:path' attribute of reply
    msrp_transport = connector.complete(full_remote_path)
except:
    connector.cleanup()
    raise

def handle_incoming(chunk=None, error=None):
    if error is not None:
       print 'Error: %s' % error
       session.shutdown()
    elif chunk is not None:
       print 'Got data: %s' % chunk.data

session = MSRPSession(msrp_transport, on_incoming_cb=handle_incoming)
session.send_chunk(msrp_transport.make_chunk(data='Hello world!'))

SIP SIMPLE Client SDK

SDK documentation¶

Misc¶

Wiki

MSRP API¶

URI¶

methods¶

MSRPRelaySettings¶

methods¶

ConnectorDirect¶

methods¶

AcceptorDirect¶

methods¶

RelayConnection¶

methods¶

MSRPTransport¶

methods¶

MSRPData¶

attributes¶

methods¶

OutgoingFile¶

attributes¶

methods¶

MSRPSession¶

methods¶

MSRPServer¶

methods¶

Headers¶

ToPathHeader¶

FromPathHeader¶

MessageIDHeader¶

SuccessReportHeader¶

FailureReportHeader¶

ByteRangeHeader¶

attributes¶

StatusHeader¶

attributes¶

ExpiresHeader¶

MinExpiresHeader¶

MaxExpiresHeader¶

UsePathHeader¶

WWWAuthenticateHeader¶

AuthorizationHeader¶

AuthenticationInfoHeader¶

ContentTypeHeader¶

ContentIDHeader¶

ContentDescriptionHeader¶

ContentDispositionHeader¶

Logging¶

methods¶

Examples¶

Creating an outbound connection¶

Waiting for an inbound connection¶