SIP SIMPLE Client SDK

= Middleware API =

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

This chapter describes the event driven ''Middleware API'' that can be used by a developer to build a user interface for SIP SIMPLE client SDK.  

 * For sub-systems communications the Middleware uses the [http://pypi.python.org/pypi/python-application/ Notification Bus] provided by [http://pypi.python.org/pypi/python-application/ python-application]

 * For configuration the Middleware uses the [wiki:SipConfigurationAPI Configuration API] to access General and SIP account  settings

To see a working example for how to use Middleware, see the [http://sipsimpleclient.com/wiki/SipTesting#TestingGuide Command Line Tools] provided with the library.

[[Image(sipsimple-middleware.png, align=center, width=800)]]

== High-level audio API ==

The high-level audio API hides the complexity of using the low-level PJMEDIA interface. This is implemented in the {{{sipsimple.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 [wiki:SipCoreApiDocumentation#AudioMixer 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 [wiki:SipCoreApiDocumentation#AudioMixer 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.

  [[BR]]consumer_slot_changed:[[BR]]

  A bool indicating whether the consumer slot was changed.

  [[BR]]producer_slot_changed:[[BR]]

  A bool indicating whether the producer slot was changed.

  [[BR]]old_consumer_slot:[[BR]]

  The old slot for consuming audio data. Only required if consumer_slot_changed is {{{True}}}.

  [[BR]]new_consumer_slot:[[BR]]

  The new slot for consuming audio data. Only required if consumer_slot_changed is {{{True}}}.

  [[BR]]old_producer_slot:[[BR]]

  The old slot for producing audio data. Only required if producer_slot_changed is {{{True}}}.

  [[BR]]new_producer_slot:[[BR]]

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

  [[BR]]mixer:[[BR]]

  The {{{AudioMixer}}} whose physical device this object represents.

  [[BR]]input_muted:[[BR]]

  A boolean which indicates whether this object should act as a producer of audio data.

  [[BR]]output_muted:[[BR]]

  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 the {{{AudioBridges}}} 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  the {{{AudioBridges}}} 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 specified {{{AudioMixer}}} 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 an {{{AudioBridge}}}; thus, this object acts like a set.

 '''remove'''(''self'', '''port''')::

  Remove a port from this {{{AudioBridge}}}. The port must have previously been added to the {{{AudioBridge}}}, otherwise a {{{ValueError}}} 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.

  [[BR]]mixer:[[BR]]

  The {{{AudioMixer}}} this object is connected to.

  [[BR]]filename:[[BR]]

  The full path to the {{{.wav}}} file from which audio data is to be read.

  [[BR]]volume:[[BR]]

  The volume at which the file should be played.

  [[BR]]loop_count:[[BR]]

  The number of times the file should be played, or {{{0}}} for infinity.

  [[BR]]pause_time:[[BR]]

  How many seconds to wait between successive plays of the file. 

  [[BR]]initial_play:[[BR]]

  Whether or not the file to play once the {{{WavePlayer}}} is started, or to wait {{{pause_time}}} seconds before the first play.

 '''start'''(''self'')::

  Start playing the {{{.wav}}} file.

 '''stop'''(''self'')::

  Stop playuing the {{{.wav}}} file immediately.

==== 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 the {{{start()}}} method has been called.

  [[BR]]timestamp:[[BR]]

  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 the {{{stop()}}} method has been called.

  [[BR]]timestamp:[[BR]]

  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.

  [[BR]]timestamp:[[BR]]

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

  [[BR]]error:[[BR]]

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

  [[BR]]mixer:[[BR]]

  The {{{AudioMixer}}} this {{{WaveRecorder}}} is connected to.

  [[BR]]filename:[[BR]]

  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 the {{{start()}}} method is called.

 '''start'''(''self'')::

  Start consuming audio data and writing it to the {{{.wav}}} file. If this object is not part of an {{{AudioBridge}}}, 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.

== SIPApplication ==

Implemented in [browser:sipsimple/application.py]

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

 * the twisted thread

 * the configuration system, via the [wiki:SipConfigurationAPI#ConfigurationManager ConfigurationManager].

 * the core [wiki:SipCoreApiDocumentation#Engine Engine] using the settings in the configuration

 * the [wiki:SipMiddlewareApi#AccountManager AccountManager], using the accounts in the configuration

 * two [wiki:SipMiddlewareApi#AudioBridge 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'', '''config_backend''')::

  Starts the {{{SIPApplication}}} which initializes all the components in the correct order. The {{{config_backend}}} is used to start the {{{ConfigurationManager}}}. If any error occurs with loading the configuration, the exception raised by the {{{ConfigurationManager}}} is propagated by this method and {{{SIPApplication}}} can be started again. After this, any fatal errors will result in the SIPApplication being stopped and unusable, which means the whole application will need to stop. This method returns as soon as the twisted thread has been started, which means the application must wait for the {{{SIPApplicationDidStart}}} notification in order to know that the application started.

 '''stop'''(''self'')::

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

=== Attributes ===

 '''running'''::

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

 '''alert_audio_mixer'''::

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

 '''alert_audio_bridge'''::

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

 '''alert_audio_device'''::

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

 '''voice_audio_mixer'''::

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

 '''voice_audio_bridge'''::

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

 '''voice_audio_device'''::

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

=== Notifications  ===

 '''SIPApplicationWillStart'''::

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

  [[BR]]timestamp:[[BR]]

  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.

  [[BR]]timestamp:[[BR]]

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

 '''SIPApplicationWillEnd'''::

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

  [[BR]]timestamp:[[BR]]

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

  [[BR]]timestamp:[[BR]]

  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.

  [[BR]]timestamp:[[BR]]

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

  [[BR]]error:[[BR]]

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

== Session ==

[[Image(sipsimple-session-state-machine.png, align=right, width=400)]]

Implemented in [browser:sipsimple/session.py]

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

A {{{Session}}} instance is a stateful object, meaning that it has a {{{state}}} attribute and that the lifetime of the session traverses different states, from session creation to termination.

State changes are triggered by methods called on the object by the application or by received network events.

Every time this attribute changes, a {{{SIPSessionChangedState}}} notification is sent by the object.

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 different set of notifications is also emitted, which provide all the necessary information to the application.

=== Attributes ===

 '''state'''::

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

 '''account'''::

  The {{{sipsimple.account.Account}}} or {{{sipsimple.account.BonjourAccount}}} object that the {{{Session}}} is associated with.

  On an outbound session, this is the account the application specified on object instantiation.

 '''direction'''::

  A string indicating the direction of the initial negotiation of the session.

  This can be either {{{None}}}, "incoming" or "outgoing".

 '''start_time'''::

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

 '''stop_time'''::

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

 '''on_hold_by_local'''::

  Boolean indicating whether the session was put on hold by the local party.

 '''on_hold_by_remote'''::

  Boolean indicating whether the session was put on hold by the remote party.

 '''on_hold'''::

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

 '''remote_user_agent'''::

  A string indicating the remote user agent, if it provided one.

  Initially this will be {{{None}}}, it will be set as soon as this information is received from the remote party (which may be never).

 '''local_uri'''::

  The {{{sipsimple.core.SIPURI}}} of the local party, if the session is active.

 '''remote_uri'''::

  The {{{sipsimple.core.SIPURI}}} of the remote party, if the session is active.

 '''caller_uri'''::

  The {{{sipsimple.core.SIPURI}}} of the calling party, if the session is active.

  Depending on the direction, this is either {{{local_uri}}} or {{{remote_uri}}}.

 '''callee_uri'''::

  The {{{sipsimple.core.SIPURI}}} of the called party, if the session is active.

  Depending on the direction, this is either {{{local_uri}}} or {{{remote_uri}}}.

 '''route'''::

  A copy of the {{{sipsimple.core.Route}}} object passed when the {{{connect()}}} method was called.

  On incoming or inactive sessions this is {{{None}}}.

 '''audio_transport'''::

  The {{{sipsimple.core.AudioTransport}}} object used by the session, if it currently contains an audio stream.

  Normally the application will not need to access this directly.

 '''has_audio'''::

  A boolean indicating if this {{{Session}}} currently has an active audio stream.

 '''audio_sample_rate'''::

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

 '''audio_codec'''::

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

 '''audio_srtp_active'''::

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

 '''audio_local_rtp_address'''::

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

 '''audio_local_rtp_port'''::

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

 '''audio_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.

 '''audio_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.

 '''audio_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.

 '''audio_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.

 '''audio_was_received'''::

  This boolean property indicates if audio was actually received on the audio stream contained within this session.

 '''audio_recording_file_name'''::

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

 '''chat_transport'''::

  The {{{sipsimple.msrp.MSRPChat}}} object used by the session as chat transport, if the session currently contains a chat stream.

  Normally the application will not need to access this directly.

 '''has_chat'''::

  A boolean property indicating if this {{{Session}}} currently has an active chat stream.

=== Methods ===

 '''!__init!__'''(''self'', '''account''')::

  Creates a new {{{Session}}} object in the {{{NULL}}} state.

  [[BR]]''account'':[[BR]]

  The local account to be associated with this {{{Session}}}.

 '''connect'''(''self'', '''callee_uri''', '''routes''', '''audio'''={{{False}}}, '''chat'''={{{False}}})::

  Will set up the {{{Session}}} as outbound and propose the new session to the specified remote party and move the state machine to the {{{CALLING}}} state.

  Before contacting the remote party, a {{{SIPSessionNewOutgoing}}} notification will be emitted.

  If there is a failure or the remote party rejected the offer, a {{{SIPSessionDidFail}}} notification will be sent, followed by a {{{SIPSessionDidEnd}}}.

  Any time a ringing indication is received from the remote party, a {{{SIPSessionGotRingIndication}}} notification is sent.

  If the remote party accepted the session, a {{{SIPSessionWillStart}}} notification will be sent, followed by a {{{SIPSessionDidStart}}} notification when the session is actually established.

  This method may only be called while in the {{{NULL}}} state.

  [[BR]]''callee_uri'':[[BR]]

  A {{{sipsimple.core.SIPURI}}} object representing the remote host to initiate the session to.

  [[BR]]''routes'':[[BR]]

  An iterable of {{{sipsimple.core.Route}}} objects, specifying the IP, port and transport to the outbound proxy.

  These routes will be tried in order, until one of them succeeds.

  [[BR]]''audio'':[[BR]]

  A boolean indicating whether an audio stream should be initially included in this session.

  [[BR]]''chat'':[[BR]]

  A boolean indicating whether a chat stream should be initially included in this session.

 '''accept'''(''self'', '''audio'''={{{False}}}, '''chat'''={{{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, a {{{SIPSessionNewIncoming}}} notification is sent, after which the application can call this method on the sender of the notification.

  After this method is called, {{{SIPSessionWillStart}}} followed by {{{SIPSessionDidStart}}} will be emitted, or {{{SIPSessionDidFail}}} followed by {{{SIPSessionDidEnd}}} on an error.

  This method may only be called while in the {{{INCOMING}}} state.

  [[BR]]''audio'':[[BR]]

  A boolean indicating whether an audio stream should be accepted for this session.

  Note that this may only be set to {{{True}}} if an audio stream was actually proposed by the remote party.

  [[BR]]''chat'':[[BR]]

  A boolean indicating whether a chat stream should be accepted for this session.

  Note that this may only be set to {{{True}}} if a chat stream was actually proposed by the remote party.

 '''reject'''(''self'', '''is_busy'''={{{False}}})::

  Reject an incoming session and move it to the {{{TERMINATING}}} state, which eventually leads to the {{{TERMINATED}}} state.

  Calling this method will cause the {{{Session}}} object to emit a {{{SIPSessionWillEnd}}} notification, followed by a {{{SIPSessionDidEnd}}} notification.

  This method may only be called while in the {{{INCOMING}}} state.

  [[BR]]''chat'':[[BR]]

  A boolean indicating whether the response code sent to the remote party should be 486 (Busy) instead of 603 (Decline).

 '''hold'''(''self'')::

  Put the session on hold.

  This will cause a {{{SIPGotHoldRequest}}} notification to be sent.

  This method may only be called while in the {{{ESTABLISHED}}} state.

 '''unhold'''(''self'')::

  Take the session out of hold.

  This will cause a {{{SIPGotUnholdRequest}}} notification to be sent.

  This method may only be called while in the {{{ESTABLISHED}}} state.

 '''start_recording_audio'''(''self'', '''file_name'''={{{None}}})::

  If an audio stream is present within this session, calling this method will record the audio to a {{{.wav}}} file.

  Note that when the session is on hold, nothing will be recorded to the file.

  Right before starting the recording a {{{SIPSessionWillStartRecordingAudio}}} notification will be emitted, followed by a {{{SIPSessionDidStartRecordingAudio}}}.

  This method may only be called while in the {{{ESTABLISHED}}} state.

  [[BR]]''file_name'':[[BR]]

  The name of the {{{.wav}}} file to record to.

  If this is set to {{{None}}}, a default file name including the session participants and the timestamp will be generated.

 '''stop_recording_audio'''(''self'')::

  This will stop a previously started recording.

  Before stopping, a {{{SIPSessionWillStopRecordingAudio}}} notification will be sent, followed by a {{{SIPSessionDidStopRecordingAudio}}}.

  This method may only be called while in the {{{ESTABLISHED}}} state.

 '''send_dtmf'''(''self'', '''digit''')::

  If this session currently has an active audio stream, send a DTMF digit to the remote party over it.

  This method may only be called while in the {{{ESTABLISHED}}} state and if the session has an active audio stream.

  [[BR]]''digit'':[[BR]]

  This should a string of length 1, containing a valid DTMF digit value.

 '''send_message'''(''self'', '''content''', '''content_type'''="text/plain", '''to_uri'''={{{None}}}, '''dt'''={{{None}}})::

  If this session currently has an active MSRP chat with the remote party, send a message over with the with the specified parameters.

  This will result in either a {{{SIPSessionDidDeliverMessage}}} or a {{{SIPSessionDidNotDeliverMessage}}} notification being sent.

  These notifications include a unique ID as data attribute which is also returned by this method.

  This method may only be called while in the {{{ESTABLISHED}}} state.

  [[BR]]''content'':[[BR]]

  The body of the MSRP message as a string.

  [[BR]]''content_type'':[[BR]]

  The Content-Type of the body as a string

  [[BR]]''to_uri'':[[BR]]

  The {{{sipsimple.core.SIPURI}}} that should be put in the {{{To:}}} header of the CPIM wrapper of the message.

  This defaults to the SIP URI of the remote party of the session if the argument is set to {{{None}}}

  [[BR]]''dt'':[[BR]]

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

  When set to {{{None}}}, this defaults to now.

 '''add_audio'''(''self'')::

  Propose the remote party to add an audio stream to this session.

  Calling this method will cause a {{{SIPSessionGotStreamProposal}}} notification to be emitted.

  After this, the state machine will move into the {{{PROPOSING}}} state until either a {{{SIPSessionAcceptedStreamProposal}}} or {{{SIPSessionRejectedStreamProposal}}} notification is sent, informing the application if the remote party accepted the proposal.

  This method may only be called while in the {{{ESTABLISHED}}} state on a {{{Session}}} object that does not currently have an audio stream.

 '''remove_audio'''(''self'')::

  Stop the audio stream currently active within the session and inform the remote party of this.

  This method may only be called while in the {{{ESTABLISHED}}} state on a {{{Session}}} object that has an audio stream.

 '''add_chat'''(''self'')::

  Propose the remote party to add a chat stream to this session.

  Calling this method will cause a {{{SIPSessionGotStreamProposal}}} notification to be emitted.

  After this, the state machine will move into the {{{PROPOSING}}} state until either a {{{SIPSessionAcceptedStreamProposal}}} or {{{SIPSessionRejectedStreamProposal}}} notification is sent, informing the application if the remote party accepted the proposal.

  This method may only be called while in the {{{ESTABLISHED}}} state on a {{{Session}}} object that does not currently have a chat stream.

 '''remove_chat'''(''self'')::

  Stop the chat stream currently active within the session and inform the remote party of this.

  This method may only be called while in the {{{ESTABLISHED}}} state on a {{{Session}}} object that has a chat stream.

 '''accept_proposal'''(''self'', '''audio'''={{{False}}}, '''chat'''={{{False}}})::

  When the remote party proposes to add a new stream, signaled by the {{{SIPSessionGotStreamProposal}}} notification, the application can use this method to accept the stream(s) being proposed.

  After calling this method a {{{SIPSessionAcceptedStreamProposal}}} notification is sent, unless an error occurs while setting up the new stream, in which case a {{{SIPSessionRejectedStreamProposal}}} notification is sent and a rejection is sent to the remote party.

  This method may only be called while in the {{{PROPOSED}}} state.

  [[BR]]''audio'':[[BR]]

  A boolean indicating whether an audio stream should be accepted for this proposal.

  Note that this may only be set to {{{True}}} if an audio stream was actually proposed by the remote party.

  [[BR]]''chat'':[[BR]]

  A boolean indicating whether a chat stream should be accepted for this proposal.

  Note that this may only be set to {{{True}}} if a chat stream was actually proposed by the remote party.

 '''reject_proposal'''(''self'')::

  When the remote party proposes (a) stream(s) that the application does not want to accept, this method can be used to reject the proposal, after which a {{{SIPSessionRejectedStreamProposal}}} notification is sent.

  This method may only be called while in the {{{PROPOSED}}} state.

 '''end'''(''self'' '''is_busy'''={{{False}}})::

  This method may be called any time when the {{{Session}}} object is active (i.e. not in the {{{NULL}}}, {{{TERMINATING}}} or {{{TERMINATED}}} states) in order to terminate the session.

  Right before termination a {{{SIPSessionWillEnd}}} notification is sent, after termination {{{SIPSessionDidEnd}}} is sent.

  [[BR]]''chat'':[[BR]]

  A boolean indicating whether the response code sent to the remote party should be 486 (Busy) instead of 603 (Decline).

=== Notifications ===

 '''SIPSessionChangedState'''::

  Will be sent whenever the {{{Session}}} object changes its state.

  [[BR]]''timestamp'':[[BR]]

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

  [[BR]]''prev_state'':[[BR]]

  The previous state state the object was in.

  [[BR]]''state'':[[BR]]

  The new state the object is in.

 '''SIPSessionNewIncoming'''::

  Will be sent when a new incoming {{{Session}}} is received.

  The application should listen for this notification from all objects specifically to get informed of incoming sessions.

  [[BR]]''timestamp'':[[BR]]

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

  [[BR]]''streams'':[[BR]]

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

 '''SIPSessionNewOutgoing'''::

  Will be sent when the applcation requests a new outgoing {{{Session}}}.

  [[BR]]''timestamp'':[[BR]]

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

  [[BR]]''streams'':[[BR]]

  A list of strings indicating the 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.

  [[BR]]''timestamp'':[[BR]]

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

 '''SIPSessionWillStart'''::

  Will be sent just before a {{{Session}}} completes negotiation.

  In terms of SIP, this is sent after the final response to the {{{INVITE}}}, but before the {{{ACK}}}.

  [[BR]]''timestamp'':[[BR]]

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

 '''SIPSessionDidStart'''::

  Will be sent when a {{{Session}}} completes negotiation.

  In terms of SIP this is sent after the {{{ACK}}} was sent or received.

  [[BR]]''timestamp'':[[BR]]

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

 '''SIPSessionDidFail'''::

  This notification is sent whenever the session fails.

  The failure reason is included in the data attributes.

  This notification is always followed by {{{SIPSessionDidEnd}}}.

  [[BR]]''timestamp'':[[BR]]

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

  [[BR]]''originator'':[[BR]]

  A string indicating the origin of the failure.

  This will either be "local" or "remote".

  [[BR]]''code'':[[BR]]

  The SIP error code of the failure.

  If this is 0, the error was an internal exception.

  [[BR]]''reason'':[[BR]]

  A string explaining the reason of the failure.

 '''SIPSessionWillEnd'''::

  Will be sent just before terminating a {{{Session}}} at the request of the application.

  [[BR]]''timestamp'':[[BR]]

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

 '''SIPSessionDidEnd'''::

  Will be sent always when a {{{Session}}} ends, either because of a failure (in which case it is preceded by {{{SIPSessionDidFail}}}), remote or local session termination.

  [[BR]]''timestamp'':[[BR]]

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

  [[BR]]''originator'':[[BR]]

  A string indicating who originated the termination.

  This will either be "local" or "remote".

 '''SIPSessionGotHoldRequest'''::

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

  [[BR]]''timestamp'':[[BR]]

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

  [[BR]]''originator'':[[BR]]

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

 '''SIPSessionGotUnholdRequest'''::

  Will be sent when the session got taken out of hold, either by the local or the remote party.

  [[BR]]''timestamp'':[[BR]]

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

  [[BR]]''originator'':[[BR]]

  A string indicating who sent the original hold request, and consequently in which direction the session got taken out of hold.

 '''SIPSessionWillStartRecordingAudio'''::

  Will be sent when the application requested that the audio stream active within the session be record to a {{{.wav}}} file, just before recording starts.

  [[BR]]''timestamp'':[[BR]]

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

  [[BR]]''file_name'':[[BR]]

  The name of the recording {{{.wav}}} file, including full path.

 '''SIPSessionDidStartRecordingAudio'''::

  Will be sent when the application requested that the audio stream active within the session be record to a {{{.wav}}} file, just after recording starts.

  [[BR]]''timestamp'':[[BR]]

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

  [[BR]]''file_name'':[[BR]]

  The name of the recording {{{.wav}}} file, including full path.

 '''SIPSessionWillStopRecordingAudio'''::

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

  [[BR]]''timestamp'':[[BR]]

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

  [[BR]]''file_name'':[[BR]]

  The name of the recording {{{.wav}}} file, including full path.

 '''SIPSessionDidStopRecordingAudio'''::

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

  [[BR]]''timestamp'':[[BR]]

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

  [[BR]]''file_name'':[[BR]]

  The name of the recording {{{.wav}}} file, including full path.

 '''SIPSessionGotNoAudio'''::

  This notification will be sent if 5 seconds after the audio stream starts, no audio was received from the remote party.

  [[BR]]''timestamp'':[[BR]]

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

 '''SIPSessionGotDTMF'''::

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

  [[BR]]''timestamp'':[[BR]]

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

  [[BR]]''digit'':[[BR]]

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

 '''SIPSessionGotMessage'''::

  Will be sent whenever a MSRP message is received on the chat stream of the session.

  [[BR]]''content'':[[BR]]

  The body of the message.

  [[BR]]''content_type'':[[BR]]

  The Content-Type of the body.

  [[BR]]''cpim_headers'':[[BR]]

  A dictionary of headers included in the CPIM wrapper.

  [[BR]]''message'':[[BR]]

  Raw MSRP message, an msrplib.protocol.MSRPData instance

 '''SIPSessionDidDeliverMessage'''::

  Will be sent when a previously sent MSRP chat message got delivered to the remote party.

  [[BR]]''message_id'':[[BR]]

  The unique identifier of this message as a string, as previously returned by the {{{send_message()}}} method.

  [[BR]]''code'':[[BR]]

  The response code of the confirmation report.

  [[BR]]''reason'':[[BR]]

  The reason string of the confirmation report.

  [[BR]]''message'':[[BR]]

  Raw MSRP message, an msrplib.protocol.MSRPData instance

 '''SIPSessionDidDeliverMessage'''::

  Will be sent when a previously sent MSRP chat message did not get delivered to the remote party.

  [[BR]]''message_id'':[[BR]]

  The unique identifier of this message as a string, as previously returned by the {{{send_message()}}} method.

  [[BR]]''code'':[[BR]]

  The response code of the confirmation report.

  [[BR]]''reason'':[[BR]]

  The reason string of the confirmation report.

  [[BR]]''message'':[[BR]]

  Raw MSRP message, an msrplib.protocol.MSRPData instance

 '''SIPSessionGotStreamProposal'''::

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

  [[BR]]''timestamp'':[[BR]]

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

  [[BR]]''proposer'':[[BR]]

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

  [[BR]]''streams'':[[BR]]

  A list of strings indicating the streams that were proposed.

 '''SIPSessionRejectedStreamProposal'''::

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

  [[BR]]''timestamp'':[[BR]]

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

  [[BR]]''proposer'':[[BR]]

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

  [[BR]]''reason'':[[BR]]

  The reason for rejecting the stream proposal.

 '''SIPSessionRejectedStreamProposal'''::

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

  [[BR]]''timestamp'':[[BR]]

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

  [[BR]]''proposer'':[[BR]]

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

 '''SIPSessionGotStreamUpdate'''::

  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.

  [[BR]]''timestamp'':[[BR]]

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

  [[BR]]''streams'':[[BR]]

  A list indicating which streams are active on the session from this point onwards.

As an example for how to use the {{{Session}}} object, the following provides a basic Python program that initiates an outgoing SIP session request:

{{{

import sys

from threading import Event

from zope.interface import implements

from application.notification import IObserver, NotificationCenter

from sipsimple.configuration import ConfigurationManager

from sipsimple.account import AccountManager

from sipsimple.engine import Engine

from sipsimple.session import Session

from sipsimple.core import SIPURI, Route

class SimpleOutboundCall(object):

    # indicate that we implement the application.notification.IObserver interface

    implements(IObserver)

    def __init__(self, remote_uri, route):

        # setup a threading.Event to signal that the Engine has stopped

        self.engine_ended_event = Event()

        # start the configuration manager

        ConfigurationManager().start()

        # start the account manager

        am = AccountManager()

        am.start()

        # start the Engine with configuration framework parameters

        Engine().start_cfg()

        # create a new Session using the default account

        self.session = Session(am.default_account)

        # listen for the notification that the Engine stopped

        NotificationCenter().add_observer(self, "SIPEngineDidEnd", Engine())

        # listen for the notification that the Session ended

        NotificationCenter().add_observer(self, "SIPSessionDidEnd", self.session)

        # start a new outbound session

        self.session.connect(remote_uri, [route], audio=True)

    def end(self):

        # if the Session is still active, terminate it

        self.session.end()

        # wait for the engine to stop, processed in handle_notification

        self.engine_ended_event.wait()

        # quit the progam, as this can only be done from the main thread

        sys.exit()

    def handle_notification(self, notification):

        if notification.name == "SIPSessionDidEnd":

            # if for whatever reason the session ended, stop the Engine

            print "Session ended"

            Engine().stop()

        elif notification.name == "SIPEngineDidEnd":

            # once the Engine has stopped, signal the (possibly) waiting main

            # thread through a threading.Event

            self.engine_ended_event.set()

# place an audio call from the specified account to the specified URI, through

# the specified SIP proxy

# edit this to reflect real settings

call = SimpleOutboundCall(SIPURI(user="bob", host="example.com"), Route("1.2.3.4"))

# block waiting for user input

print "Placing call, press enter to quit program"

raw_input()

# block in end() until the Engine has stopped

call.end()

}}}

== SessionManager ==

Implemented in [browser:sipsimple/session.py]

The {{{sipsimple.session.SessionManager}}} class is a singleton, which acts as the central aggregation point for sessions within the middleware.

Although it is mainly used internally, the application can use it to query information about all active sessions.

The SessionManager is implemented as a singleton, meaning that only one instance of this class exists within the middleware.

Note that, in order to be able to receive calls, the application has to instantiate this object.

=== Attributes ===

 '''sessions'''::

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

=== Methods ===

 '''!__init!__'''(''self'')::

  This either returns a new {{{SessionManager}}} object with default configuration objects, or returns a copy of the already existing instance.

== Account ==

Implemented in [browser:sipsimple/account.py]

The {{{sipsimple.account.Account}}} objects represent the SIP accounts which are used by the middleware. 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 [wiki:SipConfigurationAPI#Account 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 [wiki:SipMiddlewareApi#AccountManager 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.registration.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'' event and the publication of data in this event. (Not implemented yet)

 '''Account.dialog_event.enabled'''::

  This flag controls the automatic subscription to buddies for the ''dialog-info'' event and the publication of data in this event. (Not implemented yet)

 '''Account.message_summary.enabled'''::

  This flag controls the automatic subscription to the ''message-summary'' event in order to find out about voicemail messages. (Not implemented yet)

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 [wiki:SipConfigurationAPI#SettingsObject 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 of {{{str}}}) 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 attributes {{{username}}} and {{{domain}}}.

  {{{

  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.account.ContactURI}}} which is a subclass of {{{sipsimple.configuration.datatypes.SIPAddress}}}. In addition to the attributes defined in {{{SIPAddress}}}, it can be indexed by a string representing a transport ({{{'udp'}}}, {{{'tcp'}}} or {{{'tls'}}}) which will return a {{{sipsimple.core.SIPURI}}} object with the appropriate port and transport parameter. The username part is a randomly generated 8 character string consisting of lowercase letters; the domain part is the IP address on which the {{{Engine}}} is listening (as specified by the SIPSimpleSettings.local_ip setting).

  {{{

  account.contact # 'hnfkybrt@10.0.0.1'

  account.contact.username # 'hnfkybrt'

  account.contact.domain # '10.0.0.1'

  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}}} object which is built from the {{{id}}} attribute and {{{display_name}}} and {{{password}}} settings of the Account. Whenever one of these settings are changed, this attribute is updated.

  {{{

  account.credentials # <Credentials for '"Alice" <sip:alice@example.com>'>

  }}}

=== 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 the {{{SettingsObject}}} class, it is exaplained in detail in [wiki:SipConfigurationAPI#SettingsObjectNotifications SettingsObject Notifications].

 '''SIPAccountDidActivate'''::

  This notification is sent when the {{{Account}}} activates. This can happen when the {{{Account}}} 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. The notification does not contain any data.

 '''SIPAccountDidDeactivate'''::

  This notification is sent when the {{{Account}}} deactivates. This can happend when the {{{Engine}}} is stopped or when the enabled flag of the account is set to {{{False}}}. The notification does not contain any data.

 '''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:

  [[BR]]''code'':[[BR]]

   The status code of the response for the REGISTER request.

  [[BR]]''reason'':[[BR]]

   The reason of the response for the REGISTER request.

  [[BR]]''contact_uri'':[[BR]]

   The Contact URI which was registered.

  [[BR]]''contact_uri_list'':[[BR]]

   A list containing all the contact URIs registered for this SIP account.

  [[BR]]''expires'':[[BR]]

   The amount in seconds in which this registration will expire.

  [[BR]]''registration'':[[BR]]

   The {{{sipsimple.core.Registration}}} object used to register this account.

 '''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:

  [[BR]]''code'':[[BR]]

   The status code of the response for the REGISTER request. This is only present if the notification is sent as a result of a response being received.

  [[BR]]''reason'':[[BR]]

   The reason for the failure of the REGISTER request.

  [[BR]]''registration'':[[BR]]

   The {{{sipsimple.core.Registration}}} object which failed.

  [[BR]]''next_route'':[[BR]]

   A {{{sipsimple.core.Route}}} object which will be tried next for registering the account, or {{{None}}} if a new DNS lookup needs to be performed.

  [[BR]]''delay'':[[BR]]

   The amount in seconds as a {{{float}}} after which the next route will be tried for registering the account.

 '''SIPAccountRegistrationDidEnd'''::

  This notification is sent when a registration is ended (the account is unregistered). The data contained in this notification is:

  [[BR]]''code'':[[BR]]

   The status code of the response for the REGISTER with {{{Expires: 0}}} request. This is only present if a response was received.

  [[BR]]''reason'':[[BR]]

   The reason returned in the response for the Register with {{{Expires: 0}}} request. This is only present if a response was received

  [[BR]]''registration'':[[BR]]

   The {{{sipsimple.core.Registration}}} object which ended.

== BonjourAccount ==

Implemented in [browser:sipsimple/account.py]

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}}} flags 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. (Not implemented yet)

=== Attributes ===

The following attributes can be used on an BonjourAccount object and need to be considered read-only.

 '''id'''::

  This attribute is of type {{{sipsimple.configuration.datatypes.SIPAddress}}} (a subclass of {{{str}}}) 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 attributes {{{username}}} and {{{domain}}}.

  {{{

  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.ContactURI}}} which is a subclass of {{{sipsimple.configuration.datatypes.SIPAddress}}}. In addition to the attributes defined in {{{SIPAddress}}}, it can be indexed by a string representing a transport ({{{'udp'}}}, {{{'tcp'}}} or {{{'tls'}}}) which will return a {{{sipsimple.core.SIPURI}}} object with the appropriate port and transport parameter. The username part is a randomly generated 8 character string consisting of lowercase letters; the domain part is the IP address on which the {{{Engine}}} is listening (as specified by the SIPSimpleSettings.local_ip setting).

  {{{

  account.contact # 'lxzvgack@10.0.0.1'

  account.contact.username # 'lxzvgack'

  account.contact.domain # '10.0.0.1'

  account.contact['udp'] # <SIPURI "sip:lxzvgack@10.0.0.1:53024">

  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 the {{{contact}}} attribute and {{{display_name}}} setting of the BonjourAccount; the password is set to the empty string. Whenever the display_name setting is changed, this attribute is updated.

  {{{

  account.credentials # <Credentials for '"Alice" <sip:lxzvgack@10.0.0.1>'>

  }}}

=== 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 the {{{SettingsObject}}} class, it is exaplained in detail in [wiki:SipConfigurationAPI#SettingsObjectNotifications SettingsObject Notifications].

 '''SIPAccountDidActivate'''::

  This notification is sent when the {{{BonjourAccount}}} activates. This can happen when the {{{BonjourAccount}}} 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. The notification does not contain any data.

 '''SIPAccountDidDeactivate'''::

  This notification is sent when the {{{BonjourAccount}}} deactivates. This can happend when the {{{Engine}}} is stopped or when the enabled flag of the account is set to {{{False}}}. The notification does not contain any data.

== AccountManager ==

Implemented in [browser:sipsimple/account.py]

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 the {{{AccountManager}}} to be instantiated without passing any parameters. A reference to the {{{AccountManager}}} 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 [wiki:SipConfigurationAPI#ConfigurationManager ConfigurationManager] has been started. A '''SIPAccountManagerDidAddAccount''' will be sent for each account loaded.

 '''stop'''(''self'')::

  Calling this method will deactivate all accounts managed by the {{{AccountManager}}}.

 '''has_account'''(''self'', '''id''')::

  This method returns {{{True}}} if an account which has the specifed SIP ID (must be a string) exists and {{{False}}} otherwise.

 '''get_account'''(''self'', '''id''')::

  Returns the account (either an {{{Account}}} instance or the {{{BonjourAccount}}} instance) with the specified SIP ID. Will raise a {{{KeyError}}} 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 a {{{sipsimple.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. The data contains a single attribute, {{{account}}} which is the account object which was added.

 '''SIPAccountManagerDidRemoveAccount'''::

  This notification is sent when an account is deleted using the {{{delete}}} method. The data contains a single attribute, {{{account}}} which is the account object which was deleted.

 '''SIPAccountManagerDidChangeDefaultAccount'''::

  This notification is sent when the default account changes. The notification contains two attributes:

  [[BR]]''old_account'':[[BR]]

   This is the account object which used to be the default account.

  [[BR]]''account'':[[BR]]

   This is the account object which is the new default account.

== IMediaStream ==

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

This module automatically registers media streams to a stream registry

allowing for a plug and play mechanism of various types of media negoticated

in a SIP session that can be added to this library by using a generic API.

For actual usage see rtp.py and msrp.py that implement media streams based

on their respective RTP and MSRP protocols.

=== Atributes ===

 '''type''' (class attribute)::

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

 '''priority'''::

 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

=== Methods ===

 '''!__init!__'''(''self'', ''account'')::

 Initializes the generic stream instance.

 '''new_from_sdp'''(''cls'', ''account'', ''remote_sdp'', ''stream_index'')::

 '''get_local_media'''(''self'', ''for_offer'')::

 '''initialize'''(''self'', ''session'', ''direction'')::

 Initializes the stream 

 '''start'''(''self'', ''local_sdp'', ''remote_sdp'', ''stream_index'')::

 Completes the stream related connection. [[BR]]

 When done, must fire StreamChatDidStart notification. 

 '''end'''(''self'')::

 Ends the stream.  When done, must fire StreamChatDidEnd notification. 

 '''validate_update'''(''self'', ''remote_sdp'', ''stream_index'')::

 '''update'''(''self'', ''local_sdp'', ''remote_sdp'', ''stream_index'')::

 '''deactivate'''(''self'')::

 '''hold'''(''self'')::

 Puts the stream on hold if supported by the stream. Typically used by audio and video streams.

 '''unhold'''(''self'')::

 Takes the stream off hold.

=== Notifications ===

These notifications must be generated by all streams in order for the upper layer (SIP session) to perform the right decissions.

 '''MediaStreamDidInitialize'''::

 Sent when the {{{Stream}}} instance is initialized

 '''MediaStreamDidStart'''::

 Sent when the {{{Stream}}} instance has started.

 '''MediaStreamDidFail'''::

 Sent when the {{{Stream}}} instance has failed.

 '''MediaStreamWillEnd'''::

 Sent before the {{{Stream}}} instance will end.

 '''MediaStreamDidEnd'''::

 Sent when the {{{Stream}}} instance did ended.

== MediaStreamRegistry ==

The MediaStream registry is used to register streams that can be automatically dealt with by the SIP session layer.

There are several pre-built streams based on the '''iMediaStream''' API:

 * {{{sipsimple.streams.msrp.MSRPStreamBase}}}  - MSRP base stream, all MSRP derived streams inherit this

 * {{{sipsimple.streams.msrp.ChatStream}}} - Chat stream based on MSRP 

 * {{{sipsimple.streams.msrp.FileSelector}}} - Helper for selecting a file for FileTransferStream

 * {{{sipsimple.streams.msrp.FileTransferStream}}} - File Transfer stream based on MSRP 

 * {{{sipsimple.streams.msrp.VNCConnectionError}}} - Helper class for DesktopSharingStream

 * {{{sipsimple.streams.msrp.DesktopSharingHandlerBase}}}  - Helper class for DesktopSharingStream

 * {{{sipsimple.streams.msrp.InternalVNCViewerHandler}}} - Helper class for DesktopSharingStream

 * {{{sipsimple.streams.msrp.InternalVNCViewerHandler}}}  - Helper class for DesktopSharingStream

 * {{{sipsimple.streams.msrp.ExternalVNCViewerHandler}}}  - Helper class for DesktopSharingStream

 * {{{sipsimple.streams.msrp.ExternalVNCServerHandler}}}  - Helper class for DesktopSharingStream

 * {{{sipsimple.streams.msrp.DesktopSharingStream}}} -  Desktop Sharing stream based on VNC over MSRP 

 * {{{sipsimple.streams.msrp.NotificationProxyLogger}}} - Helper class for handling MSRP library logs

These classes are used internally by [wiki:SipMiddlewareApi#Session Session], which provides the necessary methods to access their features. The notifications posted by these classes are also handled internally by [wiki:SipMiddlewareApi#Session Session]. The notifications that are relevant to the user are then reposted by the Session instance. Refer to [wiki:SipMiddlewareApi#Session Session documentation] for details on the Session API. 

== AudioStream ==

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

=== SDP Example ===

{{{

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

}}}

=== Atributes ===

 '''recording_file_name''' (class attribute)::

 '''sample_rate''' (class attribute)::

 '''local_rtp_address''' (class attribute)::

 '''local_rtp_port''' (class attribute)::

 '''remote_rtp_address''' (class attribute)::

 '''remote_rtp_port''' (class attribute)::

 '''srtp_active''' (class attribute)::

 '''statistics''' (class attribute)::

=== Methods ===

 '''send_dtmf'''(''digit'')::

 '''start_recording'''(''file_name=None'', ''separate=False'')::

 '''stop_recording'''()::

=== Notifications ===

 '''AudioStreamDidChangeHoldState'''::

 '''AudioStreamDidStartRecordingAudio'''::

 '''AudioStreamDidStopRecordingAudio'''::

 '''AudioStreamGotDTMF'''::

 '''AudioStreamWillStartRecordingAudio''::

 '''AudioStreamWillStopRecordingAudio'''::

== MSRPStreamBase ==

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

=== Atributes ===

 '''media_type'''::

 '''accept_types'''::

 '''accept_wrapped_types'''::

 '''use_msrp_session'''::

=== Notifications ===

 '''MSRPLibraryLog'''::

 '''MSRPTransportTrace'''::

== ChatStream ==

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

{{{sipsimple.streams.msrp.ChatStream}}} implements Instant Messaging (IM) over MSRP for the [wiki:SipMiddlewareApi middleware]. 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, {{{ChatStreamGotMessage}}} is posted

 * plays notification sounds on received/sent message

 * reacts to and composes iscomposing payloads

=== SDP Example ===

{{{

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'')::

 Initializes the ChatStream instance.

 '''initialize'''(''self'')::

 Initializes the MSRP connection; connects to the relay if necessary. When done, fires ChatStreamDidInitialize (with 'sdpmedia' attribute, containing the appropriate 'SDPMedia' instance)

 '''start'''(''self'', ''remote_media'')::

 Completes the MSRP connection establishment; this includes binding the MSRP session. [[BR]]

 When done, fires MSRPChatDidStart notification. At this point each incoming message is posted as a {{{ChatStreamGotMessage}}} notification

 '''end'''(''self'')::

 Closes the MSRP connection or cleans up after initialize(), whatever is necessary. [[BR]]

 Before doing anything posts {{{ChatStreamWillEnd}}} notification.

 When done, posts {{{ChatStreamDidEnd}}} notification. If there was an error, posts {{{ChatStreamDidFail}}} notification. 

 {{{ChatStreamDidEnd}}} notification will be posted anyway.

 '''send_message'''(''self'', ''content'', ''content_type''={{{'text/plain'}}}, ''to_uri''={{{None}}}, ''dt''={{{None}}})::

 Sends IM message. Prefer Message/CPIM wrapper if it is supported. If called before the connection was established, the messages will be

 queued until ChatStreamDidStart notification.

 Returns the generated MSRP chunk (MSRPData instance); to get Message-ID use its 'message_id' attribute.

 ''content'' str:[[BR]]

 content of the message

 ''to_uri'' SIPURI:[[BR]]

 "To" header of CPIM wrapper; use to override the default supplied to {{{__init__}}}.

 May only differ from the one supplied in __init__ if the remote party supports private messages. If it does not, {{{MSRPChatError}}} will be raised;

 ''content_type'' str:[[BR]]

 Content-Type of wrapped message if Message/CPIM is used (Content-Type of MSRP message is always Message/CPIM in that case);

 otherwise, Content-Type of MSRP message.

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

{{{

Failure-Report: partial

Success-Report: yes

}}}

 '''send_composing_indication'''(''self'', ''state'', ''refresh'', ''last_active=None'', ''remote_identity=None'')::

 Send is composing notification.

=== Notifications ===

To communicate with the middleware, MSRPChat class uses the notification system provided by the [http://pypi.python.org/pypi/python-application python-application] package.

 '''ChatStreamGotMessage'''::

 Sent whenever a new incoming message is received,

  [[BR]]''content'':[[BR]]

  The string that the remote user has typed.

  [[BR]]''content_type'':[[BR]]

  Content-Type of the user message.

  [[BR]]''cpim_headers'':[[BR]]

  A dictionary of CPIM headers. (Empty dictionary if no CPIM wrapper was used).

  [[BR]]''message'':[[BR]]

  A {{{msrplib.protocol.MSRPData}}} instance providing all the MSRP information about the chunk.

 '''ChatStreamDidDeliverMessage'''::

 Sent when a successful report is received.

  [[BR]]''message_id'':[[BR]]

  Text identifier of the message.

  [[BR]]''code'':[[BR]]

  Integer result code.

  [[BR]]''reason'':[[BR]]

  Text comment.

  [[BR]]''message'':[[BR]]

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

 '''ChatStreamDidNotDeliverMessage'''::

 Sent when a failure report of failure transaction response is received.

  [[BR]]''message_id'':[[BR]]

  Text identifier of the message.

  [[BR]]''code'':[[BR]]

  Integer result code.

  [[BR]]''reason'':[[BR]]

  Text comment.

  [[BR]]''message'':[[BR]]

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

 '''ChatStreamDidSendMessage'''::

 Sent when an outgoing message has been sent.

 '''ChatStreamGotComposingIndication'''::

 Sent when a iscomposing payload is received.

== FileTransferStream ==

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

=== SDP Example ===

{{{

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

=== Notifications ===

 '''FileTransferStreamDidDeliverChunk'''::

 '''FileTransferStreamDidFinish'''::

 '''FileTransferStreamDidNotDeliverChunk'''::

 '''FileTransferStreamGotChunk'''::

== DesktopSharingStream ==

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

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 [http://msrprelay.org 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. 

=== SDP Example ===

{{{

m=application 2855 TCP/TLS/MSRP *

a=path:msrps://10.0.1.19:2855/b599b22d1b1d6a3324c8;tcp

a=accept-types:application/x-rfb

a=setup:active

}}}

=== Methods ===

=== Notifications ===

 '''DesktopSharingHandlerDidFail'''::

 '''DesktopSharingStreamGotData'''::

=== Route ===

This class provides a means for the application using the SIP core to set the destination address, port and transport for a particular request, i.e. the outbound proxy.

As it is the application's responsibility to look this up and pass it as an argument for every SIP primitive class it creates.

The contents of the {{{Route}}} object will be placed in the {{{Route}}} header of the request.

As with the {{{SIPURI}}} object, the attributes of this object are the same as the arguments to the {{{__init__}}} method.

==== methods ====

 '''!__init!__'''(''self'', '''address''', '''port'''=5060, '''transport'''={{{None}}})::

  Creates the Route object with the specified parameters as attributes.

  Each of these attributes can be accessed on the object once instanced.

  [[BR]]''address'':[[BR]]

  The IPv4 address that the request in question should be sent to as a string.

  [[BR]]''port'':[[BR]]

  The port to send the requests to, represented as an int.

  [[BR]]''transport'':[[BR]]

  The transport to use, this can be a string of either "udp", "tcp" or "tls" (case insensitive), depending on what transports are enabled on the {{{PJSIPUA}}} object.

 '''copy'''(''self'')::

  Returns a copy of the {{{Route}}} object.