1 // Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies).
2 // All rights reserved.
3 // This component and the accompanying materials are made available
4 // 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
5 // which accompanies this distribution, and is available
6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
16 #ifndef __MMSVATTACHMENTMANAGER_H__
17 #define __MMSVATTACHMENTMANAGER_H__
21 #include <cmsvattachment.h>
23 class MMsvAttachmentManager
25 Defines the attachment management interface.
27 This class is a pure virtual interface class that defines the APIs to be used for
28 attachment management in the Messaging Framework. It is expected that the clients of
29 this interface will be MTMs implementations that require attachment management.
31 The API allows is based around the use of the CMsvAttachment object that represents
32 any type of attachment that is supported by the Messaging Framework. The CMsvAttachment
33 object provides users with various attributes about the attachment without having to
34 actually load or retrieve the attachment.
36 This attachment manager API supports the following different types of attachments:
37 1 - File attachments, file based attachments that are copied or created in the message
39 2 - Linked file attachments, file based attachments that are not copied and are simply
40 linked to the file location on disk.
41 3 - Message entry attachments, existing message entries that can be registered as
42 attachments of another message entry.
44 For file based attachments, this API also supports the retrieval of the files as
45 open read-only file handles.
47 All functionality that requires the attachment manager to be in edit mode have been
48 defined as asynchronous. The attachment manager does not allow multiple asynchronous
49 requests to be made at the same time.
58 Adds an attachment to the message store by file path.
60 The attachment file must be located in a public area. The file path must also be a
61 full path specification. The file is copied into the message store.
63 @param aFilePath The absolute file path of the attachment file.
64 @param aAttachmentInfo The attachment info associated with the file.
65 If the routine does not leave, then ownership will be transferred to the
66 attachment manager. If the routine does leave then ownership will not have
67 been transfered and the caller is responsible for cleanup.
68 @param aStatus The client's request status to complete when the operation has completed.
69 @leave KErrAccessDenied If attachment manager is in read-only mode.
71 virtual void AddAttachmentL(const TDesC& aFilePath, CMsvAttachment* aAttachmentInfo, TRequestStatus& aStatus) = 0;
74 Adds an attachment to the message store by file handle.
76 This is used to add an attachment from an open file handle such as when adding a file
77 from the caller's private area. The file is copied into the message store. The message
78 server is responsible for closing the file handle once copied.
80 @param aFileHandle An open file handle for the attachment file. Ownership is transferred. The caller must close the file handle.
81 @param aAttachmentInfo The attachment info associated with the file.
82 If the routine does not leave, then ownership will be transferred to the
83 attachment manager. If the routine does leave then ownership will not have
84 been transfered and the caller is responsible for cleanup.
85 @param aStatus The client's request status to complete.
86 @leave KErrAccessDenied If attachment manager is in read-only mode.
88 virtual void AddAttachmentL(RFile& aFileHandle, CMsvAttachment* aAttachmentInfo, TRequestStatus& aStatus) = 0;
91 Adds an attachment as a linked file attachment.
93 The attachment is added as a link by its file path. The attachment is not copied to the
94 message store. The attachment is linked and therefore must be in a public location.
96 It is possible to change a linked attachment file after it has been attached to a message
97 entry. No integrity checking is carried out. This is left to individual MTMs or implementors
98 of this interface to decide if any checking is required such as checking if the size has changed.
100 @param aFilePath The absolute file path of the linked attachment file.
101 @param aAttachmentInfo The attachment info associated with the file.
102 If the routine does not leave, then ownership will be transferred to the
103 attachment manager. If the routine does leave then ownership will not have
104 been transfered and the caller is responsible for cleanup.
105 @param aStatus The client's request status to complete.
106 @leave KErrAccessDenied If attachment manager is in read-only mode.
108 virtual void AddLinkedAttachmentL(const TDesC& aFilePath, CMsvAttachment* aAttachmentInfo, TRequestStatus& aStatus) = 0;
111 Adds a message entry as an attachment.
113 The message entry is registered as an attachment of the current message entry. The attachment
114 message entry is not copied.
116 @param aEntryId The message Id of the entry to register as an attachment.
117 @param aAttachmentInfo The attachment info associated with the file.
118 If the routine does not leave, then ownership will be transferred to the
119 attachment manager. If the routine does leave then ownership will not have
120 been transfered and the caller is responsible for cleanup.
121 @param aStatus The client's request status to complete.
122 @leave KErrAccessDenied If attachment manager is in read-only mode.
124 virtual void AddEntryAsAttachmentL(TMsvId aEntryId, CMsvAttachment* aAttachmentInfo, TRequestStatus& aStatus) = 0;
127 Creates a new empty attachment file.
129 The caller is returned an open writable file handle to an empty attachment file in the message
130 store. The caller must pass in an uninitialised file handle. The file handle cannot be used
131 until the asynchronous request completes successfully. If the request is sucessful the file handle
132 is open and must close by the caller once the data has been written to it.
134 @param aFileName The filename to assign to the newly create attachment file.
135 @param aAttachmentFile An uninitialised file handle. This is opened and can be written to if the
136 request is successful. Ownership is transferred . The caller must close the file handle.
137 @param aAttachmentInfo The attachment info associated with the file.
138 If the routine does not leave, then ownership will be transferred to the
139 attachment manager. If the routine does leave then ownership will not have
140 been transfered and the caller is responsible for cleanup.
141 @leave KErrAccessDenied If attachment manager is in read-only mode.
143 virtual void CreateAttachmentL(const TDesC& aFileName, RFile& aAttachmentFile, CMsvAttachment* aAttachmentInfo, TRequestStatus& aStatus) = 0;
147 Renames the physical filename of an attachment.
149 @param aIndex The array index position of the attachment to be renamed.
150 @param aNewName The new name of the attachment.
151 @param aStatus The client's request status to complete.
152 @leave KErrAccessDenied If attachment manager is in read-only mode.
153 @leave KErrAlreadyExists If the supplied attachment filename already exists.
155 virtual void RenameAttachmentL(TInt aIndex, const TDesC& aNewName, TRequestStatus& aStatus) = 0;
159 Counts the number of attachments.
161 Returns the number of attachments associated with the message entry. This includes all the
162 attachments that have not been commited yet.
163 @return The number of attachments.
165 virtual TInt AttachmentCount() const = 0;
168 Returns an attachment info object.
170 This object contains attributes and information about the attachment without having actually
171 retrieving the actual attachment. The caller assumes ownership of the returned object.
173 @param aIndex The array index position of the attachment.
174 @return The attachment info for the attachment. Ownership is passed to caller,
176 virtual CMsvAttachment* GetAttachmentInfoL(TInt aIndex) = 0;
179 Returns an attachment info object.
181 This object contains attributes and information about the attachment without having actually
182 retrieving the actual attachment. The caller assumes ownership of the returned object.
184 @param aId The attachment Id of the attachment.
185 @return The attachment info for the attachment. Ownership is passed to caller,
186 @leave KErrNotFound If an attachment with the specified attachment Id is not found.
188 virtual CMsvAttachment* GetAttachmentInfoL(TMsvAttachmentId aId) = 0;
191 Modifies the attachment info for a particular attachment.
193 This allows callers to modify an existing attachment info object for a particular attachment.
194 The attachment info object passed in replaces the existing attachment info object and takes
195 ownership for the object passed in. It is expected that callers will use GetAttachmentInfoL
196 to get the object, make some changes and pass it back into this method.
198 @param aAttachmentInfo The attachment info associated with the file.
199 If the routine does not leave, then ownership will be transferred to the
200 attachment manager. If the routine does leave then ownership will not have
201 been transfered and the caller is responsible for cleanup.
202 @param aStatus The client's request status to complete.
203 @leave KErrNotFound If the attachment that is trying to be modified cannot be found.
204 @leave KErrAccessDenied If attachment manager is in read-only mode.
206 virtual void ModifyAttachmentInfoL(CMsvAttachment* aAttachmentInfo, TRequestStatus& aStatus) = 0;
209 Returns an open file handle for the attachment file.
211 Returns a read-only open file handle for the attachment file. This only applies to file based
212 attachments ie. file attachment and linked file attachments. The caller is responsible for
213 closing the returned file handle.
215 @param aIndex The array index position of the attachment.
216 @return A read-only open file handle for the attachment file. Caller must close the handle.
217 @leave KErrNotSupported If the attachment is not a file attachment in the message store.
219 virtual RFile GetAttachmentFileL(TInt aIndex) = 0;
222 Returns an open file handle for the attachment file.
224 Returns a read-only open file handle for the attachment file. This only applies to file based
225 attachments ie. file attachment and linked file attachments. The caller is responsible for
226 closing the returned file handle.
228 @param aIndex The array index position of the attachment.
229 @return A read-only open file handle for the attachment file. Caller must close the handle.
230 @leave KErrNotSupported If the attachment is not a file attachment in the message store.
231 @leave KErrNotFound If an attachment with the specified attachment Id is not found.
233 virtual RFile GetAttachmentFileL(TMsvAttachmentId aId) = 0;
236 Returns an open writable file handle for the attachment file.
238 Returns a writable open file handle for the attachment file. This only applies to file based
239 attachments ie. file attachment and linked file attachments. The caller is responsible for
240 closing the returned file handle.
242 @param aIndex The array index position of the attachment.
243 @return A writable open file handle for the attachment file. Caller must close the handle.
244 @leave KErrNotSupported If the attachment is not a file attachment in the message store.
245 @leave KErrAccessDenied If attachment manager is in read-only mode.
248 virtual RFile GetAttachmentFileForWriteL(TInt aIndex) = 0;
251 Returns an open writable file handle for the attachment file.
253 Returns a writable open file handle for the attachment file. This only applies to file based
254 attachments ie. file attachment and linked file attachments. The caller is responsible for
255 closing the returned file handle.
257 @param aIndex The array index position of the attachment.
258 @return A writable open file handle for the attachment file. Caller must close the handle.
259 @leave KErrNotSupported If the attachment is not a file attachment in the message store.
260 @leave KErrNotFound If an attachment with the specified attachment Id is not found.
261 @leave KErrAccessDenied If attachment manager is in read-only mode.
264 virtual RFile GetAttachmentFileForWriteL(TMsvAttachmentId aId) = 0;
267 Removes the attachment from the message entry.
269 This changes the array index values of all the attachments after the removed one.
270 Attachment files stored in the message store are deleted. Linked files and message entry
271 attachments are not deleted, this is left to the caller to do if required.
273 @param aParam The array index position of the attachment to be removed.
274 @leave KErrAccessDenied If attachment manager is in read-only mode.
276 virtual void RemoveAttachmentL(TInt aIndex, TRequestStatus& aStatus) = 0;
279 Removes the attachment from the message entry.
281 This changes the array index values of all the attachments after the removed one.
282 Attachment files stored in the message store are deleted. Linked files and message entry
283 attachments are not deleted, this is left to the caller to do if required.
285 @param aParam The array index position of the attachment to be removed.
286 @leave KErrAccessDenied If attachment manager is in read-only mode.
287 @leave KErrNotFound If an attachment with the specified attachment Id is not found.
289 virtual void RemoveAttachmentL(TMsvAttachmentId aId, TRequestStatus& aStatus) = 0;
292 Cancels the last asynchronous operation that was requested.
294 Allows callers to cancel the last asynchronous operation. This will have no effect
295 if an asynchronous is not waiting to complete.
297 virtual void CancelRequest() = 0;
300 #endif // __MMSVATTACHMENTMANAGER_H__