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 source: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. Thestorage
is saved as an attribute which other entities like theConfiguration Manager
will use to take the appropriate backend. If any error occurs with loading the configuration, the exception raised by theConfigurationManager
is propagated by this method andSIPApplication
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 theSIPApplicationDidStart
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
whereIAudioPort
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
whereIAudioPort
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 source: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 anySession
object that exists globally within the application and is not in theNULL
orTERMINATED
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 source: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 theNone
state.
account:
The local account to be associated with this
Session
.
connect(self, to_header, routes, streams, is_focus=False
, subject=None
, transfer_info=None
)
Will set up the
Session
as outbound and propose the new session to the specified remote party and move the state machine to theoutgoing
state.
Before contacting the remote party, aSIPSessionNewOutgoing
notification will be emitted.
If there is a failure or the remote party rejected the offer, aSIPSessionDidFail
notification will be sent.
Any time a ringing indication is received from the remote party, aSIPSessionGotRingIndication
notification is sent.
If the remote party accepted the session, aSIPSessionWillStart
notification will be sent, followed by aSIPSessionDidStart
notification when the session is actually established.
This method may only be called while in theNone
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 theContact
header according to RFC 4579.
subject:
Session subject. If not None a
Subject
header will be added with the specified value.
transfer_info:
Transfer info. Used when call is being transferred.
send_ring_indication(self)
Sends a 180 provisional response in the case of an incoming session.
accept(self, streams, is_focus=False
)
Calling this methods will accept an incoming session and move the state machine to the
accepting
state.
When there is a new incoming session, aSIPSessionNewIncoming
notification is sent, after which the application can call this method on the sender of the notification.
After this method is called,SIPSessionWillStart
followed bySIPSessionDidStart
will be emitted, orSIPSessionDidFail
on an error.
This method may only be called while in theincoming
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.
is_focus:
Wether local end-point acts like a focus, behaving like a conferencing end-point.
reject(self, code=603
, reason=None
)
Reject an incoming session and move it to the
terminating
state, which eventually leads to theterminated
state.
Calling this method will cause theSession
object to emit aSIPSessionDidFail
notification once the session has been rejected.
This method may only be called while in theincoming
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 aSIPSessionGotAcceptProposal
notification is sent, unless an error occurs while setting up the new stream, in which case aSIPSessionHadProposalFailure
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, aSIPSessionDidRenegotiateStreams
notification is also sent.
This method may only be called while in thereceived_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
orSIPSessionHadProposalFailure
notification is sent.
This method may only be called while in thereceived_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 aSIPSessionGotProposal
notification to be emitted.
After this, the state machine will move into thesending_proposal
state until either aSIPSessionGotAcceptProposal
,SIPSessionGotRejectProposal
orSIPSessionHadProposalFailure
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, aSIPSessionDidRenegotiateStreams
notification is also sent.
This method may only be called while in theconnected
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 theconnected
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 aSIPSessionDidChangeHoldState
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 aSIPSessionDidChangeHoldState
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 aSIPSessionWillEnd
notification is sent, after terminationSIPSessionDidEnd
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
orsipsimple.account.BonjourAccount
object that theSession
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 eitherNone
, "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, orNone
if the session was not yet started.
stop_time
The time the session stopped as a
datetime.datetime
object, orNone
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 beNone
, 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
orsipsimple.core.FrozenToHeader
identifying the local party, if the session is active,None
otherwise.
remote_identity
The
sipsimple.core.FrozenFromHeader
orsipsimple.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
, orNone
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 theINVITE
, but before theACK
.
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 theACK
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 bySIPSessionDidEnd
.
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 andFalse
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 andFalse
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:
Adatetime.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 source:"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
orsipsimple.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 iffor_offer
isTrue
and a response to an SDP proposal otherwise.
for_offer:
True
if theSDPMediaStream
will be used for an SDP proposal andFalse
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 aMediaStreamDidInitialize
notification or aMediaStreamDidFail
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 theSession
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 aMediaStreamDidStart
notification or aMediaStreamDidFail
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 orFalse
otherwise. If any changed streams returnFalse
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 returnsTrue
.
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 aMediaStreamDidEnd
as soon as the operation is complete. This method is always be called by theSession
on the stream if at least theinitialize()
method has been called. This means that once a stream sends theMediaStreamDidFail
notification, theSession
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.
1from zope.interface import implements
2
3from sipsimple.streams import IMediaStream, MediaStreamRegistrar
4
5class MyStream(object):
6 __metaclass__ = MediaStreamRegistrar
7
8 implements(IMediaStream)
9
10[...]
AudioStream¶
Implemented in source: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 aSIPSessionWillStartRecordingAudio
notification will be emitted, followed by aSIPSessionDidStartRecordingAudio
.
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 toNone
, 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, aSIPSessionWillStopRecordingAudio
notification will be sent, followed by aSIPSessionDidStopRecordingAudio
.
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 theSession
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 theRTPTransportICENegotiationStateDidChange
.
AudioStreamICENegotiationDidSucceed
This notification is proxied from the
RTPTransport
and as such has the same data as theRTPTransportICENegotiationDidSucceed
.
AudioStreamICENegotiationDidFail
This notification is proxied from the
RTPTransport
and as such has the same data as theRTPTransportICENegotiationDidFail
.
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 theAccount
).
MSRPStreamBase¶
Implemented in source: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 theIMediaStream
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 theapplication.log.level
object which is part of thepython-application
library.
ChatStream¶
Implemented in source: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 theTo
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 thecc
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, aChatStreamError
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 theTo
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.
set_local_nickname(self, nickname)
Sets the nickname to be used in this MSRP session.
nickname:
The nickname to be set. It may rise
ChatStreamError
if the sream is not initialized or nicknames are not supported.
notifications
ChatStreamGotMessage
Sent whenever a new incoming message is received,
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
message:
A
ChatMessage
orCPIMMessage
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 beNone
.
last_active:
A
datatime.datetime
object representing the moment when the remote endpoint was last active. May beNone
.
content_type:
The MIME type of message being composed. May be
None
.
sender:
The
ChatIdentity
orCPIMIdentity
instance which identifies the sender of the is-composing indication.
recipients:
The
ChatIdentity
orCPIMIdentity
instances list which identifies the recipients of the is-composing indication.
FileTransferStream¶
Implemented in source:sipsimple/streams/msrp.py
The FileTransferStream
supports file transfer over MSRP according to RFC5547. An example of SDP constructed using this stream follows:
Content-Type: application/sdp Content-Length: 383 v=0 o=- 3467525166 3467525166 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/e593357dc9abe90754bd;tcp a=sendonly a=accept-types:* a=accept-wrapped-types:* a=file-selector:name:"reblink.pdf" type:com.adobe.pdf size:268759 hash:sha1:60:A1:BE:8D:71:DB:E3:8E:84:C9:2C:62:9E:F2:99:78:9D:68:79:F6
methods
__init__(self, account, file_selector=None
)
Instantiate a new
FileTransferStream
. If this is constructed by the application for an outgoing file transfer, thefile_selector
argument must be present.
account:
The
sipsimple.account.Account
orsipsimple.account.BonjourAccount
instance which will be associated with the stream.
file_selector:
The
FileSelector
instance which represents the file which is to be transferred.
notifications
FileTransferStreamDidDeliverChunk
This notification is sent for an outgoing file transfer when a success report is received about part of the file being transferred.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
message_id:
The MSRP message ID of the file transfer session.
chunk:
An
msrplib.protocol.MSRPData
instance represented the received REPORT.
code:
The status code received. Will always be 200 for this notification.
reason:
The status reason received.
transferred_bytes:
The number of bytes which have currently been successfully transferred.
file_size:
The size of the file being transferred.
FileTransferStreamDidNotDeliverChunk
timestamp:
A
datetime.datetime
object indicating when the notification was sent.This notification is sent for an outgoing file transfer when a failure report is received about part of the file being transferred.
message_id:
The MSRP message ID of the file transfer session.
chunk:
An
msrplib.protocol.MSRPData
instance represented the received REPORT.
code:
The status code received.
reason:
The status reason received.
FileTransferStreamDidFinish
This notification is sent when the incoming or outgoing file transfer is finished.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
FileTransferStreamGotChunk
This notificaiton is sent for an incoming file transfer when a chunk of file data is received.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
content:
The file part which was received, as a
str
.
content_type:
The MIME type of the file which is being transferred.
transferred_bytes:
The number of bytes which have currently been successfully transferred.
file_size:
The size of the file being transferred.
IDesktopSharingHandler¶
This interface is used to describe the interface between aIDesktopSharingHandler
, which is responsible for consuming and producing RFB data, and the DesktopSharingStream
which is responsible for transporting the RFB data over MSRP. The middleware provides four implementations of this interface:
- InternalVNCViewerHandler
- InternalVNCServerHandler
- ExternalVNCViewerHandler
- ExternalVNCServerHandler
methods
initialize(self, stream)
This method will be called by the
DesktopSharingStream
when the stream has been started and RFB data can be transported. The stream has two attributes which are relevant to theIDesktopSharingHandler
: incoming_queue and outgoing_queue. These attributes areeventlet.coros.queue
instances which are used to transport RFB data between the stream and the handler.
attributes
type
"active"
or "passive"
depending on whether the handler represents a VNC viewer or server respectively.
notifications
DesktopSharingHandlerDidFail
This notification must be sent by the handler when an error occurs to notify the stream that it should fail.
context:
A string describing when the handler failed, such as
"reading"
,"sending"
or"connecting"
.
failure:
A
twisted.python.failure.Failure
instance describing the exception which led to the failure.
reason:
A string describing the failure reason.
InternalVNCViewerHandler¶
This is a concrete implementation of the IDesktopSharingHandler
interface which can be used for a VNC viewer implemented within the application.
methods
send(self, data)
Sends the specified data to the stream in order for it to be transported over MSRP to the remote endpoint.
data:
The RFB data to be transported over MSRP, in the form of a
str
.
notifications
DesktopSharingStreamGotData
This notification is sent when data is received over MSRP.
data:
The RFB data from the remote endpoint, in the form of a
str
.
InternalVNCServerHandler¶
This is a concrete implementation of the IDesktopSharingHandler
interface which can be used for a VNC server implemented within the application.
methods
send(self, data)
Sends the specified data to the stream in order for it to be transported over MSRP to the remote endpoint.
data:
The RFB data to be transported over MSRP, in the form of a
str
.
notifications
DesktopSharingStreamGotData
This notification is sent when data is received over MSRP.
data:
The RFB data from the remote endpoint, in the form of a
str
.
ExternalVNCViewerHandler¶
This implementation of IDesktopSharingHandler
can be used for an external VNC viewer which connects to a VNC server using TCP.
methods
__init__(self, address=("localhost", 0)
, connect_timeout=3
)
This instantiates a new
ExternalVNCViewerHandler
which is listening on the provided address, ready for the external VNC viewer to connect to it via TCP. After this method returns, the attributeaddress
can be used to find out exactly on what address and port the handler is listening on. The handler will only accept one conenction on this address.
address:
A tuple containing an IP address/hostname and a port on which the handler should listen. Any data received on this socket will then be forwarded to the stream and any data received from the stream will be forwarded to this socket.
attributes
address
A tuple containing an IP address and a port on which the handler is listening.
ExternalVNCServerHandler¶
This implementation of IDesktopSharingHandler
can be used for an external VNC server to which handler will connect using TCP.
methods
__init__(self, address, connect_timeout=3
)
This instantiates a new
ExternalVNCServerHandler
which will connect to the provided address on which a VNC server must be listening before the stream using this handler starts.
address:
A tuple containing an IP address/hostname and a port on which the VNC server will be listening. Any data received on this socket will then be forwared to the stream and any data received form the stream will be forwarded to this socket.
connect_timeout:
How long to wait to connect to the VNC server before giving up.
DesktopSharingStream¶
Implemented in source:sipsimple/streams/msrp.py
This stream implements desktop sharing using MSRP as a transport protocol for RFB data.
There is no standard defining this usage but is fairly easy to implement in clients that already support MSRP. To traverse a NAT-ed router, a MSRP relay configured for the called party domain is needed. Below is an example of the Session Description Protocol used for establishing a Desktop sharing session:
m=application 2855 TCP/TLS/MSRP * a=path:msrps://10.0.1.19:2855/b599b22d1b1d6a3324c8;tcp a=accept-types:application/x-rfb a=rfbsetup:active
methods
__init__(self, acount, handler)
Instantiate a new
DesktopSharingStream
.
account:
The
sipsimple.account.Account
orsipsimple.account.BonjourAccount
instance this stream is associated with.
handler:
An object implementing the
IDesktopSharingHandler
interface which will act as the handler for RFB data.
attributes
handler
This is a writable property which can be used to get or set the object implementing
IDesktopSharingHandler
which acts as the handler for RFB data. For incomingDesktopSharingStreams
, this must be set by the application before the stream starts.
incoming_queue
A
eventlet.coros.queue
instance on which incoming RFB data is written. The handler should wait for data on this queue.
outgoing_queue
A
eventlet.coros.queue
instance on which outgoing RFB data is written. The handler should write data on this queue.
ConferenceHandler¶
This class is internal to the Session
and provied the user with the ability to invite participants to a conference hosted by the remote endpoint.
Adding and removing participants is performed using a REFER
request as explained in RFC 4579, section 5.5.
In addition, the ConferenceHandler
will subscribe to the conference
event in order to get information about participants in the conference.
methods
add_participant(self, participant_uri)
Send a
REFER
request telling the server to invite the participant specified inparticipant_uri
to join the ongoing conference.
remove_participant(self, participant_uri)
Send a
REFER
request telling the server to remove the participant specified inparticipant_uri
from the ongoing conference.
notifications
All notifications are sent with the Session
object as the sender.
SIPSessionGotConferenceInfo
This notification is sent when a
NOTIFY
is received with a valid conferene payload.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
conference_info:
The
Conference
payload object.
SIPConferenceDidAddParticipant
This notification is sent when a participant was successfully added to the conference.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
participant:
URI of the participant added to the conference.
SIPConferenceDidNotAddParticipant
This notification is sent when a participant could not be added to the conference.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
participant:
URI of the participant added to the conference.
code:
SIP response code for the failure.
reason:
Reason for the failure.
SIPConferenceDidRemoveParticipant
This notification is sent when a participant was successfully removed from the conference.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
participant:
URI of the participant removed from the conference.
SIPConferenceDidNotRemoveParticipant
This notification is sent when a participant could not be removed from the conference.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
participant:
URI of the participant removed from the conference.
code:
SIP response code for the failure.
reason:
Reason for the failure.
SIPConferenceGotAddParticipantProgress
This notification is sent when a
NOTIFY
is received indicating the status of the add participant operation.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
participant:
URI of the participant whose operation is in progress.
code:
SIP response code for progress.
reason:
Reason associated with the response code.
SIPConferenceGotRemoveParticipantProgress
This notification is sent when a
NOTIFY
is received indicating the status of the remove participant operation.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
participant:
URI of the participant whose operation is in progress.
code:
SIP response code for progress.
reason:
Reason associated with the response code.
Address Resolution¶
The SIP SIMPLE middleware offers the sipsimple.lookup
module which contains an implementation for doing DNS lookups for SIP proxies, MSRP relays, STUN servers and XCAP servers. The interface offers both an asynchronous and synchronous interface. The asynchronous interface is based on notifications, while the synchronous one on green threads. In order to call the methods in a asynchronous manner, you just need to call the method and wait for the notification which is sent on behalf of the DNSLookup instance. The notifications sent by the DNSLookup object are DNSLookupDidSucceed and DNSLookupDidFail. In order to call the methods in a synchronous manner, you need to call the wait method on the object returned by the methods of DNSLookup. This wait method needs to be called from a green thread and will either return the result of the lookup or raise an exception.
The DNSLookup object uses DNSManager, an object that will use the system nameservers and it will fallback to Google's nameservers (8.8.8.8 and 8.8.4.4) in case of failure.
DNS Manager¶
This object provides DNSLookup
with the nameserver list that will be used to perform DNS lookups. It will probe the system local nameservers and check if they are able to do proper lookups (by querying sip2sip.info domain). If the local nameservers are not able to do proper lookups Google nameservers will be used and another probing operation will be scheduled. Local nameservers are always preferred.
methods
__init__(self)
Instantiate the DNSManager object (it's a Singleton).
start(self)
Start the DNSManager. It will start the probing process to determine the suitable nameservers to use.
stop(self)
Stop the DNS resolution probing.
notifications
DNSResolverDidInitialize
This notification is sent when the nameservers to use for probing (and further DNS lookups) have been set for the first time.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
nameservers:
The list of nameservers that was set on the DNS Manager.
DNSNameserversDidChange
This notification is sent when the nameservers to use for probing (and further DNS lookups) have changed as a result of the probing process.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
nameservers:
The list of nameservers that was set on the DNS Manager.
DNS Lookup¶
This object implements DNS lookup support for SIP proxies according to RFC3263 and MSRP relay and STUN server lookup using SRV records. The object initially does NS record queries in order to determine the authoritative nameservers for the domain requested; these authoritative nameservers will then be used for NAPTR, SRV and A record queries. If this fails, the locally configured nameservers are used. The reason for doing this is that some home routers have broken NAPTR and/or SRV query support.
methods
__init__(self)
Instantiate a new DNSLookup object.
lookup_service(self, uri, service, timeout=3.0
, lifetime=15.0
)
Perform an SRV lookup followed by A lookups for MSRP relays or STUN servers depending on the
service
parameter. If SRV queries on theuri.host
domain fail, an A lookup is performed on it and the default port for the service is returned. Only theuri.host
attribute is used. The return value is a list of (host, port) tuples.
uri:
A
(Frozen)SIPURI
from which thehost
attribute is used for the query domain.
service:
The service to lookup servers for,
"msrprelay"
or"stun"
.
timeout:
How many seconds to wait for a response from a nameserver.
lifetime:
How many seconds to wait for a response from all nameservers in total.
lookup_sip_proxy(self, uri, supported_transports, timeout=3.0
, lifetime=15.0
)
Perform a RFC3263 compliant DNS lookup for a SIP proxy using the URI which is considered to point to a host if either the
host
attribute is an IP address, or theport
is present. Otherwise, it is considered a domain for which NAPTR, SRV and A lookups are performed. If NAPTR or SRV queries fail, they fallback to using SRV and A queries. If the transport parameter is present in the URI, this will be used as far as it is part of the supported transports. If the URI has asips
schema, then only the TLS transport will be used as far as it doesn't conflict with the supported transports or the transport parameter. The return value is a list ofRoute
objects containing the IP address, port and transport to use for routing in the order of preference given by the supported_transports argument.
uri:
A
(Frozen)SIPURI
from which thehost
,port
,parameters
andsecure
attributes are used.
supported_transports:
A sublist of
['udp', 'tcp', 'tls']
in the application's order of preference.
timeout:
How many seconds to wait for a response from a nameserver.
lifetime:
How many seconds to wait for a response from all nameservers in total.
lookup_xcap_server(self, uri, timeout=3.0
, lifetime=15.0
)
Perform a TXT DNS query on xcap.<uri.host> and return all values of the TXT record which are URIs with a scheme of http or https. Only the
uri.host
attribute is used. The return value is a list of strings representing HTTP URIs.
uri:
A
(Frozen)SIPURI
from which thehost
attribute is used for the query domain.
timeout:
How many seconds to wait for a response from a nameserver.
lifetime:
How many seconds to wait for a response from all nameservers in total.
notifications
DNSLookupDidSucceed
This notification is sent when one of the lookup methods succeeds in finding a result.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
result:
The result of the DNS lookup in the format described in each method.
DNSLookupDidFail
This notification is sent when one of the lookup methods fails in finding a result.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
error:
A
str
object describing the error which resulted in the DNS lookup failure.
DNSLookupTrace
This notification is sent several times during a lookup process for each individual DNS query.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
query_type:
The type of the query,
"NAPTR"
,"SRV"
,"A"
,"NS"
etc.
query_name:
The name which was queried.
answer:
The answer returned by dnspython, or
None
if an error occurred.
error:
The exception which caused the query to fail, or
None
if no error occurred.
context:
The name of the method which was called on the
DNSLookup
object.
service:
The service which was queried for, only available when context is
"lookup_service"
.
uri:
The uri which was queried for.
nameservers:
The list of nameservers that was used to perform the lookup.
Route¶
This is a convinience object which contains sufficient information to identify a route to a SIP proxy. This object is returned by DNSLookup.lookup_sip_proxy
and can be used with the Session
or a (Frozen)RouteHeader
can be easily constructed from it to pass to one of the objects in the SIP core handling SIP dialogs/transactions (Invitation
, Subscription
, Request
, Registration
, Message
, Publication
). This object has three attributes which can be set in the constructor or after it was instantiated. They will only be documented as arguments to the constructor.
methods
__init__(self, address, port=None, transport='udp'
)
Creates the Route object with the specified parameters as attributes.
Each of these attributes can be accessed on the object once instanced.
address:
The IPv4 address that the request in question should be sent to as a string.
port:
The port to send the requests to, represented as an int, or None if the default port is to be used.
transport:
The transport to use, this can be a string of either "udp", "tcp" or "tls" (case insensitive).
get_uri(self)
Returns a
SIPURI
object which contains the adress, port and transport as parameter. This can be used to easily construct aRouteHeader
:
route = Route("1.2.3.4", port=1234, transport="tls") route_header = RouteHeader(route.get_uri())
SIP Accounts¶
Account Management is implemented in source:sipsimple/account.py (sipsimple.account
module) and offers support for SIP accounts registered at SIP providers and SIP bonjour accounts which are discovered using mDNS.
AccountManager¶
The sipsimple.account.AccountManager
is the entity responsible for loading and keeping track of the existing accounts. It is a singleton and can be instantiated anywhere, obtaining the same instance. It cannot be used until its start
method has been called.
methods
__init__(self)
The
__init__
method allows theAccountManager
to be instantiated without passing any parameters. A reference to theAccountManager
can be obtained anywhere before it is started.
start(self)
This method will load all the existing accounts from the configuration. If the Engine is running, the accounts will also activate. This method can only be called after the ConfigurationManager has been started. A SIPAccountManagerDidAddAccount will be sent for each account loaded. This method is called automatically by the SIPApplication when it initializes all the components of the middleware.
stop(self)
Calling this method will deactivate all accounts managed by the
AccountManager
. This method is called automatically by the SIPApplication when it stops.
has_account(self, id)
This method returns
True
if an account which has the specifed SIP ID (must be a string) exists andFalse
otherwise.
get_account(self, id)
Returns the account (either an
Account
instance or theBonjourAccount
instance) with the specified SIP ID. Will raise aKeyError
if such an account does not exist.
get_accounts(self)
Returns a list containing all the managed accounts.
iter_accounts(self)
Returns an iterator through all the managed accounts.
find_account(self, contact_uri)
Returns an account with matches the specified
contact_uri
which must be asipsimple.core.SIPURI
instance. Only the accounts with the enabled flag set will be considered. Returns None if such an account does not exist.
notifications
SIPAccountManagerDidAddAccount
This notification is sent when a new account becomes available to the
AccountManager
. The notification is also sent when the accounts are loaded from the configuration.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
account:
The account object which was added.
SIPAccountManagerDidRemoveAccount
This notification is sent when an account is deleted using the
delete
method.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
account:
The account object which was deleted.
SIPAccountManagerDidChangeDefaultAccount
This notification is sent when the default account changes.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
old_account:
This is the account object which used to be the default account.
account:
This is the account object which is the new default account.
Account¶
The sipsimple.account.Account
objects represent the SIP accounts which are registered at SIP providers. It has a dual purpose: it acts as both a container for account-related settings and as a complex object which can be used to interact with various per-account functions, such as presence, registration etc. This page documents the latter case, while the former is explained in the Configuration API.
There is exactly one instance of Account
per SIP account used and it is uniquely identifiable by its SIP ID, in the form user@domain. It is a singleton, in the sense that instantiating Account
using an already used SIP ID will return the same object. However, this is not the recommended way of accessing accounts, as this can lead to creation of new ones; the recommended way is by using the AccountManager. The next sections will use a lowercase, monospaced account
to represent an instance of Account
.
states
The Account
objects have a setting flag called enabled
which, if set to False
will deactivate it: none of the internal functions will work in this case; in addition, the application using the middleware should not do anything with a disabled account. After changing it's value, the save()
method needs to be called, as the flag is a setting and will not be used until this method is called:
account.enabled = True account.save()
The Account
objects will activate automatically when they are loaded/created if the enabled
flag is set to True
and the sipsimple.engine.Engine
is running; if it is not running, the accounts will activate after the engine starts.
In order to create a new account, just create a new instance of Account
with an id which doesn't belong to any other account.
The other functions of Account
which run automatically have other enabled flags as well. They will only be activated when both the global enabled flag is set and the function-specific one. These are:
Account.sip.register.enabled
This flag controls the automatic registration of the account. The notifications SIPAccountRegistrationDidSucceed, SIPAccountRegistrationDidFail and SIPAccountRegistrationDidEnd are used to inform the status of this registration.
Account.presence.enabled
This flag controls the automatic subscription to buddies for the presence and dialog events and the publication of data for the presence event.
Account.message_summary.enabled
This flag controls the automatic subscription to the message-summary event in order to find out about voicemail messages.
The save()
method needs to be called after changing these flags in order for them to take effect. The methods available on Account
objects are inherited from SettingsObject.
attributes
The following attributes can be used on an Account object and need to be considered read-only.
id
This attribute is of type
sipsimple.configuration.datatypes.SIPAddress
(a subclass ofstr
) and contains the SIP id of the account. It can be used as a normal string in the form user@domain, but it also allows access to the components via the attributesusername
anddomain
.
account.id # 'alice@example.com' account.id.username # 'alice' account.id.domain # 'example.com'
contact
This attribute can be used to construct the Contact URI for SIP requests sent on behalf of this account. It's type is
sipsimple.core.ContactURIFactory
. It can be indexed by a URi type plus a string representing a transport ('udp'
,'tcp'
,'tls'
) or asipsimple.util.Route
object which will return asipsimple.core.SIPURI
object with the appropriate IP, port and transport. URI types are:NoGRUU
,PublicGRUU
,TemporaryGRUU
,PublicGRUUIfAvailable
andTemporaryGRUUIfAvailable
. They can be imported fromsipsimple.core
. The username part is a randomly generated 8 character string consisting of lowercase letters; but it can be chosen by passing it to init when building theContactURIFactory
object.
account.contact # 'ContactURIFactory(username=hnfkybrt)' account.contact.username # 'hnfkybrt' account.contact['udp'] # <SIPURI "sip:hnfkybrt@10.0.0.1:53024"> account.contact['tls'] # <SIPURI "sip:hnfkybrt@10.0.0.1:54478;transport=tls">
credentials
This attribute is of type
sipsimple.core.Credentials
which is built from theid.username
attribute and thepassword
setting of the Account. Whenever this setting is changed, this attribute is updated.
account.credentials # <Credentials for 'alice'>
tls_credentials
This attribute of type
X509Credentials
returns the TLS credentials object which is later used when establishing MSRP connections, for example.
uri
This attribute is of type
sipsimple.core.SIPURI
which can be used to form aFromHeader
associated with this account. It contains the SIP ID of the account.
account.uri # <SIPURI "sip:alice@example.com">
voicemail_uri
This attribute contains a string object representing the URI which is set as the subscription target for the message-summary event.
other
registered
Returns
True
if the account has registred,False
otherwise.
mwi_active
Returns
True
if the account has an active subscription to the message-summary event,False
otherwise.
presence_state
Property which can be used to get or set the presence state for the account. The presence state needs to be a
PIDF
object from thesipsimple.payloads
module. The account itself takes care of the publication process.
dialog_state
Property which can be used to get or set the dialog state for the account. The dialog state needs to be a
DialogInfo
object from thesipsimple.payloads
module. The account itself takes care of the publication process.
notifications
CFGSettingsObjectDidChange
This notification is sent when the
save()
method is called on the account after some of the settings were changed. As the notification belongs to theSettingsObject
class, it is exaplained in detail in SettingsObject Notifications.
SIPAccountWillActivate
This notification is sent when the
Account
is about to be activated, but before actually performing any activation task. SeeSIPAccountDidActivate
for more detail.
SIPAccountDidActivate
This notification is sent when the
Account
activates. This can happen when theAccount
is loaded if it's enabled flag is set and the Engine is running, and at any later time when the status of the Engine changes or the enabled flag is modified.
SIPAccountWillDeactivate
This notification is sent when the
Account
is about to be deactivated, but before performing any deactivation task. SeeSIPAccountDidDeactivate
for more detail.
SIPAccountDidDeactivate
This notification is sent when the
Account
deactivates. This can happend when theEngine
is stopped or when the enabled flag of the account is set toFalse
.
SIPAccountWillRegister
This notification is sent when the account is about to register for the first time.
SIPAccountRegistrationWillRefresh
This notification is sent when a registration is about to be refreshed.
SIPAccountRegistrationDidSucceed
This notification is sent when a REGISTER request sent for the account succeeds (it is also sent for each refresh of the registration). The data contained in this notification is:
contact_header:
The Contact header which was registered.
contact_header_list:
A list containing all the contacts registered for this SIP account.
expires:
The amount in seconds in which this registration will expire.
registrar:
The
sipsimple.util.Route
object which was used.
SIPAccountRegistrationDidFail
This notification is sent when a REGISTER request sent for the account fails. It can fail either because a negative response was returned or because PJSIP considered the request failed (e.g. on timeout). The data contained in this notification is:
error:
The reason for the failure of the REGISTER request.
retry_after:
The amount in seconds as a
float
after which the registration will be tried again.
SIPAccountRegistrationDidEnd
This notification is sent when a registration is ended (the account is unregistered). The data contained in this notification is:
registration:
The
sipsimple.core.Registration
object which ended.
SIPAccountRegistrationDidNotEnd
This notification is sent when a registration fails to end (the account is not unregistered). The data contained in this notification is:
code:
The SIP status code received.
reason:
The SIP status reason received.
registration:
The
sipsimple.core.Registration
object which ended.
SIPAccountRegistrationGotAnswer
This notification is sent whenever a response is received to a sent REGISTER request for this account. The data contained in this notification is:
code:
The SIP status code received.
reason:
The SIP status reason received.
registration:
The
sipsimple.core.Registration
object which was used.
registrar:
The
sipsimple.util.Route
object which was used.
SIPAccountGotMessageSummary
This notification is sent when a NOTIFY is received with a message-summary payload. The data contained in this notification is:
message_summary:
A
sipsimple.payloads.messagesummary.MessageSummary
object with the parsed payload from the NOTIFY request.
SIPAccountGotPresenceWinfo
This notification is sent when a NOTIFY is received with a presence.winfo payload. The data contained in this notification is:
version:
The version number of the received document.
state:
Indicates if the received state is full or partial.
watcher_list:
A
sipsimple.payloads.watcherinfo.WatcherList
object with the parsed information from the NOTIFY request.
SIPAccountGotDialogWinfo
This notification is sent when a NOTIFY is received with a dialog.winfo payload. The data contained in this notification is:
version:
The version number of the received document.
state:
Indicates if the received state is full or partial.
watcher_list:
A
sipsimple.payloads.watcherinfo.WatcherList
object with the parsed information from the NOTIFY request.
SIPAccountGotPresenceState
This notification is sent when a NOTIFY is received with a presence payload. The data contained in this notification is:
version:
The version number of the received document.
full_state:
Boolean flag indicating if the received state is full or partial.
resource_map:
Dictionary mapping SIP URIs to
sipsimple.payloads.rlsnotify.Resource
instances which contain all presence documents associated with them.
SIPAccountGotDialogState
This notification is sent when a NOTIFY is received with a dialog payload. The data contained in this notification is:
version:
The version number of the received document.
full_state:
Boolean flag indicating if the received state is full or partial.
resource_map:
Dictionary mapping SIP URIs to
sipsimple.payloads.rlsnotify.Resource
instances which contain all dialog-info documents associated with them.
BonjourAccount¶
The sipsimple.account.BonjourAccount
represents the SIP account used for P2P mode; it does not interact with any server. The class is a singleton, as there can only be one such account on a system. Similar to the Account
, it is used both as a complex object, which implements the functions for bonjour mode, as well as a container for the related settings.
states
The BonjourAccount
has an enabled
flag which controls whether this account will be used or not. If it is set to False
, none of the internal functions will be activated and, in addition, the account should not be used by the application. The bonjour account can only activated if the Engine is running; once it is started, if the enabled flag is set, the account will activate. When the BonjourAccount
is activated, it will broadcast the contact address on the LAN and discover its neighbours sending notifications as this happens.
attributes
The following attributes can be used on a BonjourAccount object and need to be considered read-only.
id
This attribute is of type
sipsimple.configuration.datatypes.SIPAddress
(a subclass ofstr
) and contains the SIP id of the account, which is'bonjour@local'
. It can be used as a normal string, but it also allows access to the components via the attributesusername
anddomain
.
bonjour_account.id # 'bonjour@local' bonjour_account.id.username # 'bonjour' bonjour_account.id.domain # 'local'
contact
This attribute can be used to construct the Contact URI for SIP requests sent on behalf of this account. It's type is
sipsimple.account.ContactURIFactory
. It can be indexed by a string representing a transport ('udp'
,'tcp'
,'tls'
) or asipsimple.util.Route
object which will return asipsimple.core.SIPURI
object with the appropriate IP, port and transport. The username part is a randomly generated 8 character string consisting of lowercase letters; but it can be chosen by passing it to init when building theContactURIFactory
object.
bonjour_account.contact # 'ContactURIFactory(username=lxzvgack)' bonjour_account.contact.username # 'lxzvgack' bonjour_account.contact['udp'] # <SIPURI "sip:lxzvgack@10.0.0.1:53024"> bonjour_account.contact['tls'] # <SIPURI "sip:lxzvgack@10.0.0.1:54478;transport=tls">
credentials
This attribute is of type
sipsimple.core.Credentials
object which is built from thecontact.username
attribute; the password is set to the empty string.
bonjour_account.credentials # <Credentials for 'alice'>
uri
This attribute is of type
sipsimple.core.SIPURI
which can be used to form aFromHeader
associated with this account. It contains the contact address of the bonjour account:
bonjour_account.uri # <SIPURI "sip:lxzvgack@10.0.0.1">
notifications
BonjourAccountDidAddNeighbour
This notification is sent when a new Bonjour neighbour is discovered.
service_description:
BonjourServiceDescription object uniquely identifying this neighbour in the mDNS library.
display_name:
The name of the neighbour as it is published.
host:
The hostname of the machine from which the Bonjour neighbour registered its contact address.
uri:
The contact URI of the Bonjour neighbour, as a
FrozenSIPURI
object.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
BonjourAccountDidUpdateNeighbour
This notification is sent when an existing Bonjour neighbour has updates its published data.
service_description:
BonjourServiceDescription object uniquely identifying this neighbour in the mDNS library.
display_name:
The name of the neighbour as it is published.
host:
The hostname of the machine from which the Bonjour neighbour registered its contact address.
uri:
The contact URI of the Bonjour neighbour, as a
FrozenSIPURI
object.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
BonjourAccountDidRemoveNeighbour
This notification is sent when a Bonjour neighbour unregisters.
service_description:
The BonjourServiceDescription object, which uniquely identifies a neighbour, that got unregistered.
BonjourAccountDiscoveryDidFail
This notification is sent once per transport when the Bonjour account has failed to perform the discovery process for the indicated transport.
reason:
String defining the reason of the failure.
transport:
String specifying the transport for which the discovery failed.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
BonjourAccountDiscoveryFailure
This notification is sent once per transport when the Bonjour account has encountered a problem while browsing the list of neighbours for the indicated transport.
error:
String defining the error of the failure.
transport:
String specifying the transport for which the neighbour resoution failed.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
BonjourAccountRegistrationDidEnd
This notification is sent once per transport when the Bonjour account unregisters its contact address for the indicated transport using mDNS.
transport:
String specifying the transport for which the registration ended.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
BonjourAccountRegistrationDidFail
This notification is sent once per transport when the Bonjour account fails to register its contact address for the indicated transport using mDNS.
reason:
A human readable error message.
transport:
String specifying the transport for which the registration failed.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
BonjourAccountRegistrationUpdateDidFail
This notification is sent once per transport when the Bonjour account fails to update its data for the indicated transport using mDNS.
reason:
A human readable error message.
transport:
String specifying the transport for which the registration update failed.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
BonjourAccountRegistrationDidSucceed
This notification is sent once per transport when the Bonjour account successfully registers its contact address for the indicated transport using mDNS.
name:
The contact address registered.
transport:
String specifying the transport for which the registration succeeded.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
BonjourAccountWillInitateDiscovery
This notification is sent when the Bonjour account is about to start the discovery process for the indicated transport.
transport:
String specifying the transport for which the discovery will be started.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
BonjourAccountWillRegister
This notification is sent just before the Bonjour account starts the registering process for the indicated transport.
transport:
String specifying the transport for which the registration will be started.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
CFGSettingsObjectDidChange
This notification is sent when the
save()
method is called on the account after some of the settings were changed. As the notification belongs to theSettingsObject
class, it is exaplained in detail in SettingsObject Notifications.
timestamp:A
datetime.datetime
object indicating when the notification was sent.
SIPAccountWillActivate
This notification is sent when the
BonjourAccount
is about to be activated, but before actually performing any activation task. SeeSIPAccountDidActivate
for more detail.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
SIPAccountDidActivate
This notification is sent when the
BonjourAccount
activates. This can happen when theBonjourAccount
is loaded if it's enabled flag is set and the Engine is running, and at any later time when the status of the Engine changes or the enabled flag is modified.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
SIPAccountWillDeactivate
This notification is sent when the
BonjourAccount
is about to be deactivated, but before performing any deactivation task. SeeSIPAccountDidDeactivate
for more detail.
timestamp:A
datetime.datetime
object indicating when the notification was sent.
SIPAccountDidDeactivate
This notification is sent when the
BonjourAccount
deactivates. This can happend when theEngine
is stopped or when the enabled flag of the account is set toFalse
.
timestamp:A
datetime.datetime
object indicating when the notification was sent.
Audio¶
The high-level audio API hides the complexity of using the low-level PJMEDIA interface. This is implemented in thesipsimple.audio
module and contains the following components:
- IAudioPort: an interface describing an object capable of producing and/or consuming audio data.
- AudioDevice: an object conforming to the IAudioPort interface which describes a physical audio device.
- AudioBridge: a collection of objects conforming to IAudioPort which connects all of them in a full mesh.
- WavePlayer: an object conforming to the IAudioPort interface which can playback the audio data from a
.wav
file. - WaveRecorder: an object conforming to the IAudioPort interface which can record audio data to a
.wav
file.
IAudioPort¶
The IAudioPort interface describes an object capable of producing and/or consuming audio data. This can be a dynamic object, which changes its role during its lifetime and notifies such changes using a notification, which is part of the interface.
attributes
mixer
The
AudioMixer
this audio object is connected to. Only audio objects connected to the same mixer will be able to send audio data from one to another.
consumer_slot
An integer representing the slot (see AudioMixer) which this object uses to consume audio data, or
None
if this object is not a consumer.
producer_slot
An integer representing the slot (see AudioMixer) which this object uses to produce audio data, or
None
if this object is not a producer.
notifications
AudioPortDidChangeSlots
This notification needs to be sent by implementations of this interface when the slots it has change, so as to let the
AudioBridges
it is part of know that reconnections need to be made.
consumer_slot_changed:
A bool indicating whether the consumer slot was changed.
producer_slot_changed:
A bool indicating whether the producer slot was changed.
old_consumer_slot:
The old slot for consuming audio data. Only required if consumer_slot_changed is
True
.
new_consumer_slot:
The new slot for consuming audio data. Only required if consumer_slot_changed is
True
.
old_producer_slot:
The old slot for producing audio data. Only required if producer_slot_changed is
True
.
new_producer_slot:
The new slot for producing audio data. Only required if producer_slot_changed is
True
.
AudioDevice¶
The AudioDevice represents the physical audio device which is part of a AudioMixer
, implementing the IAudioPort
interface. As such, it can be uniquely identified by the mixer it represents.
methods
__init__(self, mixer, input_muted=False
, output_muted=False
):
Instantiates a new AudioDevice which represents the physical device associated with the specified
AudioMixer
.
mixer:
The
AudioMixer
whose physical device this object represents.
input_muted:
A boolean which indicates whether this object should act as a producer of audio data.
output_muted:
A boolean which indicates whether this object should act as a consumer of audio data.
attributes
input_muted
A writable property which controls whether this object should act as a producer of audio data. An
AudioPortDidChange
slots notification is sent when this attribute is changed to force connections to be reconsidered within theAudioBridges
this object is part of.
output_muted
A writable property which controls whether this object should act as a consumer of audio data. An
AudioPortDidChange
slots notification is sent when this attribute is changed to force connections to be reconsidered within theAudioBridges
this object is part of.
AudioBridge¶
The AudioBridge
is the basic component which is able to connect IAudioPort
implementations. It acts as a container which connects as the producers to all the consumers which are part of it. An object which is both a producer and a consumer of audio data will not be connected to itself. Being an implementation of IAudioPort
itself, an AudioBridge
can be part of another AudioBridge
. The AudioBridge
does not keep strong references to the ports it contains and once the port's reference count reaches 0, it is automatically removed from the AudioBridge
.
Note: although this is not enforced, there should never be any cycles when connecting
AudioBridges
.
methods
__init__(self, mixer)
Instantiate a new
AudioBridge
which uses the specifiedAudioMixer
for mixing.
add(self, port)
Add an implementation of
IAudioPort
to this AudioBridge. This will connect the new port to all the existing ports of the bridge. A port cannot be added more than once to anAudioBridge
; thus, this object acts like a set.
remove(self, port)
Remove a port from this
AudioBridge
. The port must have previously been added to theAudioBridge
, otherwise aValueError
is raised.
WavePlayer¶
A WavePlayer
is an implementation of IAudioPort
which is capable of producing audio data read from a .wav
file. This object is completely reusable, as it can be started and stopped any number of times.
methods
__init__(self, mixer, filename, volume=100
, loop_count=1
, pause_time=0
, initial_play=True
)
Instantiate a new
WavePlayer
which is capable of playing a.wav
file repeatedly. All the parameters are available as attributes of the object, but should not be changed once the object has been started.
mixer:
The
AudioMixer
this object is connected to.
filename:
The full path to the
.wav
file from which audio data is to be read.
volume:
The volume at which the file should be played.
loop_count:
The number of times the file should be played, or
0
for infinity.
pause_time:
How many seconds to wait between successive plays of the file.
initial_play:
Whether or not the file to play once the
WavePlayer
is started, or to waitpause_time
seconds before the first play.
start(self)
Start playing the
.wav
file.
stop(self)
Stop playing the
.wav
file immediately.
play(self)
Play the
.wav
file. This method is an alternative to the start/stop methods, it runs on a waitable green thread. One may callplay().wait()
in order to green-block waiting for the file playback to end.
attributes
is_active
A boolean indicating whether or not this
WavePlayer
is currently playing.
notifications
WavePlayerDidStart
This notification is sent when the
WavePlayer
starts playing the file the first time after thestart()
method has been called.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
WavePlayerDidEnd
This notification is sent when the
WavePlayer
is done playing either as a result of playing the number of times it was told to, or because thestop()
method has been called.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
WavePlayerDidFail
This notification is sent when the
WavePlayer
is not capable of playing the.wav
file.
timestamp:
A
datetime.datetime
object indicating when the notification was sent.
error:
The exception raised by the
WaveFile
which identifies the cause for not being able to play the.wav
file.
WaveRecorder¶
A WaveRecorder
is an implementation of IAudioPort
is is capable of consuming audio data and writing it to a .wav
file. Just like WavePlayer
, this object is reusable: once stopped it can be started again, but if the filename attribute is not changed, the previously written file will be overwritten.
methods
__init__(self, mixer, filename)
Instantiate a new
WaveRecorder
.
mixer:
The
AudioMixer
thisWaveRecorder
is connected to.
filename:
The full path to the
.wav
file where this object should write the audio data. The file must be writable. The directories up to the file will be created if possible when thestart()
method is called.
start(self)
Start consuming audio data and writing it to the
.wav
file. If this object is not part of anAudioBridge
, not audio data will be written.
stop(self)
Stop consuming audio data and close the
.wav
file.
attributes
is_active
A boolean indicating whether or not this
WaveRecorder
is currently recording audio data.
Conference¶
Conference support is implemented in the sipsimple.conference
module. Currently, only audio conferencing is supported.
AudioConference¶
This class contains the basic implementation for audio conferencing. It acts as a container for AudioStream
objects which it will connect in a full mesh, such that all participants can hear all other participants.
methods
__init__(self)
Instantiates a new
AudioConference
which is ready to containAudioStream
objects.
add(self, stream)
Add the specified
AudioStream
object to the conference.
remove(self, stream)
Removes the specified
AudioStream
object from the conference. Raises aValueError
if the stream is not part of the conference.
hold(self)
Puts the conference "on hold". This means that the audio device will be disconnected from the conference: all the participants will be able to continue the conference, but the local party will no longer contribute any audio data and will not receive any audio data using the input and output devices respectively. This does not affect the hold state of the streams in any way.
unhold(self)
Removes the conference "from hold". This means that the audio device will be reconnected to the conference: all the participants will start to hear the local party and the local party will start to hear all the participants. This does not affect the hold state of the streams in any way.
attributes
bridge
An
AudioBridge
which this conference uses to connect all audio streams. It can be used by the application to play a wav file using aWavePlayer
to all the participants or record the whole conference using aWaveRecorder
.
on_hold
A boolean indicating whether or not the conference is "on hold".
streams
The list of streams which are part of this conference. The application must not manipulate this list in any way.
Addressbook API¶
Implemented in source:"sipsimple/addressbook.py"
The Addressbook API is used to manage the contact list in SIP SIMPLE SDK. It stores contacts locally and uses the XCAP API underneath to synchronize the contacts between instances (if XCAP support is available). Multiple clients instances can synchronize this addressbook using XCAP-diff event package.
AddressbookManager¶
The AddressbookManager is a singleton which is started automatically by the middleware. It's the central point to the addressbook, stores contacts, groups and policies and takes care of the synchronization. Upon start it loads all contacts and policies first and groups afterwards.
methods:
has_contact(self, id)
Returns True if the given id belongs to a existing contact, False otherwise.
get_contact(self, id)
Returns the
Contact
instance for the given id.
get_contacts(self)
Returns the full list of contacts.
has_group(self, id)
Returns True if the given id belongs to a existing group, False otherwise.
get_group(self, id)
Returns the
Group
instance for the given id.
get_groups(self)
Returns the full list of groups.
has_policy(self, id)
Returns True if the given id belongs to a existing policy, False otherwise.
get_policy(self, id)
Returns the
Policy
instance for the given id.
get_policies(self)
Returns the full list of policies.
transaction(self)
Returns an instance of
MultiAccountTransaction
, which can be used as a context manager to apply multiple changes to the addressbook in a single shot.
notifications:
AddressbookManagerDidAddContact
This notification is sent when the AddressbookManager adds a new contact.
contact:
The added
Contact
object.
AddressbookManagerDidRemoveContact
This notification is sent when the AddressbookManager removes a contact.
contact:
The removed
Contact
object.
AddressbookManagerDidAddGroup
This notification is sent when the AddressbookManager adds a new group.
group:
The added
Group
object.
AddressbookManagerDidRemoveGroup
This notification is sent when the AddressbookManager removes a group.
group:
The removed
Group
object.
AddressbookManagerDidAddPolicy
This notification is sent when the AddressbookManager adds a new policy.
policy:
The added
Policy
object.
AddressbookManagerDidRemovePolicy
This notification is sent when the AddressbookManager removes a policy.
policy:
The removed
Policy
object.
Contact¶
Contact
objects represent a person with a name and a list of URIs that can be used to communicate with him. They are identified by an ID (a random string) which is assigned automatically.
Example contact in middleware configuration:
id1341414346774404637127: name = test dialog: policy = default subscribe = false presence: policy = default subscribe = false uris: id1341414346774623001554: type = uri = test@ag-projects.com
attributes:
name:
A human readable name for the contact. (unicode)
uris:
A
ContactURIList
object (it has the API of a set) containing all URIs belonging to this contact.
dialog:
Dialog subscription settings and policy.
presence:
Presence subscription settings and policy.
methods:
save(self)
Saves the object to persistent local storage and remote XCAP storage.
delete(self)
Removes the contact from persistent storage, both local and remote.
notifications:
AddressbookContactWasActivated
This notification is sent when a contact is either created or loaded from the configuration and it's ready to be used.
AddressbookContactWasCreated
This notification is sent when a contact is created for the first time.
AddressbookContactDidChange
This notification is sent when a contact has changed any of its settings. Changes could be caused by local calls to save() or remote changes.
modified:
Dictionary containing the changed attributes. Keys are the changed attribute names, and values are ModifiedValue
objects, which have old and new attributes. If the changed attribute is a list, a ModifiedList
object instance is retured instead, which has added, removed and modified attributes.
Example notification:
name = AddressbookContactDidChange sender = Contact(id='id1341414346771445396537') data = NotificationData(modified={'dialog.policy': ModifiedValue(old='default', new='block'), 'name': ModifiedValue(old='test', new='test2')}
AddressbookContactWasDeleted
This notification is sent when a contact is deleted.
ContactURI¶
ContactURI
objects represent a single URI used in a contact. It's identified by an ID (a random string), which is assigned automatically.
attributes:
uri:
The actual URI (unicode).
type:
URI type (unicode), used for labeling purpose.
Policy¶
Policy
objects represent a policy for a given URI, which is not to be displayed as a Contact
. They are identified by an ID (a random string) which is assigned automatically.
Example policy object:
id1352465065493178912902: name = "test" uri = test@ag-projects.com dialog: policy = default subscribe = false presence: policy = block subscribe = false
attributes:
name:
A human readable name for the policy element.
uri:
URI to which this policy applies.
dialog:
Dialog subscription settings and policy.
presence:
Presence subscription settings and policy.
methods:
save(self)
Saves the object to persistent local storage and remote XCAP storage.
delete(self)
Removes the contact from persistent storage, both local and remote.
notifications:
AddressbookPolicyWasActivated
This notification is sent when a policy is either created or loaded from the configuration and it's ready to be used.
AddressbookPolicyWasCreated
This notification is sent when a policy is created for the first time.
AddressbookPolicyDidChange
This notification is sent when a policy has changed any of its settings. Changes could be caused by local calls to save() or remote changes.
modified:
Dictionary containing the changed attributes. Keys are the changed attribute names, and values are ModifiedValue
objects, which have old and new attributes. If the changed attribute is a list, a ModifiedList
object instance is retured instead, which has added, removed and modified attributes.
AddressbookPolicyWasDeleted
This notification is sent when a policy is deleted.
Group¶
Group
objects contain a list of contacts. They are identified by an ID (a random string) which is assigned automatically. A Contact
may be part of multiple groups.
Example group in middleware configuration:
id1341414346762171006572: contacts = id1341414346776435374242, id1341414346775250327458, id1341414346775905712988 name = Other
attributes:
name:
A human readable name for the group. (unicode)
contacts:
List of contacts belonging to this group.
methods:
save(self)
Saves the object to persistent local storage and remote XCAP storage.
delete(self)
Removes the contact from persistent storage, both local and remote.
notifications:
AddressbookGroupWasActivated
This notification is sent when a group is either created or loaded from the configuration and it's ready to be used.
AddressbookGroupWasCreated
This notification is sent when a policy is created for the first time.
AddressbookGroupDidChange
This notification is sent when a group has changed any of its settings. Changes could be caused by local calls to save() or remote changes.
modified:
Dictionary containing the changed attributes. Keys are the changed attribute names, and values are
ModifiedValue
objects, which have old and new attributes. If the changed attribute is a list, aModifiedList
object instance is retured instead, which has added, removed and modified attributes.
Example notification:
name = AddressbookGroupDidChange sender = Group(id='id1341414346762171006572') data = NotificationData(modified={'contacts': ModifiedList(added=[Contact(id='id1341414346771445396537')], removed=[], modified=None)})
AddressbookGroupWasDeleted
This notification is sent when a group is deleted.
Subscription settings¶
Both Contact
and Policy
objects have presence and dialog attributes, which contain the presence and dialog settings respectively. Both objects have the same API:
attributes:
policy:
The value for the policy. It can be 'allow', 'block' or 'default'.
subscribe:
Boolean value indicating if the user desires to subscribe to the contact's presence.