QOrganizerItemManager Class Reference
The QOrganizerItemManager class provides an interface which allows clients with access to organizer item information stored in a particular backend. More...
#include <QOrganizerItemManager>
Public Types
enum | Error { NoError, DoesNotExistError, AlreadyExistsError, InvalidDetailError, ..., InvalidOccurrenceError } |
enum | ManagerFeature { MutableDefinitions, ChangeLogs, Anonymous } |
Public Functions
| QOrganizerItemManager ( const QString & managerName = QString(), const QMap<QString, QString> & parameters = 0, QObject * parent = 0 ) |
| QOrganizerItemManager ( const QString & managerName, int implementationVersion, const QMap<QString, QString> & parameters = 0, QObject * parent = 0 ) |
| QOrganizerItemManager ( QObject * parent ) |
| ~QOrganizerItemManager () |
QOrganizerItem | compatibleItem ( const QOrganizerItem & original ) |
QOrganizerItemDetailDefinition | detailDefinition ( const QString & definitionName, const QString & organizeritemType = QOrganizerItemType::TypeEvent ) const |
QMap<QString, QOrganizerItemDetailDefinition> | detailDefinitions ( const QString & organizeritemType = QOrganizerItemType::TypeEvent ) const |
QOrganizerItemManager::Error | error () const |
bool | hasFeature ( QOrganizerItemManager::ManagerFeature feature, const QString & organizeritemType = QOrganizerItemType::TypeEvent ) const |
bool | isFilterSupported ( const QOrganizerItemFilter & filter ) const |
QOrganizerItem | item ( const QOrganizerItemLocalId & organizeritemId, const QOrganizerItemFetchHint & fetchHint = QOrganizerItemFetchHint() ) const |
QList<QOrganizerItemLocalId> | itemIds ( const QList<QOrganizerItemSortOrder> & sortOrders = QList<QOrganizerItemSortOrder> () ) const |
QList<QOrganizerItemLocalId> | itemIds ( const QOrganizerItemFilter & filter, const QList<QOrganizerItemSortOrder> & sortOrders = QList<QOrganizerItemSortOrder> () ) const |
QList<QOrganizerItem> | itemInstances ( const QOrganizerItemFilter & filter = QOrganizerItemFilter(), const QList<QOrganizerItemSortOrder> & sortOrders = QList<QOrganizerItemSortOrder> (), const QOrganizerItemFetchHint & fetchHint = QOrganizerItemFetchHint() ) const |
QList<QOrganizerItem> | itemInstances ( const QOrganizerItem & generator, const QDateTime & periodStart = QDateTime(), const QDateTime & periodEnd = QDateTime(), int maxCount = -1 ) const |
QList<QOrganizerItem> | items ( const QList<QOrganizerItemSortOrder> & sortOrders = QList<QOrganizerItemSortOrder> (), const QOrganizerItemFetchHint & fetchHint = QOrganizerItemFetchHint() ) const |
QList<QOrganizerItem> | items ( const QOrganizerItemFilter & filter, const QList<QOrganizerItemSortOrder> & sortOrders = QList<QOrganizerItemSortOrder> (), const QOrganizerItemFetchHint & fetchHint = QOrganizerItemFetchHint() ) const |
QString | managerName () const |
QMap<QString, QString> | managerParameters () const |
QString | managerUri () const |
int | managerVersion () const |
bool | removeDetailDefinition ( const QString & definitionName, const QString & organizeritemType = QOrganizerItemType::TypeEvent ) |
bool | removeItem ( const QOrganizerItemLocalId & organizeritemId ) |
bool | removeItems ( const QList<QOrganizerItemLocalId> & organizeritemIds, QMap<int, QOrganizerItemManager::Error> * errorMap ) |
bool | saveDetailDefinition ( const QOrganizerItemDetailDefinition & def, const QString & organizeritemType = QOrganizerItemType::TypeEvent ) |
bool | saveItem ( QOrganizerItem * organizeritem ) |
bool | saveItems ( QList<QOrganizerItem> * organizeritems, QMap<int, QOrganizerItemManager::Error> * errorMap ) |
QList<QVariant::Type> | supportedDataTypes () const |
QStringList | supportedItemTypes () const |
Signals
void | dataChanged () |
void | itemsAdded ( const QList<QOrganizerItemLocalId> & organizeritemIds ) |
void | itemsChanged ( const QList<QOrganizerItemLocalId> & organizeritemIds ) |
void | itemsRemoved ( const QList<QOrganizerItemLocalId> & organizeritemIds ) |
Static Public Members
QStringList | availableManagers () |
QString | buildUri ( const QString & managerName, const QMap<QString, QString> & params, int implementationVersion = -1 ) |
QOrganizerItemManager * | fromUri ( const QString & storeUri, QObject * parent = 0 ) |
bool | parseUri ( const QString & uri, QString * pManagerId, QMap<QString, QString> * pParams ) |
Detailed Description
The QOrganizerItemManager class provides an interface which allows clients with access to organizer item information stored in a particular backend.
This class provides an abstraction of a datastore or aggregation of datastores which contains organizer item information. It provides methods to retrieve and manipulate organizer item information and supported schema definitions. It also provides metadata and error information reporting.
The functions provided by QOrganizerItemManager are purely synchronous; to access the same functionality in an asynchronous manner, clients should use the use-case-specific classes derived from QOrganizerItemAbstractRequest.
Some functionality provided by QOrganizerItemManager directly is not accessible using the asynchronous API; see the synchronous and asynchronous API information from the organizer module API documentation.
Member Type Documentation
enum QOrganizerItemManager::Error
This enum specifies an error that occurred during the most recent operation:
|
Constant | Value | Description |
QOrganizerItemManager::NoError | 0 | The most recent operation was successful |
QOrganizerItemManager::DoesNotExistError | 1 | The most recent operation failed because the requested organizeritem or detail definition does not exist |
QOrganizerItemManager::AlreadyExistsError | 2 | The most recent operation failed because the specified organizeritem or detail definition already exists |
QOrganizerItemManager::InvalidDetailError | 3 | The most recent operation failed because the specified organizeritem contains details which do not conform to their definition |
QOrganizerItemManager::InvalidItemTypeError | 13 | The most recent operation failed because the organizeritem type specified was not valid for the operation |
QOrganizerItemManager::LockedError | 4 | The most recent operation failed because the datastore specified is currently locked |
QOrganizerItemManager::DetailAccessError | 5 | The most recent operation failed because a detail was modified or removed and its access method does not allow that |
QOrganizerItemManager::PermissionsError | 6 | The most recent operation failed because the caller does not have permission to perform the operation |
QOrganizerItemManager::OutOfMemoryError | 7 | The most recent operation failed due to running out of memory |
QOrganizerItemManager::VersionMismatchError | 11 | The most recent operation failed because the backend of the manager is not of the required version |
QOrganizerItemManager::LimitReachedError | 12 | The most recent operation failed because the limit for that type of object has been reached |
QOrganizerItemManager::NotSupportedError | 8 | The most recent operation failed because the requested operation is not supported in the specified store |
QOrganizerItemManager::BadArgumentError | 9 | The most recent operation failed because one or more of the parameters to the operation were invalid |
QOrganizerItemManager::UnspecifiedError | 10 | The most recent operation failed for an undocumented reason |
QOrganizerItemManager::InvalidOccurrenceError | 14 | The most recent operation failed because it was an attempt to save an occurrence without a correct InstanceOrigin detail |
enum QOrganizerItemManager::ManagerFeature
This enum describes the possible features that a particular manager may support
|
Constant | Value | Description |
QOrganizerItemManager::MutableDefinitions | 0 | The manager supports saving, updating or removing detail definitions. Some built-in definitions may still be immutable |
QOrganizerItemManager::ChangeLogs | 2 | The manager supports reporting of timestamps of changes, and filtering and sorting by those timestamps |
QOrganizerItemManager::Anonymous | 1 | The manager is isolated from other managers |
Member Function Documentation
QOrganizerItemManager::QOrganizerItemManager ( const QString & managerName = QString(), const QMap<QString, QString> & parameters = 0, QObject * parent = 0 )
Constructs a QOrganizerItemManager whose implementation is identified by managerName with the given parameters.
The parent QObject will be used as the parent of this QOrganizerItemManager.
If an empty managerName is specified, the default implementation for the platform will be used.
QOrganizerItemManager::QOrganizerItemManager ( const QString & managerName, int implementationVersion, const QMap<QString, QString> & parameters = 0, QObject * parent = 0 )
Constructs a QOrganizerItemManager whose backend has the name managerName and version implementationVersion, where the manager is constructed with the provided parameters.
The parent QObject will be used as the parent of this QOrganizerItemManager.
If an empty managerName is specified, the default implementation for the platform will be instantiated. If the specified implementation version is not available, the manager with the name managerName with the default implementation version is instantiated.
QOrganizerItemManager::QOrganizerItemManager ( QObject * parent )
Constructs a QOrganizerItemManager whose parent QObject is parent. The default implementation for the platform will be created.
QOrganizerItemManager::~QOrganizerItemManager ()
Frees the memory used by the QOrganizerItemManager
QStringList QOrganizerItemManager::availableManagers () [static]
Returns a list of available manager ids that can be used when constructing a QOrganizerItemManager. If an empty id is specified to the constructor, the first value in this list will be used instead.
QString QOrganizerItemManager::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
QOrganizerItem QOrganizerItemManager::compatibleItem ( const QOrganizerItem & original )
Returns a pruned or modified version of the original organizeritem which is valid and can be saved in the manager. The returned organizeritem might have entire details removed or arbitrarily changed. The cache of relationships in the organizeritem are ignored entirely when considering compatibility with the backend, as they are saved and validated separately.
void QOrganizerItemManager::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.
QOrganizerItemDetailDefinition QOrganizerItemManager::detailDefinition ( const QString & definitionName, const QString & organizeritemType = QOrganizerItemType::TypeEvent ) const
Returns the definition identified by the given definitionName that is valid for the organizeritems whose type is the given organizeritemType in this store, or a default-constructed QOrganizerItemDetailDefinition if no such definition exists
QMap<QString, QOrganizerItemDetailDefinition> QOrganizerItemManager::detailDefinitions ( const QString & organizeritemType = QOrganizerItemType::TypeEvent ) const
Returns a map of identifier to detail definition for the registered detail definitions which are valid for organizeritems whose type is the given organizeritemType which are valid for the organizeritems in this store
Return the error code of the most recent operation
QOrganizerItemManager * QOrganizerItemManager::fromUri ( const QString & storeUri, QObject * parent = 0 ) [static]
Constructs a QOrganizerItemManager whose implementation, store and parameters are specified in the given storeUri, and whose parent object is parent.
bool QOrganizerItemManager::hasFeature ( QOrganizerItemManager::ManagerFeature feature, const QString & organizeritemType = QOrganizerItemType::TypeEvent ) const
Returns true if the given feature feature is supported by the manager, for the specified type of organizeritem organizeritemType
bool QOrganizerItemManager::isFilterSupported ( const QOrganizerItemFilter & filter ) const
Returns true if the given filter is supported natively by the manager, and false if the filter behaviour would be emulated.
Note: In some cases, the behaviour of an unsupported filter cannot be emulated. For example, a filter that requests organizeritems that have changed since a given time depends on having that information available. In these cases, the filter will fail.
Returns the organizeritem in the database identified by organizeritemId.
If the organizeritem does not exist, an empty, default constructed QOrganizerItem will be returned, and the error returned by error() will be QOrganizerItemManager::DoesNotExistError.
The fetchHint parameter describes the optimization hints that a manager may take. If the fetchHint is the default constructed hint, all existing details and relationships in the matching organizeritem will be returned. A client should not make changes to a organizeritem which has been retrieved using a fetch hint other than the default fetch hint. Doing so will result in information loss when saving the organizeritem back to the manager (as the "new" restricted organizeritem will replace the previously saved organizeritem in the backend).
See also QOrganizerItemFetchHint.
QList<QOrganizerItemLocalId> QOrganizerItemManager::itemIds ( const QList<QOrganizerItemSortOrder> & sortOrders = QList<QOrganizerItemSortOrder> () ) const
Return the list of organizeritem ids, sorted according to the given list of sortOrders
Returns a list of organizeritem ids that match the given filter, sorted according to the given list of sortOrders. Depending on the backend, this filtering operation may involve retrieving all the organizeritems.
QList<QOrganizerItem> QOrganizerItemManager::itemInstances ( const QOrganizerItemFilter & filter = QOrganizerItemFilter(), const QList<QOrganizerItemSortOrder> & sortOrders = QList<QOrganizerItemSortOrder> (), const QOrganizerItemFetchHint & fetchHint = QOrganizerItemFetchHint() ) const
Return the list of organizer item instances which match the given filter, sorted according to the given sortOrders. The client may instruct the manager that it does not require all possible information about each instance by specifying a fetch hint fetchHint; the manager can choose to ignore the fetch hint, but if it does so, it must return all possible information about each instance.
QList<QOrganizerItem> QOrganizerItemManager::itemInstances ( const QOrganizerItem & generator, const QDateTime & periodStart = QDateTime(), const QDateTime & periodEnd = QDateTime(), int maxCount = -1 ) const
Return the list of a maximum of maxCount organizer item instances which are occurrences of the given generator recurring item, which occur between the given periodStart date and the given periodEnd date.
If periodStart is after periodEnd, the operation will fail. If maxCount is negative, it is backend specific as to how many occurrences will be returned. Some backends may return no instances, others may return some limited number of occurrences.
QList<QOrganizerItem> QOrganizerItemManager::items ( const QList<QOrganizerItemSortOrder> & sortOrders = QList<QOrganizerItemSortOrder> (), const QOrganizerItemFetchHint & fetchHint = QOrganizerItemFetchHint() ) const
Returns the list of organizeritems stored in the manager sorted according to the given list of sortOrders.
The fetchHint parameter describes the optimization hints that a manager may take. If the fetchHint is the default constructed hint, all existing details and relationships in the matching organizeritems will be returned. A client should not make changes to a organizeritem which has been retrieved using a fetch hint other than the default fetch hint. Doing so will result in information loss when saving the organizeritem back to the manager (as the "new" restricted organizeritem will replace the previously saved organizeritem in the backend).
See also QOrganizerItemFetchHint.
QList<QOrganizerItem> QOrganizerItemManager::items ( const QOrganizerItemFilter & filter, const QList<QOrganizerItemSortOrder> & sortOrders = QList<QOrganizerItemSortOrder> (), const QOrganizerItemFetchHint & fetchHint = QOrganizerItemFetchHint() ) const
Returns a list of organizeritems that match the given filter, sorted according to the given list of sortOrders.
Depending on the manager implementation, this filtering operation might be slow and involve retrieving all the organizeritems and testing them against the supplied filter - see the isFilterSupported() function.
The fetchHint parameter describes the optimization hints that a manager may take. If the fetchHint is the default constructed hint, all existing details and relationships in the matching organizeritems will be returned. A client should not make changes to a organizeritem which has been retrieved using a fetch hint other than the default fetch hint. Doing so will result in information loss when saving the organizeritem back to the manager (as the "new" restricted organizeritem will replace the previously saved organizeritem in the backend).
See also QOrganizerItemFetchHint.
void QOrganizerItemManager::itemsAdded ( const QList<QOrganizerItemLocalId> & organizeritemIds ) [signal]
This signal is emitted at some point once the organizeritems identified by organizeritemIds have been added to a datastore managed by this manager. This signal must not be emitted if the dataChanged() signal was previously emitted for these changes.
void QOrganizerItemManager::itemsChanged ( const QList<QOrganizerItemLocalId> & organizeritemIds ) [signal]
This signal is emitted at some point once the organizeritems identified by organizeritemIds have been modified in a datastore managed by this manager. This signal must not be emitted if the dataChanged() signal was previously emitted for these changes.
void QOrganizerItemManager::itemsRemoved ( const QList<QOrganizerItemLocalId> & organizeritemIds ) [signal]
This signal is emitted at some point once the organizeritems identified by organizeritemIds have been removed from a datastore managed by this manager. This signal must not be emitted if the dataChanged() signal was previously emitted for these changes.
QString QOrganizerItemManager::managerName () const
Returns the manager name for this QOrganizerItemManager
QMap<QString, QString> QOrganizerItemManager::managerParameters () const
Return the parameters relevant to the creation of this QOrganizerItemManager
QString QOrganizerItemManager::managerUri () const
Return the uri describing this QOrganizerItemManager, consisting of the manager name and any parameters.
int QOrganizerItemManager::managerVersion () const
Returns the engine backend implementation version number
bool QOrganizerItemManager::parseUri ( const QString & uri, QString * pManagerId, QMap<QString, QString> * pParams ) [static]
Splits the given uri into the manager, store, and parameters that it describes, and places the information into the memory addressed by pManagerId and pParams respectively. Returns true if uri could be split successfully, otherwise returns false
bool QOrganizerItemManager::removeDetailDefinition ( const QString & definitionName, const QString & organizeritemType = QOrganizerItemType::TypeEvent )
Removes the detail definition identified by definitionName from the database, which is valid for organizeritems whose type is the given organizeritemType. Returns true if the definition was removed successfully, otherwise returns false
bool QOrganizerItemManager::removeItem ( const QOrganizerItemLocalId & organizeritemId )
Remove the organizeritem identified by organizeritemId from the database. Returns true if the organizeritem was removed successfully, otherwise returns false.
bool QOrganizerItemManager::removeItems ( const QList<QOrganizerItemLocalId> & organizeritemIds, QMap<int, QOrganizerItemManager::Error> * errorMap )
Remove every organizeritem whose id is contained in the list of organizeritems ids organizeritemIds. Returns true if all organizeritems were removed successfully, otherwise false.
The manager might populate errorMap (the map of indices of the organizeritemIds list to the error which occurred when saving the organizeritem at that index) for every index for which the organizeritem could not be removed, if it is able. The QOrganizerItemManager::error() function will only return QOrganizerItemManager::NoError if all organizeritems were removed successfully.
If the given list of organizeritem ids organizeritemIds is empty, the function will return false and calling error() will return QOrganizerItemManager::BadArgumentError. If the list is non-empty and contains ids which do not identify a valid organizeritem in the manager, the function will remove any organizeritems which are identified by ids in the organizeritemIds list, insert QOrganizerItemManager::DoesNotExist entries into the errorMap for the indices of invalid ids in the organizeritemIds list, return false, and set the overall operation error to QOrganizerItemManager::DoesNotExistError.
See also QOrganizerItemManager::removeItem().
bool QOrganizerItemManager::saveDetailDefinition ( const QOrganizerItemDetailDefinition & def, const QString & organizeritemType = QOrganizerItemType::TypeEvent )
Persists the given definition def in the database, which is valid for organizeritems whose type is the given organizeritemType. Returns true if the definition was saved successfully, otherwise returns false
bool QOrganizerItemManager::saveItem ( QOrganizerItem * organizeritem )
Adds the given organizeritem to the database if organizeritem has a default-constructed id, or an id with the manager URI set to the URI of this manager and a local id of zero.
If the manager URI of the id of the organizeritem is neither empty nor equal to the URI of this manager, or local id of the organizeritem is non-zero but does not exist in the manager, the operation will fail and calling error() will return QOrganizerItemManager::DoesNotExistError.
Alternatively, the function will update the existing organizeritem in the database if organizeritem has a non-zero id and currently exists in the database.
If the organizeritem contains one or more details whose definitions have not yet been saved with the manager, the operation will fail and calling error() will return QOrganizerItemManager::UnsupportedError.
Returns false on failure, or true on success. On successful save of a organizeritem with an id of zero, its id will be set to a new, valid id with the manager URI set to the URI of this manager, and the local id set to a new, valid local id. The manager will automatically synthesize the display label of the organizeritem when it is saved. The manager is not required to fetch updated details of the organizeritem on save, and as such, clients should fetch a organizeritem if they want the most up-to-date information by calling QOrganizerItemManager::item().
See also managerUri().
bool QOrganizerItemManager::saveItems ( QList<QOrganizerItem> * organizeritems, QMap<int, QOrganizerItemManager::Error> * errorMap )
Adds the list of organizeritems given by organizeritems list to the database. Returns true if the organizeritems were saved successfully, otherwise false.
The manager might populate errorMap (the map of indices of the organizeritems list to the error which occurred when saving the organizeritem at that index) for every index for which the organizeritem could not be saved, if it is able. The QOrganizerItemManager::error() function will only return QOrganizerItemManager::NoError if all organizeritems were saved successfully.
For each newly saved organizeritem that was successful, the id of the organizeritem in the organizeritems list will be updated with the new value. If a failure occurs when saving a new organizeritem, the id will be cleared.
See also QOrganizerItemManager::saveItem().
QList<QVariant::Type> QOrganizerItemManager::supportedDataTypes () const
Returns the list of data types supported by the manager
QStringList QOrganizerItemManager::supportedItemTypes () const
Returns the list of organizeritem types which are supported by this manager. This is a convenience function, equivalent to retrieving the allowable values for the QOrganizerItemType::FieldType field of the QOrganizerItemType definition which is valid in this manager.