1 /*

     2 * Copyright (c) 2005-2006 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Interface for Homescreen content publisher plug-ins.

    15 *

    16 */

    17 

    18 #ifndef _HSCONTENTPUBLISHER_H

    19 #define _HSCONTENTPUBLISHER_H

    20 

    21 // System includes

    22 #include <e32base.h>

    23 #include <ecom/ecom.h>

    24 

    25 // User includes

    26 #include <hscontentpublisheruid.hrh>

    27 #include <hspublisherinfo.h>

    28 

    29 // Constants

    30 /**

    31  * ECom plugin interface UID

    32  *

    33  * @since S60 5.2 

    34  */

    35 const TUid KInterfaceUidHsContentPlugin = { HS_UID_ECOM_INTERFACE_CONTENTPUBLISHER }; 

    36 

    37 // Forward declarations

    38 class MAiContentObserver;

    39 class MAiPluginSettings;

    40 

    41 // Type definitions

    42 typedef RPointerArray< MAiPluginSettings > RAiSettingsItemArray;

    43 

    44 /**

    45  *  ECom plug-in interface that Homescreen plug-ins must implement.

    46  *  It is used to control plug-in life cycle: load/destroy plug-ins;

    47  *  suspend/resume plug-in execution.

    48  *

    49  *  @since S60 5.2

    50  */

    51 class CHsContentPublisher : public CBase

    52     {

    53 public:

    54     // Data types

    55 

    56     /**

    57      * CHsContentPublisher start-up reason.

    58      * 

    59      * @since S60 5.2

    60      * @see CHsContentPublisher::Start()

    61      */

    62     enum TStartReason

    63         {

    64         ESystemStartup = 1,

    65         EPageStartup,

    66         EPluginStartup

    67         };

    68     

    69     /**

    70      * CHsContentPublisher shutdown reason.

    71      * 

    72      * @since S60 5.2

    73      * @see CHsContentPublisher::Stop()

    74      */

    75     enum TStopReason

    76         {

    77         ESystemShutdown = 1,

    78         EPageShutdown,

    79         EPluginShutdown

    80         };

    81     

    82     /**

    83      * CHsContentPublisher resume reason.

    84      * 

    85      * @since S60 5.2

    86      * @see CHsContentPublisher::Resume()

    87      */

    88     enum TResumeReason

    89         {

    90         /**

    91          * Homescreen is visible.

    92          */

    93         EForeground = 1

    94         };

    95     

    96     /**

    97      * CHsContentPublisher suspend reason.

    98      * 

    99      * @since S60 5.2

   100      * @see CHsContentPublisher::Suspend()

   101      */

   102     enum TSuspendReason

   103         {

   104         /**

   105          * Homescreen is invisible.

   106          */        

   107         EBackground = 1,

   108         /**

   109          * Backup/Restore is ongoing.

   110          *

   111          * The plug-in must realease all its resources 

   112          * which affects to backup/restore operation.

   113          */        

   114         EBackupRestore,        

   115         /**

   116          * General Theme is changed.

   117          *

   118          * The plug-in must re-create any data which is themeable.

   119          */

   120         EGeneralThemeChange

   121         };

   122     

   123     /**

   124      * CHsContentPublisher properties.

   125      * 

   126      * @since S60 5.2

   127      * @see CHsContentPublisher::SetProperty()

   128      * @see CHsContentPublisher::GetProperty() 

   129      */

   130     enum TProperty

   131         {

   132         /**

   133          * Enables read-only access to iterator of content selectors. GetProperty

   134          * must return instance of MAiContentItemIterator for content selectors.

   135          */        

   136         EPublisherContent = 1,

   137         

   138         /**

   139          * Enables read-only access to iterator of content references. GetProperty

   140          * must return instance of MAiContentItemIterator for content references.

   141          */    

   142         EPublisherResources,

   143         

   144         /**

   145          * Enables read-only access to iterator of events supported by plug-in.

   146          * GetProperty must return instance of MAiContentItemIterator for events.

   147          */    

   148         EPublisherEvents,

   149         

   150         /**

   151          * Provides access to MAiContentRequest interface for refreshing a content

   152          * item.

   153          * @see EPublisherContent

   154          */    

   155         EContentRequest,

   156         

   157         /**

   158          * Provides access to MAiContentRequest interface for refreshing a resource

   159          * item.

   160          * @see EPublisherResources

   161          */    

   162         EResourceRequest,

   163         

   164         /**

   165          * Provides access to localized plugin name if supported. HBufC*

   166          * @see EPublisherResources

   167          */    

   168         EPluginName

   169         };

   170 

   171 public:

   172     // Constructor and destructor

   173 

   174     /**

   175      * Creates a new plug-in instance based on implementation UID.

   176      *     

   177      * @param aPublisherInfo This plug-in's publisher info.

   178      * @return pointer to the instantiated interface implementation.

   179      * @pre Interface implementation exists by uid aImpUid.

   180      */

   181     inline static CHsContentPublisher* NewL( 

   182         const THsPublisherInfo& aPublisherInfo );

   183 

   184     /**

   185      * Destroys instance of the plug-in. Called by the framework during plug-in

   186      * destruction phase.

   187      */

   188     inline ~CHsContentPublisher();

   189 

   190 public:  

   191     // new functions

   192         

   193     /**

   194      * This method transits the plug-in into "Idle" state.

   195      * Parameter aReason explains the plug-in's startup reason.

   196      * Based on THsStartReason plug-in may decide its startup behavior.

   197      *

   198      * This method is called by the framework after plugin is constructed and configured.

   199      *

   200      * @since S60 5.2

   201      * @param aReason startup reason, see TStartReason.

   202      * @pre None

   203      * @post Plugin is in Idle state.     

   204      */

   205     virtual void Start( TStartReason aReason ) = 0;

   206     

   207     /**

   208      * This method transits the plug-in into its final state.

   209      * Parameter aReason explains the plug-in's shutdwon reason.

   210      * Based on THsStopReason plug-in may prepare itself for next startup.

   211      * 

   212      * This method is called by the framework before plugin is destroyed.

   213      *

   214      * @since S60 5.2

   215      * @param aReason reason for state change, see TStopReason.

   216      * @pre None

   217      * @post Plugin is ready to be destroyed.

   218      */

   219     virtual void Stop( TStopReason aReason ) = 0;

   220 

   221     /**

   222      * This method transits the plug-in into "Alive" state.

   223      *     

   224      * In this state the plug-in is allowed to actively publish data 

   225      * to its observers, and it can consume memory and CPU resources.

   226      *

   227      * @since S60 5.2

   228      * @param aReason reason for state change, see TResumeReason.

   229      * @pre None

   230      * @post Plugin is in "Alive" state and actively publishes its data.

   231      *

   232      * Short example what a typical resume implementation does.

   233      * @code

   234      * if( !MyEngineCreated() )

   235      *      {

   236      *      CreateEngine();

   237      *      StartEngine();

   238      *      }

   239      *  else

   240      *      {

   241      *      // Publish only changed data!

   242      *      RefreshData();

   243      *      }          

   244      * @endcode

   245      */    

   246     virtual void Resume( TResumeReason aReason ) = 0;

   247     

   248     /**

   249      * This method transits the plug-in into "Suspended" state.

   250      * 

   251      * In this state the plug-in is not allowed to publish data 

   252      * to its observers. CPU resource usage must be minimal, e.g.

   253      * timers must be stopped, outstanding asynchronous operations must

   254      * be canceled, etc.

   255      *

   256      * @since S60 5.2

   257      * @param aReason reason for state change, see TSuspendReason.

   258      * @pre None

   259      * @post Plugin suspends publishing data and free resources (timers etc).

   260      *

   261      * Short example what a typical suspend implementation does.

   262      * @code

   263      * SuspendEngine();

   264      * @endcode

   265      */    

   266     virtual void Suspend( TSuspendReason aReason ) = 0;

   267     

   268     /**

   269     * This method transits the plug-in into "Online" sub-state.

   270     * In this state plugin is allowed to use network connections.

   271     *

   272     * @since S60 5.2

   273     */            

   274     inline virtual void SetOnline();

   275 

   276     /**

   277     * This method transits the plug-in into "Offline" sub-state. 

   278     * In this state plugin is not allowed to use network connections.

   279     *

   280     * @since S60 5.2

   281     */                

   282     inline virtual void SetOffline();

   283     

   284     /**

   285      * Adds the content observer / subscriber to the plug-in. The plug-in must

   286      * maintain a registry of subscribers and publish data to all of them

   287      * when new content is available in "Alive" state.

   288      *

   289      * @since S60 5.2

   290      * @param aObserver content observer to register.

   291      * @pre None

   292      * @post Plugin publishes its data to the subscribed observer.

   293      *

   294      * Short example what a typical subscribe implementation does and

   295      * one alternative how observers are used.

   296      * @code

   297      * if( !ObserverAlreadyAdded( aObserver ) )

   298      *     {

   299      *     iMyContentObservers.AppendL( aObserver );

   300      *     }

   301      *

   302      * ...

   303      *

   304      * // Engine reports data changed in "Alive" state

   305      *

   306      * const TDesC& data = iEngine->LatestData();

   307      * for( TInt i = 0; i < iMyContentObservers.Count(); ++i )

   308      *     {

   309      *     iMyContentObservers[i].Publish( data );

   310      *     }

   311      * @endcode

   312      */    

   313     virtual void SubscribeL( MAiContentObserver& aObserver ) = 0;

   314     

   315     /**

   316      * Configures the plug-in.

   317      *

   318      * @since S60 5.2

   319      * @param aSettings setting items defined in the UI definition.

   320      *                  This plugin takes ownership of the

   321      *                  MAiPluginSettings objects in the array.

   322      *                  If this method leaves the caller will handle the cleanup.

   323      * @pre None

   324      * @post Plugin has set its state according to relevant settings.

   325      *

   326      * Short example how to read plugin settings.

   327      * @code

   328      * for( TInt i = 0; i < aSettings.Count(); ++i )

   329      *     {

   330      *     MAiPluginSettingsItem& item = (aSettings[i])->AiPluginSettingsItem();

   331      *     TInt32 value = 0;

   332      *     if( ParseInt( value, item.Value() ) != KErrNone )

   333      *         {

   334      *         continue;

   335      *         }

   336      *     if( value < 0 )

   337      *         {

   338      *         continue; // All our settings are counts, skip bad settings

   339      *         }

   340      *     if( item.Key() == EMySettingMaxUsers )

   341      *         {

   342      *         iEngine->SetMaxUsers( value );

   343      *         continue;

   344      *         }

   345      *     else if( item.Key() == EMySettingNumItems )

   346      *         {

   347      *         iNumItems = value;

   348      *         continue;

   349      *         }

   350      *     }

   351      * // aSettings ownership is passed to the plug-in, destroy array.

   352      * aSettings.ResetAndDestroy();

   353      * @endcode

   354      */    

   355     virtual void ConfigureL( RAiSettingsItemArray& aSettings ) = 0;

   356            

   357     /**

   358      * Sets property value.

   359      *

   360      * @since S60 5.2

   361      * @param aProperty - identification of property.

   362      * @param aValue - contains pointer to property value.

   363      * @see TProperty.

   364      *     

   365      * An example of setting a property

   366      * @code               

   367      * void CMyPlugin::SetPropertyL( TInt TProperty, TAny* aValue )

   368      *     {

   369      *     if( !aValue ) 

   370      *         {

   371      *         return;

   372      *         }

   373      *

   374      *     // Save the property here to a member variable

   375      *     }

   376      * @endcode

   377      */    

   378     inline virtual void SetProperty( TProperty aProperty, TAny* aAny );

   379     

   380     /**

   381      * Gets property value.

   382      *

   383      * @since S60 5.2

   384      * @param aProperty - identification of property.

   385      * @return Pointer to property value.

   386      * @see TProperty.

   387      *

   388      * An example of getting a property

   389      * @code          

   390      * void CMyPlugin::ConstructL()

   391      *     {     

   392      *     iContent = AiUtility::CreateContentItemArrayIteratorL( KMyPluginContent );

   393      *     iResources = AiUtility::CreateContentItemArrayIteratorL( KMyPluginResources );

   394      *     iEvents = AiUtility::CreateContentItemArrayIteratorL( KMyPluginEvents );

   395      *     }

   396      *

   397      * TAny* CMyPlugin::GetPropertyL( TProperty aProperty )

   398      *     {

   399      *     switch( aProperty )

   400      *         {

   401      *         case EPublisherContent:

   402      *             return iContent;

   403      * 

   404      *         case EPublisherResources:

   405      *             return iResources;

   406      * 

   407      *         case EPublisherEvents:

   408      *             return iEvents;

   409      *         }

   410      *     return NULL;

   411      *     }

   412      * @endcode

   413      */    

   414     inline virtual TAny* GetProperty( TProperty aProperty );

   415     

   416     /**

   417      * Invoked by the framework when the plug-in must handle an event.

   418      *

   419      * @since S60 5.2

   420      * @param aEvent - unique identifier of event from plug-in content model.

   421      * @param aParam - parameters associated with event. Each UI Definition

   422      *        declares events in the format: <event name>(<event params>),

   423      *        where <event name> is mapped by the framework to unique

   424      *        identifier supplied in aEvent, <event params> are provided to

   425      *        plug-in as-is in the descriptor.

   426      */    

   427     inline virtual void HandleEvent( TInt aEvent, const TDesC& aParam );

   428     

   429     /**

   430     * Invoked by the framework when the plug-in must handle an event.

   431     *

   432     * @since S60 5.2

   433     * @param aEventName - name of the event from plug-in content model.

   434     * @param aParam - parameters associated with event. Each UI Definition

   435     *        declares events in the format: <event name>(<event params>),

   436     *        where  <event name> mapping to unique identifier supplied by event 

   437     *        is failed by the frame work then the  <event name> and  

   438     *        <event params>  are provied to plug-in as-is in the descriptor.

   439     */    

   440     inline virtual void HandleEvent( const TDesC& aEventName, const TDesC& aParam );

   441     

   442     /**

   443     * Invoked by the framework to query whether the plug-in has a menu item.

   444     *

   445     * @since S60 5.2

   446     * @param aMenuItem menu item name

   447     * @return ETrue if plugin has specific menu item, EFalse otherwise

   448     */        

   449     inline virtual TBool HasMenuItem( const TDesC& aMenuItem );

   450             

   451     /**

   452      * Returns interface extension. In S60 5.2 extensions are not provided. 

   453      *

   454      * @param  aUid - UID of the extension interface to access.

   455      * @return the extension interface. Actual type depends on the passed aUid 

   456      *         argument.

   457      *

   458      * Example on how to properly return an extension.

   459      * @code

   460      * return NULL; // Requested extension not supported

   461      * @endcode

   462      */    

   463     inline virtual TAny* Extension( TUid aUid );

   464     

   465     /**

   466      * Gets plug-in's publisher info.

   467      *

   468      * @since S60 5.2

   469      * @return PublisherInfo 

   470      */        

   471     inline const THsPublisherInfo& PublisherInfo() const;

   472     

   473 private:     

   474     // data

   475     

   476     /** An identifier used during destruction. */

   477     TUid iDestructKey;

   478     /** Publisher info. */

   479     mutable THsPublisherInfo iPublisherInfo;

   480     };

   481 

   482 #include <hscontentpublisher.inl>

   483 

   484 #endif // _HSCONTENTPUBLISHER_H

   485 

   486 // End of file