epoc32/include/mmsvattachmentmanager.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000
branchSymbian2
changeset 2 2fe1408b6811
parent 0 061f57f2323e
permissions -rw-r--r--
Final list of Symbian^2 public API header files
     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__