mirror of git://git.sysmocom.de/ofono
276 lines
8.6 KiB
Plaintext
276 lines
8.6 KiB
Plaintext
SimToolkit Hierarchy [experimental]
|
|
===============
|
|
|
|
Service org.ofono
|
|
Interface org.ofono.SimToolkit
|
|
Object path [variable prefix]/{modem0,modem1,...}
|
|
|
|
Methods dict GetProperties()
|
|
|
|
Returns properties for the SimToolkit object. See the
|
|
properties section for available properties.
|
|
|
|
void SelectItem(byte item, object agent)
|
|
|
|
Selects an item from the main menu, thus triggering
|
|
a new user session. The agent parameter specifies
|
|
a new agent to be used for the duration of the
|
|
user session.
|
|
|
|
Possible Errors: [service].Error.InProgress
|
|
[service].Error.NotSupported
|
|
[service].Error.InvalidArguments
|
|
[service].Error.InvalidFormat
|
|
[service].Error.Failed
|
|
|
|
void RegisterAgent(object path)
|
|
|
|
Registers a default agent to be used for SIM initiated
|
|
actions such as Display Text, Get Inkey or Get Input.
|
|
These can typically occur when a special SMS is
|
|
received and might not involve interaction from the
|
|
user.
|
|
|
|
Possible Errors: [service].Error.InProgress
|
|
[service].Error.InvalidArguments
|
|
[service].Error.InvalidFormat
|
|
[service].Error.Failed
|
|
|
|
void UnregisterAgent(object path)
|
|
|
|
Unregisters the default agent. If no agent is
|
|
registered then unsolicited commands from the SIM
|
|
are rejected.
|
|
|
|
Possible Errors: [service].Error.InvalidArguments
|
|
[service].Error.Failed
|
|
|
|
Signals PropertyChanged(string property, variant value)
|
|
|
|
Signal is emitted whenever a property has changed.
|
|
The new value is passed as the signal argument.
|
|
|
|
Properties string IdleModeText [readonly]
|
|
|
|
Contains the text to be used when the home screen is
|
|
idle. This text is set by the SIM and can change
|
|
at any time.
|
|
|
|
byte IdleModeIcon [readonly]
|
|
|
|
Contains the identifier of the icon accompanying
|
|
the idle mode text.
|
|
|
|
array{struct{string, byte}} MainMenu [readonly]
|
|
|
|
Contains the items that make up the main menu. This
|
|
is populated by the SIM when it sends the Setup Menu
|
|
Proactive Command. The main menu is always available,
|
|
but its contents can be changed at any time. Each
|
|
item contains the item label and icon identifier.
|
|
|
|
string MainMenuTitle [readonly]
|
|
|
|
Contains the title of the main menu.
|
|
|
|
string MainMenuIcon [readonly]
|
|
|
|
Contains the identifier of the icon for the main menu.
|
|
|
|
SimToolkitAgent Hierarchy [experimental]
|
|
===============
|
|
|
|
Service unique name
|
|
Interface org.ofono.SimToolkitAgent
|
|
Object path freely definable
|
|
|
|
Methods byte RequestSelection(string title, byte icon_id,
|
|
array{struct(string, byte)} items,
|
|
int16 default)
|
|
|
|
Tells the agent to ask the user to select an item
|
|
from the menu. The default is set the the default
|
|
item index or -1 if no default is provided.
|
|
|
|
This function should return the index of the item or
|
|
an error given below.
|
|
|
|
Possible Errors: [service].Error.SimToolkit.GoBack
|
|
|
|
Implementation notes:
|
|
|
|
- Data / Navigation type not indicated
|
|
- Soft key preferred not indicated
|
|
- Help available ignored
|
|
|
|
void DisplayText(string text, byte icon_id, boolean urgent)
|
|
|
|
Tells the agent to display text from the SIM. The
|
|
boolean urgent parameter tells the agent whether this
|
|
is an urgent message and all other messages should be
|
|
cleared prior to the display of this text.
|
|
|
|
Possible Errors: [service].Error.SimToolkit.GoBack
|
|
[service].Error.SimToolkit.Busy
|
|
|
|
Implementation notes:
|
|
|
|
- High / normal priority indicated by urgent
|
|
|
|
- The clear message after delay / wait for user to
|
|
clear flags are handled as follows. If the wait for
|
|
user flag is set, then oFono sets a higher timeout
|
|
for the Agent DisplayText method call. It will then
|
|
call Cancel() on the agent after this timeout
|
|
expires and the "No response from user" terminal
|
|
response is sent. If the agent returns earlier from
|
|
this method call, a terminal response "Command
|
|
"performed successfully" is sent.
|
|
|
|
It might be required to pass a flag to the UI to
|
|
hint it that allocation of an 'acknowledgement'
|
|
button is required in the case of a longer timeout.
|
|
However, the UI can figure this out itself as well
|
|
based on a timer threshold. More input needed.
|
|
|
|
- Immediate Response indication is handled internally,
|
|
terminal response is sent immediately and no other
|
|
indication is given to the user / agent. Response
|
|
from this method call is ignored and a short
|
|
timeout is used for the method call. Once another
|
|
proactive command arrives, and the DisplayText is
|
|
still pending, Cancel() is called.
|
|
|
|
string RequestInput(string alpha, byte icon_id,
|
|
string default, byte min, byte max,
|
|
boolean hide_typing)
|
|
|
|
Tells the agent to request an input string from the
|
|
user. The alpha parameter and icon_id gives context
|
|
to the user. The default string contains the suggested
|
|
default by the SIM. The min and max parameters contain
|
|
how many characters the user should enter. The
|
|
parameter hide_typing indicates whether user's typing
|
|
should be opaque.
|
|
|
|
Possible Errors: [service].Error.SimToolkit.GoBack
|
|
|
|
Implementation notes:
|
|
|
|
- It is still unclear how to handle gsm vs ucs2
|
|
accepted alphabet selection. Can the reduced
|
|
character set functionality from SMS be applied
|
|
here? If not, then an extra gsm vs ucs2 acceptance
|
|
argument needs to be added.
|
|
|
|
string RequestDigits(string alpha, byte icon_id,
|
|
string default, byte min, byte max,
|
|
boolean hide_typing)
|
|
|
|
Same as GetInput but only digit characters (0-9, *#+)
|
|
are expected.
|
|
|
|
Possible Errors: [service].Error.SimToolkit.GoBack
|
|
|
|
string RequestKey(string alpha, byte icon_id)
|
|
|
|
Tells the agent to request a single input key from
|
|
the user. The alpha parameter contains the context
|
|
for the request.
|
|
|
|
Possible Errors: [service].Error.SimToolkit.GoBack
|
|
|
|
string RequestDigit(string alpha, byte icon_id)
|
|
|
|
Same as above, but only digits (0-9, *#+) are
|
|
expected.
|
|
|
|
Possible Errors: [service].Error.SimToolkit.GoBack
|
|
|
|
boolean RequestConfirmation(string alpha, byte icon_id)
|
|
|
|
Asks the agent to get confirmation from the user.
|
|
|
|
Possible Errors: [service].Error.SimToolkit.GoBack
|
|
|
|
boolean ConfirmCallSetup(string information, byte icon_id)
|
|
|
|
Asks the agent to request user to confirm an
|
|
outgoing call setup. If confirmed, the next new
|
|
outgoing call reported by VoiceCallManager will
|
|
have the Information and Icon properties set to
|
|
inform the user. Hanging up before the call is
|
|
connected will cause EndSession reply to be sent.
|
|
|
|
Possible Errors: [service].Error.SimToolkit.EndSession
|
|
|
|
void PlayTone(string tone, string text, byte icon_id)
|
|
|
|
Tells the agent to play an audio tone once. The
|
|
method should return once the tone is finished
|
|
playing. The text parameter contains an optional
|
|
text to be displayed to the user. The following
|
|
tones are defined:
|
|
"dial-tone"
|
|
"busy"
|
|
"congestion"
|
|
"radio-path-acknowledge"
|
|
"radio-path-not-available"
|
|
"error"
|
|
"call-waiting"
|
|
"ringing-tone"
|
|
"general-beep"
|
|
"positive-acknowledgement"
|
|
"negative-acknowledgement"
|
|
"user-ringing-tone"
|
|
"user-sms-alert"
|
|
"critical" (high priority)
|
|
"vibrate"
|
|
"happy"
|
|
"sad"
|
|
"urgent-action"
|
|
"question"
|
|
"message-received"
|
|
|
|
Possible Errors: [service].Error.SimToolkit.EndSession
|
|
|
|
void LoopTone(string tone, string text, byte icon_id)
|
|
|
|
Tells the agent to reproduce an audio tone in a
|
|
loop until the method call is cancelled. See
|
|
PlayTone() above for the list of possible tone names.
|
|
The text parameter contains an optional text to
|
|
be displayed to the user.
|
|
|
|
Possible Errors: [service].Error.SimToolkit.EndSession
|
|
|
|
void DisplayActionInformation(string text, byte icon_id)
|
|
|
|
Supplies a text string and/or icon concerning the
|
|
current activity in the terminal and UICC. The
|
|
text should be displayed to the user on screen
|
|
until the call is canceled using Cancel(). This
|
|
method should not return.
|
|
|
|
boolean ConfirmLaunchBrowser(string information,
|
|
byte icon_id, string url)
|
|
|
|
Asks the agent to request user to confirm launch
|
|
browser. If confirmed, then the agent should send
|
|
confirmation message to oFono and then should open
|
|
the launch browser with the given url.
|
|
|
|
void Cancel() [noreply]
|
|
|
|
Asks the agent to cancel any ongoing operation in
|
|
progress. This is usually either because the agent
|
|
is taking too long to respond, the Sim Application
|
|
has terminated the session or a task has finished.
|
|
|
|
void Release() [noreply]
|
|
|
|
Agent is being released, possibly because of oFono
|
|
terminating, SimToolkit interface torn down or modem
|
|
off. If the agent is registered as a global agent,
|
|
no UnregisterAgent call is expected.
|