|
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 "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // CMsvAttachmentManager.h |
|
15 // |
|
16 /** |
|
17 * @file |
|
18 * @publishedAll |
|
19 * @released |
|
20 */ |
|
21 |
|
22 #ifndef __MMSVATTACHMENTMANAGER_H__ |
|
23 #define __MMSVATTACHMENTMANAGER_H__ |
|
24 |
|
25 #include <e32base.h> |
|
26 #include <msvstd.h> |
|
27 #include <cmsvattachment.h> |
|
28 |
|
29 class MMsvAttachmentManager |
|
30 /** |
|
31 Defines the attachment management interface. |
|
32 |
|
33 This class is a pure virtual interface class that defines the APIs to be used for |
|
34 attachment management in the Messaging Framework. It is expected that the clients of |
|
35 this interface will be MTMs implementations that require attachment management. |
|
36 |
|
37 The API allows is based around the use of the CMsvAttachment object that represents |
|
38 any type of attachment that is supported by the Messaging Framework. The CMsvAttachment |
|
39 object provides users with various attributes about the attachment without having to |
|
40 actually load or retrieve the attachment. |
|
41 |
|
42 This attachment manager API supports the following different types of attachments: |
|
43 1 - File attachments, file based attachments that are copied or created in the message |
|
44 store. |
|
45 2 - Linked file attachments, file based attachments that are not copied and are simply |
|
46 linked to the file location on disk. |
|
47 3 - Message entry attachments, existing message entries that can be registered as |
|
48 attachments of another message entry. |
|
49 |
|
50 For file based attachments, this API also supports the retrieval of the files as |
|
51 open read-only file handles. |
|
52 |
|
53 All functionality that requires the attachment manager to be in edit mode have been |
|
54 defined as asynchronous. The attachment manager does not allow multiple asynchronous |
|
55 requests to be made at the same time. |
|
56 |
|
57 @see CMsvAttachment |
|
58 @publishedAll |
|
59 @released |
|
60 */ |
|
61 { |
|
62 public: |
|
63 /** |
|
64 Adds an attachment to the message store by file path. |
|
65 |
|
66 The attachment file must be located in a public area. The file path must also be a |
|
67 full path specification. The file is copied into the message store. |
|
68 |
|
69 @param aFilePath The absolute file path of the attachment file. |
|
70 @param aAttachmentInfo The attachment info associated with the file. |
|
71 If the routine does not leave, then ownership will be transferred to the |
|
72 attachment manager. If the routine does leave then ownership will not have |
|
73 been transfered and the caller is responsible for cleanup. |
|
74 @param aStatus The client's request status to complete when the operation has completed. |
|
75 @leave KErrAccessDenied If attachment manager is in read-only mode. |
|
76 */ |
|
77 virtual void AddAttachmentL(const TDesC& aFilePath, CMsvAttachment* aAttachmentInfo, TRequestStatus& aStatus) = 0; |
|
78 |
|
79 /** |
|
80 Adds an attachment to the message store by file handle. |
|
81 |
|
82 This is used to add an attachment from an open file handle such as when adding a file |
|
83 from the caller's private area. The file is copied into the message store. The message |
|
84 server is responsible for closing the file handle once copied. |
|
85 |
|
86 @param aFileHandle An open file handle for the attachment file. Ownership is transferred. The caller must close the file handle. |
|
87 @param aAttachmentInfo The attachment info associated with the file. |
|
88 If the routine does not leave, then ownership will be transferred to the |
|
89 attachment manager. If the routine does leave then ownership will not have |
|
90 been transfered and the caller is responsible for cleanup. |
|
91 @param aStatus The client's request status to complete. |
|
92 @leave KErrAccessDenied If attachment manager is in read-only mode. |
|
93 */ |
|
94 virtual void AddAttachmentL(RFile& aFileHandle, CMsvAttachment* aAttachmentInfo, TRequestStatus& aStatus) = 0; |
|
95 |
|
96 /** |
|
97 Adds an attachment as a linked file attachment. |
|
98 |
|
99 The attachment is added as a link by its file path. The attachment is not copied to the |
|
100 message store. The attachment is linked and therefore must be in a public location. |
|
101 |
|
102 It is possible to change a linked attachment file after it has been attached to a message |
|
103 entry. No integrity checking is carried out. This is left to individual MTMs or implementors |
|
104 of this interface to decide if any checking is required such as checking if the size has changed. |
|
105 |
|
106 @param aFilePath The absolute file path of the linked attachment file. |
|
107 @param aAttachmentInfo The attachment info associated with the file. |
|
108 If the routine does not leave, then ownership will be transferred to the |
|
109 attachment manager. If the routine does leave then ownership will not have |
|
110 been transfered and the caller is responsible for cleanup. |
|
111 @param aStatus The client's request status to complete. |
|
112 @leave KErrAccessDenied If attachment manager is in read-only mode. |
|
113 */ |
|
114 virtual void AddLinkedAttachmentL(const TDesC& aFilePath, CMsvAttachment* aAttachmentInfo, TRequestStatus& aStatus) = 0; |
|
115 |
|
116 /** |
|
117 Adds a message entry as an attachment. |
|
118 |
|
119 The message entry is registered as an attachment of the current message entry. The attachment |
|
120 message entry is not copied. |
|
121 |
|
122 @param aEntryId The message Id of the entry to register as an attachment. |
|
123 @param aAttachmentInfo The attachment info associated with the file. |
|
124 If the routine does not leave, then ownership will be transferred to the |
|
125 attachment manager. If the routine does leave then ownership will not have |
|
126 been transfered and the caller is responsible for cleanup. |
|
127 @param aStatus The client's request status to complete. |
|
128 @leave KErrAccessDenied If attachment manager is in read-only mode. |
|
129 */ |
|
130 virtual void AddEntryAsAttachmentL(TMsvId aEntryId, CMsvAttachment* aAttachmentInfo, TRequestStatus& aStatus) = 0; |
|
131 |
|
132 /** |
|
133 Creates a new empty attachment file. |
|
134 |
|
135 The caller is returned an open writable file handle to an empty attachment file in the message |
|
136 store. The caller must pass in an uninitialised file handle. The file handle cannot be used |
|
137 until the asynchronous request completes successfully. If the request is sucessful the file handle |
|
138 is open and must close by the caller once the data has been written to it. |
|
139 |
|
140 @param aFileName The filename to assign to the newly create attachment file. |
|
141 @param aAttachmentFile An uninitialised file handle. This is opened and can be written to if the |
|
142 request is successful. Ownership is transferred . The caller must close the file handle. |
|
143 @param aAttachmentInfo The attachment info associated with the file. |
|
144 If the routine does not leave, then ownership will be transferred to the |
|
145 attachment manager. If the routine does leave then ownership will not have |
|
146 been transfered and the caller is responsible for cleanup. |
|
147 @leave KErrAccessDenied If attachment manager is in read-only mode. |
|
148 */ |
|
149 virtual void CreateAttachmentL(const TDesC& aFileName, RFile& aAttachmentFile, CMsvAttachment* aAttachmentInfo, TRequestStatus& aStatus) = 0; |
|
150 |
|
151 |
|
152 /** |
|
153 Renames the physical filename of an attachment. |
|
154 |
|
155 @param aIndex The array index position of the attachment to be renamed. |
|
156 @param aNewName The new name of the attachment. |
|
157 @param aStatus The client's request status to complete. |
|
158 @leave KErrAccessDenied If attachment manager is in read-only mode. |
|
159 @leave KErrAlreadyExists If the supplied attachment filename already exists. |
|
160 */ |
|
161 virtual void RenameAttachmentL(TInt aIndex, const TDesC& aNewName, TRequestStatus& aStatus) = 0; |
|
162 |
|
163 |
|
164 /** |
|
165 Counts the number of attachments. |
|
166 |
|
167 Returns the number of attachments associated with the message entry. This includes all the |
|
168 attachments that have not been commited yet. |
|
169 @return The number of attachments. |
|
170 */ |
|
171 virtual TInt AttachmentCount() const = 0; |
|
172 |
|
173 /** |
|
174 Returns an attachment info object. |
|
175 |
|
176 This object contains attributes and information about the attachment without having actually |
|
177 retrieving the actual attachment. The caller assumes ownership of the returned object. |
|
178 |
|
179 @param aIndex The array index position of the attachment. |
|
180 @return The attachment info for the attachment. Ownership is passed to caller, |
|
181 */ |
|
182 virtual CMsvAttachment* GetAttachmentInfoL(TInt aIndex) = 0; |
|
183 |
|
184 /** |
|
185 Returns an attachment info object. |
|
186 |
|
187 This object contains attributes and information about the attachment without having actually |
|
188 retrieving the actual attachment. The caller assumes ownership of the returned object. |
|
189 |
|
190 @param aId The attachment Id of the attachment. |
|
191 @return The attachment info for the attachment. Ownership is passed to caller, |
|
192 @leave KErrNotFound If an attachment with the specified attachment Id is not found. |
|
193 */ |
|
194 virtual CMsvAttachment* GetAttachmentInfoL(TMsvAttachmentId aId) = 0; |
|
195 |
|
196 /** |
|
197 Modifies the attachment info for a particular attachment. |
|
198 |
|
199 This allows callers to modify an existing attachment info object for a particular attachment. |
|
200 The attachment info object passed in replaces the existing attachment info object and takes |
|
201 ownership for the object passed in. It is expected that callers will use GetAttachmentInfoL |
|
202 to get the object, make some changes and pass it back into this method. |
|
203 |
|
204 @param aAttachmentInfo The attachment info associated with the file. |
|
205 If the routine does not leave, then ownership will be transferred to the |
|
206 attachment manager. If the routine does leave then ownership will not have |
|
207 been transfered and the caller is responsible for cleanup. |
|
208 @param aStatus The client's request status to complete. |
|
209 @leave KErrNotFound If the attachment that is trying to be modified cannot be found. |
|
210 @leave KErrAccessDenied If attachment manager is in read-only mode. |
|
211 */ |
|
212 virtual void ModifyAttachmentInfoL(CMsvAttachment* aAttachmentInfo, TRequestStatus& aStatus) = 0; |
|
213 |
|
214 /** |
|
215 Returns an open file handle for the attachment file. |
|
216 |
|
217 Returns a read-only open file handle for the attachment file. This only applies to file based |
|
218 attachments ie. file attachment and linked file attachments. The caller is responsible for |
|
219 closing the returned file handle. |
|
220 |
|
221 @param aIndex The array index position of the attachment. |
|
222 @return A read-only open file handle for the attachment file. Caller must close the handle. |
|
223 @leave KErrNotSupported If the attachment is not a file attachment in the message store. |
|
224 */ |
|
225 virtual RFile GetAttachmentFileL(TInt aIndex) = 0; |
|
226 |
|
227 /** |
|
228 Returns an open file handle for the attachment file. |
|
229 |
|
230 Returns a read-only open file handle for the attachment file. This only applies to file based |
|
231 attachments ie. file attachment and linked file attachments. The caller is responsible for |
|
232 closing the returned file handle. |
|
233 |
|
234 @param aIndex The array index position of the attachment. |
|
235 @return A read-only open file handle for the attachment file. Caller must close the handle. |
|
236 @leave KErrNotSupported If the attachment is not a file attachment in the message store. |
|
237 @leave KErrNotFound If an attachment with the specified attachment Id is not found. |
|
238 */ |
|
239 virtual RFile GetAttachmentFileL(TMsvAttachmentId aId) = 0; |
|
240 |
|
241 /** |
|
242 Returns an open writable file handle for the attachment file. |
|
243 |
|
244 Returns a writable open file handle for the attachment file. This only applies to file based |
|
245 attachments ie. file attachment and linked file attachments. The caller is responsible for |
|
246 closing the returned file handle. |
|
247 |
|
248 @param aIndex The array index position of the attachment. |
|
249 @return A writable open file handle for the attachment file. Caller must close the handle. |
|
250 @leave KErrNotSupported If the attachment is not a file attachment in the message store. |
|
251 @leave KErrAccessDenied If attachment manager is in read-only mode. |
|
252 */ |
|
253 virtual RFile GetAttachmentFileForWriteL(TInt aIndex) = 0; |
|
254 |
|
255 /** |
|
256 Returns an open writable file handle for the attachment file. |
|
257 |
|
258 Returns a writable open file handle for the attachment file. This only applies to file based |
|
259 attachments ie. file attachment and linked file attachments. The caller is responsible for |
|
260 closing the returned file handle. |
|
261 |
|
262 @param aIndex The array index position of the attachment. |
|
263 @return A writable open file handle for the attachment file. Caller must close the handle. |
|
264 @leave KErrNotSupported If the attachment is not a file attachment in the message store. |
|
265 @leave KErrNotFound If an attachment with the specified attachment Id is not found. |
|
266 @leave KErrAccessDenied If attachment manager is in read-only mode. |
|
267 */ |
|
268 virtual RFile GetAttachmentFileForWriteL(TMsvAttachmentId aId) = 0; |
|
269 |
|
270 /** |
|
271 Removes the attachment from the message entry. |
|
272 |
|
273 This changes the array index values of all the attachments after the removed one. |
|
274 Attachment files stored in the message store are deleted. Linked files and message entry |
|
275 attachments are not deleted, this is left to the caller to do if required. |
|
276 |
|
277 @param aParam The array index position of the attachment to be removed. |
|
278 @leave KErrAccessDenied If attachment manager is in read-only mode. |
|
279 */ |
|
280 virtual void RemoveAttachmentL(TInt aIndex, TRequestStatus& aStatus) = 0; |
|
281 |
|
282 /** |
|
283 Removes the attachment from the message entry. |
|
284 |
|
285 This changes the array index values of all the attachments after the removed one. |
|
286 Attachment files stored in the message store are deleted. Linked files and message entry |
|
287 attachments are not deleted, this is left to the caller to do if required. |
|
288 |
|
289 @param aParam The array index position of the attachment to be removed. |
|
290 @leave KErrAccessDenied If attachment manager is in read-only mode. |
|
291 @leave KErrNotFound If an attachment with the specified attachment Id is not found. |
|
292 */ |
|
293 virtual void RemoveAttachmentL(TMsvAttachmentId aId, TRequestStatus& aStatus) = 0; |
|
294 |
|
295 /** |
|
296 Cancels the last asynchronous operation that was requested. |
|
297 |
|
298 Allows callers to cancel the last asynchronous operation. This will have no effect |
|
299 if an asynchronous is not waiting to complete. |
|
300 */ |
|
301 virtual void CancelRequest() = 0; |
|
302 }; |
|
303 |
|
304 #endif // __MMSVATTACHMENTMANAGER_H__ |