QOrganizerManager Class

Member Function Documentation

QOrganizerManager::QOrganizerManager(const QString & managerName, const QMap<QString, QString> & parameters = 0, QObject * parent = 0)

Constructs a QOrganizerManager whose backend is identified by managerName with the given parameters, and the parent object is parent.

The default backend, i.e. the first one returned by the availableManagers() function, for the platform will be created, if the managerName is empty. If the backend identified by managerName does not exist, an invalid backend is created.

QOrganizerManager::QOrganizerManager(QObject * parent = 0)

Constructs a QOrganizerManager whose parent object is parent.

The default backend, i.e. the first one returned by the availableManagers() function, for the platform will be created.

QOrganizerManager::~QOrganizerManager()

Frees the memory used by the QOrganizerManager.

QStringList QOrganizerManager::availableManagers() [static]

Returns a list of available manager names that can be used to construct a QOrganizerManager.

QString QOrganizerManager::buildUri(const QString & managerName, const QMap<QString, QString> & params) [static]

Returns a URI that describes a manager name, parameters, and version with which to instantiate a manager object, from the given managerName and params.

QOrganizerCollection QOrganizerManager::collection(const QOrganizerCollectionId & collectionId)

Returns the collection identified by the given collectionId which is managed by this manager.

QList<QOrganizerCollection> QOrganizerManager::collections()

Returns a list of all of the collections managed by this manager.

void QOrganizerManager::collectionsAdded(const QList<QOrganizerCollectionId> & collectionIds) [signal]

This signal is emitted at some point once the collections identified by collectionIds have been added to a datastore managed by this manager.

This signal will not be emitted if the dataChanged() signal was previously emitted for these changes.

See also dataChanged().

void QOrganizerManager::collectionsChanged(const QList<QOrganizerCollectionId> & collectionIds) [signal]

This signal is emitted at some point once the metadata for the collections identified by collectionIds have been modified in a datastore managed by this manager.

This signal will not be emitted if items in the collections have been added, modified, or removed.

This signal will not be emitted if the dataChanged() signal was previously emitted for these changes.

See also dataChanged().

void QOrganizerManager::collectionsModified(const QList<QPair<QOrganizerCollectionId, QOrganizerManager::Operation> > & collectionIds) [signal]

This signal is emitted at some point once the collections have been modified in a datastore managed by this manager. In the collectionIds list, the collection ID tells which item has been modified with the corresponding operation.

This signal will not be emitted if the dataChanged() signal was previously emitted for these changes.

See also dataChanged().

void QOrganizerManager::collectionsRemoved(const QList<QOrganizerCollectionId> & collectionIds) [signal]

This signal is emitted at some point once the collections identified by collectionIds have been removed from a datastore managed by this manager.

This signal will not be emitted if the dataChanged() signal was previously emitted for these changes.

See also dataChanged().

void QOrganizerManager::dataChanged() [signal]

This signal is emitted by the manager if its internal state changes, and it is unable to determine the changes which occurred, or if the manager considers the changes to be radical enough to require clients to reload all data.

If this signal is emitted, no other signals will be emitted for the associated changes.

See also itemsAdded(), itemsChanged(), and itemsRemoved().

QOrganizerCollection QOrganizerManager::defaultCollection()

Returns the default collection managed by this manager. There is always only one default collection for each backend.

QOrganizerManager::Error QOrganizerManager::error() const

Return the error code of the most recent operation.

See also errorMap().

QMap<int, QOrganizerManager::Error> QOrganizerManager::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.

Each key in the map is the index of the element in the input list for which the error (whose error code is stored in the value for that key in the map) occurred during the batch operation.

See also error(), saveItems(), and removeItems().

QList<QOrganizerItemId> QOrganizerManager::extractIds(const QList<QOrganizerItem> & items) [static]

Return a list of QOrganizerItemId extracted from the items.

QOrganizerManager * QOrganizerManager::fromUri(const QString & uri, QObject * parent = 0) [static]

Constructs a QOrganizerManager whose name, parameters, and version are specified in the given uri, and whose parent object is parent.

QOrganizerItem QOrganizerManager::item(const QOrganizerItemId & itemId, const QOrganizerItemFetchHint & fetchHint = QOrganizerItemFetchHint())

Returns the organizer item in the database identified by itemId, or an empty item if the specified item does not exist.

The fetchHint allows clients to specify which pieces of information they are interested or not interested in, to allow backends to optimise data retrieval if possible. Note that it is simply a hint; backends can ignore the fetchHint and return the full item. If a client makes changes to an organizer item which has been retrieved with a fetch hint, they should save it back using a partial save, masked by the same set of detail types in order to avoid information loss.

QList<QOrganizerItemId> QOrganizerManager::itemIds(const QDateTime & startDateTime = QDateTime(), const QDateTime & endDateTime = QDateTime(), const QOrganizerItemFilter & filter = QOrganizerItemFilter(), const QList<QOrganizerItemSortOrder> & sortOrders = QList<QOrganizerItemSortOrder> ())

Returns a list of item IDs of persisted organizer items that match the given filter, sorted according to the given list of sortOrders, for any item which occurs (or has an occurrence which occurs) in the range specified by the given startDateTime and endDateTime, inclusive.

A default-constructed (invalid) startDateTime specifies an open start date time (matches anything which occurs up until the endDateTime), and a default-constructed (invalid) endDateTime specifies an open end date time (matches anything which occurs after the startDateTime). If both the startDateTime and endDateTime are invalid, this function will return the IDs of all items which match the filter criteria.

Note that certain backends may ignore the given filter.

QList<QOrganizerItem> QOrganizerManager::itemOccurrences(const QOrganizerItem & parentItem, const QDateTime & startDateTime = QDateTime(), const QDateTime & endDateTime = QDateTime(), int maxCount = -1, const QOrganizerItemFetchHint & fetchHint = QOrganizerItemFetchHint())

Returns a list of a maximum of maxCount organizer item instances which are occurrences of the given parentItem recurring item, which occur between the given startDateTime and the given endDateTime date, inclusive.

A default-constructed (invalid) startDateTime specifies an open start date time (matches anything which occurs up until the endDateTime), and a default-constructed (invalid) endDateTime specifies an open end date time (matches anything which occurs after the startDateTime). If both the startDateTime and endDateTime are invalid, this function will return the IDs of all items.

Note that backends will decide how many occurrences are returned if maxCount is negative.

The fetchHint allows clients to specify which pieces of information they are interested or not interested in, to allow backends to optimise data retrieval if possible. Note that it is simply a hint; backends can ignore the fetchHint and return the full item. If a client makes changes to an organizer item which has been retrieved with a fetch hint, they should save it back using a partial save, masked by the same set of detail types in order to avoid information loss.

QList<QOrganizerItem> QOrganizerManager::items(const QList<QOrganizerItemId> & itemIds, const QOrganizerItemFetchHint & fetchHint = QOrganizerItemFetchHint())

Returns the organizer items in the database identified by itemIds.

The items fetched by the backend should have a one-to-one correspondence to the IDs passed into this class. That is, the nth item in the returned list should have an ID which is equal to the nth ID in the list of IDs. Any invalid ID should correspond to an empty QOrganizerItem.

The fetchHint allows clients to specify which pieces of information they are interested or not interested in, to allow backends to optimise data retrieval if possible. Note that it is simply a hint; backends can ignore the fetchHint and return the full item. If a client makes changes to an organizer item which has been retrieved with a fetch hint, they should save it back using a partial save, masked by the same set of detail types in order to avoid information loss.

Calling errorMap() will return the per-input errors for the fetch. The QOrganizerManager::error() function will only return QOrganizerManager::NoError if all organizer items are fetched successfully.

QList<QOrganizerItem> QOrganizerManager::items(const QDateTime & startDateTime = QDateTime(), const QDateTime & endDateTime = QDateTime(), const QOrganizerItemFilter & filter = QOrganizerItemFilter(), int maxCount = -1, const QList<QOrganizerItemSortOrder> & sortOrders = QList<QOrganizerItemSortOrder> (), const QOrganizerItemFetchHint & fetchHint = QOrganizerItemFetchHint())

Returns a list of a maximum of maxCount organizer items and occurrences that match the given filter, which occur in the range specified by the given startDateTime and endDateTime, inclusive, and sorted according to the given list of sortOrders.

A default-constructed (invalid) startDateTime specifies an open start date time (matches anything which occurs up until the endDateTime), and a default-constructed (invalid) endDateTime specifies an open end date time (matches anything which occurs after the startDateTime). If both the startDateTime and endDateTime are invalid, this function will return the IDs of all items which match the filter criteria.

If no sort order is provided, the list is returned sorted by date.

Note that certain backends may ignore the given filter.

Note that backends will decide how many items are returned if maxCount is negative.

The fetchHint allows clients to specify which pieces of information they are interested or not interested in, to allow backends to optimise data retrieval if possible. Note that it is simply a hint; backends can ignore the fetchHint and return the full item. If a client makes changes to an organizer item which has been retrieved with a fetch hint, they should save it back using a partial save, masked by the same set of detail types in order to avoid information loss.

void QOrganizerManager::itemsAdded(const QList<QOrganizerItemId> & itemIds) [signal]

This signal is emitted at some point once the items identified by itemIds have been added to a datastore managed by this manager.

This signal will not be emitted if the dataChanged() signal was previously emitted for these changes.

See also dataChanged().

void QOrganizerManager::itemsChanged(const QList<QOrganizerItemId> & itemIds) [signal]

This signal is emitted at some point once the items identified by itemIds have been modified in a datastore managed by this manager.

This signal will not be emitted if the dataChanged() signal was previously emitted for these changes.

See also dataChanged().

QList<QOrganizerItem> QOrganizerManager::itemsForExport(const QDateTime & startDateTime = QDateTime(), const QDateTime & endDateTime = QDateTime(), const QOrganizerItemFilter & filter = QOrganizerItemFilter(), const QList<QOrganizerItemSortOrder> & sortOrders = QList<QOrganizerItemSortOrder> (), const QOrganizerItemFetchHint & fetchHint = QOrganizerItemFetchHint())

Returns a list of organizer items that match the given filter, sorted according to the given list of sortOrders, for any item which occurs (or has an occurrence which occurs) in the range specified by the given startDateTime and endDateTime, inclusive.

A default-constructed (invalid) startDateTime specifies an open start date time (matches anything which occurs up until the endDateTime), and a default-constructed (invalid) endDateTime specifies an open end date time (matches anything which occurs after the startDateTime). If both the startDateTime and endDateTime are invalid, this function will return the IDs of all items which match the filter criteria.

This function will only return parent items and persisted exceptions which match the specified criteria; not generated occurrences.

Note that certain backends may ignore the given filter.

The fetchHint allows clients to specify which pieces of information they are interested or not interested in, to allow backends to optimise data retrieval if possible. Note that it is simply a hint; backends can ignore the fetchHint and return the full item. If a client makes changes to an organizer item which has been retrieved with a fetch hint, they should save it back using a partial save, masked by the same set of detail types in order to avoid information loss.

void QOrganizerManager::itemsModified(const QList<QPair<QOrganizerItemId, QOrganizerManager::Operation> > & itemIds) [signal]

This signal is emitted at some point once the items have been modified in a datastore managed by this manager. In the itemIds list, the item ID tells which item has been modified with the corresponding operation.

This signal will not be emitted if the dataChanged() signal was previously emitted for these changes.

See also dataChanged().

void QOrganizerManager::itemsRemoved(const QList<QOrganizerItemId> & itemIds) [signal]

This signal is emitted at some point once the items identified by itemIds have been removed from a datastore managed by this manager.

This signal will not be emitted if the dataChanged() signal was previously emitted for these changes.

See also dataChanged().

QString QOrganizerManager::managerName() const

Returns the manager name for the backend.

QMap<QString, QString> QOrganizerManager::managerParameters() const

Return the parameters used by the backend.

Note that if certain paramters are invalid, or discarded by the backend, they will not be returned. Also, the backend might add certain parameters when being constructed.

QString QOrganizerManager::managerUri() const

Return the URI describing the backend.

int QOrganizerManager::managerVersion() const

This is now obsoleted, and will be removed soon. Please parse the version from managerParameters().

bool QOrganizerManager::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.

bool QOrganizerManager::removeCollection(const QOrganizerCollectionId & collectionId)

Removes the collection identified by the given collectionId (and all items in the collection) from the manager. Returns true on success, false on failure.

If the given collectionId does not exist, the operation will fail and QOrganizerManager::DoesNotExistError will be returned when calling error().

If the given collectionId refers to the default collection, the operation will fail and QOrganizerManager::PermissionsError will be returned when calling error().

bool QOrganizerManager::removeItem(const QOrganizerItemId & itemId)

Removes all the item whose ID is itemId, and all its occurrences. Returns true if the item and occurrences are successfully removed, or false otherwise.

See also removeItems.

bool QOrganizerManager::removeItem(const QOrganizerItem * item)

Remove the organizer item from the database. If item is a generated occurrence, the start date of the occurrence is added to its parent item's exception date list. Returns true if the organizer item was removed successfully, otherwise returns false.

See also removeItems.

bool QOrganizerManager::removeItems(const QList<QOrganizerItemId> & itemIds)

Removes all the items whose ID is contained in the given list of itemIds, and all the occurrences whose parent ID is containd in the itemIds. Returns true if all the items and occurrences are successfully removed, or false otherwise.

Calling errorMap() will return the per-input errors for the operation. The error() function will only return QOrganizerManager::NoError if all organizer items were saved successfully.

See also removeItem.

bool QOrganizerManager::removeItems(const QList<QOrganizerItem> * items)

Removes every organizer item which is contained in the list of organizer items items. If the list contains generated occurrences the start date of the occurrence is added to its parent item's exception date list. Returns true if all organizer items were removed successfully, otherwise false.

Calling errorMap() will return the per-input errors for the latest batch function. The QOrganizerManager::error() function will only return QOrganizerManager::NoError if all organizer items were removed successfully.

If the given list of organizer items is empty, the function will return false and calling error() will return QOrganizerManager::BadArgumentError. If the list is non-empty and contains items which are not a valid organizer item in the manager, the function will remove any valid organizer items in the items list, insert QOrganizerManager::DoesNotExist entries into the error map for the indices of invalid id in the items list, return false, and set the overall operation error to QOrganizerManager::DoesNotExistError.

See also QOrganizerManager::removeItem().

bool QOrganizerManager::saveCollection(QOrganizerCollection * collection)

Saves the given collection to the backend, and returns true on success or false otherwise.

Note that certain backends may not allow modification nor adding new collections, in such cases the operation will fail and result a QOrganizerManager::PermissionsError error.

A new collection will be created in the backend store if the collection ID of it is null. Otherwise, an existing collection with the same ID will be updated. If the given collection ID does not exist in the backend, it will result a QOrganizerManager::DoesNotExistError error.

Note that upon successful saving, the backend may update the collection, e.g. collection ID for newly saved collections.

bool QOrganizerManager::saveItem(QOrganizerItem * item, const QList<QOrganizerItemDetail::DetailType> & detailMask = QList<QOrganizerItemDetail::DetailType> ())

Saves the given item to the backend, and returns true on success or false otherwise.

A new organizer item will be created in the backend store if the item ID of it is null. Otherwise, an existing item with the same ID will be updated. If the given item ID does not exist in the backend, it will result a QOrganizerManager::DoesNotExistError error.

If the collection ID of the item is null, it will be saved to the default collection. If the given collection ID doesn't exist, the saving will fail.

If the detailMask is empty, only the details currently existing in the item will be saved. Otherwise, only details masked by the detailMask will be saved or updated, others are kept untouched. It's useful to avoid information loss if the items are retrieved with a fetch hint.

Note that upon successful saving, the backend may update the item, e.g. item ID for newly saved items, GUID, timestamp, version, etc.

See also saveItems.

bool QOrganizerManager::saveItems(QList<QOrganizerItem> * items, const QList<QOrganizerItemDetail::DetailType> & detailMask = QList<QOrganizerItemDetail::DetailType> ())

Saves the given list of items to the backend, and returns true on success or false otherwise.

A new organizer item will be created in the backend store if the item ID of it is null. Otherwise, an existing item with the same ID will be updated. If the given item ID does not exist in the backend, it will result a QOrganizerManager::DoesNotExistError error.

If the collection ID of the item is null, it will be saved to the default collection. If the given collection ID doesn't exist, the saving will fail.

If the detailMask is empty, only the details currently existing in the item will be saved. Otherwise, only details masked by the detailMask will be saved or updated, others are kept untouched. It's useful to avoid information loss if the items are retrieved with a fetch hint.

Note that upon successful saving, the backend may update the item, e.g. item ID for newly saved items, GUID, timestamp, version, etc.

Calling errorMap() will return the per-input errors for the operation. The error() function will only return QOrganizerManager::NoError if all organizer items were saved successfully.

See also saveItem.

QList<QOrganizerItemFilter::FilterType> QOrganizerManager::supportedFilters() const

Returns the list of supported filters by this manager.

QList<QOrganizerItemDetail::DetailType> QOrganizerManager::supportedItemDetails(QOrganizerItemType::ItemType itemType) const

Returns the list of details that are supported by this manager for the given itemType.

QList<QOrganizerItemType::ItemType> QOrganizerManager::supportedItemTypes() const

Returns the list of organizer item types supported by this manager.