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