diff -r 000000000000 -r 79c6a41cd166 contextutility/inc/hgcontextutilityimpl.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/contextutility/inc/hgcontextutilityimpl.h Thu Dec 17 08:54:17 2009 +0200 @@ -0,0 +1,434 @@ +/* +* 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 */