--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/homescreensrv_plat/ai_plugin_management_api/inc/hscontentpublisher.h Fri Feb 19 23:07:29 2010 +0200
@@ -0,0 +1,486 @@
+/*
+* Copyright (c) 2005-2006 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: Interface for Homescreen content publisher plug-ins.
+*
+*/
+
+#ifndef _HSCONTENTPUBLISHER_H
+#define _HSCONTENTPUBLISHER_H
+
+// System includes
+#include <e32base.h>
+#include <ecom/ecom.h>
+
+// User includes
+#include <hscontentpublisheruid.hrh>
+#include <hspublisherinfo.h>
+
+// Constants
+/**
+ * ECom plugin interface UID
+ *
+ * @since S60 5.2
+ */
+const TUid KInterfaceUidHsContentPlugin = { HS_UID_ECOM_INTERFACE_CONTENTPUBLISHER };
+
+// Forward declarations
+class MAiContentObserver;
+class MAiPluginSettings;
+
+// Type definitions
+typedef RPointerArray< MAiPluginSettings > RAiSettingsItemArray;
+
+/**
+ * ECom plug-in interface that Homescreen plug-ins must implement.
+ * It is used to control plug-in life cycle: load/destroy plug-ins;
+ * suspend/resume plug-in execution.
+ *
+ * @since S60 5.2
+ */
+class CHsContentPublisher : public CBase
+ {
+public:
+ // Data types
+
+ /**
+ * CHsContentPublisher start-up reason.
+ *
+ * @since S60 5.2
+ * @see CHsContentPublisher::Start()
+ */
+ enum TStartReason
+ {
+ ESystemStartup = 1,
+ EPageStartup,
+ EPluginStartup
+ };
+
+ /**
+ * CHsContentPublisher shutdown reason.
+ *
+ * @since S60 5.2
+ * @see CHsContentPublisher::Stop()
+ */
+ enum TStopReason
+ {
+ ESystemShutdown = 1,
+ EPageShutdown,
+ EPluginShutdown
+ };
+
+ /**
+ * CHsContentPublisher resume reason.
+ *
+ * @since S60 5.2
+ * @see CHsContentPublisher::Resume()
+ */
+ enum TResumeReason
+ {
+ /**
+ * Homescreen is visible.
+ */
+ EForeground = 1
+ };
+
+ /**
+ * CHsContentPublisher suspend reason.
+ *
+ * @since S60 5.2
+ * @see CHsContentPublisher::Suspend()
+ */
+ enum TSuspendReason
+ {
+ /**
+ * Homescreen is invisible.
+ */
+ EBackground = 1,
+ /**
+ * Backup/Restore is ongoing.
+ *
+ * The plug-in must realease all its resources
+ * which affects to backup/restore operation.
+ */
+ EBackupRestore,
+ /**
+ * General Theme is changed.
+ *
+ * The plug-in must re-create any data which is themeable.
+ */
+ EGeneralThemeChange
+ };
+
+ /**
+ * CHsContentPublisher properties.
+ *
+ * @since S60 5.2
+ * @see CHsContentPublisher::SetProperty()
+ * @see CHsContentPublisher::GetProperty()
+ */
+ enum TProperty
+ {
+ /**
+ * Enables read-only access to iterator of content selectors. GetProperty
+ * must return instance of MAiContentItemIterator for content selectors.
+ */
+ EPublisherContent = 1,
+
+ /**
+ * Enables read-only access to iterator of content references. GetProperty
+ * must return instance of MAiContentItemIterator for content references.
+ */
+ EPublisherResources,
+
+ /**
+ * Enables read-only access to iterator of events supported by plug-in.
+ * GetProperty must return instance of MAiContentItemIterator for events.
+ */
+ EPublisherEvents,
+
+ /**
+ * Provides access to MAiContentRequest interface for refreshing a content
+ * item.
+ * @see EPublisherContent
+ */
+ EContentRequest,
+
+ /**
+ * Provides access to MAiContentRequest interface for refreshing a resource
+ * item.
+ * @see EPublisherResources
+ */
+ EResourceRequest,
+
+ /**
+ * Provides access to localized plugin name if supported. HBufC*
+ * @see EPublisherResources
+ */
+ EPluginName
+ };
+
+public:
+ // Constructor and destructor
+
+ /**
+ * Creates a new plug-in instance based on implementation UID.
+ *
+ * @param aPublisherInfo This plug-in's publisher info.
+ * @return pointer to the instantiated interface implementation.
+ * @pre Interface implementation exists by uid aImpUid.
+ */
+ inline static CHsContentPublisher* NewL(
+ const THsPublisherInfo& aPublisherInfo );
+
+ /**
+ * Destroys instance of the plug-in. Called by the framework during plug-in
+ * destruction phase.
+ */
+ inline ~CHsContentPublisher();
+
+public:
+ // new functions
+
+ /**
+ * This method transits the plug-in into "Idle" state.
+ * Parameter aReason explains the plug-in's startup reason.
+ * Based on THsStartReason plug-in may decide its startup behavior.
+ *
+ * This method is called by the framework after plugin is constructed and configured.
+ *
+ * @since S60 5.2
+ * @param aReason startup reason, see TStartReason.
+ * @pre None
+ * @post Plugin is in Idle state.
+ */
+ virtual void Start( TStartReason aReason ) = 0;
+
+ /**
+ * This method transits the plug-in into its final state.
+ * Parameter aReason explains the plug-in's shutdwon reason.
+ * Based on THsStopReason plug-in may prepare itself for next startup.
+ *
+ * This method is called by the framework before plugin is destroyed.
+ *
+ * @since S60 5.2
+ * @param aReason reason for state change, see TStopReason.
+ * @pre None
+ * @post Plugin is ready to be destroyed.
+ */
+ virtual void Stop( TStopReason aReason ) = 0;
+
+ /**
+ * This method transits the plug-in into "Alive" state.
+ *
+ * In this state the plug-in is allowed to actively publish data
+ * to its observers, and it can consume memory and CPU resources.
+ *
+ * @since S60 5.2
+ * @param aReason reason for state change, see TResumeReason.
+ * @pre None
+ * @post Plugin is in "Alive" state and actively publishes its data.
+ *
+ * Short example what a typical resume implementation does.
+ * @code
+ * if( !MyEngineCreated() )
+ * {
+ * CreateEngine();
+ * StartEngine();
+ * }
+ * else
+ * {
+ * // Publish only changed data!
+ * RefreshData();
+ * }
+ * @endcode
+ */
+ virtual void Resume( TResumeReason aReason ) = 0;
+
+ /**
+ * This method transits the plug-in into "Suspended" state.
+ *
+ * In this state the plug-in is not allowed to publish data
+ * to its observers. CPU resource usage must be minimal, e.g.
+ * timers must be stopped, outstanding asynchronous operations must
+ * be canceled, etc.
+ *
+ * @since S60 5.2
+ * @param aReason reason for state change, see TSuspendReason.
+ * @pre None
+ * @post Plugin suspends publishing data and free resources (timers etc).
+ *
+ * Short example what a typical suspend implementation does.
+ * @code
+ * SuspendEngine();
+ * @endcode
+ */
+ virtual void Suspend( TSuspendReason aReason ) = 0;
+
+ /**
+ * This method transits the plug-in into "Online" sub-state.
+ * In this state plugin is allowed to use network connections.
+ *
+ * @since S60 5.2
+ */
+ inline virtual void SetOnline();
+
+ /**
+ * This method transits the plug-in into "Offline" sub-state.
+ * In this state plugin is not allowed to use network connections.
+ *
+ * @since S60 5.2
+ */
+ inline virtual void SetOffline();
+
+ /**
+ * Adds the content observer / subscriber to the plug-in. The plug-in must
+ * maintain a registry of subscribers and publish data to all of them
+ * when new content is available in "Alive" state.
+ *
+ * @since S60 5.2
+ * @param aObserver content observer to register.
+ * @pre None
+ * @post Plugin publishes its data to the subscribed observer.
+ *
+ * Short example what a typical subscribe implementation does and
+ * one alternative how observers are used.
+ * @code
+ * if( !ObserverAlreadyAdded( aObserver ) )
+ * {
+ * iMyContentObservers.AppendL( aObserver );
+ * }
+ *
+ * ...
+ *
+ * // Engine reports data changed in "Alive" state
+ *
+ * const TDesC& data = iEngine->LatestData();
+ * for( TInt i = 0; i < iMyContentObservers.Count(); ++i )
+ * {
+ * iMyContentObservers[i].Publish( data );
+ * }
+ * @endcode
+ */
+ virtual void SubscribeL( MAiContentObserver& aObserver ) = 0;
+
+ /**
+ * Configures the plug-in.
+ *
+ * @since S60 5.2
+ * @param aSettings setting items defined in the UI definition.
+ * This plugin takes ownership of the
+ * MAiPluginSettings objects in the array.
+ * If this method leaves the caller will handle the cleanup.
+ * @pre None
+ * @post Plugin has set its state according to relevant settings.
+ *
+ * Short example how to read plugin settings.
+ * @code
+ * for( TInt i = 0; i < aSettings.Count(); ++i )
+ * {
+ * MAiPluginSettingsItem& item = (aSettings[i])->AiPluginSettingsItem();
+ * TInt32 value = 0;
+ * if( ParseInt( value, item.Value() ) != KErrNone )
+ * {
+ * continue;
+ * }
+ * if( value < 0 )
+ * {
+ * continue; // All our settings are counts, skip bad settings
+ * }
+ * if( item.Key() == EMySettingMaxUsers )
+ * {
+ * iEngine->SetMaxUsers( value );
+ * continue;
+ * }
+ * else if( item.Key() == EMySettingNumItems )
+ * {
+ * iNumItems = value;
+ * continue;
+ * }
+ * }
+ * // aSettings ownership is passed to the plug-in, destroy array.
+ * aSettings.ResetAndDestroy();
+ * @endcode
+ */
+ virtual void ConfigureL( RAiSettingsItemArray& aSettings ) = 0;
+
+ /**
+ * Sets property value.
+ *
+ * @since S60 5.2
+ * @param aProperty - identification of property.
+ * @param aValue - contains pointer to property value.
+ * @see TProperty.
+ *
+ * An example of setting a property
+ * @code
+ * void CMyPlugin::SetPropertyL( TInt TProperty, TAny* aValue )
+ * {
+ * if( !aValue )
+ * {
+ * return;
+ * }
+ *
+ * // Save the property here to a member variable
+ * }
+ * @endcode
+ */
+ inline virtual void SetProperty( TProperty aProperty, TAny* aAny );
+
+ /**
+ * Gets property value.
+ *
+ * @since S60 5.2
+ * @param aProperty - identification of property.
+ * @return Pointer to property value.
+ * @see TProperty.
+ *
+ * An example of getting a property
+ * @code
+ * void CMyPlugin::ConstructL()
+ * {
+ * iContent = AiUtility::CreateContentItemArrayIteratorL( KMyPluginContent );
+ * iResources = AiUtility::CreateContentItemArrayIteratorL( KMyPluginResources );
+ * iEvents = AiUtility::CreateContentItemArrayIteratorL( KMyPluginEvents );
+ * }
+ *
+ * TAny* CMyPlugin::GetPropertyL( TProperty aProperty )
+ * {
+ * switch( aProperty )
+ * {
+ * case EPublisherContent:
+ * return iContent;
+ *
+ * case EPublisherResources:
+ * return iResources;
+ *
+ * case EPublisherEvents:
+ * return iEvents;
+ * }
+ * return NULL;
+ * }
+ * @endcode
+ */
+ inline virtual TAny* GetProperty( TProperty aProperty );
+
+ /**
+ * Invoked by the framework when the plug-in must handle an event.
+ *
+ * @since S60 5.2
+ * @param aEvent - unique identifier of event from plug-in content model.
+ * @param aParam - parameters associated with event. Each UI Definition
+ * declares events in the format: <event name>(<event params>),
+ * where <event name> is mapped by the framework to unique
+ * identifier supplied in aEvent, <event params> are provided to
+ * plug-in as-is in the descriptor.
+ */
+ inline virtual void HandleEvent( TInt aEvent, const TDesC& aParam );
+
+ /**
+ * Invoked by the framework when the plug-in must handle an event.
+ *
+ * @since S60 5.2
+ * @param aEventName - name of the event from plug-in content model.
+ * @param aParam - parameters associated with event. Each UI Definition
+ * declares events in the format: <event name>(<event params>),
+ * where <event name> mapping to unique identifier supplied by event
+ * is failed by the frame work then the <event name> and
+ * <event params> are provied to plug-in as-is in the descriptor.
+ */
+ inline virtual void HandleEvent( const TDesC& aEventName, const TDesC& aParam );
+
+ /**
+ * Invoked by the framework to query whether the plug-in has a menu item.
+ *
+ * @since S60 5.2
+ * @param aMenuItem menu item name
+ * @return ETrue if plugin has specific menu item, EFalse otherwise
+ */
+ inline virtual TBool HasMenuItem( const TDesC& aMenuItem );
+
+ /**
+ * Returns interface extension. In S60 5.2 extensions are not provided.
+ *
+ * @param aUid - UID of the extension interface to access.
+ * @return the extension interface. Actual type depends on the passed aUid
+ * argument.
+ *
+ * Example on how to properly return an extension.
+ * @code
+ * return NULL; // Requested extension not supported
+ * @endcode
+ */
+ inline virtual TAny* Extension( TUid aUid );
+
+ /**
+ * Gets plug-in's publisher info.
+ *
+ * @since S60 5.2
+ * @return PublisherInfo
+ */
+ inline const THsPublisherInfo& PublisherInfo() const;
+
+private:
+ // data
+
+ /** An identifier used during destruction. */
+ TUid iDestructKey;
+ /** Publisher info. */
+ mutable THsPublisherInfo iPublisherInfo;
+ };
+
+#include <hscontentpublisher.inl>
+
+#endif // _HSCONTENTPUBLISHER_H
+
+// End of file