QLandmarkManager Class Reference
The QLandmarkManager class provides an interface for storage and retrieval of landmarks from a landmark store. More...
#include <QLandmarkManager>
Public Types
Public Functions
| QLandmarkManager ( QObject * parent = 0 ) |
| QLandmarkManager ( const QString & managerName, const QMap<QString, QString> & parameters = 0, QObject * parent = 0 ) |
| QLandmarkManager ( const QString & managerName, int implementationVersion, const QMap<QString, QString> & parameters = 0, QObject * parent = 0 ) |
virtual | ~QLandmarkManager () |
QList<QLandmarkCategory> | categories ( const QList<QLandmarkCategoryId> & categoryIds ) const |
QList<QLandmarkCategory> | categories ( const QLandmarkNameSort & nameSort = QLandmarkNameSort() ) const |
QLandmarkCategory | category ( const QLandmarkCategoryId & categoryId ) const |
QList<QLandmarkCategoryId> | categoryIds ( const QLandmarkNameSort & nameSort = QLandmarkNameSort() ) const |
Error | error () const |
QString | errorString () const |
bool | exportLandmarks ( QIODevice * device, const QByteArray & format = QByteArray(), QList<QLandmarkId> landmarkIds = QList<QLandmarkId> () ) |
bool | exportLandmarks ( const QString & fileName, const QByteArray & format = QByteArray(), QList<QLandmarkId> landmarkIds = QList<QLandmarkId> () ) |
FilterSupportLevel | filterSupportLevel ( const QLandmarkFilter & filter ) const |
bool | importLandmarks ( QIODevice * device, const QByteArray & format = QByteArray() ) |
bool | importLandmarks ( const QString & fileName, const QByteArray & format = QByteArray() ) |
bool | isFeatureSupported ( LandmarkFeature feature ) const |
bool | isReadOnly () const |
bool | isReadOnly ( const QLandmarkId & landmarkId ) const |
bool | isReadOnly ( const QLandmarkCategoryId & categoryId ) const |
QLandmark | landmark ( const QLandmarkId & landmarkId ) const |
QList<QLandmarkId> | landmarkIds ( const QLandmarkFilter & filter, const QList<QLandmarkSortOrder> & sortOrders, const QLandmarkFetchHint & fetchHint = QLandmarkFetchHint() ) const |
QList<QLandmarkId> | landmarkIds ( const QLandmarkFilter & filter = QLandmarkFilter(), const QLandmarkSortOrder & sortOrder = QLandmarkSortOrder(), const QLandmarkFetchHint & fetchHint = QLandmarkFetchHint() ) const |
QList<QLandmark> | landmarks ( const QLandmarkFilter & filter, const QList<QLandmarkSortOrder> & sortOrders, const QLandmarkFetchHint & fetchHint = QLandmarkFetchHint() ) const |
QList<QLandmark> | landmarks ( const QLandmarkFilter & filter = QLandmarkFilter(), const QLandmarkSortOrder & sortOrder = QLandmarkSortOrder(), const QLandmarkFetchHint & fetchHint = QLandmarkFetchHint() ) const |
QList<QLandmark> | landmarks ( const QList<QLandmarkId> & landmarkIds ) const |
QString | managerName () const |
QMap<QString, QString> | managerParameters () const |
QString | managerUri () const |
int | managerVersion () const |
bool | removeCategory ( const QLandmarkCategoryId & categoryId ) |
bool | removeLandmark ( const QLandmarkId & landmarkId ) |
bool | removeLandmarks ( const QList<QLandmarkId> & landmarkIds, QMap<int, QLandmarkManager::Error> * errorMap = 0 ) |
bool | saveCategory ( QLandmarkCategory * category ) |
bool | saveLandmark ( QLandmark * landmark ) |
bool | saveLandmarks ( QList<QLandmark> * landmarks, QMap<int, QLandmarkManager::Error> * errorMap = 0 ) |
Signals
Static Public Members
QStringList | availableManagers () |
QString | buildUri ( const QString & managerName, const QMap<QString, QString> & params, int implementationVersion = -1 ) |
QLandmarkManager * | fromUri ( const QString & storeUri, QObject * parent = 0 ) |
bool | parseUri ( const QString & uri, QString * pManagerId, QMap<QString, QString> * pParams ) |
Detailed Description
The QLandmarkManager class provides an interface for storage and retrieval of landmarks from a landmark store.
The QLandmarkManager is the starting class to use when working with landmarks. If effectively represents a landmark datastore and it provides the synchronous operations for the creation, retrieval, updating and deletion of both landmarks and categories. For asynchronous operations use the request classes which use the manager as a parameter. The manager provides notifications whenever landmarks or categories are added, updated or removed. These are important for the cases where another process is making modifications to the same manager/datastore.
Each manager is identified by a manager name which typically takes the form of a reverse domain string such as com.nokia.qt.landmarks.engines.sqlite. However every supported platform provides a default manager which may be instantiated without having to provide a name like so:
QLandmarkManager *landmarkManager = new QLandmarkManager();
Retrieval operations
To retrieve a set of landmarks we provide may provide a QLandmarkFilter, QLandmarkSortOrder and QLandmarkFetchHint as necessary. The QLandmarkFilter defines the criteria for selecting landmarks e.g. a QLandmarkCategoryFilter may be used to choose landmarks that belong to a certain category or a QLandmarkProximityFilter to choose landmarks within a certain range from a given location. A QLandmarkSortOrder order defines how the results should be sorted and the QLandmarkFetchHint allows specification of the maximum number of items to return and an offset to facilitate paging. The following demonstrates how to search for the 5 nearest landmarks to a given coordinate.
QGeoCoordinate coordinate(54.0, 23.1);
QLandmarkProximityFilter filter;
filter.setCoordinate(coordinate);
filter.setRadius(5000);
QLandmarkDistanceSort distanceSort;
distanceSort.setCoordinate(coordinate);
distanceSort.setDirection(Qt::AscendingOrder);
QLandmarkFetchHint fetchHint;
fetchHint.setMaxItems(5);
landmarkManager->landmarks(filter, sortOrder, fetchHint);
The set of parameters described above are not always necessary as defaults are provided, if we wanted to retrieve all landmarks, then the appropriate call is:
landmarkManager->landmarks();
Note: Landmark retrieval is potentially a long operation, the synchronous API provided by the manager is subject to blocking. It is generally recommended that the QLandmarkFetchRequest be used because it behaves asynchronously.
Categories may be retrieved in a similar manner:
QList<QLandmarkCategory> categories = landmarkManager->categories();
Saving and deleting
Saving and deleting landmarks and categories are fairly straightforward. To add a new landmark or category simply instantiate a QLandmark or QLandmarkCategory, set its data fields(e.g name, coordiante etc) and pass a pointer to the appropriate save operation. For example:
QLandmark monks;
monks.setName("Monk's cafe");
landmarkManager->saveLandmark(&monks);
We pass the landmark by pointer bcause it will be assigned a new QLandmarkId when the function call is done. Saving a landmark with a valid id already set will update the existing landmark.
Removal of landmark may be done as follows:
landmarkManager->removeLandmark(landmark.landmarkId());
Importing and exporting
Import and exporting are potentially long operations, to perform these operations asynchronously see QLandmarkImportRequest and QLandmarkExportRequest. The simplest way to perform import and export operations is to specify a filename:
landmarkManager->importLandmarks("places.gpx");
landmarkManager->exportLandmarks("myplaces.gpx");
At the time of the QtMobility 1.1 tech preview, only importing of landmarks by supplying a file format is functional. For the supported platforms, the file format that may be supplied is "GpxV1.1" which means only Gpx version 1.1 files are known to work. Exporting is still under development and so are notifications.
Member Type Documentation
enum QLandmarkManager::Error
Defines the possible errors for the landmark manager.
|
Constant | Value | Description |
QLandmarkManager::NoError | 0 | No error occurred. |
QLandmarkManager::DoesNotExistError | 1 | The most recent operation failed because the requested landmark or category does not exist. |
QLandmarkManager::AlreadyExistsError | 2 | The most recent operation failed because the specified landmark or category already exists. |
QLandmarkManager::LockedError | 3 | The most recent operation failed because the datastore specified is currently locked. |
QLandmarkManager::PermissionsError | 4 | The most recent operation failed because the caller does not have permission to perform the operation. |
QLandmarkManager::OutOfMemoryError | 5 | The most recent operation failed due to running out of memory. |
QLandmarkManager::VersionMismatchError | 6 | The most recent operation failed because the backend of the manager is not of the required version. |
QLandmarkManager::NotSupportedError | 7 | The most recent operation failed because the requested operation is not supported in the specified store. |
QLandmarkManager::BadArgumentError | 8 | The most recent operation failed because one or more of the parameters to the operation were invalid. |
QLandmarkManager::InvalidManagerError | 9 | The most recent operation failed because the manager failed to initialize correctly and is invalid. This could be due using a manager name that is not recognised/available. A landmark request object will return this error if if is assigned a null manager pointer. |
QLandmarkManager::ParsingError | 10 | The most recent operation failed because the imported file could not be parsed. |
QLandmarkManager::CancelError | 11 | The most recent operation failed to complete due to user cancelation. |
QLandmarkManager::UnknownError | 12 | The most recent operation failed for an unknown reason. |
enum QLandmarkManager::FilterSupportLevel
Defines the possible support levels the manager can provide for a given filter.
|
Constant | Value | Description |
QLandmarkManager::Native | 0 | The manager natively supports the filter. |
QLandmarkManager::Emulated | 1 | The manager emulates the behaviour of the filter. An emulated filter will inherently be slower than a natively supported filter. |
QLandmarkManager::None | 2 | The manager does not support the filter at all. |
enum QLandmarkManager::LandmarkFeature
Defines the possible features the landmark manager can support.
|
Constant | Value | Description |
QLandmarkManager::GenericAttributes | 0 | The manager supports landmarks and categories which have generic attributes |
Member Function Documentation
QLandmarkManager::QLandmarkManager ( QObject * parent = 0 )
Constructs a QLandmarkManager. The default implementation for the platform will be used.
The parent QObject will be used as the parent of this QLandmarkManager.
QLandmarkManager::QLandmarkManager ( const QString & managerName, const QMap<QString, QString> & parameters = 0, QObject * parent = 0 )
Constructs a QLandmarkManager whose implementation is identified by managerName with the given parameters.
The parent QObject will be used as the parent of this QLandmarkManager.
If an empty managerName is specified, the default implementation for the platform will be used.
QLandmarkManager::QLandmarkManager ( const QString & managerName, int implementationVersion, const QMap<QString, QString> & parameters = 0, QObject * parent = 0 )
Constructs a QLandmarkManager whose backend has the name managerName and version implementationVersion, where the manager is constructed with the provided parameters.
The parent QObject will be used as the parent of this QLandmarkManager.
If an empty managerName is specified, the default implementation for the platform will be instantiated. If the specified implementation version is not available, the manager with the name managerName with the default implementation version is instantiated.
QLandmarkManager::~QLandmarkManager () [virtual]
Frees the memory used by the QLandmarkManager
QStringList QLandmarkManager::availableManagers () [static]
Returns a list of available manager names that can be used when constructing a QLandmarkManager
QString QLandmarkManager::buildUri ( const QString & managerName, const QMap<QString, QString> & params, int implementationVersion = -1 ) [static]
Returns a URI that completely describes a manager implementation, datastore, and the parameters with which to instantiate the manager, from the given managerName, params and an optional implementationVersion
QList<QLandmarkCategory> QLandmarkManager::categories ( const QList<QLandmarkCategoryId> & categoryIds ) const
Returns a list of categories identified by categoryIds.
If any of the category ids cannot be found, no categories are returned and an error is set.
QList<QLandmarkCategory> QLandmarkManager::categories ( const QLandmarkNameSort & nameSort = QLandmarkNameSort() ) const
Returns a list of all categories sorted according to the given nameSort.
void QLandmarkManager::categoriesAdded ( const QList<QLandmarkCategoryId> & categoryIds ) [signal]
This signal is emitted when categories (identified by categoryIds) have been added to the datastore managed by this manager.
See also categoriesChanged() and categoriesRemoved().
void QLandmarkManager::categoriesChanged ( const QList<QLandmarkCategoryId> & categoryIds ) [signal]
This signal is emitted when categories (identified by categoryIds) have been modified in the datastore managed by this manager.
See also categoriesAdded() and categoriesRemoved().
void QLandmarkManager::categoriesRemoved ( const QList<QLandmarkCategoryId> & categoryIds ) [signal]
This signal is emitted when categories (identified by categoryIds) have been removed from the datastore managed by this manager.
See also categoriesAdded() and categoriesChanged().
Returns the cateory in the database identified by categoryId.
QList<QLandmarkCategoryId> QLandmarkManager::categoryIds ( const QLandmarkNameSort & nameSort = QLandmarkNameSort() ) const
Returns a list of all category identifiers. The identifiers are returned in order as designed by nameSort.
Error QLandmarkManager::error () const
Returns the error code of the most recent operation. All functions will modify the error based on whether the operation successfully or not.
QString QLandmarkManager::errorString () const
Returns a short human-readable description of the error that occurred in the most recent operation.
bool QLandmarkManager::exportLandmarks ( QIODevice * device, const QByteArray & format = QByteArray(), QList<QLandmarkId> landmarkIds = QList<QLandmarkId> () )
Writes landmarks to the given device. The landmarks will be written according to the specified format. If landmarkIds is empty, then all landmarks will be exported, otherwise only those landmarks that match landmarkIds will be exported.
Returns true if all specified landmarks were successfully exported, otherwise returns false. It may be possible that only a subset of landmarks are exported.
bool QLandmarkManager::exportLandmarks ( const QString & fileName, const QByteArray & format = QByteArray(), QList<QLandmarkId> landmarkIds = QList<QLandmarkId> () )
Convenience function that will write landmarks to fileName in the expected format. Internally a QFile is opened with QIODevice::WriteOnly permissions. If landmarkIds is empty, then all landmarks will be exported, otherwise only those landmarks that match landmarkIds will be exported.
Returns true if all specified landmarks were successfully exported, otherwise returns false. It may be possible that only a subset of landmarks are exported.
Returns the support level the manager provides for the given filter.
QLandmarkManager * QLandmarkManager::fromUri ( const QString & storeUri, QObject * parent = 0 ) [static]
Constructs a QLandmarkManager whose implementation, store and parameters are specified in the given storeUri, and whose parent object is parent.
bool QLandmarkManager::importLandmarks ( QIODevice * device, const QByteArray & format = QByteArray() )
Reads landmarks from the given device and saves them. The data from the device is expected to adhere to the provided format. If no format is provided, the manager tries to auto detect the format.
Returns true if all landmarks could be imported, otherwise returns false. It may be possible that only a subset of landmarks are imported.
The current default managers for the maemo and desktop platforms support GPX version 1.1, and the format to use is GpxV1.1.
bool QLandmarkManager::importLandmarks ( const QString & fileName, const QByteArray & format = QByteArray() )
Convenience function that will read landmarks from fileName in the expected format. If no format is provided, the manager tries to auto detect the format. Internally a QFile is opened with QIODevice::ReadOnly permissions.
Returns true if all landmarks could be imported, otherwise returns false. It may be possible that only a subset of landmarks are imported.
The current default managers for the maemo and desktop platforms support GPX version 1.1, and the format to use is GpxV1.1.
bool QLandmarkManager::isFeatureSupported ( LandmarkFeature feature ) const
Returns whether the manager supports the given feature.
bool QLandmarkManager::isReadOnly () const
Returns true if the manager is entirely read-only. Meaning landmarks and categories cannot be added, modified or removed.
bool QLandmarkManager::isReadOnly ( const QLandmarkId & landmarkId ) const
Returns true if the landmark identified by landmarkId considered read-only by the manager.
If the landmarkId does not refer to an existing landmark, it is considered writable unless the manager is exclusively read-only.
bool QLandmarkManager::isReadOnly ( const QLandmarkCategoryId & categoryId ) const
Returns true if the category identified by categoryId is considered read-only by the manager.
If categoryId does not refer to an existing category, it is considered writable unless the manager is exclusively read-only.
QLandmark QLandmarkManager::landmark ( const QLandmarkId & landmarkId ) const
Returns the landmark in the database identified by landmarkId
QList<QLandmarkId> QLandmarkManager::landmarkIds ( const QLandmarkFilter & filter, const QList<QLandmarkSortOrder> & sortOrders, const QLandmarkFetchHint & fetchHint = QLandmarkFetchHint() ) const
Returns a list of landmark identifiers of landmarks that match the given filter, sorted according to the given sortOrders. Various fetch operation parameters may be specified by fetchHint.
QList<QLandmarkId> QLandmarkManager::landmarkIds ( const QLandmarkFilter & filter = QLandmarkFilter(), const QLandmarkSortOrder & sortOrder = QLandmarkSortOrder(), const QLandmarkFetchHint & fetchHint = QLandmarkFetchHint() ) const
Convenience function for returning a list of landmark identifiers of landmarks that match the given filter, sorted according to the given sortOrder. Various fetch operation parameters may be specified by fetchHint.
This is a convenience function.
QList<QLandmark> QLandmarkManager::landmarks ( const QLandmarkFilter & filter, const QList<QLandmarkSortOrder> & sortOrders, const QLandmarkFetchHint & fetchHint = QLandmarkFetchHint() ) const
Returns a list of landmarks which match the given filter and are sorted according to the sortOrders. Various fetch operation parameters may be specified by fetchHint.
QList<QLandmark> QLandmarkManager::landmarks ( const QLandmarkFilter & filter = QLandmarkFilter(), const QLandmarkSortOrder & sortOrder = QLandmarkSortOrder(), const QLandmarkFetchHint & fetchHint = QLandmarkFetchHint() ) const
Returns a list of landmarks which match the given filter and are sorted according to the given sortOrder. Various fetch operation parameters may be specified by fetchHint.
QList<QLandmark> QLandmarkManager::landmarks ( const QList<QLandmarkId> & landmarkIds ) const
Returns a list of landmarks which match the given landmarkIds.
void QLandmarkManager::landmarksAdded ( const QList<QLandmarkId> & landmarkIds ) [signal]
This signal is emitted when landmarks (identified by landmarkIds) have been added to the datastore managed by this manager.
See also landmarksChanged() and landmarksRemoved().
void QLandmarkManager::landmarksChanged ( const QList<QLandmarkId> & landmarkIds ) [signal]
This signal is emitted when landmarks (identified by landmarkIds) have been modified in the datastore managed by this manager.
See also landmarksAdded() and landmarksRemoved().
void QLandmarkManager::landmarksRemoved ( const QList<QLandmarkId> & landmarkIds ) [signal]
This signal is emitted when landmarks (identified by landmarkIds) have been removed from the datastore managed by this manager.
See also landmarksAdded() and landmarksChanged().
QString QLandmarkManager::managerName () const
Returns the manager name for this QLandmarkManager.
The manager name usually takes the format of a reverse domain string. An example of a manager name is com.nokia.qt.landmarks.engines.sqlite
QMap<QString, QString> QLandmarkManager::managerParameters () const
Return the parameters relevant to the creation of this QLandmarkManager.
The parameters may be viewed as a set of key-value pairs. Each manager may have a different set of parameters depending upon its backend implementation.
QString QLandmarkManager::managerUri () const
Return the uri describing this QLandmarkManager, consisting of the manager name and any parameters.
int QLandmarkManager::managerVersion () const
Returns the engine backend implementation version number.
bool QLandmarkManager::parseUri ( const QString & uri, QString * pManagerId, QMap<QString, QString> * pParams ) [static]
Splits the given uri into the manager, store, and parameters that it describes, and places the information into the memory addressed by pManagerId and pParams respectively. Returns true if uri could be split successfully, otherwise returns false
bool QLandmarkManager::removeCategory ( const QLandmarkCategoryId & categoryId )
Remove the category identified by categoryId from the database. The categoryId is cleared(and becomes invalid) on successful removal. An unsuccessful removal will leave the identifer alone.
Returns true if the category was removed successfully, otherwise returnse false.
bool QLandmarkManager::removeLandmark ( const QLandmarkId & landmarkId )
Remove the landmark identified by landmarkId from the database.
Returns true if the landmark was removed successfully, otherwise returnse false.
bool QLandmarkManager::removeLandmarks ( const QList<QLandmarkId> & landmarkIds, QMap<int, QLandmarkManager::Error> * errorMap = 0 )
Removes every landmark whose identifier is contained in the list of landmarkIds. Returns true if all landmarks were removed successfully, otherwise false.
The manager might populate errorMap (the map of indices of the landmarkIds list to the error which occurred when saving the landmark at that index) for every index for which the landmark could not be removed. The QLandmarkManager::error() function will only return QLandmarkManager::NoError if all landmarks were removed successfully.
See also QLandmarkManager::removeLandmark().
bool QLandmarkManager::saveCategory ( QLandmarkCategory * category )
Adds the given category to the database if category has a default-constructed identifier, or an identifier with the manager URI set to the URI of this manager and an empty id.
If the manager URI of the identifier of the category is neither empty nor equal to the URI of this manager, or the id member of the identifier is not empty, but does not exist in the manager, the operation will fail and calling error() will return QLandmarkManager::DoesNotExistError.
Alternatively, the function will update the existing category in the database if category has a non-empty id and currently exists within the database.
Returns false on failure or true on success. On successful save of a category with an invalid id, it will be assigned a valid id and have its manager URI set to the URI of this manager.
bool QLandmarkManager::saveLandmark ( QLandmark * landmark )
Adds the given landmark to the database if landmark has a default-constructed identifer, or an identifier with the manager URI set to the URI of this manager and an empty id.
If the manager URI of the identifier of the landmark is neither empty nor equal to the URI of this manager, or the id member of the identifier is not empty, but does not exist in the manager, the operation will fail and calling error() will return QLandmarkManager::DoesNotExistError.
Alternatively, the function will update the existing landmark in the database if landmark has a non-empty id and currently exists within the database.
Returns false on failure or true on success. On successful save of a landmark with an empty id, it will be assigned a valid id and have its manager URI set to the URI of this manager.
bool QLandmarkManager::saveLandmarks ( QList<QLandmark> * landmarks, QMap<int, QLandmarkManager::Error> * errorMap = 0 )
Adds the list of landmarks to the database. Returns true if the landmarks were saved successfully, otherwise returns false.
The manager might populate errorMap (the map of indices of the landmarks list to the error which occurred when saving the landmark at that index) for every index for which the landmark could not be saved.
The QLandmarkManager::error() function will only return QLandmarkManager::NoError if all landmarks were saved successfully.
For each new landmark that was successfully saved, a landmark identifier is assigned to that landmark.