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