|
|
              
QLandmarkAbstractRequest Class ReferenceThe QLandmarkAbstractRequest class provides the interface from which all asynchronous request classes inherit. More... #include <QLandmarkAbstractRequest> Inherits QObject. Inherited by QLandmarkCategoryFetchByIdRequest, QLandmarkCategoryFetchRequest, QLandmarkCategoryIdFetchRequest, QLandmarkCategoryRemoveRequest, QLandmarkCategorySaveRequest, QLandmarkExportRequest, QLandmarkFetchByIdRequest, QLandmarkFetchRequest, QLandmarkIdFetchRequest, QLandmarkImportRequest, QLandmarkRemoveRequest, and QLandmarkSaveRequest. Public Types
Public Functions
Public Slots
Signals
Additional Inherited Members
Detailed DescriptionThe QLandmarkAbstractRequest class provides the interface from which all asynchronous request classes inherit. It allows a client to asynchronously request some functionality of a particular QLandmarkManager. 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, 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 the InactiveState to ActiveState. After any state transition, the request will emit the stateChanged() signal. The manager may (if it supports it) 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 may not connect the the request's signals to any slots. (Please see the note below if you are working on Symbian with QtMobility 1.1.0) 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 notifications about whether the request succeeded or not, nor the results of the request. Because clients retain ownership of any request object, and may delete a request object at any time, the manager engine, implementers must be careful to ensue that they do not assume that a request has not been deleted at some time point during processing of a request, particularly if the engine has a multithreaded implementation. Member Type Documentation
|
| Constant | Value | Description |
|---|---|---|
| QLandmarkAbstractRequest::InvalidRequest | 0 | An invalid request |
| QLandmarkAbstractRequest::LandmarkIdFetchRequest | 1 | A request to fetch a list of landmark identifiers. |
| QLandmarkAbstractRequest::CategoryIdFetchRequest | 2 | A request to fetch a list of catgory identifiers. |
| QLandmarkAbstractRequest::LandmarkFetchRequest | 3 | A request to fetch a list of landmarks |
| QLandmarkAbstractRequest::LandmarkFetchByIdRequest | 4 | A request to fetch a list of landmarks by id. |
| QLandmarkAbstractRequest::CategoryFetchRequest | 5 | A request to fetch a list of categories |
| QLandmarkAbstractRequest::CategoryFetchByIdRequest | 6 | A request to fetch a list of categories by id |
| QLandmarkAbstractRequest::LandmarkSaveRequest | 7 | A request to save a list of landmarks. |
| QLandmarkAbstractRequest::LandmarkRemoveRequest | 8 | A request to remove a list of landmarks. |
| QLandmarkAbstractRequest::CategorySaveRequest | 9 | A request to save a list of categories. |
| QLandmarkAbstractRequest::CategoryRemoveRequest | 10 | A request to remove a list of categories. |
| QLandmarkAbstractRequest::ImportRequest | 11 | A request import landmarks. |
| QLandmarkAbstractRequest::ExportRequest | 12 | A request export landmarks. |
enum QLandmarkAbstractRequest::State
Defines the possible states of asynchronous requests.
| Constant | Value | Description |
|---|---|---|
| QLandmarkAbstractRequest::InactiveState | 0 | Operation not yet started. |
| QLandmarkAbstractRequest::ActiveState | 1 | Operation started, not yet finished. |
| QLandmarkAbstractRequest::FinishedState | 2 | Operation 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 effectiely a handle to a request operation, the operation may continue or it may just be canceled, depending upon the enine implementation, even though the request itself has been destroyed. The sqlite engine continues the operation behind the scenes if the request is destroyed whilst active. For the symbian engine see the note below.
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().
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.
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 safely and will return false immediately.
(Note: This function is not supported for an import request with the symbian manager which always returns false. As of Qt Mobility 1.1.1 waitForFinished() is supported using the sqlite manager).
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.