Qt Mobility Reference Documentation

QLandmarkManager Class Reference

The QLandmarkManager class provides an interface for storage and retrieval of landmarks from a landmark store. More...

 #include <QLandmarkManager>

Public Types

enum Error { NoError, DoesNotExistError, AlreadyExistsError, LockedError, ..., UnknownError }
enum FilterSupportLevel { Native, Emulated, None }
enum LandmarkFeature { GenericAttributes }

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

void categoriesAdded ( const QList<QLandmarkCategoryId> & categoryIds )
void categoriesChanged ( const QList<QLandmarkCategoryId> & categoryIds )
void categoriesRemoved ( const QList<QLandmarkCategoryId> & categoryIds )
void landmarksAdded ( const QList<QLandmarkId> & landmarkIds )
void landmarksChanged ( const QList<QLandmarkId> & landmarkIds )
void landmarksRemoved ( const QList<QLandmarkId> & landmarkIds )

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.

ConstantValueDescription
QLandmarkManager::NoError0No error occurred.
QLandmarkManager::DoesNotExistError1The most recent operation failed because the requested landmark or category does not exist.
QLandmarkManager::AlreadyExistsError2The most recent operation failed because the specified landmark or category already exists.
QLandmarkManager::LockedError3The most recent operation failed because the datastore specified is currently locked.
QLandmarkManager::PermissionsError4The most recent operation failed because the caller does not have permission to perform the operation.
QLandmarkManager::OutOfMemoryError5The most recent operation failed due to running out of memory.
QLandmarkManager::VersionMismatchError6The most recent operation failed because the backend of the manager is not of the required version.
QLandmarkManager::NotSupportedError7The most recent operation failed because the requested operation is not supported in the specified store.
QLandmarkManager::BadArgumentError8The most recent operation failed because one or more of the parameters to the operation were invalid.
QLandmarkManager::InvalidManagerError9The 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::ParsingError10The most recent operation failed because the imported file could not be parsed.
QLandmarkManager::CancelError11The most recent operation failed to complete due to user cancelation.
QLandmarkManager::UnknownError12The most recent operation failed for an unknown reason.

enum QLandmarkManager::FilterSupportLevel

Defines the possible support levels the manager can provide for a given filter.

ConstantValueDescription
QLandmarkManager::Native0The manager natively supports the filter.
QLandmarkManager::Emulated1The manager emulates the behaviour of the filter. An emulated filter will inherently be slower than a natively supported filter.
QLandmarkManager::None2The manager does not support the filter at all.

enum QLandmarkManager::LandmarkFeature

Defines the possible features the landmark manager can support.

ConstantValueDescription
QLandmarkManager::GenericAttributes0The 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().

QLandmarkCategory QLandmarkManager::category ( const QLandmarkCategoryId & categoryId ) const

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.

FilterSupportLevel QLandmarkManager::filterSupportLevel ( const QLandmarkFilter & filter ) const

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.


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