Middleware API¶

This chapter describes the Middleware API for SIP SIMPLE client SDK that can be used for developing a user interface (e.g. Graphical User Interface). The Middleware provides a non-blocking API that communicates with the user interface asynchronously by using Notifications. For its configuration, the Middleware uses the Configuration API.

SIPApplication¶

Implemented in [browser:sipsimple/application.py]

Implements a high-level application responsable for starting and stopping various sub-systems required to implement a fully featured SIP User Agent application. The SIPApplication class is a Singleton and can be instantiated from any part of the code, obtaining a reference to the same object. The SIPApplication takes care of initializing the following components:

• the twisted thread
• the configuration system, via the ConfigurationManager
• the core Engine using the settings in the configuration
• the AccountManager, using the accounts in the configuration
• the SessionManager, in order to handle incoming sessions
• two AudioBridges, using the settings in the configuration

The attributes in this class can be set and accessed on both this class and its subclasses, as they are implemented using descriptors which keep single value for each attribute, irrespective of the class from which that attribute is set/accessed. Usually, all attributes should be considered read-only.

methods¶

__init__(self)

Instantiates a new SIPApplication.

start(self, storage)

Starts the SIPApplication which initializes all the components in the correct order. The storage is saved as an attribute which other entities like the Configuration Manager will use to take the appropriate backend. If any error occurs with loading the configuration, the exception raised by the ConfigurationManager is propagated by this method and SIPApplication can be started again. After this, any fatal errors will result in the SIPApplication being stopped and unusable, which means the whole application will need to stop. This method returns as soon as the twisted thread has been started, which means the application must wait for the SIPApplicationDidStart notification in order to know that the application started.

stop(self)

Stop all the components started by the SIPApplication. This method returns immediately, but a SIPApplicationDidEnd notification is sent when all the components have been stopped.

attributes¶

running

True if the SIPApplication is running (it has been started and it has not been told to stop), False otherwise.

storage

Holds an object which implements the ISIPSimpleStorage interface which will be used to provide a storage facility to other middleware components.

local_nat_type

String containing the detected local NAT type.

alert_audio_mixer

The AudioMixer object created on the alert audio device as defined by the configuration (by SIPSimpleSettings.audio.alert_device).

alert_audio_bridge

An AudioBridge where IAudioPort objects can be added to playback sound to the alert device.

alert_audio_device

An AudioDevice which corresponds to the alert device as defined by the configuration. This will always be part of the alert_audio_bridge.

voice_audio_mixer

The AudioMixer object created on the voice audio device as defined by the configuration (by SIPSimpleSettings.audio.input_device and SIPSimpleSettings.audio.output_device).

voice_audio_bridge

An AudioBridge where IAudioPort objects can be added to playback sound to the output device or record sound from the input device.

voice_audio_device

An AudioDevice which corresponds to the voice device as defined by the configuration. This will always be part of the voice_audio_bridge.

notifications¶

SIPApplicationWillStart

This notification is sent just after the configuration has been loaded and the twisted thread started, but before any other components have been initialized.

timestamp:

A datetime.datetime object indicating when the notification was sent.

SIPApplicationDidStart

This notification is sent when all the components have been initialized. Note: it doesn't mean that all components have succeeded, for example, the account might not have registered by this time, but the registration process will have started.

timestamp:

A datetime.datetime object indicating when the notification was sent.

SIPApplicationWillEnd

This notification is sent as soon as the stop() method has been called.

timestamp:

A datetime.datetime object indicating when the notification was sent.

SIPApplicationDidEnd

This notification is sent when all the components have been stopped. All components have been given reasonable time to shutdown gracefully, such as the account unregistering. However, because of factors outside the control of the middleware, such as network problems, some components might not have actually shutdown gracefully; this is needed because otherwise the SIPApplication could hang indefinitely (for example because the system is no longer connected to a network and it cannot be determined when it will be again).

timestamp:

A datetime.datetime object indicating when the notification was sent.

SIPApplicationFailedToStartTLS

This notification is sent when a problem arises with initializing the TLS transport. In this case, the Engine will be started without TLS support and this notification contains the error which identifies the cause for not being able to start the TLS transport.

timestamp:

A datetime.datetime object indicating when the notification was sent.

error:

The exception raised by the Engine which identifies the cause for not being able to start the TLS transport.

Storage API¶

Different middleware components may need to store data, i.e. configuration files or XCAP documents. The Storage API defines a collection of backends which other components will use to store their data.

API Definition¶

The Storage API currently requires the following attributes to be defined as per the ISIPSimpleStorage interface:

configuration_backend

The backend used for storing the configuration.

xcap_storage_factory

Factory used to create XCAP storage backends for each account.

Provided implementations¶

Two storage implementations are provided: FileStorage and MemoryStorage both located in the sipsimple.storage module.

SIP Sessions¶

SIP sessions are supported by the sipsimple.session.Session class and independent stream classes, which need to implement the sipsimple.streams.IMediaStream interface. The Session class takes care of the signalling, while the streams offer the actual media support which is negotiated by the Session. The streams which are implemented in the SIP SIMPLE middleware are provided in modules within the sipsimple.streams package, but they are accessible for import directly from sipsimple.streams. Currently, the middleware implements two types of streams, one for RTP data, with a concrete implementation in the AudioStream class, and one for MSRP sessions, with concrete implementations in the ChatStream, FileTransferStream and DesktopSharingStream classes. However, the application can provide its own stream implementation, provided they respect the IMediaStream interface.

The sipsimple.streams module also provides a mechanism for automatically registering media streams in order for them to be used for incoming sessions. This is explained in more detail in MediaStreamRegistry.

SessionManager¶

Implemented in [browser:sipsimple/session.py]

The sipsimple.session.SessionManager class is a singleton, which acts as the central aggregation point for sessions within the middleware.
Although it is mainly used internally, the application can use it to query information about all active sessions.
The SessionManager is implemented as a singleton, meaning that only one instance of this class exists within the middleware. The SessionManager is started by the SIPApplication and takes care of handling incoming sessions and closing all sessions when SIPApplication is stopped.

attributes¶

sessions

A property providing a copy of the list of all active Sesssion objects within the application, meaning any Session object that exists globally within the application and is not in the NULL or TERMINATED state.

methods¶

__init__(self)

Instantiate a new SessionManager object.

start(self)

Start the SessionManager in order to be able to handle incoming sessions. This method is called automatically when SIPApplication is started. The application should not call this method directly.

stop(self)

End all connected sessions. This method is called automatically when SIPApplication is stopped. The application should not call this method directly.

Session¶

Implemented in [browser:sipsimple/session.py]

A sipsimple.session.Session object represents a complete SIP session between the local and a remote endpoints. Both incoming and outgoing sessions are represented by this class.

A Session instance is a stateful object, meaning that it has a state attribute and that the lifetime of the session traverses different states, from session creation to termination. State changes are triggered by methods called on the object by the application or by received network events. These states and their transitions are represented in the following diagram:

Although these states are crucial to the correct operation of the Session object, an application using this object does not need to keep track of these states, as a set of notifications is also emitted, which provide all the necessary information to the application.

The Session is completely independent of the streams it contains, which need to be implementations of the sipsimple.streams.IMediaStream interface. This interface provides the API by which the Session communicates with the streams. This API should not be used by the application, unless it also provides stream implementations or a SIP INVITE session implementation.

methods¶

__init__(self, account)

Creates a new Session object in the None state.

account:

The local account to be associated with this Session.

connect(self, to_header, routes, streams, is_focus=False, subject=None)

Will set up the Session as outbound and propose the new session to the specified remote party and move the state machine to the outgoing state.
Before contacting the remote party, a SIPSessionNewOutgoing notification will be emitted.
If there is a failure or the remote party rejected the offer, a SIPSessionDidFail notification will be sent.
Any time a ringing indication is received from the remote party, a SIPSessionGotRingIndication notification is sent.
If the remote party accepted the session, a SIPSessionWillStart notification will be sent, followed by a SIPSessionDidStart notification when the session is actually established.
This method may only be called while in the None state.

to_header:

A sipsimple.core.ToHeader object representing the remote identity to initiate the session to.

routes:

An iterable of sipsimple.util.Route objects, specifying the IP, port and transport to the outbound proxy.
These routes will be tried in order, until one of them succeeds.

streams:

A list of stream objects which will be offered to the remote endpoint.

is_focus:

Boolean flag indicating if the isfocus parameter should be added to the Contact header according to RFC 4579.

subject:

Session subject. If not None a Subject header will be added with the specified value.

send_ring_indication(self)

Sends a 180 provisional response in the case of an incoming session.

accept(self, streams)

Calling this methods will accept an incoming session and move the state machine to the accepting state.
When there is a new incoming session, a SIPSessionNewIncoming notification is sent, after which the application can call this method on the sender of the notification.
After this method is called, SIPSessionWillStart followed by SIPSessionDidStart will be emitted, or SIPSessionDidFail on an error.
This method may only be called while in the incoming state.

streams:

A list of streams which needs to be a subset of the proposed streams which indicates which streams are to be accepted. All the other proposed streams will be rejected.

reject(self, code=603, reason=None)

Reject an incoming session and move it to the terminating state, which eventually leads to the terminated state.
Calling this method will cause the Session object to emit a SIPSessionDidFail notification once the session has been rejected.
This method may only be called while in the incoming state.

code:

An integer which represents the SIP status code in the response which is to be sent. Usually, this is either 486 (Busy) or 603 (Decline/Busy Everywhere).

reason:

The string which is to be sent as the SIP status reason in the response, or None if PJSIP's default reason for the specified code is to be sent.

accept_proposal(self, streams)

When the remote party proposes to add some new streams, signaled by the SIPSessionGotProposal notification, the application can use this method to accept the stream(s) being proposed.
After calling this method a SIPSessionGotAcceptProposal notification is sent, unless an error occurs while setting up the new stream, in which case a SIPSessionHadProposalFailure notification is sent and a rejection is sent to the remote party. As with any action which causes the streams in the session to change, a SIPSessionDidRenegotiateStreams notification is also sent.
This method may only be called while in the received_proposal state.

streams:

A list of streams which needs to be a subset of the proposed streams which indicates which streams are to be accepted. All the other proposed streams will be rejected.

reject_proposal(self, code=488, reason=None)

When the remote party proposes new streams that the application does not want to accept, this method can be used to reject the proposal, after which a SIPSessionGotRejectProposal or SIPSessionHadProposalFailure notification is sent.
This method may only be called while in the received_proposal state.

code:

An integer which represents the SIP status code in the response which is to be sent. Usually, this is 488 (Not Acceptable Here).

reason:

The string which is to be sent as the SIP status reason in the response, or None if PJSIP's default reason for the specified code is to be sent.

add_stream(self, stream)

Proposes a new stream to the remote party.
Calling this method will cause a SIPSessionGotProposal notification to be emitted.
After this, the state machine will move into the sending_proposal state until either a SIPSessionGotAcceptProposal, SIPSessionGotRejectProposal or SIPSessionHadProposalFailure notification is sent, informing the application if the remote party accepted the proposal. As with any action which causes the streams in the session to change, a SIPSessionDidRenegotiateStreams notification is also sent.
This method may only be called while in the connected state.

remove_stream(self, stream)

Stop the stream and remove it from the session, informing the remote party of this. Although technically this is also done via an SDP negotiation which may fail, the stream will always get remove (if the remote party refuses the re-INVITE, the result will be that the remote party will have a different view of the active streams than the local party).
This method may only be called while in the connected state.

cancel_proposal(self)

This method cancels a proposal of adding a stream to the session by sending a CANCEL request. A SIPSessionGotRejectProposal notification will be sent with code 487.

hold(self)

Put the streams of the session which support the notion of hold on hold.
This will cause a SIPSessionDidChangeHoldState notification to be sent.
This method may be called in any state and will send the re-INVITE as soon as it is possible.

unhold(self)

Take the streams of the session which support the notion of hold out of hold.
This will cause a SIPSessionDidChangeHoldState notification to be sent.
This method may be called in any state and will send teh re-INVITE as soon as it is possible.

end(self)

This method may be called any time after the Session has started in order to terminate the session by sending a BYE request.
Right before termination a SIPSessionWillEnd notification is sent, after termination SIPSessionDidEnd is sent.

transfer(self, target_uri, replaced_session=None)

Proposes a blind call transfer to a new target URI or assisted transfer to an URI belonging to an already established session.

accept_transfer(self)

Accepts an incoming call transfer request.

reject_transfer(self, code=486, *reason_=None)

Rejects an incoming call transfer request.

attributes¶

state

The state the object is currently in, being one of the states from the diagram above.

account

The sipsimple.account.Account or sipsimple.account.BonjourAccount object that the Session is associated with.
On an outbound session, this is the account the application specified on object instantiation.

direction

A string indicating the direction of the initial negotiation of the session.
This can be either None, "incoming" or "outgoing".

transport

A string representing the transport this Session is using: "udp", "tcp" or "tls".

start_time

The time the session started as a datetime.datetime object, or None if the session was not yet started.

stop_time

The time the session stopped as a datetime.datetime object, or None if the session has not yet terminated.

on_hold

Boolean indicating whether the session was put on hold, either by the local or the remote party.

remote_user_agent

A string indicating the remote user agent, if it provided one.
Initially this will be None, it will be set as soon as this information is received from the remote party (which may be never).

local_identity

The sipsimple.core.FrozenFromHeader or sipsimple.core.FrozenToHeader identifying the local party, if the session is active, None otherwise.

remote_identity

The sipsimple.core.FrozenFromHeader or sipsimple.core.FrozenToHeader identifying the remote party, if the session is active, None otherwise.

streams

A list of the currently active streams in the Session.

proposed_streams

A list of the currently proposed streams in the Session, or None if there is no proposal in progress.

conference

A ConferenceHandler object instance (or Null). It can be later used to add/remove participants from a remote conference.

subject

The session subject as a unicode object.

replaced_session

A Session object instance (or Null). It can be used for assisted call transfer.

transfer_handler

A TransferHandler object instance (or Null). It is used for managing the call transfer process.

transfer_info

A TransferInfo object instance (or Null). It is used for describing the details of a call transfer operation.

notifications¶

SIPSessionNewIncoming

Will be sent when a new incoming Session is received.
The application should listen for this notification to get informed of incoming sessions.

timestamp:

A datetime.datetime object indicating when the notification was sent.

streams:

A list of streams that were proposed by the remote party.

SIPSessionNewOutgoing

Will be sent when the application requests a new outgoing Session.

timestamp:

A datetime.datetime object indicating when the notification was sent.

streams:

A list of streams that were proposed to the remote party.

SIPSessionGotRingIndication

Will be sent when an outgoing Session receives an indication that a remote device is ringing.

timestamp:

A datetime.datetime object indicating when the notification was sent.

SIPSessionGotProvisionalResponse

Will be sent whenever the Session receives a provisional response as a result of sending a (re-)INVITE.

timestamp:

A datetime.datetime object indicating when the notification was sent.

code:

The SIP status code received.

reason:

The SIP status reason received.

SIPSessionWillStart

Will be sent just before a Session completes negotiation.
In terms of SIP, this is sent after the final response to the INVITE, but before the ACK.

timestamp:

A datetime.datetime object indicating when the notification was sent.

SIPSessionDidStart

Will be sent when a Session completes negotiation and all the streams have started.
In terms of SIP this is sent after the ACK was sent or received.

timestamp:

A datetime.datetime object indicating when the notification was sent.

streams:

The list of streams which now form the active streams of the Session.

SIPSessionDidFail

This notification is sent whenever the session fails before it starts.
The failure reason is included in the data attributes.
This notification is never followed by SIPSessionDidEnd.

timestamp:

A datetime.datetime object indicating when the notification was sent.

originator:

A string indicating the originator of the Session. This will either be "local" or "remote".

code:

The SIP error code of the failure.

reason:

A SIP status reason.

failure_reason:

A string which represents the reason for the failure, such as "user_request", "missing ACK", "SIP core error...".

SIPSessionWillEnd

Will be sent just before terminating a Session.

timestamp:

A datetime.datetime object indicating when the notification was sent.

SIPSessionDidEnd

Will be sent always when a Session ends as a result of remote or local session termination.

timestamp:

A datetime.datetime object indicating when the notification was sent.

originator:

A string indicating who originated the termination. This will either be "local" or "remote".

end_reason:

A string representing the termination reason, such as "user_request", "SIP core error...".

SIPSessionDidChangeHoldState

Will be sent when the session got put on hold or removed from hold, either by the local or the remote party.

timestamp:

A datetime.datetime object indicating when the notification was sent.

originator:

A string indicating who originated the hold request, and consequently in which direction the session got put on hold.

on_hold:

True if there is at least one stream which is on hold and False otherwise.

partial:

True if there is at least one stream which is on hold and one stream which supports hold but is not on hold and False otherwise.

SIPSessionGotProposal

Will be sent when either the local or the remote party proposes to add streams to the session.

timestamp:

A datetime.datetime object indicating when the notification was sent.

originator:

The party that initiated the stream proposal, can be either "local" or "remote".

streams:

A list of streams that were proposed.

SIPSessionGotRejectProposal

Will be sent when either the local or the remote party rejects a proposal to have streams added to the session.

timestamp:

A datetime.datetime object indicating when the notification was sent.

originator:

The party that initiated the stream proposal, can be either "local" or "remote".

code:

The code with which the proposal was rejected.

reason:

The reason for rejecting the stream proposal.

streams:

The list of streams which were rejected.

SIPSessionGotAcceptProposal

Will be sent when either the local or the remote party accepts a proposal to have stream( added to the session.

timestamp:

A datetime.datetime object indicating when the notification was sent.

originator:

The party that initiated the stream proposal, can be either "local" or "remote".

streams:

The list of streams which were accepted.

proposed_streams:

The list of streams which were originally proposed.

SIPSessionHadProposalFailure

Will be sent when a re-INVITE fails because of an internal reason (such as a stream not being able to start).

timestamp:

A datetime.datetime object indicating when the notification was sent.

failure_reason:

The error which caused the proposal to fail.

streams:

The streams which were part of this proposal.

SIPSessionDidRenegotiateStreams

Will be sent when a media stream is either activated or deactivated.
An application should listen to this notification in order to know when a media stream can be used.

timestamp:

A datetime.datetime object indicating when the notification was sent.

action:

A string which is either "add" or "remove" which specifies what happened to the streams the notificaton referes to

streams:

A list with the streams which were added or removed.

SIPSessionDidProcessTransaction

Will be sent whenever a SIP transaction is complete in order to provide low-level details of the progress of the INVITE dialog.

timestamp:
A datetime.datetime object indicating when the notification was sent.

originator:

The initiator of the transaction, "local" or "remote".

method:

The method of the request.

code:

The SIP status code of the response.

reason:

The SIP status reason of the response.

ack_received:

This attribute is only present for INVITE transactions and has one of the values True, False or "unknown". The last value may occur then PJSIP does not let us know whether the ACK was received or not.

SIPSessionTransferNewOutgoing

Will be sent whenever a SIP session initiates an outgoing call transfer request.

timestamp:

A datetime.datetime object indicating when the notification was sent.

transfer_destination:

The destination SIP URI of the call transfer request.

transfer_source:

The source SIP URI of the call transfer request.

SIPSessionTransferDidStart

Will be sent whenever a call transfer has been started.

timestamp:

A datetime.datetime object indicating when the notification was sent.

SIPSessionTransferDidFail

Will be sent whenever a call transfer request has failed.

timestamp:

A datetime.datetime object indicating when the notification was sent.

code:

The SIP failure code reported by the SIP stack.

reason:

The reason of the failure as a string.

As an example for how to use the Session object, the following provides a basic Python program that initiates an outgoing SIP session request see Minimalist Session Example code.

IMediaStream¶

Implemented in [browser:sipsimple/streams/+init+.py]

This interface describes the API which the Session uses to communicate with the streams. All streams used by the Session must respect this interface.

methods¶

__init__(self, account)

Initializes the generic stream instance.

new_from_sdp(cls, account, remote_sdp, stream_index)

A classmethod which returns an instance of this stream implementation if the sdp is accepted by the stream or None otherwise.

account:

The sipsimple.account.Account or sipsimple.account.BonjourAccount object the session which this stream would be part of is associated with.

remote_sdp:

The FrozenSDPSession which was received by the remote offer.

stream_index:

An integer representing the index within the list of media streams within the whole SDP which this stream would be instantiated for.

get_local_media(self, for_offer)

Return an SDPMediaStream which represents an offer for using this stream if for_offer is True and a response to an SDP proposal otherwise.

for_offer:

True if the SDPMediaStream will be used for an SDP proposal and False if for a response.

initialize(self, session, direction)

Initializes the stream. This method will get called as soon as the stream is known to be at least offered as part of the Session. If initialization goes fine, the stream must send a MediaStreamDidInitialize notification or a MediaStreamDidFail notification otherwise.

session:

The Session object this stream will be part of.

direction:

"incoming" if the stream was created because of a received proposal and "outgoing" if a proposal was sent. Note that this need not be the same as the initial direction of the Session since streams can be proposed in either way using re-INVITEs.

start(self, local_sdp, remote_sdp, stream_index)

Starts the stream. This method will be called as soon is known to be used in the Session (eg. only called for an incoming proposal if the local party accepts the proposed stream). If starting succeeds, the stream must send a MediaStreamDidStart notification or a MediaStreamDidFail notification otherwise.

local_sdp:

The FrozenSDPSession which is used by the local endpoint.

remote_sdp:

The FrozenSDPSession which is used by the remote endpoint.

stream_index:

An integer representing the index within the list of media streams within the whole SDP which this stream is represented by.

validate_update(self, remote_sdp, stream_index)

This method will be called when a re-INVITE is received which changes the parameters of the stream within the SDP. The stream must return True if the changes are acceptable or False otherwise. If any changed streams return False for a re-INVITE, the re-INVITE will be refused with a negative response. This means that streams must not changed any internal data when this method is called as the update is not guaranteed to be applied even if the stream returns True.

remote_sdp:

The FrozenSDPSession which is used by the remote endpoint.

stream_index:

An integer representing the index within the list of media streams within the whole SDP which this stream is represented by.

update(self, local_sdp, remote_sdp, stream_index)

This method is called when the an SDP negotiation initiated by either the local party or the remote party succeeds. The stream must update its internal state according to the new SDP in use.

local_sdp:

The FrozenSDPSession which is used by the local endpoint.

remote_sdp:

The FrozenSDPSession which is used by the remote endpoint.

stream_index:

An integer representing the index within the list of media streams within the whole SDP which this stream is represented by.

hold(self)

Puts the stream on hold if supported by the stream. Typically used by audio and video streams. The stream must immediately stop sending/receiving data and calls to get_local_media() following calls to this method must return an SDP which reflects the new hold state.

unhold(self)

Takes the stream off hold. Typically used by audio and video streams. Calls to get_local_media() following calls to this method must return an SDP which reflects the new hold state.

deactivate(self)

This method is called on a stream just before the stream will be removed from the Session (either as a result of a re-INVITE or a BYE). This method is needed because it avoids a race condition with streams using stateful protocols such as TCP: the stream connection might be terminated before the SIP signalling announces this due to network routing inconsistencies and the other endpoint would not be able to distinguish between this case and an error which caused the stream transport to fail. The stream must not take any action, but must consider that the transport being closed by the other endpoint after this method was called as a normal situation rather than an error condition.

end(self)

Ends the stream. This must close the underlying transport connection. The stream must send a MediaStreamWillEnd just after this method is called and a MediaStreamDidEnd as soon as the operation is complete. This method is always be called by the Session on the stream if at least the initialize() method has been called. This means that once a stream sends the MediaStreamDidFail notification, the Session will still call this method.

attributes¶

type (class attribute)

A string identifying the stream type (eg: "audio", "video").

priority (class attribute)

An integer value indicating the stream priority relative to the other streams types (higher numbers have higher priority).

hold_supported

True if the stream supports hold

on_hold_by_local

True if the stream is on hold by the local party

on_hold_by_remote

True if the stream is on hold by the remote

on_hold

True if either on_hold_by_local or on_hold_by_remote is true

notifications¶

These notifications must be generated by all streams in order for the Session to know the state of the stream.

MediaStreamDidInitialize

Sent when the stream has been successfully initialized.

MediaStreamDidStart

Sent when the stream has been successfully started.

MediaStreamDidFail

Sent when the stream has failed either as a result of calling one of its methods, or during the normal operation of the stream (such as the transport connection being closed).

MediaStreamWillEnd

Sent immediately after the end() method is called.

MediaStreamDidEnd

Sent when the end() method finished closing the stream.

MediaStreamRegistrar¶

This is a convenience metaclass which automatically registers a defined class with the MediaStreamRegistry. In order to use this class, one simply needs to use it as the metaclass of the new stream.

from zope.interface import implements

from sipsimple.streams import IMediaStream, MediaStreamRegistrar

class MyStream(object):
  __metaclass__ = MediaStreamRegistrar

  implements(IMediaStream)

[...] 

AudioStream¶

Implemented in [browser:sipsimple/streams/rtp.py]

The AudioStream is an implementation of IMediaStream which supports audio data using the AudioTransport and RTPTransport of the SIP core. As such, it provides all features of these objects, including ICE negotiation. An example SDP created using the AudioStream is provided below:

Content-Type: application/sdp
Content-Length:  1093

v=0
o=- 3467525278 3467525278 IN IP4 192.168.1.6
s=blink-0.10.7-beta
c=IN IP4 80.101.96.20
t=0 0
m=audio 55328 RTP/AVP 104 103 102 3 9 0 8 101
a=rtcp:55329 IN IP4 80.101.96.20
a=rtpmap:104 speex/32000
a=rtpmap:103 speex/16000
a=rtpmap:102 speex/8000
a=rtpmap:3 GSM/8000
a=rtpmap:9 G722/8000
a=rtpmap:0 PCMU/8000
a=rtpmap:8 PCMA/8000
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:esI6DbLY1+Aceu0JNswN9Z10DcFx5cZwqJcu91jb
a=crypto:2 AES_CM_128_HMAC_SHA1_32 inline:SHuEMm1BYJqOF4udKl73EaCwnsI57pO86bYKsg70
a=ice-ufrag:2701ed80
a=ice-pwd:6f8f8281
a=candidate:S 1 UDP 31 80.101.96.20 55328 typ srflx raddr 192.168.1.6 rport 55328
a=candidate:H 1 UDP 23 192.168.1.6 55328 typ host
a=candidate:H 1 UDP 23 10.211.55.2 55328 typ host
a=candidate:H 1 UDP 23 10.37.129.2 55328 typ host
a=candidate:S 2 UDP 30 80.101.96.20 55329 typ srflx raddr 192.168.1.6 rport 55329
a=candidate:H 2 UDP 22 192.168.1.6 55329 typ host
a=candidate:H 2 UDP 22 10.211.55.2 55329 typ host
a=candidate:H 2 UDP 22 10.37.129.2 55329 typ host
a=sendrecv

As an implementation of IAudioPort, an AudioStream can be added to an AudioBridge to send or to read audio data to/from other audio objects. It is connected to the voice AudioMixer (SIPApplication.voice_audio_mixer) so it can only be added to bridges using the same AudioMixer. It also contains an AudioBridge on the bridge attribute which always contains an AudioDevice corresponding to the input and output devices; when the stream is active (started and not on hold), the bridge also contains the stream itself and when recording is active, the stream contains a WaveRecorder which records audio data.

methods¶

start_recording(self, filename=None)

If an audio stream is present within this session, calling this method will record the audio to a .wav file.
Note that when the session is on hold, nothing will be recorded to the file.
Right before starting the recording a SIPSessionWillStartRecordingAudio notification will be emitted, followed by a SIPSessionDidStartRecordingAudio.
This method may only be called while the stream is started.

filename:

The name of the .wav file to record to.
If this is set to None, a default file name including the session participants and the timestamp will be generated using the directory defined in the configuration.

stop_recording(self)

This will stop a previously started recording.
Before stopping, a SIPSessionWillStopRecordingAudio notification will be sent, followed by a SIPSessionDidStopRecordingAudio.

send_dtmf(self, digit)

If the audio stream is started, sends a DTMF digit to the remote party.

digit:

This should a string of length 1, containing a valid DTMF digit value (0-9, A-D, * or #).

attributes¶

sample_rate

If the audio stream was started, this attribute contains the sample rate of the audio negotiated.

codec

If the audio stream was started, this attribute contains the name of the audio codec that was negotiated.

srtp_active

If the audio stream was started, this boolean attribute indicates if SRTP is currently being used on the stream.

ice_active

True if the ICE candidates negotiated are being used, False otherwise.

local_rtp_address

If an audio stream is present within the session, this attribute contains the local IP address used for the audio stream.

local_rtp_port

If an audio stream is present within the session, this attribute contains the local UDP port used for the audio stream.

remote_rtp_address_sdp

If the audio stream was started, this attribute contains the IP address that the remote party gave to send audio to.

remote_rtp_port_sdp

If the audio stream was started, this attribute contains the UDP port that the remote party gave to send audio to.

remote_rtp_address_received

If the audio stream was started, this attribute contains the remote IP address from which the audio stream is being received.

remote_rtp_port_received

If the audio stream was started, this attribute contains the remote UDP port from which the audio stream is being received.

local_rtp_candidate_type

The local ICE candidate type which was selected by the ICE negotiation if it succeeded and None otherwise.

remote_rtp_candidate_type

The remote ICE candidate type which was selected by the ICE negotiation if it succeeded and None otherwise.

recording_filename

If the audio stream is currently being recorded to disk, this property contains the name of the .wav file being recorded to.

notifications¶

AudioStreamDidChangeHoldState

Will be sent when the hold state is changed as a result of either a SIP message received on the network or the application calling the hold()/unhold() methods on the Session this stream is part of.

timestamp:

A datetime.datetime object indicating when the notification was sent.

originator:

A string representing the party which requested the hold change, "local" or "remote"

on_hold:

A boolean indicating the new hold state from the point of view of the originator.

*AudioStreamWillStartRecordingAudio_

Will be sent when the application requested that the audio stream be recorded to a .wav file, just before recording starts.

timestamp:

A datetime.datetime object indicating when the notification was sent.

filename:

The full path to the .wav file being recorded to.

AudioStreamDidStartRecordingAudio

Will be sent when the application requested that the audio stream be recorded to a .wav file, just after recording started.

timestamp:

A datetime.datetime object indicating when the notification was sent.

filename:

The full path to the .wav file being recorded to.

AudioStreamWillStopRecordingAudio

Will be sent when the application requested ending the recording to a .wav file, just before recording stops.

timestamp:

A datetime.datetime object indicating when the notification was sent.

filename:

The full path to the .wav file being recorded to.

AudioStreamDidStopRecordingAudio

Will be sent when the application requested ending the recording to a .wav file, just after recording stoped.

timestamp:

A datetime.datetime object indicating when the notification was sent.

filename:

The full path to the .wav file being recorded to.

AudioStreamDidChangeRTPParameters

This notification is sent when the RTP parameters are changed, such as codec, sample rate, RTP port etc.

timestamp:

A datetime.datetime object indicating when the notification was sent.

AudioStreamGotDTMF

Will be send if there is a DMTF digit received from the remote party on the audio stream.

timestamp:

A datetime.datetime object indicating when the notification was sent.

digit:

The DTMF digit that was received, in the form of a string of length 1.

AudioStreamICENegotiationStateDidChange

This notification is proxied from the RTPTransport and as such has the same data as the RTPTransportICENegotiationStateDidChange.

AudioStreamICENegotiationDidSucceed

This notification is proxied from the RTPTransport and as such has the same data as the RTPTransportICENegotiationDidSucceed.

AudioStreamICENegotiationDidFail

This notification is proxied from the RTPTransport and as such has the same data as the RTPTransportICENegotiationDidFail.

AudioStreamDidTimeout

This notification is proxied from the RTPTransport. It's sent when the RTP transport did not receive any data after the specified amount of time (rtp.timeout setting in the Account).

MSRPStreamBase¶

Implemented in [browser:sipsimple/streams/msrp.py]

The MSRPStreamBase is used as a base class for streams using the MSRP protocol. Within the SIP SIMPLE middleware, this hold for the ChatStream, FileTransferStream and DesktopSharingStream classes, however the application can also make use of this class to implement some other streams based on the MSRP protocol as a transport.

methods¶

Of the methods defined by the IMediaStream interface, only the new_from_sdp method is not implemented in this base class and needs to be provided by the subclasses. Also, the subclasses can defined methods of the form _handle_XXX, where XXX is a MSRP method name in order to handle incoming MSRP requests. Also, since this class registers as an observer for itself, it will receive the notifications it sends so subclasses can define methods having the signature _NH_<notification name>(self, notification) as used throughout the middleware in order to do various things at the different points within the life-cycle of the stream.

attributes¶

The attributes defined in the IMediaStream interface which are not provided by this class are:

• type
• priority

In addition, the following attributes need to be defined in the subclass in order for the MSRPStreamBase class to take the correct decisions

media_type

The media type as included in the SDP (eg. "message", "application").

accept_types

A list of the MIME types which should be accepted by the stream (this is also sent within the SDP).

accept_wrapped_types

A list of the MIME types which should be accepted by the stream while wrapped in a message/cpim envelope.

use_msrp_session

A boolean indicating whether or not an MSRPSession should be used.

notifications¶

While not technically notifications of MSRPStreamBase, these notifications are sent from the middleware on behalf of the MSRPTransport used by a stream in the former case, and anonymously in the latter.

MSRPTransportTrace

This notification is sent when an MSRP message is received for logging purposes.

timestamp:

A datetime.datetime object indicating when the notification was sent.

direction:

The direction of the message, "incoming" or "outgoing".

data:

The MSRP message as a string.

MSRPLibraryLog

This notification is sent anonymously whenever the MSRP library needs to log any information.

timestamp:

A datetime.datetime object indicating when the notification was sent.

message:

The log message as a string.

level:

The log level at which the message was written. One of the levels DEBUG, INFO, WARNING, ERROR, CRITICAL from the application.log.level object which is part of the python-application library.

ChatStream¶

Implemented in [browser:sipsimple/streams/msrp.py]

sipsimple.streams.msrp.ChatStream implements session-based Instant Messaging (IM) over MSRP. This class performs the following functions:

• automatically wraps outgoing messages with Message/CPIM if that's necessary according to accept-types
• unwraps incoming Message/CPIM messages; for each incoming message, the ChatStreamGotMessage notification is posted
• composes iscomposing payloads and reacts to those received by sending the ChatStreamGotComposingIndication notification

An example of an SDP created using this class follows:

Content-Type: application/sdp
Content-Length:   283

v=0
o=- 3467525214 3467525214 IN IP4 192.168.1.6
s=blink-0.10.7-beta
c=IN IP4 192.168.1.6
t=0 0
m=message 2855 TCP/TLS/MSRP *
a=path:msrps://192.168.1.6:2855/ca7940f12ddef14c3c32;tcp
a=accept-types:message/cpim text/* application/im-iscomposing+xml
a=accept-wrapped-types:*

methods¶

__init__(self, account, direction='sendrecv')

Initializes the ChatStream instance.

send_message(self, content, content_type='text/plain', recipients=None, courtesy_recipients=None, subject=None, timestamp=None, required=None, additional_headers=None)

Sends an IM message. Prefer Message/CPIM wrapper if it is supported. If called before the connection was established, the messages will be
queued until the stream starts.
Returns the generated MSRP message ID.

content:

The content of the message.

content_type:

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.

recipients:

The list of CPIMIdentity objects which will be used for the To header of the CPIM wrapper. Used to override the default which depends on the remote identity.

May only differ from the default one if the remote party supports private messages. If it does not, a ChatStreamError will be raised.

courtesy_recipients:

The list of CPIMIdentity objects which will be used for the cc header of the CPIM wrapper.

May only be specified if the remote party supports private messages and CPIM is supported. If it does not, a ChatStreamError will be raised.

subject:

A string or MultilingualText which specifies the subject and its translations to be added to the CPIM message. If CPIM is not supported, a ChatStreamError will be raised.

required:

A list of strings describing the required capabilities that the other endpoint must support in order to understand this CPIM message. If CPIM is not supported, a ChatStreamError will be raised.

additional_headers:

A list of MSRP header objects which will be added to this CPIM message. If CPIM is not supported, a ChatStreamError will be raised.

timestamp:

A datetime.datetime object representing the timestamp to put on the CPIM wrapper of the message.

When set to None, a default one representing the current moment will be added.

These MSRP headers are used to enable end-to-end success reports and to disable hop-to-hop successful responses:

Failure-Report: partial
Success-Report: yes

send_composing_indication(self, state, refresh, last_active=None, recipients=None)

Sends an is-composing message to the listed recipients.

state:

The state of the endpoint, "active" or "idle".

refresh:

How often the local endpoint will send is-composing indications to keep the state from being reverted to "idle".

last_active:

A datatime.datetime object representing the moment when the local endpoint was last active.

recipients:

The list of CPIMIdentity objects which will be used for the To header of the CPIM wrapper. Used to override the default which depends on the remote identity.

May only differ from the default one if the remote party supports private messages. If it does not, a ChatStreamError will be raised.

notifications¶

ChatStreamGotMessage

Sent whenever a new incoming message is received,

timestamp:

A datetime.datetime object indicating when the notification was sent.

message:

A ChatMessage or CPIMMessage instance, depending on whether a CPIM message was received or not.

ChatStreamDidDeliverMessage

Sent when a successful report is received.

timestamp:

A datetime.datetime object indicating when the notification was sent.

message_id:

Text identifier of the message.

code:

The status code received. Will always be 200 for this notification.

reason:

The status reason received.

chunk:

A msrplib.protocol.MSRPData instance providing all the MSRP information about the report.

ChatStreamDidNotDeliverMessage

Sent when a failure report is received.

timestamp:

A datetime.datetime object indicating when the notification was sent.

message_id:

Text identifier of the message.

code:

The status code received.

reason:

The status reason received.

chunk:

A msrplib.protocol.MSRPData instance providing all the MSRP information about the report.

ChatStreamDidSendMessage

Sent when an outgoing message has been sent.

timestamp:

A datetime.datetime object indicating when the notification was sent.

message:

A msrplib.protocol.MSRPData instance providing all the MSRP information about the sent message.

ChatStreamGotComposingIndication

Sent when a is-composing payload is received.

timestamp:

A datetime.datetime object indicating when the notification was sent.

state:

The state of the endpoint, "active" or "idle".

refresh:

How often the remote endpoint will send is-composing indications to keep the state from being reverted to "idle". May be None.

last_active:

A datatime.datetime object representing the moment when the remote endpoint was last active. May be None.

content_type:

The MIME type of message being composed. May be None.

sender:

The ChatIdentity or CPIMIdentity instance which identifies the sender of the is-composing indication.

recipients:

The ChatIdentity or CPIMIdentity instances list which identifies the recipients of the is-composing indication.