|  | Home |

# QMailContentManager Class Reference

The QMailContentManager class defines the interface to objects that provide a storage facility for message content. More...

        #include <QMailContentManager>

- List of all members, including inherited members

## Public Types

enum | DurabilityRequirement { EnsureDurability, DeferDurability }
enum | ManagerRole { FilterRole, StorageRole, IndexRole }

## Public Functions

virtual QMailStore::ErrorCode | add ( QMailMessage * message, DurabilityRequirement durability ) = 0
virtual void | clearContent ()
virtual QMailStore::ErrorCode | ensureDurability () = 0
virtual bool | init ()
virtual QMailStore::ErrorCode | load ( const QString & identifier, QMailMessage * message ) = 0
virtual QMailStore::ErrorCode | remove ( const QString & identifier ) = 0
virtual QMailStore::ErrorCode | remove ( const QList<QString> & identifiers )
virtual ManagerRole | role () const
virtual QMailStore::ErrorCode | update ( QMailMessage * message, DurabilityRequirement durability ) = 0

## Detailed Description

The QMailContentManager class defines the interface to objects that provide a storage facility for message content.

Qt Extended uses the QMailContentManager interface to delegate the filtering, storage, retrieval and indexing of message content from the QMailStore class to classes loaded from plugin libraries. A library may provide this service by exporting a class implementing the QMailContentManager interface, and an associated instance of QMailContentManagerPlugin.

There are three roles a content manager can take, as defined by ManagerRole. This changes the order in which the plugins are called.

FilterRole: A content manager may be defined as a filtering content manager by returning FilterRole from Role. Filtering content managers are called before message operations take place, and before the message is stored on the file system. Filtering content managers may change any details, and messages will be added to the database with the changes. As messages are not in the database, they will not have an id -- and setting one is invalid. Filtering content managers are not notified when a message is deleted, so they should be careful not to leak file system space. Filtering content managers should only return errors in fatal errors, not to indicate they filtered a message or not.

IndexRole: A content manager may be defined as an indexing content manager by returning IndexRole from Role. Indexing content managers are called after successful operations have taken place, and the fields updated. An indexing content manager should not modify existing messages, but only be used to do something external to QMF (e.g. Add/Remove the message from an external index). Indexing content manager should only return errors in very serious circumstances.

StorageRole: A content manager may be defined as a storage content manager by returning StorageRole from Role (the default). Storage content managers are used for saving and loading messages from the file system. The particular storage content managed used for a message is determined by the contentScheme function of a QMailMessage object. The identifier of the message content is provided by the corresponding contentIdentifier function; this property is provided for the use of the storage content manager code, and is opaque to the remainder of the system.

If a storage content manager provides data to clients by creating references to file-backed memory mappings, then the content manager must ensure that those files remain valid. The existing content within the file must not be modified, and the file must not be truncated. If the content manager updates the content of a message which is already exported using memory mappings, then the updated content should be stored to a new content location, and the message object updated with the new contentIdentifier information.

If a stored message contains parts whose content is only partially available (as defined by QMailMessagePartContainer::partialContentAvailable() and QMailMessagePartContainer::contentAvailable()), the content manager must ensure that the partial data is returned to clients in the same transfer encoding that it was stored with.

See also QMailStore and QMailMessage.

## Member Type Documentation

### enum QMailContentManager::DurabilityRequirement

This enum type is used to define the dequirement for durability in a content management request.

Constant | Value | Description
--- | --- | ---
`QMailContentManager::EnsureDurability` | `0` | The content manager should make the requested changes durable before reporting success.
`QMailContentManager::DeferDurability` | `1` | The content manager may defer ensuring that changes are durable until the next invocation of ensureDurability().

### enum QMailContentManager::ManagerRole

This enum type is used to define the purpose of the plugin

Constant | Value | Description
--- | --- | ---
`QMailContentManager::FilterRole` | `0` | The content manager is a filtering content manager. It is used to modify messages that match its own criteria. Filtering content managers are called before any others.
`QMailContentManager::StorageRole` | `1` | The content manager is a storage content manager. It is used to storage messages persistently. Storage content managers are called after filter content managers, but before index content managers.
`QMailContentManager::IndexRole` | `2` | The content manager is for indexing purposes. It is called after the message has been stored.

## Member Function Documentation

### QMailStore::ErrorCode QMailContentManager::add ( QMailMessage * message, DurabilityRequirement durability ) `[pure virtual]`

Tells the content manager of a new message. If this is a storage content manager it should add to storage and then update the message such that its contentIdentifier property contains the location at which the content is stored.

Returns NoError to indicate success.

If contentIdentifier is already populated at invocation, the content manager should determine whether the supplied identifier can be used. If not, it should use an alternate location and update message with the new identifier.

If durability is EnsureDurability then the content manager should ensure that the message addition has been recorded in a durable fashion before reporting success to the caller.

### void QMailContentManager::clearContent () `[virtual]`

Directs the content manager to clear any message content that it is responsible for.

This function is called by the mail store to remove all existing data, typically in test conditions.

### QMailStore::ErrorCode QMailContentManager::ensureDurability () `[pure virtual]`

Requests that the content manager ensure that any previous actions that were performed with the DeferDurability option be made durable.

### bool QMailContentManager::init () `[virtual]`

Directs the content manager to perform any initialization tasks required. The content manager should return false if unable to perform initialization tasks; otherwise return true.

This function is called by the mail store after it has been successfully initialized.

### QMailStore::ErrorCode QMailContentManager::load ( const QString & identifier, QMailMessage * message ) `[pure virtual]`

Requests that the storage content manager load the message content stored at the location indicated by identifier into the message record message. Returns NoError to indicate that the message content has been successfully loaded.

If the identified content does not already exist, the content manager should return InvalidId.

### QMailStore::ErrorCode QMailContentManager::remove ( const QString & identifier ) `[pure virtual]`

Notifies the content manager that the message identified by identifier has been removed.

The content manager should only remove data it has created with association to identifier. For instance a content manager that does indexing, should only remove the data it has created reaction to the identifier, but not the file itself.

Returns NoError to indicate that the message content has been successfully removed.

If the content cannot be removed, the content manager should return ContentNotRemoved to indicate that removal of the content should be retried at a later time.

If the identified content does not already exist, the content manager should return InvalidId.

### QMailStore::ErrorCode QMailContentManager::remove ( const QList<QString> & identifiers ) `[virtual]`

Notifies the content manager that the messages identified by identifiers have been removed.

The content manager should only remove data it has created with association to identifier. For instance a content manager that does indexing, should only remove the data it has created reaction to the identifier, but not the file itself.

Returns NoError to indicate that the message content has been successfully removed.

If the content cannot be removed, the content manager should return ContentNotRemoved to indicate that removal of the content should be retried at a later time.

If the identified content does not already exist, the content manager should return InvalidId.

### ManagerRole QMailContentManager::role () const `[virtual]`

This function is called by the mail store to query the purpose of this particular plugin.

### QMailStore::ErrorCode QMailContentManager::update ( QMailMessage * message, DurabilityRequirement durability ) `[pure virtual]`

Notifies the content manager that message has been updated. If this is a storage content manager it should update the message content stored at the location indicated by contentIdentifier, to contain the current content of message. Returns NoError to indicate successful update of the message content.

If the updated content is not stored to the existing location, the content manager should use an alternate location and update message with the new contentIdentifier.

The existing content should be removed if the update causes a new content identifier to be allocated. If the previous content cannot be removed, but the update was otherwise successful, the content manager should return ContentNotRemoved to indicate that removal of the content should be retried at a later time.

If durability is EnsureDurability then the content manager should ensure that the message update has been recorded in a durable fashion before reporting success to the caller.