QLandmarkManager Class Reference

 #include <QLandmarkManager>

 QLandmarkManager *landmarkManager = new QLandmarkManager();

 QLandmarkCategoryFilter filter;
 filter.setCategoryId(category.categoryId());

 QLandmarkNameSort nameSort;
 nameSort.setDirection(Qt::AscendingOrder);

 landmarkManager->landmarks(filter, 100, 0, nameSort);

 landmarkManager->landmarks();

 QList<QLandmarkCategory> categories = landmarkManager->categories();

 QLandmark monks;
 monks.setName("Monk's cafe");
 //..
 landmarkManager->saveLandmark(&monks);

 landmarkManager->removeLandmark(landmark);

 landmarkManager->importLandmarks("places.gpx");

 landmarkManager->exportLandmarks("myplaces.gpx",QLandmarkManager::Gpx);

Member Function Documentation

QLandmarkManager::QLandmarkManager ( QObject * parent = 0 )

Constructs a QLandmarkManager. The default manager 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 manager implementation for the platform will be used.

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

This function was introduced in Qt Mobility 1.1.

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

This function was introduced in Qt Mobility 1.1.

QList<QLandmarkCategory> QLandmarkManager::categories ( const QList<QLandmarkCategoryId> & categoryIds ) const

Returns a list of categories which match the given categoryIds.

This batch function will set per-input errors in the QLandmarkManager::errorMap();

The QLandmarkManager::error() function will only return QLandmarkManager::NoError if all categories were successfully retrieved.

This function was introduced in Qt Mobility 1.1.

QList<QLandmarkCategory> QLandmarkManager::categories ( int limit = -1, int offset = 0, const QLandmarkNameSort & nameSort = QLandmarkNameSort() ) const

Returns a list of categories.The limit defines the maximum number of categories to return and the offset defines the index offset of the first category. A limit of -1 means all categories should be returned(a limit of 0 means zero categories are returned). The categories are returned in the order as designated by nameSort.

This function was introduced in Qt Mobility 1.1.

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. This signal is not emitted if the dataChanged() signal was previously emitted for these changes.

This function was introduced in Qt Mobility 1.1.

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. This signal is not emitted if the dataChanged() signal was previously emitted for these changes.

This function was introduced in Qt Mobility 1.1.

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. This signal is not emitted if the dataChanged() signal was previously emitted for these changes.

This function was introduced in Qt Mobility 1.1.

See also categoriesAdded() and categoriesChanged().

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

Returns the cateory in the database identified by categoryId.

This function was introduced in Qt Mobility 1.1.

QList<QLandmarkCategoryId> QLandmarkManager::categoryIds ( int limit = -1, int offset = 0, const QLandmarkNameSort & nameSort = QLandmarkNameSort() ) const

Returns a list of category identifiers. The limit defines the maximum number of ids to return and the offset defines the index offset of the first id. A limit of -1 means ids for all categories should be returned. The identifiers are returned in order as designed by nameSort. Note that a limit of 0 will return zero category ids.

This function was introduced in Qt Mobility 1.1.

void QLandmarkManager::dataChanged () [signal]

This signal is emitted by the manager if its internal state changes and it is unable to precisely determine the changes which occurred, or if the manager considers the changes to be radical enough to require clients to reload all data. If the signal is emitted, no other signals will be emitted for the associated changes.

This function was introduced in Qt Mobility 1.1.

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.

This function was introduced in Qt Mobility 1.1.

QMap<int, QLandmarkManager::Error> QLandmarkManager::errorMap () const

Returns per-input error codes for the most recent operation. This function only returns meaningful information if the most recent operation was a batch operation. The keys in the map correspond to the index of the input list. The error map is only populated for indexes at which an error occurred. Eg If we saved 5 landmarks and an error occurred at index 3, the error map will have only a single key for index 3.

This function was introduced in Qt Mobility 1.1.

See also error(), categories(), landmarks(), saveLandmarks(), removeCategory(), and removeLandmarks().

QString QLandmarkManager::errorString () const

Returns a short human-readable description of the error that occurred in the most recent operation. The error string is intended to be used by developers and is not suitable for showing to end users.

This function was introduced in Qt Mobility 1.1.

bool QLandmarkManager::exportLandmarks ( QIODevice * device, const QString & format, const QList<QLandmarkId> & landmarkIds = QList<QLandmarkId> (), QLandmarkManager::TransferOption option = IncludeCategoryData ) const

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.

The option can be used to control whether categories will be exported or not. Note that the AttachSingleCategory option has no meaning during export and the manager will export as if option was IncludeCategoryData. Also, be aware that some file formats may not support categories at all and for these formats, the option is always treated as if it was ExcludeCategoryData.

Returns true if all specified landmarks were successfully exported, otherwise returns false. It may be possible that only a subset of landmarks are exported.

This function was introduced in Qt Mobility 1.1.

bool QLandmarkManager::exportLandmarks ( const QString & fileName, const QString & format, const QList<QLandmarkId> & landmarkIds = QList<QLandmarkId> (), QLandmarkManager::TransferOption option = IncludeCategoryData ) const

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.

The option can be used to control whether categories will be exported or not. Note that the AttachSingleCategory option has no meaning during export and the manager will export as if option was IncludeCategoryData. Also, be aware that some file formats may not support categories at all and for these formats, the option is always treated as if it was ExcludeCategoryData.

Returns true if all specified landmarks were successfully exported, otherwise returns false. It may be possible that only a subset of landmarks are exported.

This function was introduced in Qt Mobility 1.1.

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

Returns the support level the manager provides for the given filter. For the case of intersection and union filters, whether the elements will be individually processed is dependent on the particular manager implementation.

This function was introduced in Qt Mobility 1.1.

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.

This function was introduced in Qt Mobility 1.1.

bool QLandmarkManager::importLandmarks ( QIODevice * device, const QString & format = QString(), QLandmarkManager::TransferOption option = IncludeCategoryData, const QLandmarkCategoryId & categoryId = QLandmarkCategoryId() )

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.

The option can be used to control whether categories in the imported file will be added during the import. If the AttachSingleCategory option is used, then all the landmarks in the import file are assigned to the category identified by categoryId, in all other circumstances categoryId is ignored. If categoryId doesn't exist when using AttachSingleCategory, QLandmarkManager::CategoryDoesNotExistError is set. Note that some file formats may not support categories at all.

Returns true if all landmarks could be imported, otherwise returns false.

This function was introduced in Qt Mobility 1.1.

bool QLandmarkManager::importLandmarks ( const QString & fileName, const QString & format = QString(), QLandmarkManager::TransferOption option = IncludeCategoryData, const QLandmarkCategoryId & categoryId = QLandmarkCategoryId() )

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.

The option can be used to control whether categories in the imported file will be added during the import. If the AttachSingleCategory option is used, then all the landmarks in the import file are assigned to the category identified by categoryId, in all other circumstances categoryId is ignored. If categoryId doesn't exist when using AttachSingleCategory, QLandmarkManager::CategoryDoesNotExistError is set. Note that some file formats may not support categories at all.

Returns true if all landmarks could be imported, otherwise returns false.

This function was introduced in Qt Mobility 1.1.

bool QLandmarkManager::isFeatureSupported ( ManagerFeature feature ) const

Returns whether the manager supports the given feature.

This function was introduced in Qt Mobility 1.1.

bool QLandmarkManager::isReadOnly () const

Returns true if the manager is entirely read-only. Meaning landmarks and categories cannot be added, modified or removed.

This function was introduced in Qt Mobility 1.1.

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.

This function was introduced in Qt Mobility 1.1.

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.

This function was introduced in Qt Mobility 1.1.

QLandmark QLandmarkManager::landmark ( const QLandmarkId & landmarkId ) const

Returns the landmark in the database identified by landmarkId

This function was introduced in Qt Mobility 1.1.

QList<QLandmarkId> QLandmarkManager::landmarkIds ( const QLandmarkFilter & filter, int limit, int offset, const QList<QLandmarkSortOrder> & sortOrders ) const

Returns a list of landmark identifiers which match the given filter and are sorted according to the given sortOrders. The limit defines the maximum number of landmark ids to return and the offset defines the index offset of the first landmark id. A limit of -1 means that ids of all matching landmarks should be returned. Note that a limit of 0 will return zero landmark ids.

This function was introduced in Qt Mobility 1.1.

QList<QLandmarkId> QLandmarkManager::landmarkIds ( const QLandmarkFilter & filter = QLandmarkFilter(), int limit = -1, int offset = 0, const QLandmarkSortOrder & sortOrder = QLandmarkSortOrder() ) const

Convenience function to returns a list of landmark identifiers which match the given filter and are sorted according to the given sortOrder. The limit defines the maximum number of landmark ids to return and the offset defines the index offset of the first landmark id. A limit of -1 means that ids of all matching landmarks should be returned. Note that a limit of 0 will return zero landmark ids.

This function was introduced in Qt Mobility 1.1.

QList<QLandmark> QLandmarkManager::landmarks ( const QLandmarkFilter & filter, int limit, int offset, const QList<QLandmarkSortOrder> & sortOrders ) const

Returns a list of landmarks which match the given filter and are sorted according to the sortOrders. The limit defines the maximum number of landmarks to return and the offset defines the index offset of the first landmark. A limit of -1 means all matching landmarks should be returned.

This function was introduced in Qt Mobility 1.1.

QList<QLandmark> QLandmarkManager::landmarks ( const QLandmarkFilter & filter = QLandmarkFilter(), int limit = -1, int offset = 0, const QLandmarkSortOrder & sortOrder = QLandmarkSortOrder() ) const

Returns a list of landmarks which match the given filter and are sorted according to the sortOrder. The limit defines the maximum number of landmarks to return and the offset defines the index offset of the first landmark. A limit of -1 means all matching landmarks should be returned and that a limit of 0 will return zero landmarks.

This function was introduced in Qt Mobility 1.1.

QList<QLandmark> QLandmarkManager::landmarks ( const QList<QLandmarkId> & landmarkIds ) const

Returns a list of landmarks which match the given landmarkIds.

This batch function will set per-input errors in the QLandmarkManager::errorMap().

The QLandmarkManager::error() function will only return QLandmarkManager::NoError if all landmarks were successfully retrieved.

This function was introduced in Qt Mobility 1.1.

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. This signal is not emitted if the dataChanged() signal was previously emitted for these changes.

This function was introduced in Qt Mobility 1.1.

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. This signal is not emitted if the dataChanged() signal was previously emitted for these changes. Note that removal of a category will not trigger a landmarksChanged signal for landmarks belonging to that category.

This function was introduced in Qt Mobility 1.1.

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. This signal is not emitted if the dataChanged() signal was previously emitted for these changes.

This function was introduced in Qt Mobility 1.1.

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

This function was introduced in Qt Mobility 1.1.

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.

This function was introduced in Qt Mobility 1.1.

QString QLandmarkManager::managerUri () const

Return the uri describing this QLandmarkManager, consisting of the manager name and any parameters.

This function was introduced in Qt Mobility 1.1.

int QLandmarkManager::managerVersion () const

Returns the engine backend implementation version number.

This function was introduced in Qt Mobility 1.1.

bool QLandmarkManager::parseUri ( const QString & uri, QString * pManagerName, QMap<QString, QString> * pParams ) [static]

Splits the given uri into the manager name and parameters that it describes, and places the information into the memory addressed by pManagerName and pParams respectively. Returns true if uri could be split successfully, otherwise returns false

This function was introduced in Qt Mobility 1.1.

bool QLandmarkManager::removeCategory ( const QLandmarkCategoryId & categoryId )

Remove the category identified by categoryId from the database.

Returns true if the category was removed successfully, otherwise returns false.

This function was introduced in Qt Mobility 1.1.

bool QLandmarkManager::removeCategory ( const QLandmarkCategory & category )

Remove the given category from the database

Returns true if the category was removed successfully, otherwise returns false.

This function was introduced in Qt Mobility 1.1.

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.

This function was introduced in Qt Mobility 1.1.

bool QLandmarkManager::removeLandmark ( const QLandmark & landmark )

Removes the landmark from the database.

Returns true if the landmark was removed successfully, otherwise returns false.

This function was introduced in Qt Mobility 1.1.

bool QLandmarkManager::removeLandmarks ( const QList<QLandmarkId> & landmarkIds )

Removes every landmark whose identifier is contained in the list of landmarkIds. Returns true if all landmarks were removed successfully, otherwise false.

This batch function will set per-input errors in the QLandmarkManager::errorMap().

The QLandmarkManager::error() function will only return QLandmarkManager::NoError if all landmarks were removed successfully.

This function was introduced in Qt Mobility 1.1.

See also QLandmarkManager::removeLandmark().

bool QLandmarkManager::removeLandmarks ( const QList<QLandmark> & landmarks )

Convenience function to remove the given landmarks from the database. Returns true if all landmarks were removed successfully, otherwise false.

This batch function will set per input errors in the QLandmarkManager::errorMap().

The QLandmarkManager::error() function will only return QLandmarkManager::NoError if all landmarks were removed successfully.

This function was introduced in Qt Mobility 1.1.

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::CategoryDoesNotExistError.

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.

This function was introduced in Qt Mobility 1.1.

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::LandmarkDoesNotExistError.

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.

This function was introduced in Qt Mobility 1.1.

bool QLandmarkManager::saveLandmarks ( QList<QLandmark> * landmarks )

Adds the list of landmarks to the database. Returns true if the landmarks were saved successfully, otherwise returns false.

This function will set per-input errors in the QLandmarkManager::errorMap().

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.

This function was introduced in Qt Mobility 1.1.

QStringList QLandmarkManager::searchableLandmarkAttributeKeys () const

Returns a list of landmark attribute keys that may be used in a QLandmarkAttributeFilter.

This function was introduced in Qt Mobility 1.1.

SupportLevel QLandmarkManager::sortOrderSupportLevel ( const QLandmarkSortOrder & sortOrder ) const

Returns the support level the manager provides for the given sortOrder.

This function was introduced in Qt Mobility 1.1.

QStringList QLandmarkManager::supportedFormats ( TransferOperation operation ) const

Returns the file formats supported for the given transfer operation. ie import or export.

This function was introduced in Qt Mobility 1.1.