documentation: update design draft.
[meego-ux:meego-app-satk.git] / doc / sim_toolkit_design_draft.txt
1 ====== SIM Toolkit design draft ======
2
3 The MeeGo SIM Application Toolkit (SATK) handles user interaction for the proactive SIM commands, through the oFono stk-agent DBus API. 
4 The application provides a simple QML-based user interface for the oFono SIM toolkit agent, and is completely stateless.
5
6
7 ===== Summary =====
8 In a nutshell, SATK maps the oFono stk-agent DBus API to a few Qt widgets in order to provide the terminal response to the corresponding SIM commands. This section lists the proactive SIM commands that SATK needs to be aware of, and the UI widgets it uses to handle these commands in response to the oFono stk-agent DBus messages.
9
10 The commands and APIs mentionned in this section are described in the reference documents listed below:
11   * 3GPP TS 11.14 v8.18.0 Specification of the SIM Application Toolkit. Pages 86/87. http://www.3gpp.org/ftp/Specs/archive/11_series/11.14/1114-8i0.zip
12   * oFono SIM Toolkit API. http://git.kernel.org/?p=network/ofono/ofono.git;a=blob;f=doc/stk-api.txt
13   * oFono feature list. http://git.kernel.org/?p=network/ofono/ofono.git;a=blob;f=doc/features.txt
14
15
16 ==== Proactive SIM commands ====
17
18 All these commands are listed in the [[http://www.3gpp.org/ftp/Specs/archive/11_series/11.14/1114-8i0.zip|3GPP TS 11.14 v8.18.0 Specification]], with the relevant terminal response, pages 86-87. 
19
20 There are other proactive commands in the 3GPP specification, but SATK needs to be aware only of the following commands, mentioned as supported in the [[http://git.kernel.org/?p=network/ofono/ofono.git;a=blob;f=doc/features.txt|oFono feature list]].
21
22   * 02 MORE TIME
23   * 10 SETUP CALL
24   * 11 SEND SS
25   * 12 SEND USSD
26   * 13 SEND SMS
27   * 14 SEND DTMF
28   * 15 LAUNCH BROWSER
29   * 20 PLAY TONE
30   * 21 DISPLAY TEXT
31   * 22 GET INKEY
32   * 23 GET INPUT
33   * 24 SELECT ITEM
34   * 25 SETUP MENU
35   * 26 PROVIDE LOCAL INFO
36   * 27 TIMER MANAGEMENT
37   * 28 SETUP IDLE MODE TEXT
38   * 35 LANG NOTIFICATION
39
40
41 ==== UI widgets ====
42
43 Dialogs may also have a "End" button if the corresponding proactive command accepts terminal response 10 "session terminated by user". The value returned to the SimToolkitAgent method is ''Error.SimToolkit.EndSession''.
44
45   * NOTIF : Notification with icon and text
46   * MESSAGE : Dialog with icon and text
47   * YESNO : Dialog with icon and text, Yes / No buttons
48   * POPUP : Dialog with icon and text, OK / Back buttons
49   * INPUTKEY : Dialog with icon and text, single char input, OK / Back buttons
50   * INPUTTEXT : Dialog with icon and text, multiple char input, OK / Back buttons
51   * MENU : Menu with icon and text, multiple icon and text items, selection highlight, Back button
52
53 ==== oFono SimToolkit properties ====
54
55 ^ SimToolkit property ^ short description ^ 3GPP proactive command ^ UI widget  ^
56 | MainMenu | Contains the items that make up the main menu. | 25 SETUP MENU | MENU |
57
58
59 ==== oFono SimToolkitAgent API ====
60
61 The table below maps the [[http://git.kernel.org/?p=network/ofono/ofono.git;a=blob;f=doc/stk-api.txt|SimToolkitAgent DBus API]] methods, the SIM proactive commands, and the SATK UI widgets.
62
63
64 ^ SimToolkitAgent method   ^ short description                            ^ 3GPP proactive command ^ UI widget / action ^
65 | RequestSelection         | Ask the user to select an item from the menu | 24 SELECT ITEM         | MENU |
66 | DisplayText              | Display text from the SIM                    | 21 DISPLAY TEXT        | POPUP, MESSAGE or NOTIF |
67 | RequestInput             | Request an input string from the user        | 23 GET INPUT           | INPUTTEXT |
68 | RequestDigits            | Request digits (0-9, *#+) from the user      | 23 GET INPUT           | INPUTTEXT |
69 | RequestKey               | Request a single input key from the user     | 22 GET INKEY           | INPUTKEY |
70 | RequestDigit             | Request a single digit from the user         | 22 GET INKEY           | INPUTKEY |
71 | RequestConfirmation      | Get confirmation from the user (boolean)     | 22 GET INKEY           | POPUP |
72 | ConfirmCallSetup         | Request user to confirm an outgoing call setup | 10 SETUP CALL        | YESNO |
73 | PlayTone                 | Play an audio tone once (e.g. dial tone, user SMS alert, etc) | 20 PLAY TONE | MESSAGE + play sound |
74 | LoopTone                 | Play an audio tone in a loop until cancelled | 20 PLAY TONE           | MESSAGE + play sound |
75 | DisplayActionInformation | Display text or icon that reflects the current activity in the SIM until cancelled by SATK | SEND 11 SS, 12 USSD, 13 SMS, 14 DTMF | MESSAGE or NOTIF |
76 | ConfirmLaunchBrowser     | Confirm browser launch                       | 15 LAUNCH BROWSER      | YESNO + launch browser |
77 | Cancel                   | Cancel any ongoing operation (e.g. displaying action information listed above) |  | close current window |
78 | Release                  | Agent release (resource cleanup, etc)        |                        | terminate agent |
79
80
81 ===== Core functionalities =====
82
83 ==== User interface ====
84
85 === Actions ===
86 The following lists all action commands that can close a widget, and the associated return value for the SimToolkitAgent method that triggered the widget opening.
87 There may be associated data, like entered text or selected menu item id, according to the widget.
88
89   * YES : triggered from a boolean method, return TRUE
90   * NO : triggered from a boolean method, return FALSE
91   * OK : triggered from a method that returns a string / byte, return associated data
92   * BACK : return ''Error.SimToolkit.GoBack''
93   * END : return ''Error.SimToolkit.EndSession''
94
95 === Widgets ===
96 The table below shows all the actions available to the user from a given widget. According the the SimToolkitAgent method, some of these actions may be disabled.
97
98 |           ^ Actions       ^ Data ^
99 ^ NOTIF     | none          | void |
100 ^ MESSAGE   | END           | void |
101 ^ YESNO     | YES, NO, END  | boolean |
102 ^ POPUP     | OK, BACK, END | void |
103 ^ INPUTKEY  | OK, BACK      | single char key or digit |
104 ^ INPUTTEXT | OK, BACK      | text string or number |
105 ^ MENU      | OK, BACK, END | menu selection index |
106
107
108 ==== SimToolkitAgent methods ====
109
110 The SATK handling of **org.ofono.SimToolkitAgent** methods as described in http://git.kernel.org/?p=network/ofono/ofono.git;a=blob;f=doc/stk-api.txt is detailed below. 
111
112 For each method, the possible user interactions and method response are listed. For reference, the corresponding proactive SIM command and terminal responses are also mentioned.
113
114
115 === RequestSelection ===
116
117   byte RequestSelection(string title, byte icon_id, array{struct(string, byte)} items, int16 default)
118
119 ^ MENU widget actions ^ return value                ^ terminal response for ''24 SELECT ITEM'' proactive SIM command ^
120 | OK                  | Selected item index         | ''00'' Command performed successfully |
121 | BACK                | ''Error.SimToolkit.GoBack'' | ''11'' Backward move in the proactive SIM session requested by the user | 
122
123 === DisplayText ===
124
125   void DisplayText(string text, byte icon_id, boolean urgent)
126
127 ^ NOTIF widget actions   ^ return value ^ terminal response for ''21 DISPLAY TEXT'' proactive SIM command ^
128 | none                   | void         | ''12'' No response from user / ''00'' Command performed successfully | 
129
130 ^ MESSAGE widget actions ^ return value ^ terminal response for ''21 DISPLAY TEXT'' proactive SIM command ^
131 | none                   | void         | ''12'' No response from user / ''00'' Command performed successfully | 
132
133 ^ POPUP widget actions   ^ return value                ^ terminal response for ''21 DISPLAY TEXT'' proactive SIM command ^
134 | OK                     | void                        | ''00'' Command performed successfully |
135 | BACK                   | ''Error.SimToolkit.GoBack'' | ''11'' Backward move in the proactive SIM session requested by the user | 
136 | none                   | ''Error.SimToolkit.Busy''   | ''12'' No response from user | 
137
138 **TODO** Need to figure out what to do for non-urgent actions, when the SIM session is not initiated by the user.
139 Check with Handset idle-screen app.
140 For NOTIF or MESSAGE widgets, there would be no explicit user response, oFono returns ''00'' or ''12'' to SIM.
141
142
143 === RequestInput ===
144
145   string RequestInput(string alpha, byte icon_id, string default, byte min, byte max, boolean hide_typing)
146
147 ^ INPUTTEXT widget actions ^ return value                ^ terminal response for ''23 GET INPUT'' proactive SIM command ^
148 | OK                       | text string entered         | ''00'' Command performed successfully |
149 | BACK                     | ''Error.SimToolkit.GoBack'' | ''11'' Backward move in the proactive SIM session requested by the user | 
150
151
152 === RequestDigits ===
153
154   string RequestDigits(string alpha, byte icon_id, string default, byte min, byte max, boolean hide_typing)
155
156 ^ INPUTTEXT widget actions ^ return value                ^ terminal response for ''23 GET INPUT'' proactive SIM command ^
157 | OK                       | number entered              | ''00'' Command performed successfully |
158 | BACK                     | ''Error.SimToolkit.GoBack'' | ''11'' Backward move in the proactive SIM session requested by the user | 
159
160 === RequestKey ===
161
162   string RequestKey(string alpha, byte icon_id)
163
164 ^ INPUTKEY widget actions ^ return value                ^ terminal response for ''22 GET INKEY'' proactive SIM command ^
165 | OK                      | character entered           | ''00'' Command performed successfully |
166 | BACK                    | ''Error.SimToolkit.GoBack'' | ''11'' Backward move in the proactive SIM session requested by the user |
167
168 === RequestDigit ===
169
170   string RequestDigit(string alpha, byte icon_id)
171
172 ^ INPUTKEY widget actions ^ return value                ^ terminal response for ''22 GET INKEY'' proactive SIM command ^
173 | OK                      | digit entered               | ''00'' Command performed successfully |
174 | BACK                    | ''Error.SimToolkit.GoBack'' | ''11'' Backward move in the proactive SIM session requested by the user |
175
176 === RequestConfirmation ===
177
178   boolean RequestConfirmation(string alpha, byte icon_id)
179
180 ^ POPUP widget actions ^ return value                ^ terminal response for ''22 GET INKEY'' proactive SIM command ^
181 | OK                   | TRUE                        | ''00'' Command performed successfully |
182 | BACK                 | ''Error.SimToolkit.GoBack'' | ''11'' Backward move in the proactive SIM session requested by the user |
183
184 === ConfirmCallSetup ===
185
186   boolean ConfirmCallSetup(string information, byte icon_id)
187
188 ^ YESNO widget actions ^ return value                    ^ terminal response for ''10 SETUP CALL'' proactive SIM command ^
189 | YES                  | TRUE                            | ''00'' Command performed successfully |
190 | NO                   | FALSE                           | ''00'' Command performed successfully |
191 | END                  | ''Error.SimToolkit.EndSession'' | ''10'' Proactive SIM session terminated by user |
192
193 === PlayTone ===
194
195   void PlayTone(string tone, string text, byte icon_id)
196
197 ^ MESSAGE widget actions ^ return value ^ terminal response for ''20 PLAY TONE'' proactive SIM command ^
198 | none | void | ''00'' Command performed successfully | 
199 | END | ''Error.SimToolkit.EndSession'' | ''10'' Proactive SIM session terminated by user |
200
201 === LoopTone ===
202
203   void LoopTone(string tone, string text, byte icon_id)
204
205 ^ MESSAGE widget actions ^ return value                   ^ terminal response for ''20 PLAY TONE'' proactive SIM command ^
206 | END                   | ''Error.SimToolkit.EndSession'' | ''10'' Proactive SIM session terminated by user |
207
208 === DisplayActionInformation ===
209
210   void DisplayActionInformation(string text, byte icon_id)
211
212 ^ MESSAGE widget actions ^ return value ^ terminal response for proactive SIM command ^
213
214 === ConfirmLaunchBrowser ===
215
216   boolean ConfirmLaunchBrowser(string information, byte icon_id, string url)
217
218 ^ YESNO widget actions ^ return value                    ^ terminal response for ''15 LAUNCH BROWSER'' proactive SIM command ^
219 | YES                  | TRUE                            | ''00'' Command performed successfully |
220 | NO                   | FALSE                           |  |
221 | END                  | ''Error.SimToolkit.EndSession'' | ''10'' Proactive SIM session terminated by user |
222
223
224 === Cancel ===
225
226   void Cancel()
227
228 ^ widget actions        ^ return value ^ terminal response for proactive SIM command ^
229 | Close current window. | void         | |
230
231 === Release ===
232
233   void Release()
234
235 ^ widget actions   ^ return value ^ terminal response for proactive SIM command ^
236 | Terminate agent. | void         | |
237
238 ===== MeeGo platform specifics =====
239
240 ==== Launcher integration ====
241
242 The SIM Application Toolkit appears in the launcher with a name and an icon provided by the SIM card. This information is provided as properties by the **org.ofono.SimToolkit** DBUS interface. 
243
244   * string MainMenuTitle : Contains the title of the main menu.
245   * byte MainMenuIcon : Contains the identifier of the icon for the main menu. 
246
247 **TODO** The meego-app-satk.desktop file is not currently modified at runtime, the default title / icon appears in the launcher.
248
249 ==== Window stacking ====
250
251 Although the SATK application is meant to be stateless, there may be a need to distinguish the cases when SATK is invoked explicitly from the launcher by user action, or from a SIM command. 
252
253 Typically SATK may handle a non-urgent DisplayText method with a message widget if invoked from the launcher, otherwise it should display a notification. 
254
255 ==== Notifications ====
256
257 SATK application may rely on the MeeGo platform notification UI to display non-urgent messages.
258
259 **TODO** Need to investigate MeeGo platform notification UI support.
260
261 ==== Idle screen ====
262
263 Idle screen information is provided as properties by the **org.ofono.SimToolkit** DBUS interface. 
264
265   * string IdleModeText : Contains the text to be used when the home screen is idle.
266   * byte IdleModeIcon : Contains the identifier of the icon for the main menu.
267 **TODO** Need to investigate Idle screen UI on MeeGo Handset platform.
268