1 /*

     2 * Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Message store mailbox client handle.

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef __MSG_STORE_MAILBOX_H__

    21 #define __MSG_STORE_MAILBOX_H__

    22 

    23 #include <e32base.h>

    24 //<cmail>

    25 #include "MsgStoreTypes.h"

    26 #include "MsgStoreWritablePropertyContainer.h"

    27 //</cmail>

    28 

    29 class CMsgStoreMessage;

    30 class CMsgStoreSessionContext;

    31 class MMsgStoreMailBoxObserver;

    32 class CMsgStorePropertyContainer;

    33 class CMsgStoreFolder;

    34 class RMsgStoreSortCriteria;

    35 class CMsgStoreSortResultIterator;

    36 class RMsgStoreSearchCriteria;

    37 class CMsgStoreSearchHandler;

    38 

    39 /** This class defines the message store search client API.

    40  *

    41  *  This class is used to notify the search client of the completion of an asynchronous search of the

    42  *  message store.

    43 */

    44 class MMsgStoreSearchClient

    45     {

    46     public:

    47 

    48        /** Notifies the client that a match has been found

    49         * 

    50         *  /param aMessageSummary (OUT) containts the properties of the matching message.

    51         *                     The properties include those specified in RMsgStoreSearchCriteria 

    52         *                     that was passed to CMsgStoreMailBox::SearchL().

    53         *  /note client should take over the ownership ot the pointer presented by this method

    54         */

    55         virtual void MatchFound( CMsgStorePropertyContainer*& aMessageSummary ) = 0;

    56     

    57         /** Notifies that client that the search has completed

    58          * 

    59          */

    60         virtual void SearchCompleted() = 0;

    61     

    62     }; // end class MMsgStoreSearchClient

    63 

    64 /**

    65  *  A client handle to a mail box in the Message Store.

    66  *

    67  *  An instance of this class is created by the OpenAccountL() or CreateAccountL() methods 

    68  *  of the CMsgStore class.  

    69  *

    70  *  Storage-related functions will leave with KErrInUse if a backup or restore is in progress.  Operation

    71  *  of the message store will resume as normal after the backup or restore completes.

    72  *	

    73  *  Functions that increase the size of the message store may leave with KErrNoMemory if the given operation

    74  *  would cause the system disk space to go below critical levels.

    75  */

    76 class CMsgStoreMailBox : public CMsgStoreWritablePropertyContainer, public MMsgStoreSearchClient

    77 	{

    78 	public:

    79 		

    80        /** Adds an observer to the mail box

    81         *

    82         *	This function allows an observer to observe adds/changes/deletes/moves within the mail box.	

    83         *	

    84         *	No platform security capabilities are required to use this function.

    85         *	

    86         *	\note The observer will not be notified of mail box operations that are performed from

    87         *         the observer's own message store session.

    88         */

    89 		IMPORT_C void AddObserverL( MMsgStoreMailBoxObserver* aObserver );

    90 		

    91        /** Removes an observer from the message store. 

    92         *

    93         *	No platform security capabilities are required to use this function.

    94         */

    95 		IMPORT_C void RemoveObserverL( MMsgStoreMailBoxObserver* aObserver );	

    96 

    97 		

    98        /** Fetches the given list of properties for the containers with the given IDs.

    99         *

   100         *	This function will return a list of property containers for the given IDs, containing only

   101         *	the given properties.  If a container cannot be found then the function will not leave, but

   102         *	the returned list not have an entry for that container.

   103         *	

   104         *	ECapabilityReadUserData is required to use this function.			

   105         */

   106         IMPORT_C void FetchPropertiesL( const RArray<TMsgStoreId>&                 aIds, 

   107                                         const RPointerArray<TDesC8>&               aPropertyNames, 

   108                                         RPointerArray<CMsgStorePropertyContainer>& aProperties );

   109         

   110         /** Fetches the properties of a given container with the given IDs.

   111          *

   112          *  This function will return a writable property container for the given IDs.

   113          *  This function leaves if the given ID can not be found in this mail box.

   114          * 

   115          *  /note the caller owns the returned object and should free it when done using it.

   116          *  

   117          *  ECapabilityReadUserData is required to use this function.           

   118          */

   119          IMPORT_C CMsgStoreWritablePropertyContainer* FetchPropertiesL( TMsgStoreId aIds ); 

   120 		

   121 		// ----------------

   122 		// FOLDER FUNCTIONS

   123 		// ----------------

   124 

   125         /** Creates a user-defined folder.

   126         *

   127         *	This function creates a user-defined folder with the given name and the given parent folder.

   128         *	

   129         *	To create top-level folder, use this->Id() as aParentId. 

   130         *	

   131         *    The followin code creates a top-level, non-local folder with property "name" = "inbox":

   132         *    <pre>

   133         *  		

   134         *  		CMsgStorePropertyContainer* properties = CMsgStorePropertyContainer::NewL();

   135         *  		CleanupStack::PushL( properties );

   136         *  		properties->AddPropertyL( KMsgStorePropertyName, KMyInboxName );

   137         *  		

   138         *  		TMsgStoreId folderId = mailBox->CreateFolderL( Id(),           //use the mailBoxId as parent Id because we are creating top-level folder

   139         *  	                                                   *properties );  //leave aIsLocal to false because we are creating a non-local folder

   140         *  	    

   141         *  	    //now we can create messages, see CreateMessageL() for example.

   142         *  

   143         *   	</pre>    

   144         *	

   145         *	ECapabilityWriteUserData is required to use this function.			

   146         *	

   147         *	\retval The id of the new folder.

   148         */

   149         IMPORT_C TMsgStoreId CreateFolderL( TMsgStoreId                 aParentId, 

   150                                             CMsgStorePropertyContainer& aProperties,

   151                                             TBool                       aIsLocal = EFalse);

   152        /** Deletes a user-defined folder.

   153         *

   154         *	This function deletes a user-defined folder, recursively deleting all child folders, messages,

   155         *	and attachments.  The function will leave with KErrAccessDenied if the ID of a predefined

   156         *	folder is specified.  The function will leave with KErrNotFound if the specified folder ID

   157         *	is not found in the message store.  The function will leave with KErrArgument if a predefined

   158         *	folder is specified.						

   159         *	

   160         *	ECapabilityWriteUserData is required to use this function.			

   161         */

   162 		IMPORT_C void DeleteFolderL( TMsgStoreId aFolderId );

   163 

   164        /** Returns the list of children folders.

   165         *

   166         *	This function returns a list of the given folder's immediate children (i.e. nonrecursive),

   167         *   or all of its childres (recursive) depending on the aRecursive Parameter.

   168         *	The caller owns the memory of the returned objects.

   169         *	

   170         *    The followin code retrieves the top-level folders and find the one with property "name" == "inbox"

   171         *    <pre>

   172         *    

   173         *  		RPointerArray<CMsgStoreFolder> folders;

   174         *  		CleanupResetAndDestroyClosePushL( folders );

   175         *  		

   176         *  		mailBox->FoldersL( mailBox->Id(), folders );

   177         *  		

   178         *  		CMsgStoreFolder* inbox = NULL;

   179         *  		

   180         *  		for ( int i = 0 ; i < folders.Count() ; i++ )

   181         *  			{

   182         *  			CMsgStoreFolder* folder = folders[i];

   183         *  			TUint index = 0;

   184         *  			if ( folder->FindProperty( KMsgStorePropertyName, index ) )

   185         *  			    {

   186         *  			    if ( folder->PropertyValueDesL( index ) == KMyInbox )

   187         *  			    	{

   188         *  			    	//found inbox

   189         *  			    	inbox = folder;

   190         *  			    	break;

   191         *  			    	}

   192         *  			    }

   193         *            }

   194         *            

   195         *   	</pre>    

   196         *

   197         *	

   198         *	ECapabilityReadUserData is required to use this function.			

   199         */		

   200 		IMPORT_C void FoldersL( TMsgStoreId                     aFolderId, 

   201 		                        RPointerArray<CMsgStoreFolder>& aFolders,

   202 		                        TBool                           aRecursive = EFalse );

   203 		

   204        /** Returns the list of folders.

   205         *  

   206         *	This function returns a list of all folders in the message store, recursively.  The caller owns

   207         *	the memory of the returned objects.

   208         *

   209         *	ECapabilityReadUserData is required to use this function.

   210         */		

   211 		IMPORT_C void FoldersL( RPointerArray<CMsgStoreFolder>& aFolders );

   212 		

   213        /** Returns a folder object.

   214         *

   215         *	This function returns a folder object for the given folder ID.  This function will leave with

   216         *	KErrNotFound if the specified folder is not found in the message store.  The caller must

   217         *	deallocate the returned object.

   218         *	

   219         *	ECapabilityReadUserData is required to use this function.			

   220         */

   221 		IMPORT_C CMsgStoreFolder* FolderL( TMsgStoreId aId );

   222 

   223 		// -----------------

   224 		// MESSAGE FUNCTIONS

   225 		// -----------------

   226 

   227        /** Adds a message to the specified folder.

   228         *	

   229         *	This function create an individual message in the folder based on the input properties.  This

   230         *	function stores only the message headers.  The body is stored with	subsequent calls to

   231         *	the content-related functions.  The function will leave with KErrNotFound if the specified

   232         *	folder ID is not found in the message store.

   233         *	

   234         *	Note that the created message will NOT be visible in the message store until

   235         *	CMsgStoreMessage::CommitL() is invoked!  Also note that only a single modification observer

   236         *	notify (of type add) will be triggered (there will be no separate notifications for the

   237         *	attachments or content).

   238         *	

   239         *	For uncommitted messages, only certain operations are supported:

   240         *	

   241         *	    - Storing of message content

   242         *	    - Creation of message parts (including part content)

   243         *	    

   244         *	Other functionality will leave with KErrNotFound if attempted on an uncommited message.

   245         *	Subordinate partss will not be visible in the store until the parent message is

   246         *	committed.

   247         *

   248         *    Here is an example sequence, involving the creation of a message with a single attachment:

   249         *    <pre>

   250         *    

   251         *	    CMsgStorePropertyContainer* msgProperties = CMsgStorePropertyContainer::NewL();

   252         *	    CleanupStack::PushL( msgProperties );

   253         *	    

   254         *	    //add the subject line

   255         *	    msgProperties->AddPropertyL( KMsgStorePropertySubject, aSubject );

   256         *	    

   257         *	    //add more properties

   258         *	          :

   259         *	          :

   260         *	    

   261         *       message = iMailBox->CreateMessageL( iInboxFolderId, *msgProperties ); 

   262         *        

   263         *        //add the msg body properties

   264         *	    CMsgStorePropertyContainer* bodyProperties = CMsgStorePropertyContainer::NewL();

   265         *	    CleanupStack::PushL( bodyProperties );

   266         *	    

   267         *	    bodyProperties->AddPropertyL( KMsgStorePropertySize, aBodyContentSize );

   268         *	    

   269         *        CMsgStoreMessagePart* body = message->AddChildPartL( *bodyProperties ); 

   270         *        //set the content of the body 

   271         *        bod->ReplaceContentL( _L("this is the message body" ) ); 			

   272         *        

   273         *        //add the attachment body properties

   274         *	    CMsgStorePropertyContainer* attachmentProperties = CMsgStorePropertyContainer::NewL();

   275         *	    CleanupStack::PushL( attachmentProperties );

   276         *	    

   277         *	    attachmentProperties->AddPropertyL( KMsgStorePropertyContentType, aAttachmentType );

   278         *

   279         *        CMsgStoreMessagePart* attachment = message->AddChilePartL( *attachmentProperties ); 

   280         *        attachment->ReplaceContentL( _L8("SOME CONTENT") ); 

   281         *        attachment->AppendToContentL( _L8("SOME MORE CONTENT") ); 

   282         *

   283         *		//remember to commit

   284         *        message->CommitL();

   285         *        

   286         *	</pre>

   287         *	

   288         *	ECapabilityWriteUserData is required to use this function.			

   289         *	

   290         *	\retval A message object.  The caller owns the storage of the returned object.

   291         *

   292         *    \note Only works if the store is in an authenticated state, otherwise this function leaves

   293         *          with KErrNotReady.

   294         */		

   295 		IMPORT_C CMsgStoreMessage* CreateMessageL( TMsgStoreId                       aFolderId, 

   296 									  		       const CMsgStorePropertyContainer& aProperties );

   297 

   298        /** Reads a message from the message store.

   299         *	

   300         *	This function reads an individual message.  This function will leave with KErrNotFound if the

   301         *	specified message ID is not found or has been moved to another folder.  Note that the message

   302         *	body and attachments are not fetched during this call.

   303         *

   304         *   KMsgStoreInvalidId may be passed for the folder ID if there is no desire to check the parent

   305         *    folder.

   306         *

   307         *	ECapabilityReadUserData is required to use this function.			

   308         *

   309         *	\retval Returns a message object.  The caller owns the memory of the returned object.

   310         *	

   311         *   \note Only works if the store is in an authenticated state, otherwise this function leaves

   312         *          with KErrNotReady.

   313         */		

   314         IMPORT_C CMsgStoreMessage* FetchMessageL( TMsgStoreId aMessageId, 

   315         										  TMsgStoreId aFolderId );

   316 		

   317        /** Deletes a message.

   318         *	

   319         *	This function deletes an individual message.  This function will leave with KErrNotFound if the

   320         *	specified message ID is not found in the specified folder.

   321         *

   322         *    KMsgStoreInvalidId may be passed for the folder ID if there is no desire to check the parent

   323         *    folder.

   324         *    

   325         *	ECapabilityWriteUserData is required to use this function.			

   326         *	

   327         *    \note Only works if the store is in an authenticated state, otherwise this function leaves

   328         *          with KErrNotReady.

   329         */		

   330 		IMPORT_C void DeleteMessageL( TMsgStoreId aMessageId, 

   331 									  TMsgStoreId aFolderId );

   332 		

   333        /** Moves a message to another folder.

   334         *	

   335         *   This function moves a message to the given folder.  The ID of the message is not changed by

   336         *   this operation.  This function will leave with KErrNotFound	if the specified message ID is

   337         *   not found in the source folder or if the destination folder is not found. 

   338         *

   339         *   KMsgStoreInvalidId may be passed for the source folder ID if there is no desire to check the

   340         *   source folder.

   341         *    

   342         *   ECapabilityWriteUserData is required to use this function.			

   343         *	

   344         *   \note Only works if the store is in an authenticated state, otherwise this function leaves

   345         *         with KErrNotReady.

   346         */		

   347 		IMPORT_C void MoveMessageL( TMsgStoreId aMessageId, 

   348 		                            TMsgStoreId aSourceFolderId, 

   349 		                            TMsgStoreId aDestinationFolderId );

   350 		/** Moves a folder to another folder.

   351         *	

   352         *   This function moves a folder to the given folder.  The ID of the folder is not changed by

   353         *   this operation.  This function will leave with KErrNotFound	if the specified folder ID is

   354         *   not found in the source folder or if the destination folder is not found. 

   355         *

   356         *   KMsgStoreInvalidId may be passed for the source folder ID if there is no desire to check the

   357         *   source folder.

   358         *    

   359         *   ECapabilityWriteUserData is required to use this function.			

   360         *	

   361         *   \note Only works if the store is in an authenticated state, otherwise this function leaves

   362         *         with KErrNotReady.

   363         */		                            

   364 		IMPORT_C void MoveFolderL( TMsgStoreId aFolderId, 

   365 								   TMsgStoreId aSourceFolderId, 

   366 								   TMsgStoreId aDestinationFolderId );

   367 								   

   368         /** Copies a message to another folder.

   369         *

   370         *    This function copies a message to the given folder, including the properties, content, and

   371         *    all attachments.  This function will leave with KErrNotFound if the specified message ID is

   372         *    not found in the source folder or if the destination folder is not found.

   373         *    

   374         *    KMsgStoreInvalidId may be passed for the source folder ID if there is no desire to check the

   375         *    source folder.

   376         *    

   377         *    ECapabilityWriteUserData is required to use this function.			

   378         *    

   379         *    \retval Returns the ID of the new message.

   380         *    

   381         *    \note Only works if the store is in an authenticated state, otherwise this function leaves

   382         *          with KErrNotReady.

   383         */		

   384 		IMPORT_C TMsgStoreId CopyMessageL( TMsgStoreId aMessageId, 

   385 		                                   TMsgStoreId aSourceFolderId, 

   386 		                                   TMsgStoreId aDestinationFolderId );

   387 		

   388 		

   389 		/** Returns a list of messages a folder.

   390 			

   391 			This function populates the input RArray with the IDs of the messages in the given folder.

   392 			The function will leave with KErrNotFound if the folder is no longer found in the message store.	

   393 		*/		

   394 		IMPORT_C void MessageIdsL( TMsgStoreId          aFolderId, 

   395 		                           RArray<TMsgStoreId>& aMessageIdList );

   396 	

   397        /** Returns the total and unread message counts for the given folder.

   398         *

   399         *    This function returns the total message count and the unread message count for the given

   400         *    folder.  The function will leave with KErrNotFound if the folder is no longer found in the

   401         *    message store.

   402         */		

   403 		IMPORT_C void MessageCountsL( TMsgStoreId aFolderId, 

   404 		                              TUint&      aTotalCount, 

   405 		                              TUint&      aUnreadCount );		

   406 

   407        /** Returns the counts for the entire message store.

   408         *

   409         *   This function returns the total message count and the unread message count for the entire

   410         *   message store.

   411         */		

   412 		IMPORT_C void TotalMessageCountsL( TUint& aTotalCount, 

   413 		                                   TUint& aUnreadCount );

   414         

   415         

   416         /** Request a sorting operation.

   417          * 

   418          *  Fill out the sort criteria and pass it in.  The sorted results will be 

   419          *  represented by the iterator returned.  Use the iterator to retrieve 

   420          *  rows in the sorted result.

   421          * 

   422          *  /note The message store sever keeps the sorted results in memory unntil the 

   423          *        iterator is deleted. Therefore, to conserve memory, it is very important

   424          *        for the clients to delete the iterator when it's no longer needed.

   425          * 

   426          *  @see RMsgStoreSortCriteria

   427          *  @see CMsgStoreSortResultIterator

   428         */      

   429         IMPORT_C CMsgStoreSortResultIterator* SortL( RMsgStoreSortCriteria& aSortCriteria, TBool aInMemorySort = EFalse );

   430         

   431         /** Initiates an asynchronous search for matching messages.

   432          *

   433          *  This function will search the given folders for message's containing the given search string.

   434          *  The search will be performed on the To, Cc, Bcc, subject, body or any combination of these

   435          *  fields based on the search criteria.  The search client will be notified of each found message,

   436          *  and upon completion of the search.  Only one search can be performed at a time, per session.  

   437          *  This search is not recursive.

   438          *  

   439          *  To change the sort order in the search result, simply use the same search string in the

   440          *  search criteria but change the "sort by" field.  The message store "caches" the search

   441          *  results generated by the same search string. 

   442          *    

   443          *  The function will leave with KErrInUse if a search is already in progress.

   444          *   

   445          *  ECapabilityReadUserData is required to use this function.           

   446          *   

   447          *  \note Only works if the store is in an authenticated state, otherwise this function leaves

   448          *         with KErrNotReady.            

   449         */

   450         IMPORT_C void SearchL( RMsgStoreSearchCriteria&  aSearchCriteria, 

   451                                MMsgStoreSearchClient&    aSearchClient );

   452                                                   

   453         /** Cancels the current asynchronous search.

   454          *        

   455          *   This function cancels the current asynchronous search, if any.  The search client will not be

   456          *   called back after this function is called.

   457          * 

   458          *   \note CancelSearch() method does NOT clear the search result cached in the store. 

   459          *         A different sort order can be used for the same search string, and the 

   460          *         cache will be utilized.  Only by using a different search string can the

   461          *         cache be cleaned.

   462         */

   463         IMPORT_C void CancelSearch();

   464         

   465         /** Inform the message store to clean up its cache for search results.

   466          *        

   467          *  This method cancels the the ongoing search session (if exists), and than sends a 

   468          *  request to the servr to clecnup its cache.

   469          * 

   470          *  This function should be called by the UI when search results are no longer in display.

   471         */

   472         IMPORT_C void ClearSearchResultCache();

   473         

   474         /** Add the addresses to Most Recent Used address list.

   475          *        

   476          *  This method adds the input addresses to the "top" of the MRU address list.

   477          *  If input contains more than one address, than addresses in the "front" of the array 

   478          *  (with smaller index numbers) are considered "more recent" than those in the "back"

   479          *  of the array (with bigger index numbers).

   480          *  

   481          *  /note The memory in the input array is NOT transferred to the store, so the caller 

   482          *        needs to free it.

   483         */

   484         IMPORT_C void AddMruAddressesL( RPointerArray<CMsgStoreAddress>& aAddressArray );

   485         

   486         /** Gets the Most Recent Used address list.

   487          *        

   488          *  This method retrieves the MRU address list.

   489          *  Note that addresses in the "front" of the returned array (with smaller index numbers) 

   490          *  are considered "more recent" than those in the "back" of the array (with bigger index

   491          *  numbers).

   492          * 

   493          *  /note The memory in the output array is transferred to the caller.

   494         */

   495         IMPORT_C void MruAddressesL( RPointerArray<CMsgStoreAddress>& aAddressArray );

   496         

   497         /** Get the container type by an ID.

   498          * 

   499          *  Added for Mail for Exchange email adaptor

   500          */

   501         IMPORT_C TMsgStoreContainerType ContainerTypeById( TMsgStoreId aId );

   502         

   503 

   504         /** Checks if the mailbox is a corporate mailbox

   505          *

   506          */

   507         IMPORT_C TBool IsCorporateMailbox();

   508 

   509         IMPORT_C void BeginBatchInsertL();

   510         

   511         IMPORT_C void FinishBatchInsertL();

   512         

   513 

   514         /** Destructor */

   515 		virtual ~CMsgStoreMailBox();

   516 		

   517 		// ---------------------------

   518 		// INTERNAL USE (NOT EXPORTED)

   519 		// ---------------------------

   520 		/** Creates a heap-based instance of this class. */	

   521 		static CMsgStoreMailBox* NewL( CMsgStoreSessionContext& aContext, TMsgStoreId aId, const TDesC8& aProperties );

   522 		

   523         /** Checks if the "isDefault" mailbox flag is set. */

   524         TBool IsDefaultMailbox();

   525         

   526         /** Sets the "isDefault" mailbox flag. */

   527 		void SetDefaultMailboxL( TBool aIsDefault );

   528 										 

   529 	private:

   530 	

   531 		CMsgStoreMailBox( CMsgStoreSessionContext& aContext, TMsgStoreId aId );

   532 		

   533 		void ConstructL( const TDesC8& aProperties );	

   534 

   535 		// inherited from MMsgStoreSearchClient

   536 		virtual void MatchFound( CMsgStorePropertyContainer*& aMessageSummary );

   537 		virtual void SearchCompleted();

   538         

   539     private:

   540     

   541         RPointerArray<CMsgStoreSearchHandler> iOldSearchHandlers;

   542 		

   543 	}; // end CMsgStoreSession;

   544 

   545 #endif