/*

* 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 HGCONTEXTUTILITY_H

#define HGCONTEXTUTILITY_H

#include <e32base.h>

#include <e32cmn.h>

#include <bamdesca.h>

#include <badesca.h>

#include <mdccommon.h>

#include <hg/hgcontextutilitybase.h>

class MVPbkStoreContact;

class MVPbkContactLink;

class CVPbkContactLinkArray;

class CMdESession;

/**

 *  Utility class to publish and access context through the Context Framework.

 *  @lib hgcontextutility.lib

 *

 *  Typical usage in applications that are publishing context:

 *  During construction:

 *  \code

 *    iContextUtility = CHgContextUtility::NewL();

 *    iContextUtility->RePublishWhenFgL( ETrue );

 *  \endcode

 *  Publishing is accomplished with one single call, for example:

 *  \code

 *    void ContactChanged( MVPbkStoreContact* aNewContact ) {

 *      ...

 *      iContextUtility->PublishContactContextL( *aNewContact );

 *      ...

 *  \endcode

 *

 *  By default publishing requests are ignored if the application is

 *  not in foreground (does not apply to apps that do not have the

 *  ui environment). If there is still a good reason to allow this

 *  then call AllowPublishFromBackground( ETrue ).

 */

NONSHARABLE_CLASS( CHgContextUtility ) : public CHgContextUtilityBase

    {

public:

    /**

     * 2-phased constructor.

     */

    IMPORT_C static CHgContextUtility* NewL();

    /**

     * 2-phased constructor.

     */

    IMPORT_C static CHgContextUtility* NewLC();

    /*

     * Destructor.

     */

    IMPORT_C ~CHgContextUtility();

    /**

     * 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.

     */

    IMPORT_C void PublishContactContextL( const MVPbkStoreContact& aContact,

        const TTimeIntervalMicroSeconds32& aDelay = 0 );

    /**

     * Publishes contact context.

     * @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.

     */

    IMPORT_C void PublishContactContextL( const MVPbkContactLink& aContactLink,

        const TTimeIntervalMicroSeconds32& aDelay = 0 );

    /**

     * 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.

     */

    IMPORT_C void PublishContactContextL( const TDesC& aContactName,

        const TTimeIntervalMicroSeconds32& aDelay = 0 );

    /**

     * Overload for publishing multiple contacts.

     * Ownership of passed pointers is not taken.

     * @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.

     */

    IMPORT_C void PublishContactContextL(

        const RPointerArray<MVPbkStoreContact>& aContacts,

        const TTimeIntervalMicroSeconds32& aDelay = 0 );

    /**

     * Overload for publishing multiple contacts.

     * @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.

     */

    IMPORT_C void PublishContactContextL(

        const CVPbkContactLinkArray& aContactLinks,

        const TTimeIntervalMicroSeconds32& aDelay = 0 );

    /**

     * 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.

     */

    IMPORT_C void PublishContactContextL( const MDesCArray& aContactNames,

        const TTimeIntervalMicroSeconds32& aDelay = 0 );

    /**

     * 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.

     */

    IMPORT_C void PublishTextContextL( const TDesC& aText,

        const TTimeIntervalMicroSeconds32& aDelay = 0 );

    /**

     * 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.

     */

    IMPORT_C void PublishUrlContextL( const TDesC& aUrl,

        const TTimeIntervalMicroSeconds32& aDelay = 0 );

    /**

     * 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.

     */

    IMPORT_C void PublishTimeContextL( const TTime& aTime,

        const TTimeIntervalMicroSeconds32& aDelay = 0 );

    /**

     * 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.

     */

    IMPORT_C void PublishPhotoContextL( const TDesC& aFilename,

        const TTimeIntervalMicroSeconds32& aDelay = 0 );

    /**

     * 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.

     */

    IMPORT_C void PublishPhotoContextL( TItemId aMdeItemId,

        CMdESession& aMdeSession,

        const TTimeIntervalMicroSeconds32& aDelay = 0 );

    /**

     * 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

     */

    IMPORT_C 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.

     */

    IMPORT_C 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

     */

    IMPORT_C 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

     */

    IMPORT_C void AllowPublishFromBackground( TBool aAllow );

    /**

     * Adds new music context info to music context publishing parameters.

     * This method is to be used in context with PublishMusicContextL. Fill in the

     * parameters and then call PublishMusicContextL.

     * This parameter list is cleared after publishing music context.

     * 

     * @param aKey Name of the key to be published.

     * @param aData Data for the key.

     * @leave KErrNotFound, when key is empty.

     * @leave KErrAlreadyExists, when key is already in the list.

     * @see hgcontextdef.h for keys

     * @see PublishMusicContextL

     */

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

    /**

     * Publishes music context from provided parameters as music context.

     * Publishes all known (in hgcontextdef.h) music context fields as music

     * context. All keys, which do not contain any data, are automatically 

     * filled with '<unknown>' -string.

     * Clears the parameter list after publishing the context.

     * 

     * @leave KErrNotReady, when music context data parameter list is empty.

     * * @see hgcontextdef.h for keys

     * @see AddMusicContextInfoL

     */

    IMPORT_C void PublishMusicContextL( 

        const TTimeIntervalMicroSeconds32& aDelay = 0 );

    /**

     * Publishes Radio context.

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

     * @param   aRadioName        radio name

     * @param   aRadioUrl         radio url

     * @param   aRadioFrequency   radio frequency

     * @param   aRadioRDSPI       radio identification code

     */

    IMPORT_C void PublishRadioContextL( 

            const TDesC& aRadioName,

            const TDesC& aRadioUrl,

            const TDesC& aRadioFrequency,

            const TDesC& aRadioRDSPI );

    /**

     * 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

     */

    IMPORT_C 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

     */

    IMPORT_C static void SplitCombinedStringL( const TDesC& aString,

        CDesCArray& aArray );

protected:

    CHgContextUtility();

    void ConstructL();

    };

#endif /* HGCONTEXTUTILITY_H */