--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/homescreensrv_plat/context_utility_api/inc/hgcontextutility.h Thu Dec 17 08:54:17 2009 +0200
@@ -0,0 +1,327 @@
+/*
+* 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 */