1 /*

     2 * Copyright (c) 2007-2007 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:  Wrapper for CMS contact fetching

    15 *

    16 */

    17 

    18 

    19 #ifndef C_CCACMSCONTACTFETCHERWRAPPER_H

    20 #define C_CCACMSCONTACTFETCHERWRAPPER_H

    21 

    22 #include <VPbkFieldTypeSelectorFactory.h>

    23 #include "cmsnotificationhandlerapi.h"

    24 

    25 class CCCAParameter;

    26 class RCmsContact;

    27 class RCmsSession;

    28 class CCmsContactFieldInfo;

    29 

    30 /**

    31  * Interface-class to notify observers about contact data fields

    32  *

    33  * Inherit from this class and start getting notifications.

    34  *

    35  *  @code

    36  *   See CCCAppCmsContactFetcherWrapper

    37  *  @endcode

    38  *

    39  *  @lib ccappcommlauncherplugin.dll

    40  *  @since S60 v5.0

    41  */

    42 class MCCAppContactFieldDataObserver

    43     {

    44 public:

    45 

    46     /**

    47      * Simple class to transfer parameters through observer

    48      * interface. 

    49      *

    50      * @since S60 v5.0

    51      */  

    52     class TParameter

    53         {

    54     public:

    55 

    56         enum TNotifyType

    57             {

    58             EUninitialised,

    59             EContactInfoAvailable,

    60             EContactDataFieldAvailable,

    61             EContactsChanged,

    62             EContactDeleted,

    63             EContactPresenceChanged

    64             };

    65 

    66         inline TParameter():

    67             iType( EUninitialised ),

    68             iContactInfo( NULL ),

    69             iContactField( NULL ),

    70             iStatusFlag( 0 ){};

    71     

    72         /*  

    73          * With iType the observer knows what data is available.

    74          *

    75          * @since S60 v5.0

    76          */ 

    77         TNotifyType iType;

    78         /*  

    79          * With iStatusFlag the observer knows are fetching operations

    80          * completed. In the last fetched field notify this flag is set

    81          * as EOperationsCompleted (from CCCAppCmsContactFetcherWrapper::TOperationState)

    82          * 

    83          * @since S60 v5.0

    84          */ 

    85          TInt iStatusFlag;

    86          /*  

    87          * Only the one member indicated by TNotifyType above

    88          * will have valid data. Others will be NULL.

    89          *

    90          * Note: Ownership of the objects stays in 

    91          * CCCAppCmsContactFetcherWrapper-class

    92          *

    93          * @since S60 v5.0

    94          */  

    95         CCmsContactFieldInfo* iContactInfo;

    96         CCmsContactField* iContactField;

    97         };

    98    

    99     /**

   100      * Observer for CCCAppCmsContactFetcherWrapper -class.

   101      * This callback is triggered when there is information

   102      * available about the enabled fields of contact or 

   103      * contact field is fetched.

   104      *

   105      * Note: Ownership of the object stays in 

   106      * CCCAppCmsContactFetcherWrapper-class

   107      *

   108      * @since S60 v5.0

   109      * @param aParameter containing the needed data

   110      */   

   111     virtual void ContactFieldDataObserverNotifyL( 

   112         MCCAppContactFieldDataObserver::TParameter& aParameter ) = 0;

   113 

   114     /**

   115      * Observer for CCCAppCmsContactFetcherWrapper -class.

   116      * This callback is triggered when there has been or

   117      * are errors during contact data fetching. If there has

   118      * been errors before observer registers itself, this

   119      * callback will be called immediately.

   120      *

   121      * @since S60 v5.0

   122      * @param aState state of CCCAppCmsContactFetcherWrapper-class

   123      * @param aError error occured

   124      */  

   125     virtual void ContactFieldDataObserverHandleErrorL( 

   126         TInt aState, TInt aError ) = 0;

   127 

   128     };

   129 

   130 /**

   131  * This class encapsulates the contact fetching functionality from CMS.

   132  *

   133  *  @code

   134  *

   135  *  // Basic usage

   136  *  // create the instance first

   137  *  iCmsWrapper = CCCAppCmsContactFetcherWrapper::InstanceL();//not owned

   138  *

   139  *  // 1st get whatever fetched so far

   140  *  const CCmsContactFieldInfo* info = iCmsWrapper->ContactInfo();//not owned

   141  *  if ( info )// if NULL, info fetching not completed

   142  *      {

   143  *      HandleTheInfoAsBestForYouL( *info );

   144  *      // if info is fetched, there can be actual fields fetched also

   145  *      RPointerArray<CCmsContactField> fieldArray = iCmsWrapper->ContactFieldDataArray();//not owned

   146  *      const TInt count = fieldArray.Count();

   147  *      for ( TInt i = 0; i < count; i++ )

   148  *          {

   149  *          HandleTheContactDataFieldAsYouLikeL( *fieldArray[i] );

   150  *          }

   151  *      }

   152  *

   153  *  // 2nd register as observer for following events

   154  *  iCmsWrapper->AddObserverL( *this );

   155  *

   156  *  // remember to remove observer when not needed anymore

   157  *

   158  *  iCmsWrapper->RemoveObserver( *this );

   159  *  iCmsWrapper->Release();

   160  *

   161  *  @endcode

   162  *

   163  *  @lib ccapputil.dll

   164  *  @since S60 v5.0

   165  */ 

   166 class CCCAppCmsContactFetcherWrapper : public CActive, public MCmsNotificationHandlerAPI

   167     {

   168 #ifdef __CCAPPUNITTESTMODE

   169     friend class T_CCCACmsContactFetcherWrapper;

   170 #endif// __COMMLAUNCHERPLUGINUNITTESTMODE   

   171 

   172 public: // Construction and destruction

   173 

   174     enum TWrapperParam

   175         {

   176         EDefaultFunctionality,

   177         /**

   178          * When this is used the contact information is searched also

   179          * from contact stores not defined in contact link

   180          */

   181         EFindContactFromOtherStores = 1

   182         };

   183     

   184     /**

   185      * Creates a new instance of this class. This should be used only

   186      * during the lifetime of CCApplication.

   187      *

   188      * Note: Deletion of this object is done by calling Release()

   189      *

   190      * @param aParameter contains the contact related information     

   191      * @param aWrapperParam contains wrapper specific parameters 

   192      * @return pointer to a new instance of this class

   193      */

   194     IMPORT_C static CCCAppCmsContactFetcherWrapper* CreateInstanceL( 

   195         CCCAParameter* aParameter, TWrapperParam aWrapperParam = EDefaultFunctionality );

   196 

   197 

   198 public: //new

   199 

   200     /**

   201      * States of the class

   202      *

   203      * @since S60 v5.0

   204      */ 

   205     enum TOperationState

   206         {

   207         EInitial,

   208         EOpeningContact,

   209         EFindingFromOtherStores,

   210         ELoadingEnabledFields,

   211         ELoadingFields,

   212         EOperationsCompleted,

   213         ESettingVoiceCallDefault

   214         };

   215 

   216     /**

   217      * Returns with pointer to already created instance. 

   218      *

   219      * Note: Deletion of this object is done by calling Release()

   220      *

   221      * @return pointer to a instance of this clas.

   222      */

   223     IMPORT_C static CCCAppCmsContactFetcherWrapper* InstanceL();

   224     

   225      /**

   226      * Adds observer to start receiving MCCAppContactFieldDataObserver-events

   227      *

   228      * @since S60 v5.0

   229      */

   230     IMPORT_C void Release();

   231 

   232     /**

   233      * Getter function for the CCmsContactFieldInfo. Returns NULL if

   234      * not fetched yet.

   235      * 

   236      * Note: Ownership of the object stays in 

   237      * CCCAppCmsContactFetcherWrapper-class

   238      *

   239      * @since S60 v5.0

   240      * @return CCmsContactFieldInfo contains info all the available fields

   241      */ 

   242     IMPORT_C const CCmsContactFieldInfo* ContactInfo();

   243 

   244     /**

   245      * Returns contact field array.

   246      *

   247      * Note: Ownership of the object stays in 

   248      * CCCAppCmsContactFetcherWrapper-class

   249      *

   250      * @since S60 v5.0

   251      */    

   252     IMPORT_C RPointerArray<CCmsContactField>& ContactFieldDataArray();

   253 

   254     /**

   255      * Returns packed contact identifiers

   256      *

   257      * @since S60 v5.0

   258      */    

   259     IMPORT_C HBufC8* ContactIdentifierLC();

   260 

   261     /**

   262      * Adds observer to start receiving MCCAppContactFieldDataObserver-events.

   263      * If there has been errors already, ContactFieldDataObserverHandleErrorL-

   264      * callback will be called immediately.

   265      *

   266      * @since S60 v5.0

   267      */    

   268     IMPORT_C void AddObserverL( MCCAppContactFieldDataObserver& aObserver );

   269 

   270     /**

   271      * Removes observer from observer queue

   272      *

   273      * @since S60 v5.0

   274      */    

   275     IMPORT_C void RemoveObserver( MCCAppContactFieldDataObserver& aObserver );

   276     

   277     /**

   278      * Checks if the service is available

   279      *

   280      * @since S60 v5.0

   281      * @param aContactAction Type of the service

   282      * @return TInt 1 if there is a service available, 0 otherwise. Voip is 

   283      * a special case having more levels than just on/off.

   284      */

   285     IMPORT_C TInt IsServiceAvailable( 

   286         VPbkFieldTypeSelectorFactory::TVPbkContactActionTypeSelector aContactAction );

   287     

   288     /**

   289      * Check from which store this contact is from

   290      *

   291      * @since S60 v5.0

   292      * @return store type containing this contact

   293      */

   294     IMPORT_C TCmsContactStore ContactStore() const;

   295     

   296     /**

   297      * Gets contact action field count for a current contact.

   298      * 

   299      * @param aContactAction contact action

   300      */

   301     IMPORT_C TInt GetContactActionFieldCount(

   302         VPbkFieldTypeSelectorFactory::TVPbkContactActionTypeSelector aContactAction);

   303     

   304     /**

   305     * From MCmsNotificationHandlerAPI

   306     * (see details from baseclass )

   307     */

   308     virtual void HandlePresenceNotificationL( CCmsContactField* aField );

   309     

   310     /**

   311      * From MCmsNotificationHandlerAPI

   312      * (see details from baseclass )

   313      */

   314     virtual void HandlePhonebookNotificationL( TCmsPhonebookEvent aNotificationType );

   315     

   316     /**

   317      * From MCmsNotificationHandlerAPI

   318      * (see details from baseclass )    

   319      */    

   320     virtual void CmsNotificationTerminatedL( TInt aStatus, 

   321         CCmsContactFieldItem::TCmsContactNotification aNotificationType );

   322     

   323     /**

   324      * Reset the associated contact from phonebook

   325      */

   326     virtual void RefetchContactL();

   327 

   328 	/**

   329      * Checks whether the Current contact is top contact.

   330      *

   331      * @return ETrue if aContact it top contact, otherwise EFalse 

   332      */

   333     IMPORT_C TBool IsTopContact();

   334 

   335 private:// new

   336 

   337     /**

   338      * Starts the fetching.

   339      *

   340      * @since S60 v5.0

   341      */ 

   342     void StartFetcherL( TBool aSetDefault = EFalse );        

   343     

   344     /**

   345      * Opens the contact from contact db

   346      *

   347      * @since S60 v5.0

   348      */ 

   349     void OpenContactL();

   350 

   351     /**

   352      * Starts the asynchronic part of the fetching.

   353      *

   354      * @since S60 v5.0

   355      */    

   356     void StartAsyncFetchingL();     

   357     

   358     /**

   359      * Finds the possible matches from other contact stores than

   360      * the one defined in contact link

   361      *

   362      * @since S60 v5.0

   363      */ 

   364     void FindFromOtherStoresL();    

   365     

   366     /**

   367      * Starts the fetching of enabled fields -operation.

   368      *

   369      * @since S60 v5.0

   370      */ 

   371     void FetchContactInfoL();

   372     

   373     /**

   374      * Informs observers about the change. Then start fetching

   375      * concrete data fields.

   376      *

   377      * @since S60 v5.0

   378      */       

   379     void HandleContactInfoUpdateL();

   380 

   381     /**

   382      * Depending on the iNeededContactData-array constructed

   383      * by MapPreferredCommMethodsToAddressFieldsL will start

   384      * the contact data field fetching.

   385      *

   386      * @since S60 v5.0

   387      */        

   388     void StartContactDataFieldFetchingL();

   389 

   390     /**

   391      * Fetches one contact data field set using CMS.

   392      * A MCCAppCLContactChangeObserver::ContactChangedNotifyL 

   393      * is used to notify when information has been fetched.

   394      *

   395      * @since S60 v5.0

   396      */        

   397     void FetchContactDataFieldL();

   398 

   399     /**

   400      * Updates the contact data storage and informs

   401      * observers about the change. Then start fetching

   402      * next field or completes the operation.

   403      *

   404      * @since S60 v5.0

   405      */        

   406     void HandleContactDataFieldUpdateL();

   407  

   408      /**

   409      * Notifies the observers.

   410      *

   411      * @since S60 v5.0

   412      */ 

   413     void NotifyErrorL();

   414     

   415     /**

   416     * Set default for voice call.

   417     *

   418     * @since S60 v5.0

   419     */

   420     void SetDefaultForVoiceCallL();

   421 private: // from base class CActive

   422  

   423     /**

   424      * From CActive

   425      */

   426     void RunL();

   427 

   428     /**

   429      * From CActive

   430      */

   431     TInt RunError( TInt aError );

   432 

   433     /**

   434      * From CActive

   435      */

   436     void DoCancel();

   437 

   438 private: // construction

   439 

   440     CCCAppCmsContactFetcherWrapper( CCCAParameter* aParameter, TWrapperParam aWrapperParam );

   441     void ConstructL();

   442     /**

   443      * Destructor.

   444      */

   445     ~CCCAppCmsContactFetcherWrapper();

   446 

   447 private: // data

   448     

   449     /**

   450      * CCA parameter.

   451      * Not own.

   452      */    

   453     CCCAParameter* iParameter;

   454     /**

   455      * CMS session

   456      * Own.

   457      */

   458     RCmsSession iCmsSession;

   459     /**

   460      * Data field fetcher

   461      * Own.

   462      */    

   463     RCmsContact iCmsContactDataFetcher;

   464     /**

   465      * The internal state of this class

   466      * Own.

   467      */

   468     TOperationState iHandlerState;

   469     /**

   470      * Contact data field used when fetched new field

   471      * Not own.

   472      */

   473     CCmsContactField* iContactField;

   474     /**

   475      * Index for the iNeededContactData-array

   476      * Own.

   477      */    

   478     TInt iContactDataFetchingIndex;

   479     /**

   480      * Pointer to enabled fields.

   481      * Own.

   482      */

   483     CCmsContactFieldInfo* iContactInfo;

   484     /**

   485      * Pointer to already fetched contact data fields.

   486      * Own.

   487      */

   488     RPointerArray<CCmsContactField> iContactFieldsArray;

   489     /**

   490      * Pointer to observers.

   491      * Not owed.

   492      */

   493     RPointerArray<MCCAppContactFieldDataObserver> iObservers;

   494     /**

   495      * Member to store error code

   496      * Own.

   497      */

   498     TInt iErrorsOccured;

   499     /**

   500      * Singleton reference counter.

   501      * Own.

   502      */

   503     TInt iRefCount;

   504     /**

   505      * Info related to wrapper

   506      * Own.

   507      */

   508     TInt iWrapperParam;

   509     };

   510 

   511 

   512 #endif // C_CCACMSCONTACTFETCHERWRAPPER_H

   513 

   514 // End of File