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
 120                         Implementation notes:
 121
 122                         - High / normal priority indicated by urgent
 123
 124                         - The clear message after delay / wait for user to
 125                           clear flags are handled as follows.  If the wait for
 126                           user flag is set, then oFono sets a higher timeout
 127                           for the Agent DisplayText method call.  It will then
 128                           call Cancel() on the agent after this timeout
 129                           expires and the "No response from user" terminal
 130                           response is sent.  If the agent returns earlier from
 131                           this method call, a terminal response "Command
 132                           "performed successfully" is sent.
 133
 134                           It might be required to pass a flag to the UI to
 135                           hint it that allocation of an 'acknowledgement'
 136                           button is required in the case of a longer timeout.
 137                           However, the UI can figure this out itself as well
 138                           based on a timer threshold.  More input needed.
 139
 140                         - Immediate Response indication is handled internally,
 141                           terminal response is sent immediately and no other
 142                           indication is given to the user / agent.  Response
 143                           from this method call is ignored and a short
 144                           timeout is used for the method call.  Once another
 145                           proactive command arrives, and the DisplayText is
 146                           still pending, Cancel() is called.
 147
 148                 string RequestInput(string alpha, byte icon_id,
 149                                 string default, byte min, byte max,
 150                                 boolean hide_typing)
 151
 152                         Tells the agent to request an input string from the
 153                         user.  The alpha parameter and icon_id gives context
 154                         to the user.  The default string contains the suggested
 155                         default by the SIM.  The min and max parameters contain
 156                         how many characters the user should enter.  The
 157                         parameter hide_typing indicates whether user's typing
 158                         should be opaque.
 159
 160                         Possible Errors: [service].Error.SimToolkit.GoBack
 161
 162                         Implementation notes:
 163
 164                         - It is still unclear how to handle gsm vs ucs2
 165                           accepted alphabet selection.  Can the reduced
 166                           character set functionality from SMS be applied
 167                           here?  If not, then an extra gsm vs ucs2 acceptance
 168                           argument needs to be added.
 169
 170                 string RequestDigits(string alpha, byte icon_id,
 171                                         string default, byte min, byte max,
 172                                         boolean hide_typing)
 173
 174                         Same as GetInput but only digit characters (0-9, *#+)
 175                         are expected.
 176
 177                         Possible Errors: [service].Error.SimToolkit.GoBack
 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
 187                 string RequestDigit(string alpha, byte icon_id)
 188
 189                         Same as above, but only digits (0-9, *#+) are
 190                         expected.
 191
 192                         Possible Errors: [service].Error.SimToolkit.GoBack
 193
 194                 boolean RequestConfirmation(string alpha, byte icon_id)
 195
 196                         Asks the agent to get confirmation from the user.
 197
 198                         Possible Errors: [service].Error.SimToolkit.GoBack
 199
 200                 boolean ConfirmCallSetup(string information, byte icon_id)
 201
 202                         Asks the agent to request user to confirm an
 203                         outgoing call setup.  If confirmed, the next new
 204                         outgoing call reported by VoiceCallManager will
 205                         have the Information and Icon properties set to
 206                         inform the user.  Hanging up before the call is
 207                         connected will cause EndSession reply to be sent.
 208
 209                         Possible Errors: [service].Error.SimToolkit.EndSession
 210
 211                 void PlayTone(string tone, string text, byte icon_id)
 212
 213                         Tells the agent to play an audio tone once.  The
 214                         method should return once the tone is finished
 215                         playing.  The text parameter contains an optional
 216                         text to be displayed to the user.  The following
 217                         tones are defined:
 218                                 "dial-tone"
 219                                 "busy"
 220                                 "congestion"
 221                                 "radio-path-acknowledge"
 222                                 "radio-path-not-available"
 223                                 "error"
 224                                 "call-waiting"
 225                                 "ringing-tone"
 226                                 "general-beep"
 227                                 "positive-acknowledgement"
 228                                 "negative-acknowledgement"
 229                                 "user-ringing-tone"
 230                                 "user-sms-alert"
 231                                 "critical" (high priority)
 232                                 "vibrate"
 233                                 "happy"
 234                                 "sad"
 235                                 "urgent-action"
 236                                 "question"
 237                                 "message-received"
 238
 239                         Possible Errors: [service].Error.SimToolkit.EndSession
 240
 241                 void LoopTone(string tone, string text, byte icon_id)
 242
 243                         Tells the agent to reproduce an audio tone in a
 244                         loop until the method call is cancelled.  See
 245                         PlayTone() above for the list of possible tone names.
 246                         The text parameter contains an optional text to
 247                         be displayed to the user.
 248
 249                         Possible Errors: [service].Error.SimToolkit.EndSession
 250
 251                 void Cancel()
 252
 253                         Asks the agent to cancel any ongoing operation in
 254                         progress.  This is usually either because the agent
 255                         is taking too long to respond or the Sim Application
 256                         has terminated the session.
 257
 258                 void Release()
 259
 260                         Agent is being released, possibly because of oFono
 261                         terminating, SimToolkit interface torn down or modem
 262                         off.  If the agent is registered as a global agent,
 263                         no UnregisterAgent call is expected.