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