diff -r 502e5d91ad42 -r 15e4dd19031c homescreensrv_plat/context_utility_api/inc/hgcontextutility.h --- a/homescreensrv_plat/context_utility_api/inc/hgcontextutility.h Mon Mar 15 12:41:53 2010 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,327 +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 HGCONTEXTUTILITY_H -#define HGCONTEXTUTILITY_H - -#include -#include -#include -#include -#include -#include - -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 ", "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& 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 '' -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 */