1 mmsvattachmentmanager.h |
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". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // |
|
15 |
|
16 #ifndef __MMSVATTACHMENTMANAGER_H__ |
|
17 #define __MMSVATTACHMENTMANAGER_H__ |
|
18 |
|
19 #include <e32base.h> |
|
20 #include <msvstd.h> |
|
21 #include <cmsvattachment.h> |
|
22 |
|
23 class MMsvAttachmentManager |
|
24 /** |
|
25 Defines the attachment management interface. |
|
26 |
|
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. |
|
30 |
|
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. |
|
35 |
|
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 |
|
38 store. |
|
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. |
|
43 |
|
44 For file based attachments, this API also supports the retrieval of the files as |
|
45 open read-only file handles. |
|
46 |
|
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. |
|
50 |
|
51 @see CMsvAttachment |
|
52 @publishedAll |
|
53 @released |
|
54 */ |
|
55 { |
|
56 public: |
|
57 /** |
|
58 Adds an attachment to the message store by file path. |
|
59 |
|
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. |
|
62 |
|
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. |
|
70 */ |
|
71 virtual void AddAttachmentL(const TDesC& aFilePath, CMsvAttachment* aAttachmentInfo, TRequestStatus& aStatus) = 0; |
|
72 |
|
73 /** |
|
74 Adds an attachment to the message store by file handle. |
|
75 |
|
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. |
|
79 |
|
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. |
|
87 */ |
|
88 virtual void AddAttachmentL(RFile& aFileHandle, CMsvAttachment* aAttachmentInfo, TRequestStatus& aStatus) = 0; |
|
89 |
|
90 /** |
|
91 Adds an attachment as a linked file attachment. |
|
92 |
|
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. |
|
95 |
|
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. |
|
99 |
|
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. |
|
107 */ |
|
108 virtual void AddLinkedAttachmentL(const TDesC& aFilePath, CMsvAttachment* aAttachmentInfo, TRequestStatus& aStatus) = 0; |
|
109 |
|
110 /** |
|
111 Adds a message entry as an attachment. |
|
112 |
|
113 The message entry is registered as an attachment of the current message entry. The attachment |
|
114 message entry is not copied. |
|
115 |
|
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. |
|
123 */ |
|
124 virtual void AddEntryAsAttachmentL(TMsvId aEntryId, CMsvAttachment* aAttachmentInfo, TRequestStatus& aStatus) = 0; |
|
125 |
|
126 /** |
|
127 Creates a new empty attachment file. |
|
128 |
|
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. |
|
133 |
|
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. |
|
142 */ |
|
143 virtual void CreateAttachmentL(const TDesC& aFileName, RFile& aAttachmentFile, CMsvAttachment* aAttachmentInfo, TRequestStatus& aStatus) = 0; |
|
144 |
|
145 |
|
146 /** |
|
147 Renames the physical filename of an attachment. |
|
148 |
|
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. |
|
154 */ |
|
155 virtual void RenameAttachmentL(TInt aIndex, const TDesC& aNewName, TRequestStatus& aStatus) = 0; |
|
156 |
|
157 |
|
158 /** |
|
159 Counts the number of attachments. |
|
160 |
|
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. |
|
164 */ |
|
165 virtual TInt AttachmentCount() const = 0; |
|
166 |
|
167 /** |
|
168 Returns an attachment info object. |
|
169 |
|
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. |
|
172 |
|
173 @param aIndex The array index position of the attachment. |
|
174 @return The attachment info for the attachment. Ownership is passed to caller, |
|
175 */ |
|
176 virtual CMsvAttachment* GetAttachmentInfoL(TInt aIndex) = 0; |
|
177 |
|
178 /** |
|
179 Returns an attachment info object. |
|
180 |
|
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. |
|
183 |
|
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. |
|
187 */ |
|
188 virtual CMsvAttachment* GetAttachmentInfoL(TMsvAttachmentId aId) = 0; |
|
189 |
|
190 /** |
|
191 Modifies the attachment info for a particular attachment. |
|
192 |
|
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. |
|
197 |
|
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. |
|
205 */ |
|
206 virtual void ModifyAttachmentInfoL(CMsvAttachment* aAttachmentInfo, TRequestStatus& aStatus) = 0; |
|
207 |
|
208 /** |
|
209 Returns an open file handle for the attachment file. |
|
210 |
|
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. |
|
214 |
|
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. |
|
218 */ |
|
219 virtual RFile GetAttachmentFileL(TInt aIndex) = 0; |
|
220 |
|
221 /** |
|
222 Returns an open file handle for the attachment file. |
|
223 |
|
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. |
|
227 |
|
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. |
|
232 */ |
|
233 virtual RFile GetAttachmentFileL(TMsvAttachmentId aId) = 0; |
|
234 |
|
235 /** |
|
236 Returns an open writable file handle for the attachment file. |
|
237 |
|
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. |
|
241 |
|
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. |
|
246 @internalComponent |
|
247 */ |
|
248 virtual RFile GetAttachmentFileForWriteL(TInt aIndex) = 0; |
|
249 |
|
250 /** |
|
251 Returns an open writable file handle for the attachment file. |
|
252 |
|
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. |
|
256 |
|
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. |
|
262 @internalComponent |
|
263 */ |
|
264 virtual RFile GetAttachmentFileForWriteL(TMsvAttachmentId aId) = 0; |
|
265 |
|
266 /** |
|
267 Removes the attachment from the message entry. |
|
268 |
|
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. |
|
272 |
|
273 @param aParam The array index position of the attachment to be removed. |
|
274 @leave KErrAccessDenied If attachment manager is in read-only mode. |
|
275 */ |
|
276 virtual void RemoveAttachmentL(TInt aIndex, TRequestStatus& aStatus) = 0; |
|
277 |
|
278 /** |
|
279 Removes the attachment from the message entry. |
|
280 |
|
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. |
|
284 |
|
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. |
|
288 */ |
|
289 virtual void RemoveAttachmentL(TMsvAttachmentId aId, TRequestStatus& aStatus) = 0; |
|
290 |
|
291 /** |
|
292 Cancels the last asynchronous operation that was requested. |
|
293 |
|
294 Allows callers to cancel the last asynchronous operation. This will have no effect |
|
295 if an asynchronous is not waiting to complete. |
|
296 */ |
|
297 virtual void CancelRequest() = 0; |
|
298 }; |
|
299 |
|
300 #endif // __MMSVATTACHMENTMANAGER_H__ |