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 IdleText
  59
  60                         Contains the text to be used when the home screen is
  61                         idle.  This text is set by the SIM and can be changed
  62                         at any time.
  63
  64                 array{struct{string, byte}} MainMenu
  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.
  70
  71                 string MainMenuTitle
  72
  73                         Contains the title of the main menu.
  74
  75                 array{byte} Icons
  76
  77                         Contains the identifiers of all available icons for
  78                         this SIM.
  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                                         byte default)
  90
  91                         Tells the agent to ask the user to select an item
  92                         from the menu.  This function should return the index
  93                         of the item or an error given below:
  94
  95                         Possible Errors: [service].Error.SimToolkit.GoBack
  96
  97                         Implementation notes:
  98
  99                         - Data / Navigation type not indicated
 100                         - Soft key preferred not indicated
 101                         - Help available ignored
 102
 103                 void DisplayText(string text, byte icon_id, boolean urgent)
 104
 105                         Tells the agent to display text from the SIM.  The
 106                         boolean urgent parameter tells the agent whether this
 107                         is an urgent message and all other messages should be
 108                         cleared prior to the display of this text.
 109
 110                         Possible Errors: [service].Error.SimToolkit.GoBack
 111
 112                         Implementation notes:
 113
 114                         - High / normal priority indicated by urgent
 115
 116                         - The clear message after delay / wait for user to
 117                           clear flags are handled as follows.  If the wait for
 118                           user flag is set, then oFono sets a higher timeout
 119                           for the Agent DisplayText method call.  It will then
 120                           call Cancel() on the agent after this timeout
 121                           expires and the "No response from user" terminal
 122                           response is sent.  If the agent returns earlier from
 123                           this method call, a terminal response "Command
 124                           "performed successfully" is sent.
 125
 126                           It might be required to pass a flag to the UI to
 127                           hint it that allocation of an 'acknowledgement'
 128                           button is required in the case of a longer timeout.
 129                           However, the UI can figure this out itself as well
 130                           based on a timer threshold.  More input needed.
 131
 132                         - Immediate Response indication is handled internally,
 133                           terminal response is sent immediately and no other
 134                           indication is given to the user / agent.  Response
 135                           from this method call is ignored and a short
 136                           timeout is used for the method call.  Once another
 137                           proactive command arrives, and the DisplayText is
 138                           still pending, Cancel() is called.
 139
 140                 string RequestInput(string alpha, byte icon_id,
 141                                 string default, byte min, byte max,
 142                                 boolean hide_typing)
 143
 144                         Tells the agent to request an input string from the
 145                         user.  The alpha parameter and icon_id gives context
 146                         to the user.  The default string contains the suggested
 147                         default by the SIM.  The min and max parameters contain
 148                         how many characters the user should enter.  The
 149                         parameter hide_typing indicates whether user's typing
 150                         should be opaque.
 151
 152                         Possible Errors: [service].Error.SimToolkit.GoBack
 153
 154                         Implementation notes:
 155
 156                         - It is still unclear how to handle gsm vs ucs2
 157                           accepted alphabet selection.  Can the reduced
 158                           character set functionality from SMS be applied
 159                           here?  If not, then an extra gsm vs ucs2 acceptance
 160                           argument needs to be added.
 161
 162                 string RequestDigits(string alpha, byte icon_id,
 163                                         string default, byte min, byte max,
 164                                         boolean hide_typing)
 165
 166                         Same as GetInput but only digit characters (0-9, *#+)
 167                         are expected.
 168
 169                         Possible Errors: [service].Error.SimToolkit.GoBack
 170
 171                 string RequestKey(string alpha, byte icon_id)
 172
 173                         Tells the agent to request a single input key from
 174                         the user.  The alpha parameter contains the context
 175                         for the request.
 176
 177                         Possible Errors: [service].Error.SimToolkit.GoBack
 178
 179                 string RequestDigit(string alpha, byte icon_id)
 180
 181                         Same as above, but only digits (0-9, *#+) are
 182                         expected.
 183
 184                         Possible Errors: [service].Error.SimToolkit.GoBack
 185
 186                 boolean RequestConfirmation(string alpha, byte icon_id)
 187
 188                         Asks the agent to get confirmation from the user.
 189
 190                         Possible Errors: [service].Error.SimToolkit.GoBack
 191
 192                 void Cancel()
 193
 194                         Asks the agent to cancel any ongoing operation in
 195                         progress.  This is usually either because the agent
 196                         is taking too long to respond or the Sim Application
 197                         has terminated the session.
 198
 199                 void Release()
 200
 201                         Agent is being released, possibly because of oFono
 202                         terminating, SimToolkit interface torn down or modem
 203                         off.  If the agent is registered as a global agent,
 204                         no UnregisterAgent call is expected.