Member Function Documentation
QOrganizerManagerEngine::QOrganizerManagerEngine(QObject * parent = 0)
Constructs an empty QOrganizerManagerEngine with the given parent.
Insert toAdd to the defaultSorted map. If toAdd does not have valid start or end date, returns false and does not insert toAdd to defaultSorted map.
This function provides default sorting, which should be used for sorting fetch results, if no sort order was defined for the fetch. The default sorting algorithm is to sort based on start time of an item. If start time does not exist, end time or due time is used instead. For allday events, time 00:00 is used for sorting purposes. Items with no start or end time are last in the sorting order.
This function sorts items using QMultiMap, where QDateTime is used as a key. To get a sorted list of items, QMultiMap::values function should be called and items without start and end date added to the end of the list.
Insert toAdd to the sorted list, according to the provided sortOrders. The index where toAdd is inserted is returned.
The first one in the sortOrders list has the highest priority.
bool QOrganizerManagerEngine::cancelRequest(QOrganizerAbstractRequest * request) [virtual]
This function is called when the client tries to cancel the given asynchronous request. Returns true if the request is calcelled successfully, or false otherwise.
Given an input filter, returns the canonical version of the filter.
Some of the following transformations may be applied:
This function should be reimplemented to support synchronous calls to fetch a collection based on its ID. Any errors encountered during this operation should be stored to error. If the given collectionId does not specify a valid collection, error will be set to QOrganizerManager::DoesNotExistError.
This function should be reimplemented to support synchronous calls to fetch all the collections managed by this backend. Any errors encountered during this operation should be stored to error.
void QOrganizerManagerEngine::collectionsAdded(const QList<QOrganizerCollectionId> & collectionIds) [signal]
This signal should be emitted at some point once the collections identified by collectionIds have been added to the backend.
This signal should not be emitted if the dataChanged() signal was previously emitted for these changes.
See also dataChanged().
void QOrganizerManagerEngine::collectionsChanged(const QList<QOrganizerCollectionId> & collectionIds) [signal]
This signal should be emitted at some point once the collections identified by collectionIds have been changed in the backend.
This signal should not be emitted if items in the collections have been added, modified, or removed.
This signal should not be emitted if the dataChanged() signal was previously emitted for these changes.
See also dataChanged().
This signal should be emitted at some point once the collections identified by collectionIds have been modified in the backend.
This signal should not be emitted if the dataChanged() signal was previously emitted for these changes.
See also dataChanged().
void QOrganizerManagerEngine::collectionsRemoved(const QList<QOrganizerCollectionId> & collectionIds) [signal]
This signal should be emitted at some point once the collections identified by collectionIds have been removed from the backend.
This signal should not be emitted if the dataChanged() signal was previously emitted for these changes.
See also dataChanged().
Compares two organizer items (a and b) using the given list of sortOrders. Returns a negative number if a should appear before b according to the sort order, a positive number if a should appear after b according to the sort order, and zero if the two are unable to be sorted.
int QOrganizerManagerEngine::compareVariant(const QVariant & first, const QVariant & second, Qt::CaseSensitivity sensitivity) [static]
Compares first against second. If the types are strings (QVariant::String(obsolete)), the sensitivity argument controls case sensitivity when comparing.
Returns: <0 if first is less than second 0 if first is equal to second >0 if first is greater than second.
The results are undefined if the variants are different types, or cannot be compared.
void QOrganizerManagerEngine::dataChanged() [signal]
This signal should be emitted if the internal state of the plugin changes, and it is unable to determine the changes which occurred, or if it 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().
This function should be reimplemented to support synchronous calls to fetch the default collection. Any errors encountered during this operation should be stored to error.
const QOrganizerCollectionEngineId * QOrganizerManagerEngine::engineCollectionId(const QOrganizerCollectionId & id) [static]
Returns the engine ID from the given collection id.
The caller does not take ownership of the pointer, and should not delete returned id or undefined behavior may occur.
const QOrganizerItemEngineId * QOrganizerManagerEngine::engineItemId(const QOrganizerItemId & id) [static]
Returns the engine ID from the given item id.
The caller does not take ownership of the pointer, and should not delete returned id or undefined behavior may occur.
QList<QDate> QOrganizerManagerEngine::filterByPosition(const QList<QDate> & dates, const QSet<int> positions) [static]
Returns a list of dates from dates which are at the indices specified by positions. For positive values in positions, the values represent a 1-based index into dates. For negative values, they represent indices counting from the end of dates (eg. -1 means the last value of dates).
QDate QOrganizerManagerEngine::firstDateInNextPeriod(const QDate & date, QOrganizerRecurrenceRule::Frequency frequency, Qt::DayOfWeek firstDayOfWeek) [static]
Returns the date which is the first date of the next calendar period after date specified by frequency. eg. if frequency is Monthly, then this returns the first day of the next month. If frequency is Weekly, then it returns the first firstDayOfWeek after date.
QDate QOrganizerManagerEngine::firstDateInPeriod(const QDate & date, QOrganizerRecurrenceRule::Frequency frequency, Qt::DayOfWeek firstDayOfWeek) [static]
Returns the date which is the first date of the calendar period that date resides in. eg. if the frequency is Monthly, then this returns the first day of date's month. If the frequency is Weekly, then it returns the first day of date's week, considering the week to start on firstDayOfWeek
QList<QDateTime> QOrganizerManagerEngine::generateDateTimes(const QDateTime & initialDateTime, QOrganizerRecurrenceRule rrule, const QDateTime & periodStart, const QDateTime & periodEnd, int maxCount) [static]
Generates all start times for recurrence rrule during the given time period. The time period is defined by periodStart and periodEnd. initialDateTime is the start time of the event, which defines the first start time for rrule. maxCount can be used to limit the amount of generated start times.
QOrganizerItem QOrganizerManagerEngine::generateOccurrence(const QOrganizerItem & parentItem, const QDateTime & rdate) [static]
Generates a new occurrence for parentItem. All parentItem details, except for QOrganizerItemType and QOrganizerItemRecurrence copied to the occurrence. Occurrence start date is set to the date given in rdate. End date is modified accordingly. Occurrence's QOrganizerItemParent detail contains the id of parentItem and the original date given in rdate.
bool QOrganizerManagerEngine::inMultipleOfInterval(const QDate & date, const QDate & initialDate, QOrganizerRecurrenceRule::Frequency frequency, int interval, Qt::DayOfWeek firstDayOfWeek) [static]
Returns true if the calendar period (specified by frequency) of date is an interval multiple of periods ahead of the calendar period of initialDate. For Weekly frequencies, firstDayOfWeek is used to determine when the week boundary is. eg. If frequency is Monthly and interval is 3, then true is returned iff date is in the same month as initialDate, in a month 3 months ahead, 6 months ahead, etc.
void QOrganizerManagerEngine::inferMissingCriteria(QOrganizerRecurrenceRule * rrule, const QDate & initialDate) [static]
Determines if rrule is underspecified and if so, fills in missing information based on initialDate.
bool QOrganizerManagerEngine::isItemBetweenDates(const QOrganizerItem & item, const QDateTime & startPeriod, const QDateTime & endPeriod) [static]
Returns true if the given item (or an occurrence of the item) occurs within the range specified by the startPeriod and the endPeriod, inclusive. A default-constructed startPeriod signifies that the lower bound of the range is infinitely small (i.e., will match anything up to the endPeriod) and a default-constructed endPeriod signifies that the upper bound of the range is infinitely large (i.e., will match anything which occurs after the startPeriod).
bool QOrganizerManagerEngine::itemHasReccurence(const QOrganizerItem & oi) [static]
Returns true if the given organizer item oi has any recurrence.
This function should be reimplemented to support synchronous calls to fetch organizer item IDs.
This function is supposed to return 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. Any error which occurs should be saved in error.
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.
It's up to the backend to decide how filters are supported.
bool QOrganizerManagerEngine::itemLessThan(const QOrganizerItem & a, const QOrganizerItem & b) [static]
Returns true if and only if a is temporally less than b. Items with an earlier date are temporally less than items with a later date, or items with no date. All day items are temporally less than non-all day items on the same date. For events and todos, the start date is used, or if null, the end date is used. This function defines a total ordering suitable for use in a sort function.
This function should be reimplemented to support synchronous calls to fetch occurrences of the given parent item.
This function is supposed to return 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. Any error which occurs should be saved in error.
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.
It's up to the backend to decide how many occurrences are returned if the given maxCount is negative.
It's up to the backend to decide if fetch hint is supported. If supported, only the details defined by fetchHint will be fetched.
This function should be reimplemented to support synchronous calls to fetch organizer items by their IDs 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.
It's up to the backend to decide if fetch hint is supported. If supported, only the details defined by fetchHint will be fetched.
Any operation error which occurs should be saved in error. And the per-input errors should be stored in errorMap.
This function should be reimplemented to support synchronous calls to fetch organizer items.
This function is supposed to return 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. Any operation error which occurs should be saved in error.
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.
It's up to the backend to decide how many items should be returned if maxCount is negative.
It's up to the backend to decide if filter and fetch hint are supported.
void QOrganizerManagerEngine::itemsAdded(const QList<QOrganizerItemId> & itemIds) [signal]
This signal should be emitted at some point once the items identified by itemIds have been added to the backend.
This signal should not be emitted if the dataChanged() signal was previously emitted for these changes.
See also dataChanged().
void QOrganizerManagerEngine::itemsChanged(const QList<QOrganizerItemId> & itemIds) [signal]
This signal should be emitted at some point once the items identified by itemIds have been modified in the backend.
This signal should not be emitted if the dataChanged() signal was previously emitted for these changes.
See also dataChanged().
This function should be reimplemented to support synchronous calls to fetch organizer items for export.
This function is supposed to return 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. Any operation error which occurs should be saved in error.
Note that event occurrences and TODO occurrences should only be returned when they represent an exceptional occurrence (i.e. the client has specifically saved the occurrence in the backend).
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.
It's up to the backend to decide if filter and fetch hint are supported. If the fetch hint is supported, only the details defined by fetchHint will be fetched.
This signal should be emitted at some point once the items identified by itemIds have been modified in the backend.
This signal should not be emitted if the dataChanged() signal was previously emitted for these changes.
See also dataChanged().
void QOrganizerManagerEngine::itemsRemoved(const QList<QOrganizerItemId> & itemIds) [signal]
This signal should be emitted at some point once the items identified by itemIds have been removed from the backend.
This signal should not be emitted if the dataChanged() signal was previously emitted for these changes.
See also dataChanged().
QString QOrganizerManagerEngine::managerName() const [virtual]
This function should be reimplemented to return the name of this backend. The default implementation returns the name "invalid".
QMap<QString, QString> QOrganizerManagerEngine::managerParameters() const [virtual]
This function should be reimplemented to return the parameters used in when constructing this backend. The default implementation returns an empty QMap.
If certain paramters are invalid, or discarded by the backend, they should not be returned.
QString QOrganizerManagerEngine::managerUri() const
Returns the unique URI of this manager, which is built from the manager name and the parameters used to construct it.
QList<QDate> QOrganizerManagerEngine::matchingDates(const QDate & periodStart, const QDate & periodEnd, const QOrganizerRecurrenceRule & rrule) [static]
Returns a list of dates between periodStart (inclusive) and periodEnd (inclusive) which match the rrule. Only daysOfWeek, daysOfMonth, daysOfYear, weeksOfYear and months from the rrule are matched.
This function should be reimplemented to support synchronous calls to remove a collection.
This function is supposed to remove the collection identified by the given collectionId, and all items in the collection. Returns true on success, or false otherwise. Any errors encountered during this operation should be stored to error.
Note that removing the default collection should not be allowed and should result a QOrganizerManager::PermissionsError error.
This function should be reimplemented to support synchronous calls to remove organizer items.
This function is supposed to remove 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. If the list contains ids which do not identify a valid item in the manager error will be set to QOrganizerManager::DoesNotExist. Returns true if all the items and occurrences are successfully removed, or false otherwise.
Any error which occurs should be saved in error, and per-input errors for the operation should be stored in errorMap.
This function should be reimplemented to support synchronous calls to remove organizer items.
This function is supposed to remove all the items in the given list of items, and all the occurrences whose parent is containd in the items. If item in the list is a generated occurrence, an exception date is added to the parent item. If the list contains ids which do not identify a valid item in the manager error will be set to QOrganizerManager::DoesNotExist. Returns true if all the items and occurrences are successfully removed, or false otherwise.
Any error which occurs should be saved in error, and per-input errors for the operation should be stored in errorMap.
void QOrganizerManagerEngine::requestDestroyed(QOrganizerAbstractRequest * request) [virtual]
This function is called when the given request has been destroyed by the client.
When this function is called, it means for the backend:
- The client doesn't care about the request any more. The engine can still complete it, but completion is not required.
- It can't reliably access any properties of the request pointer any more. The pointer will be invalid once this function returns.
Note that since the request may run in another thread, this function should be blocked until the worker thread gets fully notified.
This function should be reimplemented to support synchronous calls to save a collection.
This function is supposed to save the given collection to the backend, and returns true on success or false otherwise. Any errors encountered during this operation should be stored to 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.
This function should be reimplemented to support synchronous calls to save organizer items.
This function is supposed to save 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 and error will be set to QOrganizerManager::InvalidCollectionError.
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.
Any error which occurs should be saved in error, and per-input errors for the operation should be stored in errorMap.
bool QOrganizerManagerEngine::startRequest(QOrganizerAbstractRequest * request) [virtual]
This function is called when the client tries to start the given asynchronous request. Returns true if the request is started successfully, or false otherwise.
Note that the request is supposed to run in an asynchronous manner that this function should return as soon as possible. Therefore, it the operation would last sometime, a worker thread should be used to queue and process the request. In such cases, backend should be aware that the request may be deleted by the client, and requestDestroyed() function will be called.
This function should be reimplemented to return the list of filters supported by this backend. The default implementation returns an empty list.
QList<QOrganizerItemDetail::DetailType> QOrganizerManagerEngine::supportedItemDetails(QOrganizerItemType::ItemType itemType) const [virtual]
This function should be reimplemented to return the list of details supported by this backend for the given itemType. The default implementation returns an empty list.
QList<QOrganizerItemType::ItemType> QOrganizerManagerEngine::supportedItemTypes() const [virtual]
This function should be reimplemented to return the list of item types supported by this backend. The default implementation returns an empty list.
bool QOrganizerManagerEngine::testFilter(const QOrganizerItemFilter & filter, const QOrganizerItem & item) [static]
Returns true if the supplied item item matches the supplied filter filter.
This function will test each condition in the filter, possibly recursing.
Updates the given QOrganizerCollectionFetchRequest req with the latest results result and an operation error error. In addition, the state of the request will be changed to newState.
It then causes the request to emit its resultsAvailable() signal to notify clients of the request progress. If the new request state is different from the previous state, the stateChanged() signal will also be emitted from the request.
Updates the given QOrganizerCollectionRemoveRequest req with the operation error error, and map of input index to individual error errorMap. In addition, the state of the request will be changed to newState.
It then causes the request to emit its resultsAvailable() signal to notify clients of the request progress. If the new request state is different from the previous state, the stateChanged() signal will also be emitted from the request.
Updates the given QOrganizerCollectionSaveRequest req with the latest results result, operation error error, and map of input index to individual error errorMap. In addition, the state of the request will be changed to newState.
It then causes the request to emit its resultsAvailable() signal to notify clients of the request progress. If the new request state is different from the previous state, the stateChanged() signal will also be emitted from the request.
Updates the given QOrganizerItemFetchByIdRequest req with the latest results result, and operation error error, and map of input index to individual error errorMap. In addition, the state of the request will be changed to newState.
It then causes the request to emit its resultsAvailable() signal to notify clients of the request progress.
If the new request state is different from the previous state, the stateChanged() signal will also be emitted from the request.
Updates the given QOrganizerItemFetchForExportRequest req with the latest results result, and operation error error. In addition, the state of the request will be changed to newState.
It then causes the request to emit its resultsAvailable() signal to notify clients of the request progress.
If the new request state is different from the previous state, the stateChanged() signal will also be emitted from the request.
Updates the given QOrganizerItemFetchRequest req with the latest results result, and operation error error. In addition, the state of the request will be changed to newState.
It then causes the request to emit its resultsAvailable() signal to notify clients of the request progress.
If the new request state is different from the previous state, the stateChanged() signal will also be emitted from the request.
Updates the given QOrganizerItemIdFetchRequest req with the latest results result, and operation error error. In addition, the state of the request will be changed to newState.
It then causes the request to emit its resultsAvailable() signal to notify clients of the request progress.
If the new request state is different from the previous state, the stateChanged() signal will also be emitted from the request.
Updates the given QOrganizerItemOccurrenceFetchRequest req with the latest results result, and operation error error. In addition, the state of the request will be changed to newState.
It then causes the request to emit its resultsAvailable() signal to notify clients of the request progress.
If the new request state is different from the previous state, the stateChanged() signal will also be emitted from the request.
Updates the given QOrganizerItemRemoveByIdRequest req with the operation error error, and map of input index to individual error errorMap. In addition, the state of the request will be changed to newState.
It then causes the request to emit its resultsAvailable() signal to notify clients of the request progress.
If the new request state is different from the previous state, the stateChanged() signal will also be emitted from the request.
Updates the given QOrganizerItemRemoveRequest req with the operation error error, and map of input index to individual error errorMap. In addition, the state of the request will be changed to newState.
It then causes the request to emit its resultsAvailable() signal to notify clients of the request progress.
If the new request state is different from the previous state, the stateChanged() signal will also be emitted from the request.
Updates the given QOrganizerItemSaveRequest req with the latest results result, operation error error, and map of input index to individual error errorMap. In addition, the state of the request will be changed to newState.
It then causes the request to emit its resultsAvailable() signal to notify clients of the request progress.
If the new request state is different from the previous state, the stateChanged() signal will also be emitted from the request.
Updates the given asynchronous request req by setting the new state of the request. If the new state is different, the stateChanged() signal will be emitted by the request.
bool QOrganizerManagerEngine::waitForRequestFinished(QOrganizerAbstractRequest * request, int msecs) [virtual]
This function is called when the client wants to be blocked until the given request is completed, or until msecs milliseconds have passed. Returns true when the request is completed, or false otherwise.
