Qt Mobility Reference Documentation

QContactAction Class Reference

The QContactAction class provides an interface for performing an action on a QContact or QContactDetail. More...

 #include <QContactAction>

Public Types

enum State { InactiveState, FinishedDetachedState, ActiveState, FinishedState, FinishedWithErrorState }

Public Functions

virtual ~QContactAction () = 0
virtual QContactActionDescriptor actionDescriptor () const = 0
virtual QContactFilter contactFilter () const = 0
virtual bool invokeAction ( const QContact & contact, const QContactDetail & detail = QContactDetail(), const QVariantMap & parameters = QVariantMap() ) = 0
virtual bool isDetailSupported ( const QContactDetail & detail, const QContact & contact = QContact() ) const = 0
virtual QVariantMap metaData () const = 0
virtual QVariantMap results () const = 0
virtual State state () const = 0
virtual QList<QContactDetail> supportedDetails ( const QContact & contact ) const = 0

Signals

void resultsAvailable ()
void stateChanged ( QContactAction::State newState )

Static Public Members

QContactAction * action ( const QContactActionDescriptor & descriptor )
QList<QContactActionDescriptor> actionDescriptors ( const QString & actionName = QString(), const QString & vendorName = QString(), int implementationVersion = -1 )
QStringList availableActions ( const QString & vendor = QString(), int implementationVersion = -1 )

Detailed Description

The QContactAction class provides an interface for performing an action on a QContact or QContactDetail.

An action is anything that can be performed on a contact, or a detail of a contact. An example of an action might be "Send Email" or "Dial" or "Plot Navigation Route". One action may be implemented by multiple vendors, and indeed one vendor may provide multiple implementations of the same action. The name of an action identifies its semantics, while its implementation version distinguishes it from other implementations of the action by the same vendor.

Invocation of an action is asynchronous; at some stage after calling invokeAction() the action instance will emit the stateChanged() signal. Any results of the action may be retrieved by calling results(), and as results become available the action will emit resultsAvailable().

Each instance of a QContactAction is created by a QContactActionFactory when QContactActionFactory::instance() is called; the caller takes ownership of the action instance.

See also QContactActionFactory and QContactActionFilter.


Member Type Documentation

enum QContactAction::State

Describes the current status of the asynchronous action operation

ConstantValueDescription
QContactAction::InactiveState0The operation has not yet been initiated
QContactAction::FinishedDetachedState3The operation was initiated but no further information is or will be available
QContactAction::ActiveState1The operation was initiated and is not yet finished
QContactAction::FinishedState2The operation successfully completed
QContactAction::FinishedWithErrorState4The operation has finished, but an error occurred

Member Function Documentation

QContactAction::~QContactAction () [pure virtual]

Clears any memory in use by this instance of the action implementation

QContactAction * QContactAction::action ( const QContactActionDescriptor & descriptor ) [static]

Returns a pointer to a new instance of the action implementation identified by the given descriptor. The caller takes ownership of the action implementation and must delete it to avoid leaking memory.

QContactActionDescriptor QContactAction::actionDescriptor () const [pure virtual]

Returns the descriptor which uniquely identifies this action implementation. A descriptor consists of an action name, a vendor name and an implementation version. The name of the action identifies the action provided; different implementations of an action with the same name must provide the same functionality, but may differ in implementation semantics. Hence, the action name includes the major version of the interface definition implemented. The vendor name is the identification string of the vendor which has provided this implementation. The implementation version is the (minor) version of the implementation, and is vendor-specific.

See also QContactActionDescriptor.

QList<QContactActionDescriptor> QContactAction::actionDescriptors ( const QString & actionName = QString(), const QString & vendorName = QString(), int implementationVersion = -1 ) [static]

Returns a list of QContactActionDescriptor instances which identified implementations of the given actionName which are provided by the given vendorName and are of the given implementationVersion. If actionName is empty, descriptors for implementations of all actions are returned; if vendorName is empty, descriptors for implementations provided by any vendor and of any implementation version are returned; if implementationVersion is empty, descriptors for any implementations provided by the given vendorName of the given actionName are returned.

QStringList QContactAction::availableActions ( const QString & vendor = QString(), int implementationVersion = -1 ) [static]

Returns a list of identifiers of the available actions which are provided by the given vendor and of the given implementationVersion. If vendor is empty, actions from all vendors and of any implementation version are returned; if implementationVersion is empty, any actions from the given vendor (regardless of implementation version) are returned.

QContactFilter QContactAction::contactFilter () const [pure virtual]

Returns a filter which may be used to filter contacts by the availability of this action implementation for them.

bool QContactAction::invokeAction ( const QContact & contact, const QContactDetail & detail = QContactDetail(), const QVariantMap & parameters = QVariantMap() ) [pure virtual]

Initiates the implemented action on the specified detail of the given contact, or on the first eligible detail saved in the contact if the given detail is empty, with the given parameters specified. At some point after invocation, one or more resultsAvailable() signals will be emitted by the action instance. The results of the action (if any) may be retrieved by calling results(). When the state of the action changes, the stateChanged() signal will be emitted.

Returns true if the action was invoked successfully, otherwise false. The return value says nothing about whether the action which was invoked was successful or not, only whether it was initiated or the request for it to be initiated was sent successfully (e.g., if the action is implemented as a one-way RPC call).

See also results() and stateChanged().

bool QContactAction::isDetailSupported ( const QContactDetail & detail, const QContact & contact = QContact() ) const [pure virtual]

Returns true if the provided detail contains the fields required for this action to be performed on it; otherwise, returns false. Some actions may require other information to be available in order to complete successfully; in that case, the action will also inspect the given contact to ensure that it contains the information required. If the contact contains the required information, the function will return true; otherwise, returns false.

QVariantMap QContactAction::metaData () const [pure virtual]

Returns the meta-data associated with this action, such as icons, labels or sound cues

QVariantMap QContactAction::results () const [pure virtual]

Returns the result of the action, if any exists. Calling this function prior to receiving the resultsAvailable() signal will not return a meaningful result.

void QContactAction::resultsAvailable () [signal]

This signal is emitted by an action instance whose functionality has been initiated with invokeAction() when results of the action are available. Not all actions will have results, and these actions will not emit the resultsAvailable() signal.

If the action implementation is incapable of reporting results of the operation (for example, the action is implemented via a one-way IPC call) it should transition to the QContactAction::FinishedDetachedState state immediately upon invocation.

State QContactAction::state () const [pure virtual]

Returns the current state of the action.

See also stateChanged().

void QContactAction::stateChanged ( QContactAction::State newState ) [signal]

This signal is emitted when the state of an action changes to the given newState.

See also state().

QList<QContactDetail> QContactAction::supportedDetails ( const QContact & contact ) const [pure virtual]

Returns a list of the details saved in the given contact which contain the fields required for this action to be performed on them.

The default implementation of this function simply tests all the details in the contact using isDetailSupported()


Copyright © 2009-2010 Nokia Corporation and/or its subsidiary(-ies) Trademarks
Qt Mobility Project 1.1.0