QSimToolkit Class Reference
[QtTelephonyModule]

Detailed Description

The QSimToolkit class provides an interface to SIM toolkit applications.

This class is used by a host program (usually simapp) to access the SIM toolkit facilities defined by 3GPP TS 11.14.

The SIM toolkit application sends a stream of QSimCommand objects to the host program by way of the command() signal. The host program then performs the designated command and responds by calling one of the methods in the QSimToolkit class.

For example, if the SIM toolkit sends a SetupMenu command to the host program, the program displays the indicated menu to the user. When the user selects an item, the host program calls sendEnvelope() to inform the SIM toolkit of the choice. The SIM toolkit will then send another QSimCommand object for the next phase of the application.

Most commands use sendResponse() to send the client's response to the command, except SetupMenu which uses sendEnvelope().

Some commands are automatically acknowledged by the modem or modem vendor plugin and do not need an explicit client acknowledgement with sendResponse(). The emitCommandAndRespond() function documents the commands that should be automatically acknowledged.

See also QSimCommand and QSimMenuItem.

Member Function Documentation

QSimToolkit::QSimToolkit ( const QString & service = QString(), QObject * parent = 0, QCommInterface::Mode mode = Client )

Construct a new SIM toolkit handling object for service and attach it to parent. The object will be created in client mode if mode is Client, or server mode otherwise.

If service is empty, this class will use the first available service that supports SIM toolkit. If there is more than one service that supports SIM toolkit, the caller should enumerate them with QCommServiceManager::supports() and create separate QSimToolkit objects for each.

See also QCommServiceManager::supports().

QSimToolkit::~QSimToolkit ()

Destroy this SIM toolkit handling object.

void QSimToolkit::aborted ()   [slot]

Tell the SIM that the current session was aborted by the user. The SIM returns to the main menu.

This function is deprecated because it cannot properly match commands and responses. Use sendResponse() to generate a QSimTerminalResponse::SessionTerminated response instead.

void QSimToolkit::allowCallSetup ()   [slot]

Allow a call setup request to proceed.

Applies to: SetupCall.

This function is deprecated because it cannot properly match commands and responses. Use sendResponse() to generate a QSimTerminalResponse::Success response instead.

See also denyCallSetup().

void QSimToolkit::begin ()   [virtual slot]

Begin using the SIM toolkit facilities and request the main menu.

This is the first method that should be called by a host program that wishes to access the SIM toolkit.

In response, this class will emit a command() signal with the main menu, or a beginFailed() signal if SIM toolkit facilities are not available.

See also end(), command(), and beginFailed().

void QSimToolkit::beginFailed ()   [signal]

Signal that is emitted if begin() fails because SIM toolkit functionality was not available.

void QSimToolkit::cannotProcess ()   [slot]

Tell the SIM that the previous request was beyond the capability of the ME to perform. i.e. the ME does not have the functionality at all.

This function is deprecated because it cannot properly match commands and responses. Use sendResponse() to generate a QSimTerminalResponse::BeyondMECapabilities response instead.

void QSimToolkit::clearText ()   [slot]

The user has cleared the text display after a DisplayText command that did not have QSimCommand::clearAfterDelay() set.

Applies to: DisplayText.

This function is deprecated because it cannot properly match commands and responses. Use sendResponse() to generate a QSimTerminalResponse::Success response instead.

See also sendResponse().

void QSimToolkit::command ( const QSimCommand & command )   [signal]

Signal that is emitted when the application running in the SIM wishes to send a command to the host program.

Usually server-side implementations will use emitCommandAndRespond() instead of directly emitting command(), because there are some commands that need an immediate response.

See also QSimCommand and emitCommandAndRespond().

void QSimToolkit::controlEvent ( const QSimControlEvent & event )   [signal]

Signal that is emitted when a SIM control event arrives.

See also QSimControlEvent.

void QSimToolkit::denyCallSetup ()   [slot]

The user denied a call setup request.

Applies to: SetupCall.

This function is deprecated because it cannot properly match commands and responses. Use sendResponse() to generate a QSimTerminalResponse::UserDidNotAccept response instead.

See also allowCallSetup().

void QSimToolkit::emitCommandAndRespond ( const QSimCommand & command )   [protected]

Emits the command() signal, passing command as its argument. Then, if the commmand needs an immediate response to the SIM toolkit application, then sendResponse() is called.

The following commands need an immediate response by emitCommandAndRespond(), but the commands themselves are processed by client applications:

The following commands are expected to be handled internally by the modem, or the modem vendor plugin. Qt Extended will simply acknowledge receipt of the command with sendResponse() and then passes the command up to the client applications. Most of these can be safely ignored by client applications, or the application only needs to display a text string and/or an icon until such time as a new command becomes available.

If the modem does not handle one or more of the above commands internally, the modem vendor plugin is responsible implementing the command and for composing the correct terminal response. If the modem vendor plugin does this, it should bypass emitCommandAndRespond() and emit the command() signal directly.

For example, if the modem does not handle the SendSMS command internally, the modem vendor plugin is responsible for formatting the correct SMS message and transmitting it over the network. The client application only needs to handle text display while the message is being sent.

In the case of ProvideLocalInformation, if the language setting is being requested, the current Qt Extended language code is returned.

See also command() and sendResponse().

void QSimToolkit::end ()   [virtual slot]

End using the SIM toolkit facilities.

See also begin().

void QSimToolkit::endSession ()   [slot]

End the current session, upon the user's request. The SIM returns to the main menu.

Applies to: GetInkey, GetInput, SelectItem.

This function is deprecated because it cannot properly match commands and responses. Use sendResponse() to generate a QSimTerminalResponse::SessionTerminated response instead.

void QSimToolkit::help ( QSimCommand::Type command, uint item = 0 )   [slot]

Request help for a particular type of command or menu item.

Applies to: SetupMenu, GetInkey, GetInput, SelectItem.

This function is deprecated because it cannot properly match commands and responses. Use sendResponse() or sendEnvelope() to generate the appropriate help request instead.

void QSimToolkit::idleScreen ()   [slot]

Indicate to the SIM toolkit application that the system has become idle and the SIM had previously requested IdleScreen events.

Applies to: SetupEventList.

This function is deprecated. Use sendEnvelope() to generate an idle screen event instead.

See also userActivity().

void QSimToolkit::input ( const QString & value )   [slot]

Sends a string value in response to a GetInput command.

Applies to: GetInput.

This function is deprecated because it cannot properly match commands and responses. Use sendResponse() to generate a QSimTerminalResponse::Success response instead.

See also key().

void QSimToolkit::key ( const QString & value )   [slot]

Sends a string value in response to a GetInkey command.

Applies to: GetInkey.

This function is deprecated because it cannot properly match commands and responses. Use sendResponse() to generate a QSimTerminalResponse::Success response instead.

See also sendResponse() and input().

void QSimToolkit::mainMenuSelected ( uint item )   [slot]

Indicate to the SIM toolkit application that an item on the main menu has been selected.

Applies to: SetupMenu.

This function is deprecated. Use sendEnvelope() to generate a QSimEnvelope::MenuSelection envelope instead.

See also sendEnvelope().

void QSimToolkit::moveBackward ()   [slot]

Move backward within the current session.

This function is deprecated because it cannot properly match commands and responses. Use sendResponse() to generate a QSimTerminalResponse::BackwardMove response instead.

void QSimToolkit::noResponseFromUser ()   [slot]

Tell the SIM that no response has been received from the user within a reasonable period of time.

This function is deprecated because it cannot properly match commands and responses. Use sendResponse() to generate a QSimTerminalResponse::NoResponseFromUser response instead.

void QSimToolkit::sendEnvelope ( const QSimEnvelope & env )   [virtual slot]

Sends an ENVELOPE env to the SIM toolkit application. This is typically used for selecting items from the main menu.

See also sendResponse() and command().

void QSimToolkit::sendResponse ( const QSimTerminalResponse & resp )   [virtual slot]

Sends a TERMINAL RESPONSE resp for the last SIM toolkit command that was received via command(). The command must be set on the response with QSimTerminalResponse::setCommand() so that the SIM knows which command is being responded to.

See also sendEnvelope(), command(), and QSimTerminalResponse::setCommand().

void QSimToolkit::subMenuExited ()   [slot]

Indicate to the SIM toolkit application that the user has chosen to exit from the current sub menu.

Applies to: SelectItem.

This function is deprecated because it cannot properly match commands and responses. Use sendResponse() to generate a QSimTerminalResponse::BackwardMove response instead.

See also subMenuSelected().

void QSimToolkit::subMenuSelected ( uint item )   [slot]

Indicate to the SIM toolkit application that an item on a sub menu has been selected.

Applies to: SelectItem.

This function is deprecated because it cannot properly match commands and responses. Use sendResponse() to generate a QSimTerminalResponse::Success response instead.

See also subMenuExited().

void QSimToolkit::temporarilyUnavailable ()   [slot]

Tell the SIM that the ME cannot process the previous request at this time, but may be able to later.

This function is deprecated because it cannot properly match commands and responses. Use sendResponse() to generate a QSimTerminalResponse::MEUnableToProcess response instead.

void QSimToolkit::userActivity ()   [slot]

Indicate to the SIM toolkit application that user activity has occurred and the SIM had previously requested UserActivity events.

Applies to: SetupEventList.

This function is deprecated. Use sendEnvelope() to generate a user activity event instead.

See also idleScreen().