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