SIP SIMPLE Client SDK

= SIP SIMPLE client GUI =

Development blueprint for the development of a cross platform GUI for the SIP SIMPLE client library.

== Background ==

SIP SIMPLE client is a Python software library that allows for easy development of Internet
communications end-points based on SIP and related protocols for voice,
rich presence, session based instant messaging (IM), file transfers and desktop sharing.
Other media types can be easily added by using an extensible high-level API.

== Stages ==

The implementation of the GUI consists of the following stages:

1. ~~Design Design and implementation of a middleware API~~ API
1. ~~Implementation Implementation of a notification bus ~~

1. ~~Identifications Identifications of the GUI events~~ events
1. ~~Identifications Identifications of the GUI visual elements~~ elements
1. ~~Identification Identification of GUI toolkits~~ toolkits
1. ~~Study Study GUI toolkit documentation~~ documentation
1. ~~Identify Identify the platform dependent modifications required for the library~~ library
1. ~~Implement Implement a prototype GUI~~ GUI
1. ~~Fine Fine tune middleware classes and events~~ events
1. ~~Finalize Finalize the specifications for the GUI development~~ development
1. Implement cross platform GUI based
1. Create GUI installation packages for each target OS
1. Deploy GUI to end user and collect feedback
1. Update GUI with end-user feed back

Below is a rough visual representation of the progress for each component.

[[Image(sipsimple-gui-development.png)]]

== Design and implementation of a middleware API ==

The GUI should not be aware about the underlying protocols and their interaction. this requires the building of an extra layer between the GUI and the protocol components (called middleware). The middleware has been implemented as an addition to SIP SIMPLE library as follows:

* [browser:sipsimple/session.py] - event driven high level class for handling sessions
* [browser:sipsimple/account.py] - account manager to handle multiple SIP accounts
* [browser:sipsimple/configuration/settings.py] - storage container for middleware and GUI settings

== Implementation of a notification bus ==

The notification bus is a mechanism to receive notifications from the underlying SIP SIMPLE libraries and translate them into GUI events.

It has been implemented into version 1.1.0 of python application from http://pypi.python.org/pypi/python-application/

== Identifications of the GUI events ==

Such events consists of notifications for sessions or presence notification from the underlying components.

==== notifications ====

'''SCSessionChangedState'''::
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.
'''SCSessionNewIncoming'''::
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]]''has_audio'':[[BR]]
A boolean indicating if the remote party proposed an audio stream within this session.
[[BR]]''has_chat'':[[BR]]
A boolean indicating if the remote party proposed a chat stream within this session.
'''SCSessionNewOutgoing'''::
Will be sent when the applcation requests a new outgoing {{{Session}}}.
[[BR]]''timestamp'':[[BR]]
A {{{datetime.datetime}}} object indicating when the notification was sent.
'''SCSessionGotRingIndication'''::
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.
'''SCSessionWillStart'''::
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.
'''SCSessionDidStart'''::
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.
'''SCSessionDidFail'''::
This notification is sent whenever the session fails.
The failure reason is included in the data attributes.
This notification is always followed by {{{SCSessionDidEnd}}}.
[[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.
'''SCSessionWillEnd'''::
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.
'''SCSessionDidEnd'''::
Will be sent always when a {{{Session}}} ends, either because of a failure (in which case it is preceded by {{{SCSessionDidFail}}}), 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".
'''SCSessionGotHoldRequest'''::
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.
'''SCSessionGotUnholdRequest'''::
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.
'''SCSessionWillStartRecordingAudio'''::
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.
'''SCSessionDidStartRecordingAudio'''::
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.
'''SCSessionWillStopRecordingAudio'''::
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.
'''SCSessionDidStopRecordingAudio'''::
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.
'''SCSessionGotNoAudio'''::
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.
'''SCSessionGotDTMF'''::
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.
'''SCSessionGotMessage'''::
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
'''SCSessionDidDeliverMessage'''::
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
'''SCSessionDidDeliverMessage'''::
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
'''SCSessionGotStreamProposal'''::
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]]''adds_audio'':[[BR]]
A boolean indicating if the proposal would add an audio stream.
[[BR]]''adds_chat'':[[BR]]
A boolean indicating if the proposal would add a chat stream.
'''SCSessionRejectedStreamProposal'''::
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.
'''SCSessionRejectedStreamProposal'''::
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".


== Identification of GUI toolkits ==

The following toolkits have been identified:

* Cocoa for MacOSX OS - used for prototyping the final middleware and GUI specifications
* QT - used for Linux, Windows and other supported OS based

== Study GUI toolkit documentation ==

Cocoa toolkit documentation has been studied.