Qt Mobility Reference Documentation

QLandmarkAbstractRequest Class Reference

The QLandmarkAbstractRequest class provides the interface from which all asynchronous request classes inherit. More...

 #include <QLandmarkAbstractRequest>

Inherited by QLandmarkCategoryFetchByIdRequest, QLandmarkCategoryFetchRequest, QLandmarkCategoryIdFetchRequest, QLandmarkCategoryRemoveRequest, QLandmarkCategorySaveRequest, QLandmarkExportRequest, QLandmarkFetchByIdRequest, QLandmarkFetchRequest, QLandmarkIdFetchRequest, QLandmarkImportRequest, QLandmarkRemoveRequest, and QLandmarkSaveRequest.


Public Types

enum RequestType { InvalidRequest, LandmarkIdFetchRequest, CategoryIdFetchRequest, LandmarkFetchRequest, ..., ExportRequest }
enum State { InactiveState, ActiveState, FinishedState }

Public Functions

QLandmarkAbstractRequest ( QLandmarkManager * manager, QObject * parent = 0 )
virtual ~QLandmarkAbstractRequest ()
QLandmarkManager::Error error () const
QString errorString () const
bool isActive () const
bool isFinished () const
bool isInactive () const
QLandmarkManager * manager () const
void setManager ( QLandmarkManager * manager )
State state ()
RequestType type () const

Public Slots

bool cancel ()
bool start ()
bool waitForFinished ( int msecs = 0 )

Signals

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

Detailed Description

The QLandmarkAbstractRequest class provides the interface from which all asynchronous request classes inherit.

It allows a client to asynchronously request some functionality of a particular QContactManager. Instances of the class will emit signals when the state of the request changes, or when more results become available.

Clients should not attempt to create instances of this class directly, but should instead use the use-case-specific classes derived from this class.

All such request classes have a similar interface: clients set the parameters of the asynchronous call, including which manager the request will be made of, and then call the start() slot of the request. The manager will then enqueue or begin to process the request, at which point the request's state will transition from InactiveState to ActiveState. After any state transition, the request will emit the stateChanged() signal. The manager may periodically update the request with results, at which point the request will emit the resultsAvailable() signal. These results are not guaranteed to have a stable ordering. Error information is considered a result, so some requests will emit the resultsAvailable() signal even if no results are possible from the request (for example, a landmark remove request) when the manager updates the request with information about any errors which may have occurred.

Clients can choose which signals they wish to handle from a request. If the client is not interested in interim results, they can choose to handle only the stateChanged() signal, and in the slot to which that signal is connected, check whether the state has changed to the FinishedState (which signifies that the manager has finished handling the request, and that the request will not be updated with any more results). If the client is not interested in any results (including error information), they may choose to delete the request after calling start(), or simply not connect the request's signals to any slots.

If the request is allocated via operator new, the client must delete the request when they are no longer using it in order to avoid leaking memory. That is, the client retains ownership of the request.

The client may delete a heap-allocated request in various ways: by deleting it directly (but not within a slot connected to a signal emitted by the request), or by using the deleteLater() slot to schedule the request for deletion when control returns to the event loop (from within a slot connected to a signal emitted by the request, for example stateChanged()).

An active request may be deleted by the client, but the client will not receive any notifications about whether the request succeeded or not, nor any results of the request.

Because clients retain ownership of any request object, and may delete a request object at any time, manager engine implementors must be careful to ensure that they do not assume that a request has not been deleted at some point during processing of a request, particularly if the engine has a multithreaded implementation.


Member Type Documentation

enum QLandmarkAbstractRequest::RequestType

Defines the possible types of asynchronous requests.

ConstantValueDescription
QLandmarkAbstractRequest::InvalidRequest0An invalid request
QLandmarkAbstractRequest::LandmarkIdFetchRequest1A request to fetch a list of landmark identifiers.
QLandmarkAbstractRequest::CategoryIdFetchRequest2A request to fetch a list of catgory identifiers.
QLandmarkAbstractRequest::LandmarkFetchRequest3A request to fetch a list of landmarks
QLandmarkAbstractRequest::LandmarkFetchByIdRequest4A request to fetch a list of landmarks by id.
QLandmarkAbstractRequest::CategoryFetchRequest5A request to fetch a list of categories
QLandmarkAbstractRequest::CategoryFetchByIdRequest6A request to fetch a list of categories by id
QLandmarkAbstractRequest::LandmarkSaveRequest7A request to save a list of landmarks.
QLandmarkAbstractRequest::LandmarkRemoveRequest8A request to remove a list of landmarks.
QLandmarkAbstractRequest::CategorySaveRequest9A request to save a list of categories.
QLandmarkAbstractRequest::CategoryRemoveRequest10A request to remove a list of categories.
QLandmarkAbstractRequest::ImportRequest11A request import landmarks.
QLandmarkAbstractRequest::ExportRequest12A request export landmarks.

enum QLandmarkAbstractRequest::State

Defines the possible states of asynchronous requests.

ConstantValueDescription
QLandmarkAbstractRequest::InactiveState0Operation not yet started.
QLandmarkAbstractRequest::ActiveState1Operation started, not yet finished.
QLandmarkAbstractRequest::FinishedState2Operation completed. (Can be mean either successful or unsuccessful completion).

Member Function Documentation

QLandmarkAbstractRequest::QLandmarkAbstractRequest ( QLandmarkManager * manager, QObject * parent = 0 )

Constructs a new, invalid asynchronous request with the given manager and parent.

QLandmarkAbstractRequest::~QLandmarkAbstractRequest () [virtual]

Destroys the asynchronous request. Because the request object is effectively a handle to a request operation, the operation may continue or it may be canceled, depending upon the engine implementation, even though the request object itself has been destroyed.

bool QLandmarkAbstractRequest::cancel () [slot]

Notifies the request that it should be canceled.

Returns true if the request was successfully notified that it should be canceled. The request may or may not honor the cancel notification. Returns false if the notification could not be made or the request is not in the QLandmarkManager::Active state.

See also start() and ..

QLandmarkManager::Error QLandmarkAbstractRequest::error () const

Returns the overall error of the most recent asynchronous operation.

See also errorString().

QString QLandmarkAbstractRequest::errorString () const

Returns a human readable string of the last error that occurred. This error string is intended to be used by developers only and should not be seen by end users.

See also error().

bool QLandmarkAbstractRequest::isActive () const

Returns true if the request is in the QLandmarkAbstractRequest::Active state; otherwise, returns false.

See also state().

bool QLandmarkAbstractRequest::isFinished () const

Returns true if the request is in the QLandmarkAbstractRequest::Finished state; otherwise, returns false.

See also state().

bool QLandmarkAbstractRequest::isInactive () const

Returns true if the request is in the QLandmarkAbstractRequest::Inactive state; otherwise, returns false.

See also state().

QLandmarkManager * QLandmarkAbstractRequest::manager () const

Returns a pointer to the landmark manager which this request operates on.

See also setManager().

void QLandmarkAbstractRequest::resultsAvailable () [signal]

This signal is emitted when new results are available. Results can include the operation error which may be accessed via error(), or derived-class specific results which are accessible through the derived class API.

See also error().

void QLandmarkAbstractRequest::setManager ( QLandmarkManager * manager )

Sets the manager which this request operates on.

Note that if a NULL manager is set, the functions start(), cancel() and waitForFinished() will return false and error will be set to QLandmarkManager::InvalidManagerError.

A manager cannot be assigned while the request is in the QLandmarkAbstractRequest::ActiveState.

See also manager().

bool QLandmarkAbstractRequest::start () [slot]

Attempts to start the request.

Returns true if the request was started, otherwise false. Trying to start a request that is already active returns false.

See also cancel() and ..

State QLandmarkAbstractRequest::state ()

Returns the state of the request

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

This signal is emitted when the state of the request is changed. The new state of the request will be contained in newState.

RequestType QLandmarkAbstractRequest::type () const

Returns the type of this asynchronous request.

bool QLandmarkAbstractRequest::waitForFinished ( int msecs = 0 ) [slot]

Blocks until the request has been completed or until msecs milliseconds has elapsed. If msecs is zero or negative, this function will block indefinitely.

Returns true if the request was canceled or completed within the given period, otherwise returns false. Some backends may be unable to support this operation saafely and will return false immediately.

Note that any signals generated while waiting for the request to be complete may be queued and delivered sometime after this function has returned, when the calling thread's event loop is dispatched. If your code depends on your slots being invoked, you may need to process events after calling this function.

X

Thank you for giving your feedback.

Make sure it is related to this specific page. For more general bugs and requests, please use the Qt Bug Tracker.