1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/mw/mmsvattachmentmanager.h Wed Mar 31 12:27:01 2010 +0100
1.3 @@ -0,0 +1,300 @@
1.4 +// Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// 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
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +//
1.18 +
1.19 +#ifndef __MMSVATTACHMENTMANAGER_H__
1.20 +#define __MMSVATTACHMENTMANAGER_H__
1.21 +
1.22 +#include <e32base.h>
1.23 +#include <msvstd.h>
1.24 +#include <cmsvattachment.h>
1.25 +
1.26 +class MMsvAttachmentManager
1.27 +/**
1.28 +Defines the attachment management interface.
1.29 +
1.30 +This class is a pure virtual interface class that defines the APIs to be used for
1.31 +attachment management in the Messaging Framework. It is expected that the clients of
1.32 +this interface will be MTMs implementations that require attachment management.
1.33 +
1.34 +The API allows is based around the use of the CMsvAttachment object that represents
1.35 +any type of attachment that is supported by the Messaging Framework. The CMsvAttachment
1.36 +object provides users with various attributes about the attachment without having to
1.37 +actually load or retrieve the attachment.
1.38 +
1.39 +This attachment manager API supports the following different types of attachments:
1.40 +1 - File attachments, file based attachments that are copied or created in the message
1.41 + store.
1.42 +2 - Linked file attachments, file based attachments that are not copied and are simply
1.43 + linked to the file location on disk.
1.44 +3 - Message entry attachments, existing message entries that can be registered as
1.45 + attachments of another message entry.
1.46 +
1.47 +For file based attachments, this API also supports the retrieval of the files as
1.48 +open read-only file handles.
1.49 +
1.50 +All functionality that requires the attachment manager to be in edit mode have been
1.51 +defined as asynchronous. The attachment manager does not allow multiple asynchronous
1.52 +requests to be made at the same time.
1.53 +
1.54 +@see CMsvAttachment
1.55 +@publishedAll
1.56 +@released
1.57 +*/
1.58 + {
1.59 +public:
1.60 + /**
1.61 + Adds an attachment to the message store by file path.
1.62 +
1.63 + The attachment file must be located in a public area. The file path must also be a
1.64 + full path specification. The file is copied into the message store.
1.65 +
1.66 + @param aFilePath The absolute file path of the attachment file.
1.67 + @param aAttachmentInfo The attachment info associated with the file.
1.68 + If the routine does not leave, then ownership will be transferred to the
1.69 + attachment manager. If the routine does leave then ownership will not have
1.70 + been transfered and the caller is responsible for cleanup.
1.71 + @param aStatus The client's request status to complete when the operation has completed.
1.72 + @leave KErrAccessDenied If attachment manager is in read-only mode.
1.73 + */
1.74 + virtual void AddAttachmentL(const TDesC& aFilePath, CMsvAttachment* aAttachmentInfo, TRequestStatus& aStatus) = 0;
1.75 +
1.76 + /**
1.77 + Adds an attachment to the message store by file handle.
1.78 +
1.79 + This is used to add an attachment from an open file handle such as when adding a file
1.80 + from the caller's private area. The file is copied into the message store. The message
1.81 + server is responsible for closing the file handle once copied.
1.82 +
1.83 + @param aFileHandle An open file handle for the attachment file. Ownership is transferred. The caller must close the file handle.
1.84 + @param aAttachmentInfo The attachment info associated with the file.
1.85 + If the routine does not leave, then ownership will be transferred to the
1.86 + attachment manager. If the routine does leave then ownership will not have
1.87 + been transfered and the caller is responsible for cleanup.
1.88 + @param aStatus The client's request status to complete.
1.89 + @leave KErrAccessDenied If attachment manager is in read-only mode.
1.90 + */
1.91 + virtual void AddAttachmentL(RFile& aFileHandle, CMsvAttachment* aAttachmentInfo, TRequestStatus& aStatus) = 0;
1.92 +
1.93 + /**
1.94 + Adds an attachment as a linked file attachment.
1.95 +
1.96 + The attachment is added as a link by its file path. The attachment is not copied to the
1.97 + message store. The attachment is linked and therefore must be in a public location.
1.98 +
1.99 + It is possible to change a linked attachment file after it has been attached to a message
1.100 + entry. No integrity checking is carried out. This is left to individual MTMs or implementors
1.101 + of this interface to decide if any checking is required such as checking if the size has changed.
1.102 +
1.103 + @param aFilePath The absolute file path of the linked attachment file.
1.104 + @param aAttachmentInfo The attachment info associated with the file.
1.105 + If the routine does not leave, then ownership will be transferred to the
1.106 + attachment manager. If the routine does leave then ownership will not have
1.107 + been transfered and the caller is responsible for cleanup.
1.108 + @param aStatus The client's request status to complete.
1.109 + @leave KErrAccessDenied If attachment manager is in read-only mode.
1.110 + */
1.111 + virtual void AddLinkedAttachmentL(const TDesC& aFilePath, CMsvAttachment* aAttachmentInfo, TRequestStatus& aStatus) = 0;
1.112 +
1.113 + /**
1.114 + Adds a message entry as an attachment.
1.115 +
1.116 + The message entry is registered as an attachment of the current message entry. The attachment
1.117 + message entry is not copied.
1.118 +
1.119 + @param aEntryId The message Id of the entry to register as an attachment.
1.120 + @param aAttachmentInfo The attachment info associated with the file.
1.121 + If the routine does not leave, then ownership will be transferred to the
1.122 + attachment manager. If the routine does leave then ownership will not have
1.123 + been transfered and the caller is responsible for cleanup.
1.124 + @param aStatus The client's request status to complete.
1.125 + @leave KErrAccessDenied If attachment manager is in read-only mode.
1.126 + */
1.127 + virtual void AddEntryAsAttachmentL(TMsvId aEntryId, CMsvAttachment* aAttachmentInfo, TRequestStatus& aStatus) = 0;
1.128 +
1.129 + /**
1.130 + Creates a new empty attachment file.
1.131 +
1.132 + The caller is returned an open writable file handle to an empty attachment file in the message
1.133 + store. The caller must pass in an uninitialised file handle. The file handle cannot be used
1.134 + until the asynchronous request completes successfully. If the request is sucessful the file handle
1.135 + is open and must close by the caller once the data has been written to it.
1.136 +
1.137 + @param aFileName The filename to assign to the newly create attachment file.
1.138 + @param aAttachmentFile An uninitialised file handle. This is opened and can be written to if the
1.139 + request is successful. Ownership is transferred . The caller must close the file handle.
1.140 + @param aAttachmentInfo The attachment info associated with the file.
1.141 + If the routine does not leave, then ownership will be transferred to the
1.142 + attachment manager. If the routine does leave then ownership will not have
1.143 + been transfered and the caller is responsible for cleanup.
1.144 + @leave KErrAccessDenied If attachment manager is in read-only mode.
1.145 + */
1.146 + virtual void CreateAttachmentL(const TDesC& aFileName, RFile& aAttachmentFile, CMsvAttachment* aAttachmentInfo, TRequestStatus& aStatus) = 0;
1.147 +
1.148 +
1.149 + /**
1.150 + Renames the physical filename of an attachment.
1.151 +
1.152 + @param aIndex The array index position of the attachment to be renamed.
1.153 + @param aNewName The new name of the attachment.
1.154 + @param aStatus The client's request status to complete.
1.155 + @leave KErrAccessDenied If attachment manager is in read-only mode.
1.156 + @leave KErrAlreadyExists If the supplied attachment filename already exists.
1.157 + */
1.158 + virtual void RenameAttachmentL(TInt aIndex, const TDesC& aNewName, TRequestStatus& aStatus) = 0;
1.159 +
1.160 +
1.161 + /**
1.162 + Counts the number of attachments.
1.163 +
1.164 + Returns the number of attachments associated with the message entry. This includes all the
1.165 + attachments that have not been commited yet.
1.166 + @return The number of attachments.
1.167 + */
1.168 + virtual TInt AttachmentCount() const = 0;
1.169 +
1.170 + /**
1.171 + Returns an attachment info object.
1.172 +
1.173 + This object contains attributes and information about the attachment without having actually
1.174 + retrieving the actual attachment. The caller assumes ownership of the returned object.
1.175 +
1.176 + @param aIndex The array index position of the attachment.
1.177 + @return The attachment info for the attachment. Ownership is passed to caller,
1.178 + */
1.179 + virtual CMsvAttachment* GetAttachmentInfoL(TInt aIndex) = 0;
1.180 +
1.181 + /**
1.182 + Returns an attachment info object.
1.183 +
1.184 + This object contains attributes and information about the attachment without having actually
1.185 + retrieving the actual attachment. The caller assumes ownership of the returned object.
1.186 +
1.187 + @param aId The attachment Id of the attachment.
1.188 + @return The attachment info for the attachment. Ownership is passed to caller,
1.189 + @leave KErrNotFound If an attachment with the specified attachment Id is not found.
1.190 + */
1.191 + virtual CMsvAttachment* GetAttachmentInfoL(TMsvAttachmentId aId) = 0;
1.192 +
1.193 + /**
1.194 + Modifies the attachment info for a particular attachment.
1.195 +
1.196 + This allows callers to modify an existing attachment info object for a particular attachment.
1.197 + The attachment info object passed in replaces the existing attachment info object and takes
1.198 + ownership for the object passed in. It is expected that callers will use GetAttachmentInfoL
1.199 + to get the object, make some changes and pass it back into this method.
1.200 +
1.201 + @param aAttachmentInfo The attachment info associated with the file.
1.202 + If the routine does not leave, then ownership will be transferred to the
1.203 + attachment manager. If the routine does leave then ownership will not have
1.204 + been transfered and the caller is responsible for cleanup.
1.205 + @param aStatus The client's request status to complete.
1.206 + @leave KErrNotFound If the attachment that is trying to be modified cannot be found.
1.207 + @leave KErrAccessDenied If attachment manager is in read-only mode.
1.208 + */
1.209 + virtual void ModifyAttachmentInfoL(CMsvAttachment* aAttachmentInfo, TRequestStatus& aStatus) = 0;
1.210 +
1.211 + /**
1.212 + Returns an open file handle for the attachment file.
1.213 +
1.214 + Returns a read-only open file handle for the attachment file. This only applies to file based
1.215 + attachments ie. file attachment and linked file attachments. The caller is responsible for
1.216 + closing the returned file handle.
1.217 +
1.218 + @param aIndex The array index position of the attachment.
1.219 + @return A read-only open file handle for the attachment file. Caller must close the handle.
1.220 + @leave KErrNotSupported If the attachment is not a file attachment in the message store.
1.221 + */
1.222 + virtual RFile GetAttachmentFileL(TInt aIndex) = 0;
1.223 +
1.224 + /**
1.225 + Returns an open file handle for the attachment file.
1.226 +
1.227 + Returns a read-only open file handle for the attachment file. This only applies to file based
1.228 + attachments ie. file attachment and linked file attachments. The caller is responsible for
1.229 + closing the returned file handle.
1.230 +
1.231 + @param aIndex The array index position of the attachment.
1.232 + @return A read-only open file handle for the attachment file. Caller must close the handle.
1.233 + @leave KErrNotSupported If the attachment is not a file attachment in the message store.
1.234 + @leave KErrNotFound If an attachment with the specified attachment Id is not found.
1.235 + */
1.236 + virtual RFile GetAttachmentFileL(TMsvAttachmentId aId) = 0;
1.237 +
1.238 + /**
1.239 + Returns an open writable file handle for the attachment file.
1.240 +
1.241 + Returns a writable open file handle for the attachment file. This only applies to file based
1.242 + attachments ie. file attachment and linked file attachments. The caller is responsible for
1.243 + closing the returned file handle.
1.244 +
1.245 + @param aIndex The array index position of the attachment.
1.246 + @return A writable open file handle for the attachment file. Caller must close the handle.
1.247 + @leave KErrNotSupported If the attachment is not a file attachment in the message store.
1.248 + @leave KErrAccessDenied If attachment manager is in read-only mode.
1.249 + @internalComponent
1.250 + */
1.251 + virtual RFile GetAttachmentFileForWriteL(TInt aIndex) = 0;
1.252 +
1.253 + /**
1.254 + Returns an open writable file handle for the attachment file.
1.255 +
1.256 + Returns a writable open file handle for the attachment file. This only applies to file based
1.257 + attachments ie. file attachment and linked file attachments. The caller is responsible for
1.258 + closing the returned file handle.
1.259 +
1.260 + @param aIndex The array index position of the attachment.
1.261 + @return A writable open file handle for the attachment file. Caller must close the handle.
1.262 + @leave KErrNotSupported If the attachment is not a file attachment in the message store.
1.263 + @leave KErrNotFound If an attachment with the specified attachment Id is not found.
1.264 + @leave KErrAccessDenied If attachment manager is in read-only mode.
1.265 + @internalComponent
1.266 + */
1.267 + virtual RFile GetAttachmentFileForWriteL(TMsvAttachmentId aId) = 0;
1.268 +
1.269 + /**
1.270 + Removes the attachment from the message entry.
1.271 +
1.272 + This changes the array index values of all the attachments after the removed one.
1.273 + Attachment files stored in the message store are deleted. Linked files and message entry
1.274 + attachments are not deleted, this is left to the caller to do if required.
1.275 +
1.276 + @param aParam The array index position of the attachment to be removed.
1.277 + @leave KErrAccessDenied If attachment manager is in read-only mode.
1.278 + */
1.279 + virtual void RemoveAttachmentL(TInt aIndex, TRequestStatus& aStatus) = 0;
1.280 +
1.281 + /**
1.282 + Removes the attachment from the message entry.
1.283 +
1.284 + This changes the array index values of all the attachments after the removed one.
1.285 + Attachment files stored in the message store are deleted. Linked files and message entry
1.286 + attachments are not deleted, this is left to the caller to do if required.
1.287 +
1.288 + @param aParam The array index position of the attachment to be removed.
1.289 + @leave KErrAccessDenied If attachment manager is in read-only mode.
1.290 + @leave KErrNotFound If an attachment with the specified attachment Id is not found.
1.291 + */
1.292 + virtual void RemoveAttachmentL(TMsvAttachmentId aId, TRequestStatus& aStatus) = 0;
1.293 +
1.294 + /**
1.295 + Cancels the last asynchronous operation that was requested.
1.296 +
1.297 + Allows callers to cancel the last asynchronous operation. This will have no effect
1.298 + if an asynchronous is not waiting to complete.
1.299 + */
1.300 + virtual void CancelRequest() = 0;
1.301 + };
1.302 +
1.303 +#endif // __MMSVATTACHMENTMANAGER_H__