/*

* 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