#include <MMsvAttachmentManager.h>
Class MMsvAttachmentManager
class MMsvAttachmentManager;
Description
Defines the attachment management interface.
This class is a pure virtual interface class that defines the APIs to be used for attachment management in the Messaging Framework.
It is expected that the clients of this interface will be MTMs implementations that require attachment management.
The API allows is based around the use of the CMsvAttachment
object that represents any type of attachment that is supported by the Messaging Framework. The CMsvAttachment
object provides users with various attributes about the attachment without having to actually load or retrieve the attachment.
This attachment manager API supports the following different types of attachments: 1 - File attachments, file based attachments
that are copied or created in the message store. 2 - Linked file attachments, file based attachments that are not copied and
are simply linked to the file location on disk. 3 - Message entry attachments, existing message entries that can be registered
as attachments of another message entry.
For file based attachments, this API also supports the retrieval of the files as open read-only file handles.
All functionality that requires the attachment manager to be in edit mode have been defined as asynchronous. The attachment
manager does not allow multiple asynchronous requests to be made at the same time.
Members
Defined in MMsvAttachmentManager
:
AddAttachmentL(RFile &,CMsvAttachment *,TRequestStatus &)
Adds an attachment to the message store by file handle.
AddAttachmentL(const TDesC &,CMsvAttachment *,TRequestStatus &)
Adds an attachment to the message store by file path.
AddEntryAsAttachmentL(TMsvId,CMsvAttachment *,TRequestStatus &)
Adds a message entry as an attachment.
AddLinkedAttachmentL(const TDesC &,CMsvAttachment *,TRequestStatus &)
Adds an attachment as a linked file attachment.
AttachmentCount()const
Counts the number of attachments.
CancelRequest()
Cancels the last asynchronous operation that was requested.
CreateAttachmentL(const TDesC &,RFile &,CMsvAttachment *,TRequestStatus &)
Creates a new empty attachment file.
GetAttachmentFileL(TInt)
Returns an open file handle for the attachment file.
GetAttachmentFileL(TMsvAttachmentId)
Returns an open file handle for the attachment file.
GetAttachmentInfoL(TInt)
Returns an attachment info object.
GetAttachmentInfoL(TMsvAttachmentId)
Returns an attachment info object.
ModifyAttachmentInfoL(CMsvAttachment *,TRequestStatus &)
Modifies the attachment info for a particular attachment.
RemoveAttachmentL(TInt,TRequestStatus &)
Removes the attachment from the message entry.
RemoveAttachmentL(TMsvAttachmentId,TRequestStatus &)
Removes the attachment from the message entry.
RenameAttachmentL(TInt,const TDesC &,TRequestStatus &)
Renames the physical filename of an attachment.
See also:
CMsvAttachment
Represents a single attachment and information about the attachment.
Member functions
AddAttachmentL(const TDesC &,CMsvAttachment *,TRequestStatus &)
virtual void AddAttachmentL(const TDesC &aFilePath, CMsvAttachment *aAttachmentInfo, TRequestStatus &aStatus)=0;
Description
Adds an attachment to the message store by file path.
The attachment file must be located in a public area. The file path must also be a full path specification. The file is copied
into the message store.
Parameters
const TDesC16 &aFilePath |
The absolute file path of the attachment file.
|
CMsvAttachment *aAttachmentInfo |
The attachment info associated with the file. If the routine does not leave, then ownership will be transferred to the attachment
manager. If the routine does leave then ownership will not have been transfered and the caller is responsible for cleanup.
|
TRequestStatus &aStatus |
The client's request status to complete when the operation has completed.
|
|
Leave codes
KErrAccessDenied |
If attachment manager is in read-only mode.
|
|
AddAttachmentL(RFile &,CMsvAttachment *,TRequestStatus &)
virtual void AddAttachmentL(RFile &aFileHandle, CMsvAttachment *aAttachmentInfo, TRequestStatus &aStatus)=0;
Description
Adds an attachment to the message store by file handle.
This is used to add an attachment from an open file handle such as when adding a file from the caller's private area. The
file is copied into the message store. The message server is responsible for closing the file handle once copied.
Parameters
RFile &aFileHandle |
An open file handle for the attachment file. Ownership is transferred. The caller must close the file handle.
|
CMsvAttachment *aAttachmentInfo |
The attachment info associated with the file. If the routine does not leave, then ownership will be transferred to the attachment
manager. If the routine does leave then ownership will not have been transfered and the caller is responsible for cleanup.
|
TRequestStatus &aStatus |
The client's request status to complete.
|
|
Leave codes
KErrAccessDenied |
If attachment manager is in read-only mode.
|
|
AddLinkedAttachmentL(const TDesC &,CMsvAttachment *,TRequestStatus &)
virtual void AddLinkedAttachmentL(const TDesC &aFilePath, CMsvAttachment *aAttachmentInfo, TRequestStatus &aStatus)=0;
Description
Adds an attachment as a linked file attachment.
The attachment is added as a link by its file path. The attachment is not copied to the message store. The attachment is linked
and therefore must be in a public location.
It is possible to change a linked attachment file after it has been attached to a message entry. No integrity checking is
carried out. This is left to individual MTMs or implementors of this interface to decide if any checking is required such
as checking if the size has changed.
Parameters
const TDesC16 &aFilePath |
The absolute file path of the linked attachment file.
|
CMsvAttachment *aAttachmentInfo |
The attachment info associated with the file. If the routine does not leave, then ownership will be transferred to the attachment
manager. If the routine does leave then ownership will not have been transfered and the caller is responsible for cleanup.
|
TRequestStatus &aStatus |
The client's request status to complete.
|
|
Leave codes
KErrAccessDenied |
If attachment manager is in read-only mode.
|
|
AddEntryAsAttachmentL(TMsvId,CMsvAttachment *,TRequestStatus &)
virtual void AddEntryAsAttachmentL(TMsvId aEntryId, CMsvAttachment *aAttachmentInfo, TRequestStatus &aStatus)=0;
Description
Adds a message entry as an attachment.
The message entry is registered as an attachment of the current message entry. The attachment message entry is not copied.
Parameters
TMsvId aEntryId |
The message Id of the entry to register as an attachment.
|
CMsvAttachment *aAttachmentInfo |
The attachment info associated with the file. If the routine does not leave, then ownership will be transferred to the attachment
manager. If the routine does leave then ownership will not have been transfered and the caller is responsible for cleanup.
|
TRequestStatus &aStatus |
The client's request status to complete.
|
|
Leave codes
KErrAccessDenied |
If attachment manager is in read-only mode.
|
|
CreateAttachmentL(const TDesC &,RFile &,CMsvAttachment *,TRequestStatus &)
virtual void CreateAttachmentL(const TDesC &aFileName, RFile &aAttachmentFile, CMsvAttachment *aAttachmentInfo, TRequestStatus
&aStatus)=0;
Description
Creates a new empty attachment file.
The caller is returned an open writable file handle to an empty attachment file in the message store. The caller must pass
in an uninitialised file handle. The file handle cannot be used until the asynchronous request completes successfully. If
the request is sucessful the file handle is open and must close by the caller once the data has been written to it.
Parameters
const TDesC16 &aFileName |
The filename to assign to the newly create attachment file.
|
RFile &aAttachmentFile |
An uninitialised file handle. This is opened and can be written to if the request is successful. Ownership is transferred
. The caller must close the file handle.
|
CMsvAttachment *aAttachmentInfo |
The attachment info associated with the file. If the routine does not leave, then ownership will be transferred to the attachment
manager. If the routine does leave then ownership will not have been transfered and the caller is responsible for cleanup.
|
TRequestStatus &aStatus |
|
|
Leave codes
KErrAccessDenied |
If attachment manager is in read-only mode.
|
|
RenameAttachmentL(TInt,const TDesC &,TRequestStatus &)
virtual void RenameAttachmentL(TInt aIndex, const TDesC &aNewName, TRequestStatus &aStatus)=0;
Description
Renames the physical filename of an attachment.
Parameters
TInt aIndex |
The array index position of the attachment to be renamed.
|
const TDesC16 &aNewName |
The new name of the attachment.
|
TRequestStatus &aStatus |
The client's request status to complete.
|
|
Leave codes
KErrAccessDenied |
If attachment manager is in read-only mode.
|
KErrAlreadyExists |
If the supplied attachment filename already exists.
|
|
virtual TInt AttachmentCount() const=0;
Description
Counts the number of attachments.
Returns the number of attachments associated with the message entry. This includes all the attachments that have not been
commited yet.
Return value
TInt
|
The number of attachments.
|
|
virtual CMsvAttachment* GetAttachmentInfoL(TInt aIndex)=0;
Description
Returns an attachment info object.
This object contains attributes and information about the attachment without having actually retrieving the actual attachment.
The caller assumes ownership of the returned object.
Parameters
TInt aIndex |
The array index position of the attachment.
|
|
Return value
CMsvAttachment *
|
The attachment info for the attachment. Ownership is passed to caller,
|
|
GetAttachmentInfoL(TMsvAttachmentId)
virtual CMsvAttachment* GetAttachmentInfoL(TMsvAttachmentId aId)=0;
Description
Returns an attachment info object.
This object contains attributes and information about the attachment without having actually retrieving the actual attachment.
The caller assumes ownership of the returned object.
Parameters
Return value
CMsvAttachment *
|
The attachment info for the attachment. Ownership is passed to caller,
|
|
Leave codes
KErrNotFound |
If an attachment with the specified attachment Id is not found.
|
|
ModifyAttachmentInfoL(CMsvAttachment *,TRequestStatus &)
virtual void ModifyAttachmentInfoL(CMsvAttachment *aAttachmentInfo, TRequestStatus &aStatus)=0;
Description
Modifies the attachment info for a particular attachment.
This allows callers to modify an existing attachment info object for a particular attachment. The attachment info object passed
in replaces the existing attachment info object and takes ownership for the object passed in. It is expected that callers
will use GetAttachmentInfoL to get the object, make some changes and pass it back into this method.
Parameters
CMsvAttachment *aAttachmentInfo |
The attachment info associated with the file. If the routine does not leave, then ownership will be transferred to the attachment
manager. If the routine does leave then ownership will not have been transfered and the caller is responsible for cleanup.
|
TRequestStatus &aStatus |
The client's request status to complete.
|
|
Leave codes
KErrNotFound |
If the attachment that is trying to be modified cannot be found.
|
KErrAccessDenied |
If attachment manager is in read-only mode.
|
|
virtual RFile GetAttachmentFileL(TInt aIndex)=0;
Description
Returns an open file handle for the attachment file.
Returns a read-only open file handle for the attachment file. This only applies to file based attachments ie. file attachment
and linked file attachments. The caller is responsible for closing the returned file handle.
Parameters
TInt aIndex |
The array index position of the attachment.
|
|
Return value
RFile
|
A read-only open file handle for the attachment file. Caller must close the handle.
|
|
Leave codes
KErrNotSupported |
If the attachment is not a file attachment in the message store.
|
|
GetAttachmentFileL(TMsvAttachmentId)
virtual RFile GetAttachmentFileL(TMsvAttachmentId aId)=0;
Description
Returns an open file handle for the attachment file.
Returns a read-only open file handle for the attachment file. This only applies to file based attachments ie. file attachment
and linked file attachments. The caller is responsible for closing the returned file handle.
Parameters
Return value
RFile
|
A read-only open file handle for the attachment file. Caller must close the handle.
|
|
Leave codes
KErrNotSupported |
If the attachment is not a file attachment in the message store.
|
KErrNotFound |
If an attachment with the specified attachment Id is not found.
|
|
RemoveAttachmentL(TInt,TRequestStatus &)
virtual void RemoveAttachmentL(TInt aIndex, TRequestStatus &aStatus)=0;
Description
Removes the attachment from the message entry.
This changes the array index values of all the attachments after the removed one. Attachment files stored in the message store
are deleted. Linked files and message entry attachments are not deleted, this is left to the caller to do if required.
Parameters
Leave codes
KErrAccessDenied |
If attachment manager is in read-only mode.
|
|
RemoveAttachmentL(TMsvAttachmentId,TRequestStatus &)
virtual void RemoveAttachmentL(TMsvAttachmentId aId, TRequestStatus &aStatus)=0;
Description
Removes the attachment from the message entry.
This changes the array index values of all the attachments after the removed one. Attachment files stored in the message store
are deleted. Linked files and message entry attachments are not deleted, this is left to the caller to do if required.
Parameters
Leave codes
KErrAccessDenied |
If attachment manager is in read-only mode.
|
KErrNotFound |
If an attachment with the specified attachment Id is not found.
|
|
virtual void CancelRequest()=0;
Description
Cancels the last asynchronous operation that was requested.
Allows callers to cancel the last asynchronous operation. This will have no effect if an asynchronous is not waiting to complete.