1.1 --- a/epoc32/include/mmsvattachmentmanager.h Tue Mar 16 16:12:26 2010 +0000
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,300 +0,0 @@
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__