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