diff -r 2f40063dfb5c -r 66e84aa0ed46 contextutility/inc/hgcontextutilityimpl.h --- a/contextutility/inc/hgcontextutilityimpl.h Wed Mar 03 15:38:34 2010 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,434 +0,0 @@ -/* -* 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 -#include -#include -#include -#include -#include -#include - -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 ", "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& 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 iMusicContextInfo; - }; - -#endif /* HGCONTEXTUTILITYIMPL_H */