doc/stk-api.txt

   1 SimToolkit Hierarchy
   2 ===============
   3
   4 Service         org.ofono
   5 Interface       org.ofono.SimToolkit
   6 Object path     [variable prefix]/{modem0,modem1,...}
   7
   8 Methods         dict GetProperties()
   9
  10                         Returns properties for the SimToolkit object.  See the
  11                         properties section for available properties.
  12
  13                 void SelectItem(byte item, object agent)
  14
  15                         Selects an item from the main menu, thus triggering
  16                         a new user session.  The agent parameter specifies
  17                         a new agent to be used for the duration of the
  18                         user session.
  19
  20                         Possible Errors: [service].Error.InProgress
  21                                          [service].Error.NotSupported
  22                                          [service].Error.InvalidArguments
  23                                          [service].Error.InvalidFormat
  24                                          [service].Error.Failed
  25
  26                 void RegisterAgent(object path)
  27
  28                         Registers a default agent to be used for SIM initiated
  29                         actions such as Display Text, Get Inkey or Get Input.
  30                         These can typically occur when a special SMS is
  31                         received and might not involve interaction from the
  32                         user.
  33
  34                         Possible Errors: [service].Error.InProgress
  35                                          [service].Error.InvalidArguments
  36                                          [service].Error.InvalidFormat
  37                                          [service].Error.Failed
  38
  39                 void UnregisterAgent(object path)
  40
  41                         Unregisters the default agent.  If no agent is
  42                         registered then unsolicited commands from the SIM
  43                         are rejected.
  44
  45                         Possible Errors: [service].Error.InvalidArguments
  46                                          [service].Error.Failed
  47
  48 Signals         PropertyChanged(string property, variant value)
  49
  50                         Signal is emitted whenever a property has changed.
  51                         The new value is passed as the signal argument.
  52
  53 Properties      string IdleModeText [readonly]
  54
  55                         Contains the text to be used when the home screen is
  56                         idle.  This text is set by the SIM and can change
  57                         at any time.
  58
  59                 byte IdleModeIcon [readonly]
  60
  61                         Contains the identifier of the icon accompanying
  62                         the idle mode text.
  63
  64                 array{struct{string, byte}} MainMenu [readonly]
  65
  66                         Contains the items that make up the main menu.  This
  67                         is populated by the SIM when it sends the Setup Menu
  68                         Proactive Command.  The main menu is always available,
  69                         but its contents can be changed at any time.  Each
  70                         item contains the item label and icon identifier.
  71
  72                 string MainMenuTitle [readonly]
  73
  74                         Contains the title of the main menu.
  75
  76                 string MainMenuIcon [readonly]
  77
  78                         Contains the identifier of the icon for the main menu.
  79
  80 SimToolkitAgent Hierarchy
  81 ===============
  82
  83 Service         unique name
  84 Interface       org.ofono.SimToolkitAgent
  85 Object path     freely definable
  86
  87 Methods         byte RequestSelection(string title, byte icon_id,
  88                                         array{struct(string, byte)} items,
  89                                         int16 default)
  90
  91                         Tells the agent to ask the user to select an item
  92                         from the menu.  The default is set the the default
  93                         item index or -1 if no default is provided.
  94
  95                         This function should return the index of the item or
  96                         an error given below.
  97
  98                         Possible Errors: [service].Error.SimToolkit.GoBack
  99                                          [service].Error.SimToolkit.EndSession
 100
 101                         Implementation notes:
 102
 103                         - Data / Navigation type not indicated
 104                         - Soft key preferred not indicated
 105                         - Help available ignored
 106
 107                 void DisplayText(string text, byte icon_id, boolean urgent)
 108
 109                         Tells the agent to display text from the SIM.  The
 110                         boolean urgent parameter tells the agent whether this
 111                         is an urgent message and all other messages should be
 112                         cleared prior to the display of this text.
 113
 114                         Possible Errors: [service].Error.SimToolkit.GoBack
 115                                          [service].Error.SimToolkit.EndSession
 116                                          [service].Error.SimToolkit.Busy
 117
 118                         Implementation notes:
 119
 120                         - High / normal priority indicated by urgent
 121
 122                         - The clear message after delay / wait for user to
 123                           clear flags are handled as follows.  If the wait for
 124                           user flag is set, then oFono sets a higher timeout
 125                           for the Agent DisplayText method call.  It will then
 126                           call Cancel() on the agent after this timeout
 127                           expires and the "No response from user" terminal
 128                           response is sent.  If the agent returns earlier from
 129                           this method call, a terminal response "Command
 130                           "performed successfully" is sent.
 131
 132                           It might be required to pass a flag to the UI to
 133                           hint it that allocation of an 'acknowledgement'
 134                           button is required in the case of a longer timeout.
 135                           However, the UI can figure this out itself as well
 136                           based on a timer threshold.  More input needed.
 137
 138                         - Immediate Response indication is handled internally,
 139                           terminal response is sent immediately and no other
 140                           indication is given to the user / agent.  Response
 141                           from this method call is ignored and a short
 142                           timeout is used for the method call.  Once another
 143                           proactive command arrives, and the DisplayText is
 144                           still pending, Cancel() is called.
 145
 146                 string RequestInput(string alpha, byte icon_id,
 147                                 string default, byte min, byte max,
 148                                 boolean hide_typing)
 149
 150                         Tells the agent to request an input string from the
 151                         user.  The alpha parameter and icon_id gives context
 152                         to the user.  The default string contains the suggested
 153                         default by the SIM.  The min and max parameters contain
 154                         how many characters the user should enter.  The
 155                         parameter hide_typing indicates whether user's typing
 156                         should be opaque.
 157
 158                         Possible Errors: [service].Error.SimToolkit.GoBack
 159                                          [service].Error.SimToolkit.EndSession
 160
 161                         Implementation notes:
 162
 163                         - It is still unclear how to handle gsm vs ucs2
 164                           accepted alphabet selection.  Can the reduced
 165                           character set functionality from SMS be applied
 166                           here?  If not, then an extra gsm vs ucs2 acceptance
 167                           argument needs to be added.
 168
 169                 string RequestDigits(string alpha, byte icon_id,
 170                                         string default, byte min, byte max,
 171                                         boolean hide_typing)
 172
 173                         Same as GetInput but only digit characters (0-9, *#+)
 174                         are expected.
 175
 176                         Possible Errors: [service].Error.SimToolkit.GoBack
 177                                          [service].Error.SimToolkit.EndSession
 178
 179                 string RequestKey(string alpha, byte icon_id)
 180
 181                         Tells the agent to request a single input key from
 182                         the user.  The alpha parameter contains the context
 183                         for the request.
 184
 185                         Possible Errors: [service].Error.SimToolkit.GoBack
 186                                          [service].Error.SimToolkit.EndSession
 187
 188                 string RequestDigit(string alpha, byte icon_id)
 189
 190                         Same as above, but only digits (0-9, *#+) are
 191                         expected.
 192
 193                         Possible Errors: [service].Error.SimToolkit.GoBack
 194                                          [service].Error.SimToolkit.EndSession
 195
 196                 string RequestQuickDigit(string alpha, byte icon_id)
 197
 198                         Same as above but the entered digit shall not be
 199                         displayed and the response shall be sent immediately
 200                         after the key press. "+" is not allowed for user input.
 201
 202                         Possible Errors: [service].Error.SimToolkit.GoBack
 203                                          [service].Error.SimToolkit.EndSession
 204
 205                 boolean RequestConfirmation(string alpha, byte icon_id)
 206
 207                         Asks the agent to get confirmation from the user.
 208
 209                         Possible Errors: [service].Error.SimToolkit.GoBack
 210                                          [service].Error.SimToolkit.EndSession
 211
 212                 boolean ConfirmCallSetup(string information, byte icon_id)
 213
 214                         Asks the agent to request user to confirm an
 215                         outgoing call setup.  If confirmed, the next new
 216                         outgoing call reported by VoiceCallManager will
 217                         have the Information and Icon properties set to
 218                         inform the user.  Hanging up before the call is
 219                         connected will cause EndSession reply to be sent.
 220
 221                         Possible Errors: [service].Error.SimToolkit.EndSession
 222
 223                 void PlayTone(string tone, string text, byte icon_id)
 224
 225                         Tells the agent to play an audio tone once.  The
 226                         method should return once the tone is finished
 227                         playing.  The text parameter contains an optional
 228                         text to be displayed to the user.  The following
 229                         tones are defined:
 230                                 "dial-tone"
 231                                 "busy"
 232                                 "congestion"
 233                                 "radio-path-acknowledge"
 234                                 "radio-path-not-available"
 235                                 "error"
 236                                 "call-waiting"
 237                                 "ringing-tone"
 238                                 "general-beep"
 239                                 "positive-acknowledgement"
 240                                 "negative-acknowledgement"
 241                                 "user-ringing-tone"
 242                                 "user-sms-alert"
 243                                 "critical" (high priority)
 244                                 "vibrate"
 245                                 "happy"
 246                                 "sad"
 247                                 "urgent-action"
 248                                 "question"
 249                                 "message-received"
 250
 251                         Possible Errors: [service].Error.SimToolkit.EndSession
 252
 253                 void LoopTone(string tone, string text, byte icon_id)
 254
 255                         Tells the agent to reproduce an audio tone in a
 256                         loop until the method call is cancelled.  See
 257                         PlayTone() above for the list of possible tone names.
 258                         The text parameter contains an optional text to
 259                         be displayed to the user.
 260
 261                         Possible Errors: [service].Error.SimToolkit.EndSession
 262
 263                 void DisplayActionInformation(string text,
 264                                                 byte icon_id)
 265
 266                         Supplies a text string and/or icon concerning the
 267                         current activity in the terminal and UICC.  The
 268                         text should be displayed to the user on screen
 269                         until the call is canceled using Cancel().  If the
 270                         method returns it is assumed that the user has
 271                         explicitly dismissed the dialog and no Cancel() is
 272                         sent.
 273
 274                 boolean ConfirmLaunchBrowser(string information,
 275                                                 byte icon_id, string url)
 276
 277                         Asks the agent to request user to confirm launch
 278                         browser. If confirmed, then the agent should send
 279                         confirmation message to oFono and then should open
 280                         the launch browser with the given url.
 281
 282                 void DisplayAction(string text, byte icon_id)
 283
 284                         Supplies a text string and/or icon concerning the
 285                         current activity in the terminal and UICC. The
 286                         text should be displayed to the user on screen
 287                         until the call is canceled using Cancel() or until the
 288                         user decides to end the session.
 289
 290                         Possible Errors: [service].Error.SimToolkit.EndSession
 291
 292                 boolean ConfirmOpenChannel(string information,
 293                                                 byte icon_id) [experimental]
 294
 295                         Asks the agent to request user to confirm the channel
 296                         set-up.
 297
 298                         Possible Errors: [service].Error.SimToolkit.EndSession
 299
 300                 void Cancel() [noreply]
 301
 302                         Asks the agent to cancel any ongoing operation in
 303                         progress.  This is usually either because the agent
 304                         is taking too long to respond, the Sim Application
 305                         has terminated the session or a task has finished.
 306
 307                 void Release() [noreply]
 308
 309                         Agent is being released, possibly because of oFono
 310                         terminating, SimToolkit interface torn down or modem
 311                         off.  If the agent is registered as a global agent,
 312                         no UnregisterAgent call is expected.