/*

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

* All rights reserved.

* This component and the accompanying materials are made available

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

* which accompanies this distribution, and is available

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

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:  Context publishing helper dll

*

*/

#ifndef HGCONTEXTUTILITYIMPL_H

#define HGCONTEXTUTILITYIMPL_H

#include <e32base.h>

#include <cflistener.h>

#include <bamdesca.h>

#include <badesca.h>

#include <mdccommon.h>

#include <coemain.h>

#include <e32hashtab.h>

class CCFClient;

class MVPbkContactLink;

class MVPbkStoreContact;

class CVPbkContactLinkArray;

class CMdESession;

/**

 *  Utility class offering static and non-static functions for

 *  publishing and accessing context through the Context Framework.

 */

NONSHARABLE_CLASS( CHgContextUtilityImpl ) :

        public CTimer,

        public MCFListener,

        public MCoeForegroundObserver

    {

public:

    static CHgContextUtilityImpl* NewL();

    static CHgContextUtilityImpl* NewLC();

    virtual ~CHgContextUtilityImpl();

    /**

     * Publishes context.

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

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

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

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

     * LocalServices capability.

     * @param   aContextType    context type, source is always KHgCFSource

     * @param   aContextData    value for the context

     */

    void PublishContextL( const TDesC& aContextType,

        const TDesC& aContextData );

    /**

     * Publishes context, the value will contain all the strings

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

     * @see PublishContextL

     * @param   aContextType    context type, source is always KHgCFSource

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

     * version of all the strings from this array

     */

    void PublishContextL( const TDesC& aContextType,

        const MDesCArray& aContextData );

    /**

     * Static version that uses the given CCFClient instance.

     * @param   aCFClient       a CCFClient instance

     * @param   aContextType    context type, source is always KHgCFSource

     * @param   aContextData    value for the context

     */

    static void PublishContextL( CCFClient& aCFClient,

        const TDesC& aContextType, const TDesC& aContextData );

    /**

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

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

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

     * @param   aContextType    context type, source is always KHgCFSource

     * @param   aContextData    value for the context

     * @param   aDelay          delay for the timer

     */

    void PublishContextDelayedL( const TDesC& aContextType,

        const TDesC& aContextData, TTimeIntervalMicroSeconds32 aDelay );

    /**

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

     * @param   aContextType    context type

     * @param   aContextData    string array

     * @param   aDelay          delay for the timer, in microseconds

     */

    void PublishContextDelayedL( const TDesC& aContextType,

        const MDesCArray& aContextData, TTimeIntervalMicroSeconds32 aDelay );

    /**

     * Requests the given context and returns the value for the

     * first result. Returns NULL if not found.

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

     */        

    HBufC* GetContextL( const TDesC& aContextType );

    /**

     * Requests the given context and returns the value for the

     * first result. Returns NULL if not found.

     * @param   aContextSource  context source

     * @param   aContextType    context type

     */

    HBufC* GetContextL( const TDesC& aContextSource,

        const TDesC& aContextType );

    /**

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

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

     * @param   aArray      string array

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

     */

    static HBufC* BuildCombinedStringL( const MDesCArray& aArray );

    /**

     * Splits the given combined string and appends the components to

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

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

     * then aString is appended to aArray without any changes.

     * @param   aString     combined string, input

     * @param   aArray      array, output

     */

    static void SplitCombinedStringL( const TDesC& aString,

        CDesCArray& aArray );

    /**

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

     * The pointer is left on the cleanup stack.

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

     */

    HBufC* MakeLinkPublishableLC( const MVPbkContactLink& aLink );

    /**

     * Publishes contact context.

     * @param   aContact            contact

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

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

     * pending value will not be published.

     */

    void PublishContactContextL( const MVPbkStoreContact& aContact,

        const TTimeIntervalMicroSeconds32& aDelay );

    /**

     * Publishes contact context.

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

     * only after this function returns.

     * @param   aContactLink        contact link

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

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

     * pending value will not be published.

     */

    void PublishContactContextL( const MVPbkContactLink& aContactLink,

        const TTimeIntervalMicroSeconds32& aDelay );

    /**

     * Publishes contact context.

     * Attempts to publish an empty value will be ignored.

     *

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

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

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

     *

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

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

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

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

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

     * pending value will not be published.

     */

    void PublishContactContextL( const TDesC& aContactName,

        const TTimeIntervalMicroSeconds32& aDelay );

    /**

     * Overload for publishing multiple contacts.

     * @param   aContacts           contact array

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

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

     * pending value will not be published.

     */

    void PublishContactContextL(

        const RPointerArray<MVPbkStoreContact>& aContacts,

        const TTimeIntervalMicroSeconds32& aDelay );

    /**

     * Overload for publishing multiple contacts.

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

     * only after this function returns.

     * @param   aContactLinks       contact link array

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

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

     * pending value will not be published.

     */

    void PublishContactContextL(

        const CVPbkContactLinkArray& aContactLinks,

        const TTimeIntervalMicroSeconds32& aDelay );

    /**

     * Overload for publishing multiple contacts.

     * @param   aContactNames   string array, for element format

     * see PublishContactContextL(const TDesC&)

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

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

     * pending value will not be published.

     */

    void PublishContactContextL( const MDesCArray& aContactNames,

        const TTimeIntervalMicroSeconds32& aDelay );

    /**

     * Publishes freetext context.

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

     * @param   aText   some text, typically the highlighted substring

     * from a viewer or editor control

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

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

     * pending value will not be published.

     */

    void PublishTextContextL( const TDesC& aText,

        const TTimeIntervalMicroSeconds32& aDelay );

    /**

     * Publishes URL context.

     * @param   aUrl    URL

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

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

     * pending value will not be published.

     */

    void PublishUrlContextL( const TDesC& aUrl,

        const TTimeIntervalMicroSeconds32& aDelay );

    /**

     * Publishes date/time context.

     * @param   aTime   time

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

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

     * pending value will not be published.

     */

    void PublishTimeContextL( const TTime& aTime,

        const TTimeIntervalMicroSeconds32& aDelay );

    /**

     * Publishes photo context.

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

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

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

     * pending value will not be published.

     */

    void PublishPhotoContextL( const TDesC& aFilename,

        const TTimeIntervalMicroSeconds32& aDelay );

    /**

     * Publishes photo context.

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

     * @param   aMdeSession opened metadata engine session

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

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

     * pending value will not be published.

     */

    void PublishPhotoContextL( TItemId aMdeItemId,

        CMdESession& aMdeSession,

        const TTimeIntervalMicroSeconds32& aDelay );

    /**

     * Publishes TV context.

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

     * @param   aChannelName        channel name

     * @param   aProgramName        program name

     * @param   aProgramDescription program description

     * @param   aGenre              genre

     */

    void PublishTvContextL( const TDesC& aChannelName,

        const TDesC& aProgramName, const TDesC& aProgramDescription,

        const TDesC& aGenre );

    /**

     * Publishes an account id as contact context.

     *

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

     * @param   aAccountId  the account id

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

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

     * pending value will not be published.

     */

    void PublishServiceIdL( const TDesC& aServiceId,

        const TDesC& aAccountId,

        const TTimeIntervalMicroSeconds32& aDelay = 0 );

    /**

     * Enables or disables automatic re-publishing of the latest

     * context (published via this context utility instance) whenever

     * the application comes to foreground.

     *

     * It is DISABLED by default.

     *

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

     * context publishing in HandleForegroundEventL etc.

     *

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

     * environment is not available.

     *

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

     */

    void RePublishWhenFgL( TBool aEnable );

    /**

     * Enables or disables context publishing when being in background.

     * Applies to all PublishContextL variants.

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

     * caller application is not in foreground.

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

     * allowed in that case.

     *

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

     * from applications that are not in foreground.

     *

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

     */

    void AllowPublishFromBackground( TBool aAllow );

    /**

     * @see CHgContextUtility::AddMusicContextInfo

     */

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

    /**

     * @see CHgContextUtility::AddMusicContextInfo

     */

    void PublishMusicContextL( 

        const TTimeIntervalMicroSeconds32& aDelay = 0 );

    /**

     * @see CHgContextUtility::PublishRadioContextL

     */

    void PublishRadioContextL( 

            const TDesC& aRadioName,

            const TDesC& aRadioUrl,

            const TDesC& aRadioFrequency,

            const TDesC& aRadioRDSPI );

private: // from MCFListener

    void ContextIndicationL( const CCFContextIndication& aChangedContext );

    void ActionIndicationL( const CCFActionIndication& aActionToExecute );

    void HandleContextFrameworkError( TCFError aError,

        const TDesC& aSource, const TDesC& aType );

    TAny* Extension( const TUid& aExtensionUid ) const;

private: // from MCoeForegroundObserver

    void HandleGainingForeground();

    void HandleLosingForeground();

private: // from CTimer

    void RunL();

    TInt RunError( TInt aError );

private:

    /**

     * Constructor.

     */

    CHgContextUtilityImpl();

    /**

     * 2nd phase constructor.

     */

    void ConstructL();

    /**

     * Creates CCFClient instance if not yet done.

     * Does not leave if creation fails.

     * Returns ETrue if iCFClient is usable.

     */    

    TBool CFReady();

    /**

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

     * the focused window group's wgid.

     * Always returns ETrue if CCoeEnv is not available.

     */

    TBool IsForeground();

    /**

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

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

     */

    TBool AllowedToPublish();

    /**

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

     * 

     * @param aKey Key to be checked and published.

     * @param aDelay Delay for publishing the context data. 

     */

    void VerifyAndPublishMusicContextL( 

        const TDesC& aKey,

        const TTimeIntervalMicroSeconds32& aDelay );

    /**

     * Simple wrapper to handle between delayed and instant publish.

     * @see PublishContextL

     * @see PublishContextDelayedL

     */

    void PublishContextL( 

        const TDesC& aContextType,

        const TDesC& aContextData,

        const TTimeIntervalMicroSeconds32& aDelay );

    CCFClient* iCFClient;

    HBufC* iPendingContextType;

    HBufC* iPendingContextData;

    CDesCArray* iPendingContextDataArray;

    HBufC* iLastContextType;

    HBufC* iLastContextData;

    TBool iFgWatchEnabled;

    CCoeEnv* iEnv; // not own

    TBool iAllowPublishFromBackground;

    /**

     * List of parameters to be published. Owns pointers.

     */

    RPtrHashMap<TDesC, TDesC> iMusicContextInfo;

    };

#endif /* HGCONTEXTUTILITYIMPL_H */