doc/stk-api.txt

   1 SimToolkit Hierarchy [experimental]
   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 [experimental]
  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                 boolean RequestConfirmation(string alpha, byte icon_id)
 197
 198                         Asks the agent to get confirmation from the user.
 199
 200                         Possible Errors: [service].Error.SimToolkit.GoBack
 201                                          [service].Error.SimToolkit.EndSession
 202
 203                 boolean ConfirmCallSetup(string information, byte icon_id)
 204
 205                         Asks the agent to request user to confirm an
 206                         outgoing call setup.  If confirmed, the next new
 207                         outgoing call reported by VoiceCallManager will
 208                         have the Information and Icon properties set to
 209                         inform the user.  Hanging up before the call is
 210                         connected will cause EndSession reply to be sent.
 211
 212                         Possible Errors: [service].Error.SimToolkit.EndSession
 213
 214                 void PlayTone(string tone, string text, byte icon_id)
 215
 216                         Tells the agent to play an audio tone once.  The
 217                         method should return once the tone is finished
 218                         playing.  The text parameter contains an optional
 219                         text to be displayed to the user.  The following
 220                         tones are defined:
 221                                 "dial-tone"
 222                                 "busy"
 223                                 "congestion"
 224                                 "radio-path-acknowledge"
 225                                 "radio-path-not-available"
 226                                 "error"
 227                                 "call-waiting"
 228                                 "ringing-tone"
 229                                 "general-beep"
 230                                 "positive-acknowledgement"
 231                                 "negative-acknowledgement"
 232                                 "user-ringing-tone"
 233                                 "user-sms-alert"
 234                                 "critical" (high priority)
 235                                 "vibrate"
 236                                 "happy"
 237                                 "sad"
 238                                 "urgent-action"
 239                                 "question"
 240                                 "message-received"
 241
 242                         Possible Errors: [service].Error.SimToolkit.EndSession
 243
 244                 void LoopTone(string tone, string text, byte icon_id)
 245
 246                         Tells the agent to reproduce an audio tone in a
 247                         loop until the method call is cancelled.  See
 248                         PlayTone() above for the list of possible tone names.
 249                         The text parameter contains an optional text to
 250                         be displayed to the user.
 251
 252                         Possible Errors: [service].Error.SimToolkit.EndSession
 253
 254                 void DisplayActionInformation(string text, byte icon_id)
 255                                                 [noreply]
 256
 257                         Supplies a text string and/or icon concerning the
 258                         current activity in the terminal and UICC.  The
 259                         text should be displayed to the user on screen
 260                         until the call is canceled using Cancel().  This
 261                         method should not return.
 262
 263                 boolean ConfirmLaunchBrowser(string information,
 264                                                 byte icon_id, string url)
 265
 266                         Asks the agent to request user to confirm launch
 267                         browser. If confirmed, then the agent should send
 268                         confirmation message to oFono and then should open
 269                         the launch browser with the given url.
 270
 271                 void DisplayAction(string text, byte icon_id)
 272
 273                         Supplies a text string and/or icon concerning the
 274                         current activity in the terminal and UICC. The
 275                         text should be displayed to the user on screen
 276                         until the call is canceled using Cancel() or until the
 277                         user decides to end the session.
 278
 279                         Possible Errors: [service].Error.SimToolkit.EndSession
 280
 281                 boolean ConfirmOpenChannel(string information, byte icon_id)
 282
 283                         Asks the agent to request user to confirm the channel
 284                         set-up.
 285
 286                         Possible Errors: [service].Error.SimToolkit.EndSession
 287
 288                 void Cancel() [noreply]
 289
 290                         Asks the agent to cancel any ongoing operation in
 291                         progress.  This is usually either because the agent
 292                         is taking too long to respond, the Sim Application
 293                         has terminated the session or a task has finished.
 294
 295                 void Release() [noreply]
 296
 297                         Agent is being released, possibly because of oFono
 298                         terminating, SimToolkit interface torn down or modem
 299                         off.  If the agent is registered as a global agent,
 300                         no UnregisterAgent call is expected.