1 /*

     2 * Copyright (c) 2005-2007 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:  Plug-in main class

    15 *

    16 */

    17 

    18 

    19 #ifndef SAPIDATAPLUGIN_H

    20 #define SAPIDATAPLUGIN_H

    21 

    22 #include <aicontentpublisher.h>

    23 #include <aipropertyextension.h>

    24 #include <aicontentmodel.h>

    25 #include <aieventhandlerextension.h>

    26 

    27 class MAiContentObserver;

    28 class MAiContentItemIterator;

    29 class MAiPSPropertyObserver;

    30 class CSapiData;

    31 class CDesC16Array;

    32 class CGulIcon;

    33 

    34 /**

    35  *  @ingroup group_sapidataplugin

    36  *

    37  *  Plug-in main class

    38  *

    39  *  @since S60 v3.2

    40  */

    41 class CSapiDataPlugin : public CAiContentPublisher,

    42                      	public MAiPropertyExtension,

    43                      	public MAiEventHandlerExtension

    44                     

    45     {

    46     

    47 public :

    48 	 /**

    49 	 * Plugin's network state.

    50 	 */

    51 	enum TPluginNetworkStatus 

    52 		{

    53 		EUnknown, 

    54 		EOffline,

    55 		EOnline

    56 		};

    57 	

    58 	/**

    59 	 * Plugin's state.

    60 	 */

    61 	enum TPluginStates

    62 		{

    63 		ENone,

    64 		EResume,

    65 		ESuspend,

    66 		EInActive,

    67 		};

    68 public:

    69 

    70     /**

    71     * Part of the two phased constuction

    72     *

    73     * @param none

    74     * @return none

    75     */

    76     static CSapiDataPlugin* NewL();

    77     

    78     /**

    79     * Destructor

    80     *

    81     * @param none

    82     * @return none

    83     */

    84     ~CSapiDataPlugin();

    85 

    86 private:

    87     

    88     /**

    89     * Constructor

    90     *

    91     * @param none

    92     * @return none

    93     */

    94     CSapiDataPlugin();

    95 	

    96     /**

    97     * Part of the two phased construction

    98     *

    99     * @param void

   100     * @return void

   101     */

   102     void ConstructL();

   103 

   104     /**

   105     * Resume the plug-in.

   106     *

   107     * @param aReason reason for state change, see TAiTransitionChange.

   108     * @return void

   109     */    

   110     void DoResumeL(TAiTransitionReason aReason);

   111     

   112 public: // from base class CAiContentPublisher

   113     

   114     /**

   115     * From CAiContentPublisher

   116     * The method is called by the framework to request the plug-in free all

   117     * memory and CPU resources and close all its open files, e.g. the plug-in 

   118     * should unload its engines due backup operation. The method transits the 

   119     * plug-in to "Idle" state.

   120     *

   121     * @param aReason reason for state change, see TAiTransitionChange.

   122     * @return void

   123     */

   124     void Stop( TAiTransitionReason aReason );

   125 

   126     /**

   127     * From CAiContentPublisher

   128     * The method is called by the framework to instruct plug-in that it is

   129     * allowed to consume CPU resources, e.g plug-in is able to run timers,

   130     * perform asynchronous operations, etc. The method transits the plug-in

   131     * to "Alive" state.

   132     *

   133     * @param aReason reason for state change, see TAiTransitionChange.

   134     * @return void

   135     */

   136     void Resume( TAiTransitionReason aReason );

   137 

   138     /**

   139     * From CAiContentPublisher

   140     * The method is called by the framework to instruct plug-in that it is

   141     * not allowed to consume CPU resources, e.g plug-in MUST stop each

   142     * timers, cancel outstanding asynchronous operations, etc. The method

   143     * transits the plug-in to "Suspendend" state.

   144     *

   145     * @param aReason reason for state change, see TAiTransitionChange.

   146     * @return void

   147     */

   148     void Suspend( TAiTransitionReason aReason );

   149 

   150     /**

   151     * From CAiContentPublisher

   152     * Adds the content observer / subscriber to plug-in. The plug-in MUST

   153     * maintain a registry of subscribers and send notification to all them

   154     * whenever the plug-in changes state or new content available.

   155     *

   156     * @param aObserver content observer to register.

   157     * @return void

   158     */

   159     void SubscribeL( MAiContentObserver& aObserver );

   160     

   161     /**

   162     * From CAiContentPublisher

   163     * Configures the plug-in.

   164     * Plug-ins take ownership of the settings array, so it must either

   165     * store it in a member or free it. Framework has put the array in cleanup

   166     * stack so the plugin shouldn't do that.

   167     * If this leaves, the plug-in will be destroyed by AI FW.

   168     * Plug-in must support LaunchByValue-event even if normal shortcuts don't

   169     * work. The only allowed serious enough leave is KErrNotFound from CenRep.

   170     *

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

   172     * @return void

   173     */

   174     void ConfigureL( RAiSettingsItemArray& aSettings );

   175     

   176     /**

   177     * From CAiContentPublisher

   178     * Returns interface extension. In Series 60 3.1 only event & property

   179     * extensions are supported. See MAiEventExtension & MAiPropertyExtension

   180     * interfaces.

   181     *

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

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

   184     *         argument.

   185     */

   186     TAny* Extension( TUid aUid );  

   187 

   188 // from base class MAiPropertyExtension

   189 

   190     /**

   191     * From MAiPropertyExtension.

   192     * Read property of publisher plug-in.

   193     *

   194     * @param aProperty - identification of property.

   195     * @return pointer to property value.

   196     */

   197     TAny* GetPropertyL( TInt aProperty );

   198 

   199     /**

   200     * From MAiPropertyExtension.

   201     * Write property value.

   202     *

   203     * @param aProperty - identification of property.

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

   205     */

   206     void SetPropertyL( TInt aProperty, TAny* aValue );

   207   

   208  // from base class MAiEventHandlerExtension

   209    

   210      /**

   211      * From MAiEventHandlerExtension

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

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

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

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

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

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

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

   219      * @since S60 3.2

   220      */

   221      void HandleEvent(TInt aEvent, const TDesC& aParam);

   222     

   223      /**

   224      * From MAiEventHandlerExtension

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

   226      *

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

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

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

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

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

   232      *        <event params>  are provided to plug-in as-is in the descriptor.

   233      */

   234      void HandleEvent(const TDesC& aEventName, const TDesC& aParam);

   235 

   236     /**

   237  	* Invoked by the framework for querying if plugin has menu item

   238  	*

   239  	* @param aMenuItem  menu item name.

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

   241 	*/

   242     TBool HasMenuItem(const TDesC16& aMenuItem);

   243      

   244 public : // new functions

   245 	

   246     /**

   247     * Publishes widget's texts and images

   248     *

   249     * @param void

   250     * @return void

   251     */

   252     void PublishL();	

   253 	

   254 	/**

   255 	* Gets the id of a content  

   256 	*

   257 	* @param aObjectId image or text id

   258 	* @return id of the content

   259 	*/

   260 	TInt GetIdL(TDesC& aObjectId);

   261 	

   262     /**

   263     * Gets the type of a specific content

   264     *

   265     * @param aObjectId image or text id

   266     * @return void

   267     */

   268 	const TDesC& GetTypeL( TDesC& aObjectId );

   269 	

   270     /**

   271     * RefereshL a specific image of text in the widget

   272     *

   273     * @param aContentType content type

   274     * @param aOperation operation performed

   275     * @return void

   276     */

   277     void RefreshL(TDesC& aContentType, TDesC& aOperation);

   278     

   279     /**

   280     * Is plugin active to publish the data 

   281     *

   282     * @param void 

   283     * @return boolean (ETrue/EFalse)

   284     */

   285     TBool IsActive();

   286     

   287     /**

   288 	* Publish a specific text of the widget  

   289 	*

   290 	* @param aObserver observer

   291 	* @param aContentId content model id

   292 	* @param aContentValue content value

   293 	* @return void

   294 	*/

   295 	void PublishTextL(MAiContentObserver* aObserver, 

   296 			TInt& aContentId, TDesC& aContentValue);

   297 

   298 	/**

   299     * Publish a specific image of the widget  

   300     *

   301     * @param aObserver observer

   302     * @param aContentId content model id

   303     * @param aHandle image handle 

   304     * @param aMaskHandle handle of the mask image

   305     * @return void

   306     */

   307     void PublishImageL(MAiContentObserver* aObserver, 

   308             TInt& aContentId, TInt aHandle, TInt aMaskHandle);

   309 

   310     /**

   311     * Publish a specific image of the widget  

   312     *

   313     * @param aObserver observer

   314     * @param aContentId content model id

   315     * @param aPath image path / skin id pattern / mif id Pattern 

   316     * @return void

   317     */

   318     void PublishImageL(MAiContentObserver* aObserver,

   319             TInt aContentId, TDesC& aPath );

   320     

   321     /**

   322     * Cleans a data from the widget

   323     *

   324     * @param aObserver observer

   325     * @param aContentId content model id

   326     * @return void

   327     */

   328     void Clean(MAiContentObserver* aObserver, 

   329             TInt& aContentId );

   330     

   331     /**

   332      * CSapiData getter

   333      * @return Pointer to CSapiData

   334      */

   335     inline CSapiData* Data() const

   336         {

   337         return iData;

   338         }

   339 

   340 	/*

   341 	 * Plugin's network status getter

   342 	 * @return Pointer to Harvester status observer

   343 	 */

   344 	inline TPluginNetworkStatus NetworkStatus() const

   345 		{

   346 		return iNetworkStatus;

   347 		}

   348 	

   349 private: // data

   350 

   351     // Iterator for plugin content

   352     // Own

   353     MAiContentItemIterator* iContent;

   354 

   355     // Array of content observers

   356     // Own

   357     RPointerArray<MAiContentObserver> iObservers;

   358     

   359     // Information about the content publisher (this plug-in)

   360     TAiPublisherInfo iInfo;

   361 	

   362 	// Number of data in the content model.

   363 	TInt iDataCount;

   364 	 

   365 	// Dynamic content model

   366 	// Own

   367 	TAiContentItem* iContentModel;

   368 	

   369 	// Reference array for Published text

   370 	// Own

   371 	RPointerArray<HBufC> iDataArray;

   372 	

   373 	// Service API Data Subscriber.

   374 	// Own

   375 	CSapiData* iData;

   376     

   377     // References array for published images 

   378     // Own

   379     RArray<CGulIcon*> iIconArray;

   380     

   381     // File Server

   382     // Reference

   383     RFs iRfs;

   384     

   385     // Plugin's network status

   386     TPluginNetworkStatus iNetworkStatus;

   387     

   388     // Is Homescreen foreground.

   389     TBool iHSForeGround;

   390 

   391 	// Plugin state    

   392     TPluginStates iPluginState;

   393     };

   394 

   395 #endif // SAPIDATAPLUGIN_H

   396 

   397