1 /*

     2 * Copyright (c) 2005 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:  Requestor utilities, supports Resolving of Requestors.

    15 *

    16 */

    17 

    18 

    19 #ifndef CLOCREQUESTORUTILSRESOLVER_H_

    20 #define CLOCREQUESTORUTILSRESOLVER_H_

    21 

    22 //  INCLUDES

    23 #include <MVPbkContactFindObserver.h>

    24 #include <MVPbkSingleContactOperationObserver.h>

    25 #include <MVPbkContactLink.h>

    26 #include <MVPbkContactStoreListObserver.h>

    27 #include <MVPbkContactStoreObserver.h>

    28 #include <eikenv.h>

    29 

    30 //FORWARD DECLARATION

    31 class CVPbkContactManager;

    32 class CActiveSchedulerWait;

    33 class CPosRequestor;

    34 class MVPbkContactOperationBase;

    35 class MVPbkContactLinkArray;

    36 class MVPbkStoreContact;

    37 class MVPbkFieldTypeList;

    38 class CPbk2SortOrderManager;

    39 class MPbk2ContactNameFormatter;

    40 

    41 // CLASS DECLARATION

    42 

    43 /**

    44 *   This class is a version requestor utilities with resolving.

    45 *  @lib locutils.lib

    46 *  @since 3.0

    47 */

    48 class CLocRequestorUtilsResolver  :	public CActive,

    49                                     public MVPbkContactFindObserver,

    50                                     public MVPbkSingleContactOperationObserver,

    51                                     public MVPbkContactStoreListObserver

    52     {

    53     public: // Constructors and destructor

    54 

    55         /**

    56         * Symbian OS constructor

    57         * @param None

    58         * @return new object

    59         */

    60         IMPORT_C static CLocRequestorUtilsResolver* NewL();

    61 

    62         /**

    63         * Destructor.

    64         */

    65         virtual ~CLocRequestorUtilsResolver();

    66 

    67 	public: // Implement base class virtual methods

    68        /**

    69         * Processes the requestors. In this case there is no processing done.

    70         * @param aRequestors Array of Requestors

    71         * @return name descriptor, ownership is transferred to caller

    72         */

    73         IMPORT_C void ProcessRequestorsL( 

    74         				RPointerArray<CPosRequestor>& aRequestors );

    75 

    76         /**

    77         * This static method tells if requestor's name should be formatted

    78         * according to phone number formatting rules.

    79         * @param aRequestor who's name and id are investigated

    80         * @return ETrue if requestor has no name and id is of type 

    81         *               phone number.

    82         */

    83         IMPORT_C static TBool PhoneNumberAsName(

    84                         const CPosRequestor& aRequestor );

    85 

    86         /**

    87         * Static method for checking whether requestor id is valid or not.

    88         * Valid id means that a contact or service item can be created.

    89         * @param aRequestor requestor to be checked

    90         * @return ETrue if requestor id is valid, EFalse otherwise

    91         */

    92         IMPORT_C static TBool RequestorIdValid(

    93                         const CPosRequestor& aRequestor );

    94 

    95         /**

    96         * Returns requestor name. In this case the requestor Id String.

    97         * @param aRequestor Reference to the requestor for which

    98         *					the name is required.

    99         * @return name descriptor, ownership is transferred to caller

   100         */

   101         IMPORT_C HBufC* RequestorNameL( const CPosRequestor& aRequestor );

   102 

   103     protected: // From Base class MVPbkContactFindObserver.

   104        /**

   105         * Called when find is complete. The ownership of results in transferred

   106         * to this class.

   107         * In case of an error during find, the aResults may contain only 

   108         * partial results of the find.

   109         *

   110         * @param aResults Array of contact links that matched the find.

   111         *                 Callee must take ownership of this object in

   112         *                 the end of the function, ie. in case the function

   113         *                 does not leave.

   114         */

   115         virtual void FindCompleteL(MVPbkContactLinkArray* aResults);

   116 

   117        /**

   118         * Called in case the find fails for some reason.

   119         * 

   120         * @param aError One of the system wide error codes.

   121         */

   122         virtual void FindFailed(TInt aError);

   123     

   124     protected: // From Base class MVPbkSingleContactOperationObserver

   125        /**

   126         * Called when operation is completed.

   127         *

   128         * @param aOperation the completed operation.

   129         * @param aContact  the contact returned by the operation.

   130         *                  Client must take the ownership immediately.

   131         *

   132         */

   133         virtual void VPbkSingleContactOperationComplete(

   134                 MVPbkContactOperationBase& aOperation,

   135                 MVPbkStoreContact* aContact);

   136 

   137        /**

   138         * Called if the operation fails.

   139         *

   140         * @param aOperation    the failed operation.

   141         * @param aError        error code of the failure.

   142         */

   143         virtual void VPbkSingleContactOperationFailed(

   144                 MVPbkContactOperationBase& aOperation, 

   145                 TInt aError);

   146 

   147     protected: //From base class MVPbkContactStoreListObserver

   148         /**

   149          * Called when the opening process is complete, 

   150          * ie. all stores have been reported

   151          * either failed or successful open.

   152          */

   153         virtual void OpenComplete();

   154     

   155     protected: //From base class MVPbkContactStoreObserver

   156         /**

   157          * Called when a contact store is ready to use.

   158          */

   159         virtual void StoreReady(MVPbkContactStore& aContactStore);

   160 

   161         /**

   162          * Called when a contact store becomes unavailable.

   163          * Client may inspect the reason of the unavailability and decide whether or not

   164          * it will keep the store opened (ie. listen to the store events).

   165          * @param aContactStore The store that became unavailable.

   166          * @param aReason The reason why the store is unavailable.

   167          *                This is one of the system wide error codes.

   168          */

   169         virtual void StoreUnavailable(MVPbkContactStore& aContactStore, TInt aReason);

   170 

   171         /**

   172          * Called when changes occur in the contact store.

   173          * @see TVPbkContactStoreEvent

   174          *

   175          * @param aStoreEvent Event that has occured.

   176          */

   177         virtual void HandleStoreEventL(

   178                 MVPbkContactStore& aContactStore, 

   179                 TVPbkContactStoreEvent aStoreEvent);

   180     

   181     protected:

   182         /**

   183         * From Base class CActive

   184         * This method is called by the ActiveScheduler when the asynchronous

   185         * operation gets completed.

   186         */

   187         virtual void RunL();

   188 

   189         /**

   190         * From Base class CActive

   191         * If RunL leaves then it is handled in RunError.

   192         * @param aError the ErrorCode on which RunL did a Leave.

   193         */

   194         virtual TInt RunError(TInt aError);

   195 

   196         /**

   197         * From Base class CActive

   198         * DoCancel is called when the operation performed by the Active Object

   199         * needs to be cancelled.

   200         */

   201     	virtual void DoCancel();

   202     

   203     private: // Constructors

   204         /**

   205         * C++ default constructor.

   206         */

   207         CLocRequestorUtilsResolver();

   208 

   209 		/**

   210 		* The Symbian 2nd Phase Constructor is always Private

   211 		*/

   212 		void ConstructL();

   213 

   214     private: // New Methods

   215 		/**

   216         * This resolves the requestor by searching the contacts database

   217         * based on the requestor Id Information.

   218         * This searches only the default contact database now.

   219         */

   220         void ResolveRequestorNameL(CPosRequestor& aRequestor);

   221 

   222 		/**

   223         * This resolves the requestor by searching the contacts database

   224         * based on Phone Number.

   225         * This searches only the default contact database now.

   226         */

   227 		void ResolveRequestorByPhoneNumberL(

   228 								CPosRequestor& aRequestor);

   229 

   230 		/**

   231         * This resolves the requestor by searching the contacts database

   232         * based on Other Fields. Used to search based on E-mail and URL 

   233         * type. This searches only the default contact database now.

   234         */

   235 		void ResolveRequestorByOtherFieldsL(

   236 								CPosRequestor& aRequestor,

   237 								MVPbkFieldTypeList* aFieldType);

   238 

   239 		/**

   240 		* This sets the contact card name in the requestor.

   241 		* Also the Requestor Format is changes to GenericName

   242 		*/

   243 		void SetContactNameToRequestorL(TInt aCntLinkArrayIndex);

   244 

   245     private: // Helper methods

   246 		/**

   247 		* Schedule this dumy Active object to run again.

   248 		*/

   249         void ScheduleAORun();

   250         

   251 		/**

   252 		* Complete the Contact resolving operation.

   253 		*/

   254         void CompleteRequest();

   255     

   256     private: // State of Contacts Resolving

   257         enum TContactResolverState

   258             {

   259             KNoProcessing = 0,

   260             KResolveRequestor,

   261             KMatchedContacts,

   262             KRetrievedContactInfo,

   263             KResolvingCompleted

   264             };

   265     

   266     private: // member data

   267         // Ref : The current requestor stack that is being resolved.

   268     	RPointerArray<CPosRequestor>* iRequestors;

   269     	

   270     	// Own : Handle to the Contact Engine used to resolve the requestors

   271 		CVPbkContactManager* iPbkContactEngine;

   272 		

   273 		// Own: Parameter for the MPbk2ContactNameFormatter

   274         CPbk2SortOrderManager* iPbkSortManager;

   275         

   276 		// Own: Parameter for the Find API

   277         MPbk2ContactNameFormatter* iPbkCntFormatter;

   278         

   279 		// Own : ActiveSchedulerWait Loop.

   280 		CActiveSchedulerWait iWait;

   281 		

   282 		// Own : Handle to the Current operation being performed

   283 		MVPbkContactOperationBase* iCntsOperation;

   284 		

   285 		// Own : the Link to the matched contacts

   286 		MVPbkContactLinkArray* iCntLinkArray;

   287 		

   288 		// Own: The Contact retrieved

   289 		MVPbkStoreContact* iContact;

   290 

   291         // The current state of contacts resolving

   292         TContactResolverState iState;

   293         

   294 		// The index of the current requestor that is being processed.

   295 		TInt iCount;

   296     

   297         // The offset returned by the AddResourceFile

   298         // Used to delete the resource file.

   299         TInt iResourceOffset;

   300         

   301         // Eikon Env

   302         CEikonEnv* iEnv;

   303     };

   304 

   305 #endif // CLOCREQUESTORUTILSRESOLVER_H_

   306             

   307 // End of File