SipMiddlewareApi
Version 165 (Tijmen de Mes, 04/19/2012 05:01 pm) → Version 166/238 (Tijmen de Mes, 04/19/2012 05:02 pm)
h1. 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 [[SipConfigurationAPI|Configuration API]].
!={width:500px}sipsimple-middleware.png!
h2. 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 [[SipConfigurationAPI#ConfigurationManager|ConfigurationManager]]
* the core [[SipCoreApiDocumentation#Engine|Engine]] using the settings in the configuration
* the [[SipMiddlewareApi#AccountManager|AccountManager]], using the accounts in the configuration
* the [[SipMiddlewareApi#SessionManager|SessionManager]], in order to handle incoming sessions
* two [[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.
h4. methods
*<notextile>__init__</notextile>*(_self_)
>Instantiates a new SIPApplication.
*start*(_self_, *storage*)
>Starts the @SIPApplication@ which initializes all the components in the correct order. The @storage@ is saved as an attribute which other entities like the @Configuration Manager@ will use to take the appropriate backend. If any error occurs with loading the configuration, the exception raised by the @ConfigurationManager@ is propagated by this method and @SIPApplication@ can be started again. After this, any fatal errors will result in the SIPApplication being stopped and unusable, which means the whole application will need to stop. This method returns as soon as the twisted thread has been started, which means the application must wait for the @SIPApplicationDidStart@ notification in order to know that the application started.
*stop*(_self_)
>Stop all the components started by the SIPApplication. This method returns immediately, but a @SIPApplicationDidEnd@ notification is sent when all the components have been stopped.
h4. attributes
*running*
>@True@ if the SIPApplication is running (it has been started and it has not been told to stop), @False@ otherwise.
*storage*
>Holds an object which implements the @ISIPSimpleStorage@ interface which will be used to provide a storage facility to other middleware components.
*local_nat_type*
>String containing the detected local NAT type.
*alert_audio_mixer*
>The @AudioMixer@ object created on the alert audio device as defined by the configuration (by SIPSimpleSettings.audio.alert_device).
*alert_audio_bridge*
>An @AudioBridge@ where @IAudioPort@ objects can be added to playback sound to the alert device.
*alert_audio_device*
>An @AudioDevice@ which corresponds to the alert device as defined by the configuration. This will always be part of the alert_audio_bridge.
*voice_audio_mixer*
>The @AudioMixer@ object created on the voice audio device as defined by the configuration (by SIPSimpleSettings.audio.input_device and SIPSimpleSettings.audio.output_device).
*voice_audio_bridge*
>An @AudioBridge@ where @IAudioPort@ objects can be added to playback sound to the output device or record sound from the input device.
*voice_audio_device*
>An @AudioDevice@ which corresponds to the voice device as defined by the configuration. This will always be part of the voice_audio_bridge.
h4. 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.
h2. 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.
h3. 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.
h3. Provided implementations
Two storage implementations are provided: *FileStorage* and *MemoryStorage* both located in the *sipsimple.storage* module.
h2. 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 [[SipMiddlewareApi#MediaStreamRegistry|MediaStreamRegistry]].
h3. SessionManager
Implemented in [browser:sipsimple/session.py]
The @sipsimple.session.SessionManager@ class is a singleton, which acts as the central aggregation point for sessions within the middleware.
Although it is mainly used internally, the application can use it to query information about all active sessions.
The SessionManager is implemented as a singleton, meaning that only one instance of this class exists within the middleware. The SessionManager is started by the SIPApplication and takes care of handling incoming sessions and closing all sessions when SIPApplication is stopped.
h4. 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.
h4. methods
*<notextile>__init__</notextile>*(_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.
h3. Session
Implemented in [browser:sipsimple/session.py]
A @sipsimple.session.Session@ object represents a complete SIP session between the local and a remote endpoints. Both incoming and outgoing sessions are represented by this class.
A @Session@ instance is a stateful object, meaning that it has a @state@ attribute and that the lifetime of the session traverses different states, from session creation to termination. State changes are triggered by methods called on the object by the application or by received network events. These states and their transitions are represented in the following diagram:
!sipsimple-core-invite-state-machine-2.png!
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.
h4. methods
*<notextile>__init__</notextile>*(_self_, *account*)
>Creates a new @Session@ object in the @None@ state.
>+_account_+:
>>The local account to be associated with this @Session@.
*connect*(_self_, *to_header*, *routes*, *streams*, *is_focus*=@False@, *subject*=@None@)
>Will set up the @Session@ as outbound and propose the new session to the specified remote party and move the state machine to the @outgoing@ state.
>Before contacting the remote party, a @SIPSessionNewOutgoing@ notification will be emitted.
>If there is a failure or the remote party rejected the offer, a @SIPSessionDidFail@ notification will be sent.
>Any time a ringing indication is received from the remote party, a @SIPSessionGotRingIndication@ notification is sent.
>If the remote party accepted the session, a @SIPSessionWillStart@ notification will be sent, followed by a @SIPSessionDidStart@ notification when the session is actually established.
>This method may only be called while in the @None@ state.
>+_to_header_+:
>>A @sipsimple.core.ToHeader@ object representing the remote identity to initiate the session to.
>+_routes_+:
>>An iterable of @sipsimple.util.Route@ objects, specifying the IP, port and transport to the outbound proxy.
>>These routes will be tried in order, until one of them succeeds.
>+_streams_+:
>>A list of stream objects which will be offered to the remote endpoint.
>+_is_focus_+:
>>Boolean flag indicating if the @isfocus@ parameter should be added to the @Contact@ header according to RFC 4579.
>+_subject_+:
>>Session subject. If not None a @Subject@ header will be added with the specified value.
*send_ring_indication*(_self_)
>Sends a 180 provisional response in the case of an incoming session.
*accept*(_self_, *streams*)
>Calling this methods will accept an incoming session and move the state machine to the @accepting@ state.
>When there is a new incoming session, a @SIPSessionNewIncoming@ notification is sent, after which the application can call this method on the sender of the notification.
>After this method is called, @SIPSessionWillStart@ followed by @SIPSessionDidStart@ will be emitted, or @SIPSessionDidFail@ on an error.
>This method may only be called while in the @incoming@ state.
>+_streams_+:
>>A list of streams which needs to be a subset of the proposed streams which indicates which streams are to be accepted. All the other proposed streams will be rejected.
*reject*(_self_, *code*=@603@, *reason*=@None@)
>Reject an incoming session and move it to the @terminating@ state, which eventually leads to the @terminated@ state.
>Calling this method will cause the @Session@ object to emit a @SIPSessionDidFail@ notification once the session has been rejected.
>This method may only be called while in the @incoming@ state.
>+_code_+:
>>An integer which represents the SIP status code in the response which is to be sent. Usually, this is either 486 (Busy) or 603 (Decline/Busy Everywhere).
>+_reason_+:
>>The string which is to be sent as the SIP status reason in the response, or None if PJSIP's default reason for the specified code is to be sent.
*accept_proposal*(_self_, *streams*)
>When the remote party proposes to add some new streams, signaled by the @SIPSessionGotProposal@ notification, the application can use this method to accept the stream(s) being proposed.
>After calling this method a @SIPSessionGotAcceptProposal@ notification is sent, unless an error occurs while setting up the new stream, in which case a @SIPSessionHadProposalFailure@ notification is sent and a rejection is sent to the remote party. As with any action which causes the streams in the session to change, a @SIPSessionDidRenegotiateStreams@ notification is also sent.
>This method may only be called while in the @received_proposal@ state.
>+_streams_+:
>>A list of streams which needs to be a subset of the proposed streams which indicates which streams are to be accepted. All the other proposed streams will be rejected.
*reject_proposal*(_self_, *code*=@488@, *reason*=@None@)
>When the remote party proposes new streams that the application does not want to accept, this method can be used to reject the proposal, after which a @SIPSessionGotRejectProposal@ or @SIPSessionHadProposalFailure@ notification is sent.
>This method may only be called while in the @received_proposal@ state.
>+_code_+:
>>An integer which represents the SIP status code in the response which is to be sent. Usually, this is 488 (Not Acceptable Here).
>+_reason_+:
>>The string which is to be sent as the SIP status reason in the response, or None if PJSIP's default reason for the specified code is to be sent.
*add_stream*(_self_, *stream*)
>Proposes a new stream to the remote party.
>Calling this method will cause a @SIPSessionGotProposal@ notification to be emitted.
>After this, the state machine will move into the @sending_proposal@ state until either a @SIPSessionGotAcceptProposal@, @SIPSessionGotRejectProposal@ or @SIPSessionHadProposalFailure@ notification is sent, informing the application if the remote party accepted the proposal. As with any action which causes the streams in the session to change, a @SIPSessionDidRenegotiateStreams@ notification is also sent.
>This method may only be called while in the @connected@ state.
*remove_stream*(_self_, *stream*)
>Stop the stream and remove it from the session, informing the remote party of this. Although technically this is also done via an SDP negotiation which may fail, the stream will always get remove (if the remote party refuses the re-INVITE, the result will be that the remote party will have a different view of the active streams than the local party).
>This method may only be called while in the @connected@ state.
*cancel_proposal*(_self_)
>This method cancels a proposal of adding a stream to the session by sending a CANCEL request. A @SIPSessionGotRejectProposal@ notification will be sent with code 487.
*hold*(_self_)
>Put the streams of the session which support the notion of hold on hold.
>This will cause a @SIPSessionDidChangeHoldState@ notification to be sent.
>This method may be called in any state and will send the re-INVITE as soon as it is possible.
*unhold*(_self_)
>Take the streams of the session which support the notion of hold out of hold.
>This will cause a @SIPSessionDidChangeHoldState@ notification to be sent.
>This method may be called in any state and will send teh re-INVITE as soon as it is possible.
*end*(_self_)
>This method may be called any time after the @Session@ has started in order to terminate the session by sending a BYE request.
>Right before termination a @SIPSessionWillEnd@ notification is sent, after termination @SIPSessionDidEnd@ is sent.
*transfer*(_self_, *target_uri*, *replaced_session*=@None@)
>Proposes a blind call transfer to a new target URI or assisted transfer to an URI belonging to an already established session.
*accept_transfer*(_self_)
>Accepts an incoming call transfer request.
*reject_transfer*(_self_, *code*=@486@, *reason_=@None@)
>Rejects an incoming call transfer request.
h4. attributes
*state*
>The state the object is currently in, being one of the states from the diagram above.
*account*
>The @sipsimple.account.Account@ or @sipsimple.account.BonjourAccount@ object that the @Session@ is associated with.
>On an outbound session, this is the account the application specified on object instantiation.
*direction*
>A string indicating the direction of the initial negotiation of the session.
>This can be either @None@, "incoming" or "outgoing".
*transport*
>A string representing the transport this @Session@ is using: @"udp"@, @"tcp"@ or @"tls"@.
*start_time*
>The time the session started as a @datetime.datetime@ object, or @None@ if the session was not yet started.
*stop_time*
>The time the session stopped as a @datetime.datetime@ object, or @None@ if the session has not yet terminated.
*on_hold*
>Boolean indicating whether the session was put on hold, either by the local or the remote party.
*remote_user_agent*
>A string indicating the remote user agent, if it provided one.
>Initially this will be @None@, it will be set as soon as this information is received from the remote party (which may be never).
*local_identity*
>The @sipsimple.core.FrozenFromHeader@ or @sipsimple.core.FrozenToHeader@ identifying the local party, if the session is active, @None@ otherwise.
*remote_identity*
>The @sipsimple.core.FrozenFromHeader@ or @sipsimple.core.FrozenToHeader@ identifying the remote party, if the session is active, @None@ otherwise.
*streams*
>A list of the currently active streams in the @Session@.
*proposed_streams*
>A list of the currently proposed streams in the @Session@, or @None@ if there is no proposal in progress.
*conference*
>A @ConferenceHandler@ object instance (or Null). It can be later used to add/remove participants from a remote conference.
*subject*
>The session subject as a unicode object.
*replaced_session*
>A @Session@ object instance (or Null). It can be used for assisted call transfer.
*transfer_handler*
>A @TransferHandler@ object instance (or Null). It is used for managing the call transfer process.
*transfer_info*
>A @TransferInfo@ object instance (or Null). It is used for describing the details of a call transfer operation.
h4. notifications
*SIPSessionNewIncoming*
>Will be sent when a new incoming @Session@ is received.
>The application should listen for this notification to get informed of incoming sessions.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
>+_streams_+:
>>A list of streams that were proposed by the remote party.
*SIPSessionNewOutgoing*
>Will be sent when the application requests a new outgoing @Session@.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
>+_streams_+:
>>A list of streams that were proposed to the remote party.
*SIPSessionGotRingIndication*
>Will be sent when an outgoing @Session@ receives an indication that a remote device is ringing.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
*SIPSessionGotProvisionalResponse*
>Will be sent whenever the @Session@ receives a provisional response as a result of sending a (re-)INVITE.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
>+_code_+:
>>The SIP status code received.
>+_reason_+:
>>The SIP status reason received.
*SIPSessionWillStart*
>Will be sent just before a @Session@ completes negotiation.
>In terms of SIP, this is sent after the final response to the @INVITE@, but before the @ACK@.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
*SIPSessionDidStart*
>Will be sent when a @Session@ completes negotiation and all the streams have started.
>In terms of SIP this is sent after the @ACK@ was sent or received.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
>+_streams_+:
>>The list of streams which now form the active streams of the @Session@.
*SIPSessionDidFail*
>This notification is sent whenever the session fails before it starts.
>The failure reason is included in the data attributes.
>This notification is never followed by @SIPSessionDidEnd@.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
>+_originator_+:
>>A string indicating the originator of the @Session@. This will either be "local" or "remote".
>+_code_+:
>>The SIP error code of the failure.
>+_reason_+:
>>A SIP status reason.
>+_failure_reason_+:
>>A string which represents the reason for the failure, such as @"user_request"@, @"missing ACK"@, @"SIP core error..."@.
*SIPSessionWillEnd*
>Will be sent just before terminating a @Session@.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
*SIPSessionDidEnd*
>Will be sent always when a @Session@ ends as a result of remote or local session termination.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
>+_originator_+:
>>A string indicating who originated the termination. This will either be "local" or "remote".
>+_end_reason_+:
>>A string representing the termination reason, such as @"user_request"@, @"SIP core error..."@.
*SIPSessionDidChangeHoldState*
>Will be sent when the session got put on hold or removed from hold, either by the local or the remote party.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
>+_originator_+:
>>A string indicating who originated the hold request, and consequently in which direction the session got put on hold.
>+_on_hold_+:
>>@True@ if there is at least one stream which is on hold and @False@ otherwise.
>+_partial_+:
>>@True@ if there is at least one stream which is on hold and one stream which supports hold but is not on hold and @False@ otherwise.
*SIPSessionGotProposal*
>Will be sent when either the local or the remote party proposes to add streams to the session.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
>+_originator_+:
>>The party that initiated the stream proposal, can be either "local" or "remote".
>+_streams_+:
>>A list of streams that were proposed.
*SIPSessionGotRejectProposal*
>Will be sent when either the local or the remote party rejects a proposal to have streams added to the session.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
>+_originator_+:
>>The party that initiated the stream proposal, can be either "local" or "remote".
>+_code_+:
>>The code with which the proposal was rejected.
>+_reason_+:
>>The reason for rejecting the stream proposal.
>+_streams_+:
>>The list of streams which were rejected.
*SIPSessionGotAcceptProposal*
>Will be sent when either the local or the remote party accepts a proposal to have stream( added to the session.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
>+_originator_+:
>>The party that initiated the stream proposal, can be either "local" or "remote".
>+_streams_+:
>>The list of streams which were accepted.
>+_proposed_streams_+:
>>The list of streams which were originally proposed.
*SIPSessionHadProposalFailure*
>Will be sent when a re-INVITE fails because of an internal reason (such as a stream not being able to start).
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
>+_failure_reason_+:
>>The error which caused the proposal to fail.
>+_streams_+:
>>The streams which were part of this proposal.
*SIPSessionDidRenegotiateStreams*
>Will be sent when a media stream is either activated or deactivated.
>An application should listen to this notification in order to know when a media stream can be used.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
>+_action_+:
>>A string which is either @"add"@ or @"remove"@ which specifies what happened to the streams the notificaton referes to
>+_streams_+:
>>A list with the streams which were added or removed.
*SIPSessionDidProcessTransaction*
>Will be sent whenever a SIP transaction is complete in order to provide low-level details of the progress of the INVITE dialog.
>>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
>+_originator_+:
>>The initiator of the transaction, @"local"@ or @"remote"@.
>+_method_+:
>>The method of the request.
>+_code_+:
>>The SIP status code of the response.
>+_reason_+:
>>The SIP status reason of the response.
>+_ack_received_+:
>>This attribute is only present for INVITE transactions and has one of the values @True@, @False@ or @"unknown"@. The last value may occur then PJSIP does not let us know whether the ACK was received or not.
*SIPSessionTransferNewOutgoing*
>>Will be sent whenever a SIP session initiates an outgoing call transfer request.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
>+_transfer_destination_+:
>>The destination SIP URI of the call transfer request.
>+_transfer_source_+:
>>The source SIP URI of the call transfer request.
*SIPSessionTransferDidStart*
>Will be sent whenever a call transfer has been started.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
*SIPSessionTransferDidFail*
>Will be sent whenever a call transfer request has failed.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
>+_code_+:
>>The SIP failure code reported by the SIP stack.
>+_reason_+:
>>The reason of the failure as a string.
As an example for how to use the @Session@ object, the following provides a basic Python program that initiates an outgoing SIP session request see [[SipSessionExample|Minimalist Session Example code]].
h3. IMediaStream
Implemented in [browser:sipsimple/streams/+init+.py]
This interface describes the API which the @Session@ uses to communicate with the streams. All streams used by the @Session@ +must+ respect this interface.
h4. methods
*<notextile>__init__</notextile>*(_self_, _account_)
>Initializes the generic stream instance.
*new_from_sdp*(_cls_, _account_, _remote_sdp_, _stream_index_)
>A classmethod which returns an instance of this stream implementation if the sdp is accepted by the stream or None otherwise.
>+_account_+:
>>The @sipsimple.account.Account@ or @sipsimple.account.BonjourAccount@ object the session which this stream would be part of is associated with.
>+_remote_sdp_+:
>>The @FrozenSDPSession@ which was received by the remote offer.
>+_stream_index_+:
>>An integer representing the index within the list of media streams within the whole SDP which this stream would be instantiated for.
*get_local_media*(_self_, _for_offer_)
>Return an @SDPMediaStream@ which represents an offer for using this stream if @for_offer@ is @True@ and a response to an SDP proposal otherwise.
>+_for_offer_+:
>>@True@ if the @SDPMediaStream@ will be used for an SDP proposal and @False@ if for a response.
*initialize*(_self_, _session_, _direction_)
>Initializes the stream. This method will get called as soon as the stream is known to be at least offered as part of the @Session@. If initialization goes fine, the stream must send a @MediaStreamDidInitialize@ notification or a @MediaStreamDidFail@ notification otherwise.
>+_session_+:
>>The @Session@ object this stream will be part of.
>+_direction_+:
>>@"incoming"@ if the stream was created because of a received proposal and @"outgoing"@ if a proposal was sent. Note that this need not be the same as the initial direction of the @Session@ since streams can be proposed in either way using re-INVITEs.
*start*(_self_, _local_sdp_, _remote_sdp_, _stream_index_)
>Starts the stream. This method will be called as soon is known to be used in the @Session@ (eg. only called for an incoming proposal if the local party accepts the proposed stream). If starting succeeds, the stream must send a @MediaStreamDidStart@ notification or a @MediaStreamDidFail@ notification otherwise.
>+_local_sdp_+:
>>The @FrozenSDPSession@ which is used by the local endpoint.
>+_remote_sdp_+:
>>The @FrozenSDPSession@ which is used by the remote endpoint.
>+_stream_index_+:
>>An integer representing the index within the list of media streams within the whole SDP which this stream is represented by.
*validate_update*(_self_, _remote_sdp_, _stream_index_)
>This method will be called when a re-INVITE is received which changes the parameters of the stream within the SDP. The stream must return @True@ if the changes are acceptable or @False@ otherwise. If any changed streams return @False@ for a re-INVITE, the re-INVITE will be refused with a negative response. This means that streams must not changed any internal data when this method is called as the update is not guaranteed to be applied even if the stream returns @True@.
>+_remote_sdp_+:
>>The @FrozenSDPSession@ which is used by the remote endpoint.
>+_stream_index_+:
>>An integer representing the index within the list of media streams within the whole SDP which this stream is represented by.
*update*(_self_, _local_sdp_, _remote_sdp_, _stream_index_)
>This method is called when the an SDP negotiation initiated by either the local party or the remote party succeeds. The stream must update its internal state according to the new SDP in use.
>+_local_sdp_+:
>>The @FrozenSDPSession@ which is used by the local endpoint.
>+_remote_sdp_+:
>>The @FrozenSDPSession@ which is used by the remote endpoint.
>+_stream_index_+:
>>An integer representing the index within the list of media streams within the whole SDP which this stream is represented by.
*hold*(_self_)
>Puts the stream on hold if supported by the stream. Typically used by audio and video streams. The stream must immediately stop sending/receiving data and calls to @get_local_media()@ following calls to this method must return an SDP which reflects the new hold state.
*unhold*(_self_)
>Takes the stream off hold. Typically used by audio and video streams. Calls to @get_local_media()@ following calls to this method must return an SDP which reflects the new hold state.
*deactivate*(_self_)
>This method is called on a stream just before the stream will be removed from the @Session@ (either as a result of a re-INVITE or a BYE). This method is needed because it avoids a race condition with streams using stateful protocols such as TCP: the stream connection might be terminated before the SIP signalling announces this due to network routing inconsistencies and the other endpoint would not be able to distinguish between this case and an error which caused the stream transport to fail. The stream must not take any action, but must consider that the transport being closed by the other endpoint after this method was called as a normal situation rather than an error condition.
*end*(_self_)
>Ends the stream. This must close the underlying transport connection. The stream must send a @MediaStreamWillEnd@ just after this method is called and a @MediaStreamDidEnd@ as soon as the operation is complete. This method is always be called by the @Session@ on the stream if at least the @initialize()@ method has been called. This means that once a stream sends the @MediaStreamDidFail@ notification, the @Session@ will still call this method.
h4. 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
h4. 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.
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 [[SipConfigurationAPI|Configuration API]].
!={width:500px}sipsimple-middleware.png!
h2. 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 [[SipConfigurationAPI#ConfigurationManager|ConfigurationManager]]
* the core [[SipCoreApiDocumentation#Engine|Engine]] using the settings in the configuration
* the [[SipMiddlewareApi#AccountManager|AccountManager]], using the accounts in the configuration
* the [[SipMiddlewareApi#SessionManager|SessionManager]], in order to handle incoming sessions
* two [[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.
h4. methods
*<notextile>__init__</notextile>*(_self_)
>Instantiates a new SIPApplication.
*start*(_self_, *storage*)
>Starts the @SIPApplication@ which initializes all the components in the correct order. The @storage@ is saved as an attribute which other entities like the @Configuration Manager@ will use to take the appropriate backend. If any error occurs with loading the configuration, the exception raised by the @ConfigurationManager@ is propagated by this method and @SIPApplication@ can be started again. After this, any fatal errors will result in the SIPApplication being stopped and unusable, which means the whole application will need to stop. This method returns as soon as the twisted thread has been started, which means the application must wait for the @SIPApplicationDidStart@ notification in order to know that the application started.
*stop*(_self_)
>Stop all the components started by the SIPApplication. This method returns immediately, but a @SIPApplicationDidEnd@ notification is sent when all the components have been stopped.
h4. attributes
*running*
>@True@ if the SIPApplication is running (it has been started and it has not been told to stop), @False@ otherwise.
*storage*
>Holds an object which implements the @ISIPSimpleStorage@ interface which will be used to provide a storage facility to other middleware components.
*local_nat_type*
>String containing the detected local NAT type.
*alert_audio_mixer*
>The @AudioMixer@ object created on the alert audio device as defined by the configuration (by SIPSimpleSettings.audio.alert_device).
*alert_audio_bridge*
>An @AudioBridge@ where @IAudioPort@ objects can be added to playback sound to the alert device.
*alert_audio_device*
>An @AudioDevice@ which corresponds to the alert device as defined by the configuration. This will always be part of the alert_audio_bridge.
*voice_audio_mixer*
>The @AudioMixer@ object created on the voice audio device as defined by the configuration (by SIPSimpleSettings.audio.input_device and SIPSimpleSettings.audio.output_device).
*voice_audio_bridge*
>An @AudioBridge@ where @IAudioPort@ objects can be added to playback sound to the output device or record sound from the input device.
*voice_audio_device*
>An @AudioDevice@ which corresponds to the voice device as defined by the configuration. This will always be part of the voice_audio_bridge.
h4. 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.
h2. 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.
h3. 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.
h3. Provided implementations
Two storage implementations are provided: *FileStorage* and *MemoryStorage* both located in the *sipsimple.storage* module.
h2. 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 [[SipMiddlewareApi#MediaStreamRegistry|MediaStreamRegistry]].
h3. SessionManager
Implemented in [browser:sipsimple/session.py]
The @sipsimple.session.SessionManager@ class is a singleton, which acts as the central aggregation point for sessions within the middleware.
Although it is mainly used internally, the application can use it to query information about all active sessions.
The SessionManager is implemented as a singleton, meaning that only one instance of this class exists within the middleware. The SessionManager is started by the SIPApplication and takes care of handling incoming sessions and closing all sessions when SIPApplication is stopped.
h4. 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.
h4. methods
*<notextile>__init__</notextile>*(_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.
h3. Session
Implemented in [browser:sipsimple/session.py]
A @sipsimple.session.Session@ object represents a complete SIP session between the local and a remote endpoints. Both incoming and outgoing sessions are represented by this class.
A @Session@ instance is a stateful object, meaning that it has a @state@ attribute and that the lifetime of the session traverses different states, from session creation to termination. State changes are triggered by methods called on the object by the application or by received network events. These states and their transitions are represented in the following diagram:
!sipsimple-core-invite-state-machine-2.png!
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.
h4. methods
*<notextile>__init__</notextile>*(_self_, *account*)
>Creates a new @Session@ object in the @None@ state.
>+_account_+:
>>The local account to be associated with this @Session@.
*connect*(_self_, *to_header*, *routes*, *streams*, *is_focus*=@False@, *subject*=@None@)
>Will set up the @Session@ as outbound and propose the new session to the specified remote party and move the state machine to the @outgoing@ state.
>Before contacting the remote party, a @SIPSessionNewOutgoing@ notification will be emitted.
>If there is a failure or the remote party rejected the offer, a @SIPSessionDidFail@ notification will be sent.
>Any time a ringing indication is received from the remote party, a @SIPSessionGotRingIndication@ notification is sent.
>If the remote party accepted the session, a @SIPSessionWillStart@ notification will be sent, followed by a @SIPSessionDidStart@ notification when the session is actually established.
>This method may only be called while in the @None@ state.
>+_to_header_+:
>>A @sipsimple.core.ToHeader@ object representing the remote identity to initiate the session to.
>+_routes_+:
>>An iterable of @sipsimple.util.Route@ objects, specifying the IP, port and transport to the outbound proxy.
>>These routes will be tried in order, until one of them succeeds.
>+_streams_+:
>>A list of stream objects which will be offered to the remote endpoint.
>+_is_focus_+:
>>Boolean flag indicating if the @isfocus@ parameter should be added to the @Contact@ header according to RFC 4579.
>+_subject_+:
>>Session subject. If not None a @Subject@ header will be added with the specified value.
*send_ring_indication*(_self_)
>Sends a 180 provisional response in the case of an incoming session.
*accept*(_self_, *streams*)
>Calling this methods will accept an incoming session and move the state machine to the @accepting@ state.
>When there is a new incoming session, a @SIPSessionNewIncoming@ notification is sent, after which the application can call this method on the sender of the notification.
>After this method is called, @SIPSessionWillStart@ followed by @SIPSessionDidStart@ will be emitted, or @SIPSessionDidFail@ on an error.
>This method may only be called while in the @incoming@ state.
>+_streams_+:
>>A list of streams which needs to be a subset of the proposed streams which indicates which streams are to be accepted. All the other proposed streams will be rejected.
*reject*(_self_, *code*=@603@, *reason*=@None@)
>Reject an incoming session and move it to the @terminating@ state, which eventually leads to the @terminated@ state.
>Calling this method will cause the @Session@ object to emit a @SIPSessionDidFail@ notification once the session has been rejected.
>This method may only be called while in the @incoming@ state.
>+_code_+:
>>An integer which represents the SIP status code in the response which is to be sent. Usually, this is either 486 (Busy) or 603 (Decline/Busy Everywhere).
>+_reason_+:
>>The string which is to be sent as the SIP status reason in the response, or None if PJSIP's default reason for the specified code is to be sent.
*accept_proposal*(_self_, *streams*)
>When the remote party proposes to add some new streams, signaled by the @SIPSessionGotProposal@ notification, the application can use this method to accept the stream(s) being proposed.
>After calling this method a @SIPSessionGotAcceptProposal@ notification is sent, unless an error occurs while setting up the new stream, in which case a @SIPSessionHadProposalFailure@ notification is sent and a rejection is sent to the remote party. As with any action which causes the streams in the session to change, a @SIPSessionDidRenegotiateStreams@ notification is also sent.
>This method may only be called while in the @received_proposal@ state.
>+_streams_+:
>>A list of streams which needs to be a subset of the proposed streams which indicates which streams are to be accepted. All the other proposed streams will be rejected.
*reject_proposal*(_self_, *code*=@488@, *reason*=@None@)
>When the remote party proposes new streams that the application does not want to accept, this method can be used to reject the proposal, after which a @SIPSessionGotRejectProposal@ or @SIPSessionHadProposalFailure@ notification is sent.
>This method may only be called while in the @received_proposal@ state.
>+_code_+:
>>An integer which represents the SIP status code in the response which is to be sent. Usually, this is 488 (Not Acceptable Here).
>+_reason_+:
>>The string which is to be sent as the SIP status reason in the response, or None if PJSIP's default reason for the specified code is to be sent.
*add_stream*(_self_, *stream*)
>Proposes a new stream to the remote party.
>Calling this method will cause a @SIPSessionGotProposal@ notification to be emitted.
>After this, the state machine will move into the @sending_proposal@ state until either a @SIPSessionGotAcceptProposal@, @SIPSessionGotRejectProposal@ or @SIPSessionHadProposalFailure@ notification is sent, informing the application if the remote party accepted the proposal. As with any action which causes the streams in the session to change, a @SIPSessionDidRenegotiateStreams@ notification is also sent.
>This method may only be called while in the @connected@ state.
*remove_stream*(_self_, *stream*)
>Stop the stream and remove it from the session, informing the remote party of this. Although technically this is also done via an SDP negotiation which may fail, the stream will always get remove (if the remote party refuses the re-INVITE, the result will be that the remote party will have a different view of the active streams than the local party).
>This method may only be called while in the @connected@ state.
*cancel_proposal*(_self_)
>This method cancels a proposal of adding a stream to the session by sending a CANCEL request. A @SIPSessionGotRejectProposal@ notification will be sent with code 487.
*hold*(_self_)
>Put the streams of the session which support the notion of hold on hold.
>This will cause a @SIPSessionDidChangeHoldState@ notification to be sent.
>This method may be called in any state and will send the re-INVITE as soon as it is possible.
*unhold*(_self_)
>Take the streams of the session which support the notion of hold out of hold.
>This will cause a @SIPSessionDidChangeHoldState@ notification to be sent.
>This method may be called in any state and will send teh re-INVITE as soon as it is possible.
*end*(_self_)
>This method may be called any time after the @Session@ has started in order to terminate the session by sending a BYE request.
>Right before termination a @SIPSessionWillEnd@ notification is sent, after termination @SIPSessionDidEnd@ is sent.
*transfer*(_self_, *target_uri*, *replaced_session*=@None@)
>Proposes a blind call transfer to a new target URI or assisted transfer to an URI belonging to an already established session.
*accept_transfer*(_self_)
>Accepts an incoming call transfer request.
*reject_transfer*(_self_, *code*=@486@, *reason_=@None@)
>Rejects an incoming call transfer request.
h4. attributes
*state*
>The state the object is currently in, being one of the states from the diagram above.
*account*
>The @sipsimple.account.Account@ or @sipsimple.account.BonjourAccount@ object that the @Session@ is associated with.
>On an outbound session, this is the account the application specified on object instantiation.
*direction*
>A string indicating the direction of the initial negotiation of the session.
>This can be either @None@, "incoming" or "outgoing".
*transport*
>A string representing the transport this @Session@ is using: @"udp"@, @"tcp"@ or @"tls"@.
*start_time*
>The time the session started as a @datetime.datetime@ object, or @None@ if the session was not yet started.
*stop_time*
>The time the session stopped as a @datetime.datetime@ object, or @None@ if the session has not yet terminated.
*on_hold*
>Boolean indicating whether the session was put on hold, either by the local or the remote party.
*remote_user_agent*
>A string indicating the remote user agent, if it provided one.
>Initially this will be @None@, it will be set as soon as this information is received from the remote party (which may be never).
*local_identity*
>The @sipsimple.core.FrozenFromHeader@ or @sipsimple.core.FrozenToHeader@ identifying the local party, if the session is active, @None@ otherwise.
*remote_identity*
>The @sipsimple.core.FrozenFromHeader@ or @sipsimple.core.FrozenToHeader@ identifying the remote party, if the session is active, @None@ otherwise.
*streams*
>A list of the currently active streams in the @Session@.
*proposed_streams*
>A list of the currently proposed streams in the @Session@, or @None@ if there is no proposal in progress.
*conference*
>A @ConferenceHandler@ object instance (or Null). It can be later used to add/remove participants from a remote conference.
*subject*
>The session subject as a unicode object.
*replaced_session*
>A @Session@ object instance (or Null). It can be used for assisted call transfer.
*transfer_handler*
>A @TransferHandler@ object instance (or Null). It is used for managing the call transfer process.
*transfer_info*
>A @TransferInfo@ object instance (or Null). It is used for describing the details of a call transfer operation.
h4. notifications
*SIPSessionNewIncoming*
>Will be sent when a new incoming @Session@ is received.
>The application should listen for this notification to get informed of incoming sessions.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
>+_streams_+:
>>A list of streams that were proposed by the remote party.
*SIPSessionNewOutgoing*
>Will be sent when the application requests a new outgoing @Session@.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
>+_streams_+:
>>A list of streams that were proposed to the remote party.
*SIPSessionGotRingIndication*
>Will be sent when an outgoing @Session@ receives an indication that a remote device is ringing.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
*SIPSessionGotProvisionalResponse*
>Will be sent whenever the @Session@ receives a provisional response as a result of sending a (re-)INVITE.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
>+_code_+:
>>The SIP status code received.
>+_reason_+:
>>The SIP status reason received.
*SIPSessionWillStart*
>Will be sent just before a @Session@ completes negotiation.
>In terms of SIP, this is sent after the final response to the @INVITE@, but before the @ACK@.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
*SIPSessionDidStart*
>Will be sent when a @Session@ completes negotiation and all the streams have started.
>In terms of SIP this is sent after the @ACK@ was sent or received.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
>+_streams_+:
>>The list of streams which now form the active streams of the @Session@.
*SIPSessionDidFail*
>This notification is sent whenever the session fails before it starts.
>The failure reason is included in the data attributes.
>This notification is never followed by @SIPSessionDidEnd@.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
>+_originator_+:
>>A string indicating the originator of the @Session@. This will either be "local" or "remote".
>+_code_+:
>>The SIP error code of the failure.
>+_reason_+:
>>A SIP status reason.
>+_failure_reason_+:
>>A string which represents the reason for the failure, such as @"user_request"@, @"missing ACK"@, @"SIP core error..."@.
*SIPSessionWillEnd*
>Will be sent just before terminating a @Session@.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
*SIPSessionDidEnd*
>Will be sent always when a @Session@ ends as a result of remote or local session termination.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
>+_originator_+:
>>A string indicating who originated the termination. This will either be "local" or "remote".
>+_end_reason_+:
>>A string representing the termination reason, such as @"user_request"@, @"SIP core error..."@.
*SIPSessionDidChangeHoldState*
>Will be sent when the session got put on hold or removed from hold, either by the local or the remote party.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
>+_originator_+:
>>A string indicating who originated the hold request, and consequently in which direction the session got put on hold.
>+_on_hold_+:
>>@True@ if there is at least one stream which is on hold and @False@ otherwise.
>+_partial_+:
>>@True@ if there is at least one stream which is on hold and one stream which supports hold but is not on hold and @False@ otherwise.
*SIPSessionGotProposal*
>Will be sent when either the local or the remote party proposes to add streams to the session.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
>+_originator_+:
>>The party that initiated the stream proposal, can be either "local" or "remote".
>+_streams_+:
>>A list of streams that were proposed.
*SIPSessionGotRejectProposal*
>Will be sent when either the local or the remote party rejects a proposal to have streams added to the session.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
>+_originator_+:
>>The party that initiated the stream proposal, can be either "local" or "remote".
>+_code_+:
>>The code with which the proposal was rejected.
>+_reason_+:
>>The reason for rejecting the stream proposal.
>+_streams_+:
>>The list of streams which were rejected.
*SIPSessionGotAcceptProposal*
>Will be sent when either the local or the remote party accepts a proposal to have stream( added to the session.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
>+_originator_+:
>>The party that initiated the stream proposal, can be either "local" or "remote".
>+_streams_+:
>>The list of streams which were accepted.
>+_proposed_streams_+:
>>The list of streams which were originally proposed.
*SIPSessionHadProposalFailure*
>Will be sent when a re-INVITE fails because of an internal reason (such as a stream not being able to start).
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
>+_failure_reason_+:
>>The error which caused the proposal to fail.
>+_streams_+:
>>The streams which were part of this proposal.
*SIPSessionDidRenegotiateStreams*
>Will be sent when a media stream is either activated or deactivated.
>An application should listen to this notification in order to know when a media stream can be used.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
>+_action_+:
>>A string which is either @"add"@ or @"remove"@ which specifies what happened to the streams the notificaton referes to
>+_streams_+:
>>A list with the streams which were added or removed.
*SIPSessionDidProcessTransaction*
>Will be sent whenever a SIP transaction is complete in order to provide low-level details of the progress of the INVITE dialog.
>>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
>+_originator_+:
>>The initiator of the transaction, @"local"@ or @"remote"@.
>+_method_+:
>>The method of the request.
>+_code_+:
>>The SIP status code of the response.
>+_reason_+:
>>The SIP status reason of the response.
>+_ack_received_+:
>>This attribute is only present for INVITE transactions and has one of the values @True@, @False@ or @"unknown"@. The last value may occur then PJSIP does not let us know whether the ACK was received or not.
*SIPSessionTransferNewOutgoing*
>>Will be sent whenever a SIP session initiates an outgoing call transfer request.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
>+_transfer_destination_+:
>>The destination SIP URI of the call transfer request.
>+_transfer_source_+:
>>The source SIP URI of the call transfer request.
*SIPSessionTransferDidStart*
>Will be sent whenever a call transfer has been started.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
*SIPSessionTransferDidFail*
>Will be sent whenever a call transfer request has failed.
>+_timestamp_+:
>>A @datetime.datetime@ object indicating when the notification was sent.
>+_code_+:
>>The SIP failure code reported by the SIP stack.
>+_reason_+:
>>The reason of the failure as a string.
As an example for how to use the @Session@ object, the following provides a basic Python program that initiates an outgoing SIP session request see [[SipSessionExample|Minimalist Session Example code]].
h3. IMediaStream
Implemented in [browser:sipsimple/streams/+init+.py]
This interface describes the API which the @Session@ uses to communicate with the streams. All streams used by the @Session@ +must+ respect this interface.
h4. methods
*<notextile>__init__</notextile>*(_self_, _account_)
>Initializes the generic stream instance.
*new_from_sdp*(_cls_, _account_, _remote_sdp_, _stream_index_)
>A classmethod which returns an instance of this stream implementation if the sdp is accepted by the stream or None otherwise.
>+_account_+:
>>The @sipsimple.account.Account@ or @sipsimple.account.BonjourAccount@ object the session which this stream would be part of is associated with.
>+_remote_sdp_+:
>>The @FrozenSDPSession@ which was received by the remote offer.
>+_stream_index_+:
>>An integer representing the index within the list of media streams within the whole SDP which this stream would be instantiated for.
*get_local_media*(_self_, _for_offer_)
>Return an @SDPMediaStream@ which represents an offer for using this stream if @for_offer@ is @True@ and a response to an SDP proposal otherwise.
>+_for_offer_+:
>>@True@ if the @SDPMediaStream@ will be used for an SDP proposal and @False@ if for a response.
*initialize*(_self_, _session_, _direction_)
>Initializes the stream. This method will get called as soon as the stream is known to be at least offered as part of the @Session@. If initialization goes fine, the stream must send a @MediaStreamDidInitialize@ notification or a @MediaStreamDidFail@ notification otherwise.
>+_session_+:
>>The @Session@ object this stream will be part of.
>+_direction_+:
>>@"incoming"@ if the stream was created because of a received proposal and @"outgoing"@ if a proposal was sent. Note that this need not be the same as the initial direction of the @Session@ since streams can be proposed in either way using re-INVITEs.
*start*(_self_, _local_sdp_, _remote_sdp_, _stream_index_)
>Starts the stream. This method will be called as soon is known to be used in the @Session@ (eg. only called for an incoming proposal if the local party accepts the proposed stream). If starting succeeds, the stream must send a @MediaStreamDidStart@ notification or a @MediaStreamDidFail@ notification otherwise.
>+_local_sdp_+:
>>The @FrozenSDPSession@ which is used by the local endpoint.
>+_remote_sdp_+:
>>The @FrozenSDPSession@ which is used by the remote endpoint.
>+_stream_index_+:
>>An integer representing the index within the list of media streams within the whole SDP which this stream is represented by.
*validate_update*(_self_, _remote_sdp_, _stream_index_)
>This method will be called when a re-INVITE is received which changes the parameters of the stream within the SDP. The stream must return @True@ if the changes are acceptable or @False@ otherwise. If any changed streams return @False@ for a re-INVITE, the re-INVITE will be refused with a negative response. This means that streams must not changed any internal data when this method is called as the update is not guaranteed to be applied even if the stream returns @True@.
>+_remote_sdp_+:
>>The @FrozenSDPSession@ which is used by the remote endpoint.
>+_stream_index_+:
>>An integer representing the index within the list of media streams within the whole SDP which this stream is represented by.
*update*(_self_, _local_sdp_, _remote_sdp_, _stream_index_)
>This method is called when the an SDP negotiation initiated by either the local party or the remote party succeeds. The stream must update its internal state according to the new SDP in use.
>+_local_sdp_+:
>>The @FrozenSDPSession@ which is used by the local endpoint.
>+_remote_sdp_+:
>>The @FrozenSDPSession@ which is used by the remote endpoint.
>+_stream_index_+:
>>An integer representing the index within the list of media streams within the whole SDP which this stream is represented by.
*hold*(_self_)
>Puts the stream on hold if supported by the stream. Typically used by audio and video streams. The stream must immediately stop sending/receiving data and calls to @get_local_media()@ following calls to this method must return an SDP which reflects the new hold state.
*unhold*(_self_)
>Takes the stream off hold. Typically used by audio and video streams. Calls to @get_local_media()@ following calls to this method must return an SDP which reflects the new hold state.
*deactivate*(_self_)
>This method is called on a stream just before the stream will be removed from the @Session@ (either as a result of a re-INVITE or a BYE). This method is needed because it avoids a race condition with streams using stateful protocols such as TCP: the stream connection might be terminated before the SIP signalling announces this due to network routing inconsistencies and the other endpoint would not be able to distinguish between this case and an error which caused the stream transport to fail. The stream must not take any action, but must consider that the transport being closed by the other endpoint after this method was called as a normal situation rather than an error condition.
*end*(_self_)
>Ends the stream. This must close the underlying transport connection. The stream must send a @MediaStreamWillEnd@ just after this method is called and a @MediaStreamDidEnd@ as soon as the operation is complete. This method is always be called by the @Session@ on the stream if at least the @initialize()@ method has been called. This means that once a stream sends the @MediaStreamDidFail@ notification, the @Session@ will still call this method.
h4. 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
h4. 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.