1 /*

     2 * Copyright (c) 2008 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:  Context publishing helper dll

    15 *

    16 */

    17 

    18 

    19 #ifndef HGCONTEXTUTILITYIMPL_H

    20 #define HGCONTEXTUTILITYIMPL_H

    21 

    22 #include <e32base.h>

    23 #include <cflistener.h>

    24 #include <bamdesca.h>

    25 #include <badesca.h>

    26 #include <mdccommon.h>

    27 #include <coemain.h>

    28 #include <e32hashtab.h>

    29 

    30 class CCFClient;

    31 class MVPbkContactLink;

    32 class MVPbkStoreContact;

    33 class CVPbkContactLinkArray;

    34 class CMdESession;

    35 

    36 /**

    37  *  Utility class offering static and non-static functions for

    38  *  publishing and accessing context through the Context Framework.

    39  */

    40 NONSHARABLE_CLASS( CHgContextUtilityImpl ) :

    41         public CTimer,

    42         public MCFListener,

    43         public MCoeForegroundObserver

    44     {

    45 public:

    46     static CHgContextUtilityImpl* NewL();

    47     static CHgContextUtilityImpl* NewLC();

    48     virtual ~CHgContextUtilityImpl();

    49     

    50     /**

    51      * Publishes context.

    52      * Also defines the context if it has not been defined.

    53      * Publishing empty value is not allowed, however such errors are ignored

    54      * here so the function will not leave when CFW responds with KErrArgument.

    55      * The security policy for the context will be set to require

    56      * LocalServices capability.

    57      * @param   aContextType    context type, source is always KHgCFSource

    58      * @param   aContextData    value for the context

    59      */

    60     void PublishContextL( const TDesC& aContextType,

    61         const TDesC& aContextData );

    62 

    63     /**

    64      * Publishes context, the value will contain all the strings

    65      * from the given array, typically by using some separator character.

    66      * @see PublishContextL

    67      * @param   aContextType    context type, source is always KHgCFSource

    68      * @param   aContextData    value for the context will be a combined

    69      * version of all the strings from this array

    70      */

    71     void PublishContextL( const TDesC& aContextType,

    72         const MDesCArray& aContextData );

    73     

    74     /**

    75      * Static version that uses the given CCFClient instance.

    76      * @param   aCFClient       a CCFClient instance

    77      * @param   aContextType    context type, source is always KHgCFSource

    78      * @param   aContextData    value for the context

    79      */

    80     static void PublishContextL( CCFClient& aCFClient,

    81         const TDesC& aContextType, const TDesC& aContextData );

    82 

    83     /**

    84      * Publishes context but only after a short interval, using a timer.

    85      * If it is called again before the timer expires then the timer

    86      * is restarted (and so the previous pending value is never published).

    87      * @param   aContextType    context type, source is always KHgCFSource

    88      * @param   aContextData    value for the context

    89      * @param   aDelay          delay for the timer

    90      */

    91     void PublishContextDelayedL( const TDesC& aContextType,

    92         const TDesC& aContextData, TTimeIntervalMicroSeconds32 aDelay );

    93 

    94     /**

    95      * Overload for delayed publishing of a value combined from multiple strings.

    96      * @param   aContextType    context type

    97      * @param   aContextData    string array

    98      * @param   aDelay          delay for the timer, in microseconds

    99      */

   100     void PublishContextDelayedL( const TDesC& aContextType,

   101         const MDesCArray& aContextData, TTimeIntervalMicroSeconds32 aDelay );

   102 

   103     /**

   104      * Requests the given context and returns the value for the

   105      * first result. Returns NULL if not found.

   106      * @param   aContextType    context type, the source is always KHgCFSource

   107      */        

   108     HBufC* GetContextL( const TDesC& aContextType );

   109     

   110     /**

   111      * Requests the given context and returns the value for the

   112      * first result. Returns NULL if not found.

   113      * @param   aContextSource  context source

   114      * @param   aContextType    context type

   115      */

   116     HBufC* GetContextL( const TDesC& aContextSource,

   117         const TDesC& aContextType );

   118 

   119     /**

   120      * Creates a combined string from the elements of the given array.

   121      * Returns NULL if the array has less than 2 elements.

   122      * @param   aArray      string array

   123      * @return  combined string or NULL, ownership transferred to caller

   124      */

   125     static HBufC* BuildCombinedStringL( const MDesCArray& aArray );

   126 

   127     /**

   128      * Splits the given combined string and appends the components to

   129      * the given array. The initial content of the array is not modified.

   130      * If aString does not seem to be a string combined from multiple entries

   131      * then aString is appended to aArray without any changes.

   132      * @param   aString     combined string, input

   133      * @param   aArray      array, output

   134      */

   135     static void SplitCombinedStringL( const TDesC& aString,

   136         CDesCArray& aArray );

   137 

   138     /**

   139      * Gets a string that can be published straight via PublishContextL.

   140      * The pointer is left on the cleanup stack.

   141      * Returned & pushed pointer may also be NULL is something goes wrong.

   142      */

   143     HBufC* MakeLinkPublishableLC( const MVPbkContactLink& aLink );

   144 

   145     /**

   146      * Publishes contact context.

   147      * @param   aContact            contact

   148      * @param   aDelay              if non-zero then context is published only after

   149      * a short delay. If a new publish call is made before the timer fires the

   150      * pending value will not be published.

   151      */

   152     void PublishContactContextL( const MVPbkStoreContact& aContact,

   153         const TTimeIntervalMicroSeconds32& aDelay );

   154 

   155     /**

   156      * Publishes contact context.

   157      * This may include async operations and therefore the actual publishing may happen

   158      * only after this function returns.

   159      * @param   aContactLink        contact link

   160      * @param   aDelay              if non-zero then context is published only after

   161      * a short delay. If a new publish call is made before the timer fires the

   162      * pending value will not be published.

   163      */

   164     void PublishContactContextL( const MVPbkContactLink& aContactLink,

   165         const TTimeIntervalMicroSeconds32& aDelay );

   166 

   167     /**

   168      * Publishes contact context.

   169      * Attempts to publish an empty value will be ignored.

   170      *

   171      * Prefer using the overloads taking vpbk contact or link, whenever possible.

   172      * Use this in case of unknown contacts only, that is, a name, phone number,

   173      * or email address that does not belong to a phonebook contact.

   174      *

   175      * @param   aContactName    formatted name, phone number, or email address,

   176      * or a combination of them, e.g. "firstname lastname", "+12345678",

   177      * "lastname firstname <abcd@efg.com>", "firstname, lastname <0501234567>".

   178      * @param   aDelay              if non-zero then context is published only after

   179      * a short delay. If a new publish call is made before the timer fires the

   180      * pending value will not be published.

   181      */

   182     void PublishContactContextL( const TDesC& aContactName,

   183         const TTimeIntervalMicroSeconds32& aDelay );

   184 

   185     /**

   186      * Overload for publishing multiple contacts.

   187      * @param   aContacts           contact array

   188      * @param   aDelay              if non-zero then context is published only after

   189      * a short delay. If a new publish call is made before the timer fires the

   190      * pending value will not be published.

   191      */

   192     void PublishContactContextL(

   193         const RPointerArray<MVPbkStoreContact>& aContacts,

   194         const TTimeIntervalMicroSeconds32& aDelay );

   195 

   196     /**

   197      * Overload for publishing multiple contacts.

   198      * This may include async operations and therefore the actual publishing may happen

   199      * only after this function returns.

   200      * @param   aContactLinks       contact link array

   201      * @param   aDelay              if non-zero then context is published only after

   202      * a short delay. If a new publish call is made before the timer fires the

   203      * pending value will not be published.

   204      */

   205     void PublishContactContextL(

   206         const CVPbkContactLinkArray& aContactLinks,

   207         const TTimeIntervalMicroSeconds32& aDelay );

   208 

   209     /**

   210      * Overload for publishing multiple contacts.

   211      * @param   aContactNames   string array, for element format

   212      * see PublishContactContextL(const TDesC&)

   213      * @param   aDelay              if non-zero then context is published only after

   214      * a short delay. If a new publish call is made before the timer fires the

   215      * pending value will not be published.

   216      */

   217     void PublishContactContextL( const MDesCArray& aContactNames,

   218         const TTimeIntervalMicroSeconds32& aDelay );

   219 

   220     /**

   221      * Publishes freetext context.

   222      * Not to be used for bulk text (e.g. full content of some text viewer component).

   223      * @param   aText   some text, typically the highlighted substring

   224      * from a viewer or editor control

   225      * @param   aDelay              if non-zero then context is published only after

   226      * a short delay. If a new publish call is made before the timer fires the

   227      * pending value will not be published.

   228      */

   229     void PublishTextContextL( const TDesC& aText,

   230         const TTimeIntervalMicroSeconds32& aDelay );

   231 

   232     /**

   233      * Publishes URL context.

   234      * @param   aUrl    URL

   235      * @param   aDelay              if non-zero then context is published only after

   236      * a short delay. If a new publish call is made before the timer fires the

   237      * pending value will not be published.

   238      */

   239     void PublishUrlContextL( const TDesC& aUrl,

   240         const TTimeIntervalMicroSeconds32& aDelay );

   241 

   242     /**

   243      * Publishes date/time context.

   244      * @param   aTime   time

   245      * @param   aDelay              if non-zero then context is published only after

   246      * a short delay. If a new publish call is made before the timer fires the

   247      * pending value will not be published.

   248      */

   249     void PublishTimeContextL( const TTime& aTime,

   250         const TTimeIntervalMicroSeconds32& aDelay );

   251 

   252     /**

   253      * Publishes photo context.

   254      * @param   aFilename   name of image file, with full path

   255      * @param   aDelay              if non-zero then context is published only after

   256      * a short delay. If a new publish call is made before the timer fires the

   257      * pending value will not be published.

   258      */

   259     void PublishPhotoContextL( const TDesC& aFilename,

   260         const TTimeIntervalMicroSeconds32& aDelay );

   261 

   262     /**

   263      * Publishes photo context.

   264      * @param   aMdeItemId  item id for the Image object in MDS

   265      * @param   aMdeSession opened metadata engine session

   266      * @param   aDelay              if non-zero then context is published only after

   267      * a short delay. If a new publish call is made before the timer fires the

   268      * pending value will not be published.

   269      */

   270     void PublishPhotoContextL( TItemId aMdeItemId,

   271         CMdESession& aMdeSession,

   272         const TTimeIntervalMicroSeconds32& aDelay );

   273 

   274     /**

   275      * Publishes TV context.

   276      * Pass KNullDesC if some of the needed data is not available.

   277      * @param   aChannelName        channel name

   278      * @param   aProgramName        program name

   279      * @param   aProgramDescription program description

   280      * @param   aGenre              genre

   281      */

   282     void PublishTvContextL( const TDesC& aChannelName,

   283         const TDesC& aProgramName, const TDesC& aProgramDescription,

   284         const TDesC& aGenre );

   285 

   286     /**

   287      * Publishes an account id as contact context.

   288      *

   289      * @param   aServiceId  the service prefix, e.g. "Ovi"

   290      * @param   aAccountId  the account id

   291      * @param   aDelay   if non-zero then context is published only after

   292      * a short delay. If a new publish call is made before the timer fires the

   293      * pending value will not be published.

   294      */

   295     void PublishServiceIdL( const TDesC& aServiceId,

   296         const TDesC& aAccountId,

   297         const TTimeIntervalMicroSeconds32& aDelay = 0 );

   298 

   299     /**

   300      * Enables or disables automatic re-publishing of the latest

   301      * context (published via this context utility instance) whenever

   302      * the application comes to foreground.

   303      *

   304      * It is DISABLED by default.

   305      *

   306      * By enabling this the applications do not have to care about

   307      * context publishing in HandleForegroundEventL etc.

   308      *

   309      * The feature needs CCoeEnv and calls will be ignored if the

   310      * environment is not available.

   311      *

   312      * @param   aEnable     flag to turn the feature on/off

   313      */

   314     void RePublishWhenFgL( TBool aEnable );

   315 

   316     /**

   317      * Enables or disables context publishing when being in background.

   318      * Applies to all PublishContextL variants.

   319      * If disabled then no context will be published if it seems that the

   320      * caller application is not in foreground.

   321      * Has no effect if there is no CCoeEnv available, publishing is always

   322      * allowed in that case.

   323      *

   324      * It is DISABLED by default, that is, publishing is not allowed

   325      * from applications that are not in foreground.

   326      *

   327      * @param   aAllow  flag to turn the feature on/off

   328      */

   329     void AllowPublishFromBackground( TBool aAllow );

   330     

   331     /**

   332      * @see CHgContextUtility::AddMusicContextInfo

   333      */

   334     void AddMusicContextInfoL( const TDesC& aKey, const TDesC& aData );

   335     

   336     /**

   337      * @see CHgContextUtility::AddMusicContextInfo

   338      */

   339     void PublishMusicContextL( 

   340         const TTimeIntervalMicroSeconds32& aDelay = 0 );

   341     

   342     /**

   343      * @see CHgContextUtility::PublishRadioContextL

   344      */

   345     void PublishRadioContextL( 

   346             const TDesC& aRadioName,

   347             const TDesC& aRadioUrl,

   348             const TDesC& aRadioFrequency,

   349             const TDesC& aRadioRDSPI );

   350 

   351 private: // from MCFListener

   352     void ContextIndicationL( const CCFContextIndication& aChangedContext );

   353     void ActionIndicationL( const CCFActionIndication& aActionToExecute );

   354     void HandleContextFrameworkError( TCFError aError,

   355         const TDesC& aSource, const TDesC& aType );

   356     TAny* Extension( const TUid& aExtensionUid ) const;

   357 

   358 private: // from MCoeForegroundObserver

   359     void HandleGainingForeground();

   360     void HandleLosingForeground();

   361 

   362 private: // from CTimer

   363     void RunL();

   364     TInt RunError( TInt aError );

   365 

   366 private:

   367     /**

   368      * Constructor.

   369      */

   370     CHgContextUtilityImpl();

   371     

   372     /**

   373      * 2nd phase constructor.

   374      */

   375     void ConstructL();

   376 

   377     /**

   378      * Creates CCFClient instance if not yet done.

   379      * Does not leave if creation fails.

   380      * Returns ETrue if iCFClient is usable.

   381      */    

   382     TBool CFReady();

   383     

   384     /**

   385      * Returns ETrue if the root window's wgid is same as

   386      * the focused window group's wgid.

   387      * Always returns ETrue if CCoeEnv is not available.

   388      */

   389     TBool IsForeground();

   390     

   391     /**

   392      * Returns ETrue if publishing context is allowed at the moment.

   393      * Uses IsForeground and the allow-publish-from-background setting.

   394      */

   395     TBool AllowedToPublish();

   396     

   397     /**

   398      * Makes sure the specific key contains valid data and publishes it.

   399      * 

   400      * @param aKey Key to be checked and published.

   401      * @param aDelay Delay for publishing the context data. 

   402      */

   403     void VerifyAndPublishMusicContextL( 

   404         const TDesC& aKey,

   405         const TTimeIntervalMicroSeconds32& aDelay );

   406     

   407     /**

   408      * Simple wrapper to handle between delayed and instant publish.

   409      * @see PublishContextL

   410      * @see PublishContextDelayedL

   411      */

   412     void PublishContextL( 

   413         const TDesC& aContextType,

   414         const TDesC& aContextData,

   415         const TTimeIntervalMicroSeconds32& aDelay );

   416 

   417     CCFClient* iCFClient;

   418     HBufC* iPendingContextType;

   419     HBufC* iPendingContextData;

   420     CDesCArray* iPendingContextDataArray;

   421 

   422     HBufC* iLastContextType;

   423     HBufC* iLastContextData;

   424     TBool iFgWatchEnabled;

   425     CCoeEnv* iEnv; // not own

   426     TBool iAllowPublishFromBackground;

   427     

   428     /**

   429      * List of parameters to be published. Owns pointers.

   430      */

   431     RPtrHashMap<TDesC, TDesC> iMusicContextInfo;

   432     };

   433     

   434 #endif /* HGCONTEXTUTILITYIMPL_H */