path: root/doc/stk-api.txt

SimToolkit Hierarchy
===============

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
===============

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
					 [service].Error.SimToolkit.EndSession

			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.EndSession
					 [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
					 [service].Error.SimToolkit.EndSession

			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
					 [service].Error.SimToolkit.EndSession

		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
					 [service].Error.SimToolkit.EndSession

		string RequestDigit(string alpha, byte icon_id)

			Same as above, but only digits (0-9, *#+) are
			expected.

			Possible Errors: [service].Error.SimToolkit.GoBack
					 [service].Error.SimToolkit.EndSession

		string RequestQuickDigit(string alpha, byte icon_id)

			Same as above but the entered digit shall not be
			displayed and the response shall be sent immediately
			after the key press. "+" is not allowed for user input.

			Possible Errors: [service].Error.SimToolkit.GoBack
					 [service].Error.SimToolkit.EndSession

		boolean RequestConfirmation(string alpha, byte icon_id)

			Asks the agent to get confirmation from the user.

			Possible Errors: [service].Error.SimToolkit.GoBack
					 [service].Error.SimToolkit.EndSession

		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().  If the
			method returns it is assumed that the user has
			explicitly dismissed the dialog and no Cancel() is
			sent.

		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 DisplayAction(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() or until the
			user decides to end the session.

			Possible Errors: [service].Error.SimToolkit.EndSession

		boolean ConfirmOpenChannel(string information,
						byte icon_id) [experimental]

			Asks the agent to request user to confirm the channel
			set-up.

			Possible Errors: [service].Error.SimToolkit.EndSession

		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.