QLandmarkManager Class ReferenceThe QLandmarkManager class provides an interface for storage and retrieval of landmarks from a landmark store. More... #include <QLandmarkManager> Inherits QObject. Public Types
Public Functions
Signals
Static Public Members
Additional Inherited Members
Detailed DescriptionThe 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. It 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. 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 operationsTo retrieve a set of landmarks we provide may provide a QLandmarkFilter, QLandmarkSortOrder and limit and offset 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. A QLandmarkSortOrder order defines how the results should be sorted. (Note that if you wish to sort by distance, you should use a proxmity filter, see QLandmarkProximityFilter). The limit allows specification of the maximum number of items to return and the offset defines the index of the first item. The following demonstrates how to search for the first 100 landmarks belonging to a given category, sorted by name. QLandmarkCategoryFilter filter; filter.setCategoryId(category.categoryId()); QLandmarkNameSort nameSort; nameSort.setDirection(Qt::AscendingOrder); landmarkManager->landmarks(filter, 100, 0, nameSort); 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 deletingSaving 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); Importing and exportingImport and exporting are potentially long operations, to perform these operations asynchronously see QLandmarkImportRequest and QLandmarkExportRequest. The simplest way to perform an import is to supply a filename while an export will need both a filename and format. landmarkManager->importLandmarks("places.gpx"); landmarkManager->exportLandmarks("myplaces.gpx",QLandmarkManager::Gpx); Member Type Documentation
|
Constant | Value | Description |
---|---|---|
QLandmarkManager::NoError | 0 | No error occurred |
QLandmarkManager::DoesNotExistError | 1 | The most recent operation failed due to an item not being found, usually an import file. |
QLandmarkManager::LandmarkDoesNotExistError | 2 | The most recent operation failed due to a specified landmark not being found. |
QLandmarkManager::CategoryDoesNotExistError | 3 | The most recent operation faied due to a specified category not being found. |
QLandmarkManager::AlreadyExistsError | 4 | The most recent operation failed because the specified landmark or category already exists. |
QLandmarkManager::LockedError | 5 | The most recent operation failed because the datastore specified is currently locked. |
QLandmarkManager::PermissionsError | 6 | The most recent operation failed because the caller does not have permission to perform the operation. |
QLandmarkManager::OutOfMemoryError | 7 | The most recent operation failed due to running out of memory. |
QLandmarkManager::VersionMismatchError | 8 | The most recent operation failed because the backend of the manager is not of the required version. |
QLandmarkManager::NotSupportedError | 9 | The most recent operation failed because the requested operation is not supported by the manager. |
QLandmarkManager::BadArgumentError | 10 | The most recent operation failed because one or more of the parameters to the operation were invalid. |
QLandmarkManager::InvalidManagerError | 11 | 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 | 12 | The most recent operation failed because the imported file could not be parsed. |
QLandmarkManager::CancelError | 13 | The most recent operation failed to complete due to user cancelation. |
QLandmarkManager::UnknownError | 14 | The most recent operation failed for an unknown reason. |
Defines the possible features the landmark manager can support.
Constant | Value | Description |
---|---|---|
QLandmarkManager::ImportExportFeature | 0 | The manager supports import and/or export operations |
QLandmarkManager::NotificationsFeature | 1 | The manager will emit notification signals when landmarks/categories have been added/modified/removed from the datastore it manages. |
Defines the possible support levels the manager can provide for a given filter or sort order list.
Constant | Value | Description |
---|---|---|
QLandmarkManager::NativeSupport | 0 | The manager natively supports the filter or sort order list. |
QLandmarkManager::EmulatedSupport | 1 | The manager emulates the behaviour of the filter or sort order list. Emulated behaviour will inherently be slower than a natively supported implementation. |
QLandmarkManager::NoSupport | 2 | The manager does not support the filter or sort order list at all. |
Defines the type of transfer.
Constant | Value | Description |
---|---|---|
QLandmarkManager::ImportOperation | 0 | Landmarks are being copied from a file to the device. |
QLandmarkManager::ExportOperation | 1 | Landmarks are being copied from the device to a file. |
Defines the possible options when transferring landmarks during import or export.
Constant | Value | Description |
---|---|---|
QLandmarkManager::IncludeCategoryData | 0 | During an import, category data is included. If an imported category doesn't exist the category is created. If the imported category name matches an existing category name, then the landmark is added to that category. For exports, categories are included in the exported file if the file format allows it. |
QLandmarkManager::ExcludeCategoryData | 1 | Landmarks are imported or exported without any categories assigned to the landmarks. |
QLandmarkManager::AttachSingleCategory | 2 | Only relevant for import operations. When landmarks are imported they are all assigned to a given category. |
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.
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.
Frees the memory used by the QLandmarkManager
Returns a list of available manager names that can be used when constructing a QLandmarkManager
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
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.
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 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.
See also categoriesChanged() and categoriesRemoved().
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.
See also categoriesAdded() and categoriesRemoved().
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.
See also categoriesAdded() and categoriesChanged().
Returns the cateory in the database identified by categoryId.
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 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.
Returns the error code of the most recent operation. All functions will modify the error based on whether the operation successfully or not.
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.
See also error(), categories(), landmarks(), saveLandmarks(), removeCategory(), and removeLandmarks().
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.
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.
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.
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.
Constructs a QLandmarkManager whose implementation, store and parameters are specified in the given storeUri, and whose parent object is parent.
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.
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.
Returns whether the manager supports the given feature.
Returns true if the manager is entirely read-only. Meaning landmarks and categories cannot be added, modified or removed.
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.
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.
Returns the landmark in the database identified by landmarkId
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.
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.
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.
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.
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 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.
See also landmarksChanged() and landmarksRemoved().
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.
See also landmarksAdded() and landmarksRemoved().
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.
See also landmarksAdded() and landmarksChanged().
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
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.
Return the uri describing this QLandmarkManager, consisting of the manager name and any parameters.
Returns the engine backend implementation version number.
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
Remove the category identified by categoryId from the database.
Returns true if the category was removed successfully, otherwise returnse false.
Remove the given category from the database
Returns true if the category was removed successfully, otherwise returnse false.
Remove the landmark identified by landmarkId from the database.
Returns true if the landmark was removed successfully, otherwise returnse false.
Removes the landmark from the database.
Returns true if the landmark was removed successfully, otherwise returns false.
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.
See also QLandmarkManager::removeLandmark().
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.
See also QLandmarkManager::removeLandmark().
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.
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.
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.
Returns a list of landmark attribute keys that may be used in a QLandmarkAttributeFilter.
Returns the support level the manager provides for the given sortOrder.
Returns the file formats supported for the given transfer operation. ie import or export.
The format constant to define using the gpx format in the import and export functions.
See also importLandmarks() and exportLandmarks().
The format constant to define using the kml format in the import and export functions.
See also importLandmarks() and exportLandmarks().
The format constant to define using the kmz format in the import and export functions.
See also importLandmarks() and exportLandmarks().
The format constant to define using the lmx format in the import and export functions.
See also importLandmarks() and exportLandmarks().