1 /*

     2 * Copyright (c) 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:  Updates applications and icons in Operator Tile.

    15 *

    16 */

    17 

    18 

    19 // This file defines the API for hswidgetpublisher.dll

    20 

    21 #ifndef __HSWIDGETPUBLISHER_H__

    22 #define __HSWIDGETPUBLISHER_H__

    23 

    24 //  Include Files

    25 #include <cctype>

    26 #include <memory>

    27 #include <string>

    28 

    29 namespace Hs {

    30 

    31 //  Class Definitions

    32 class HsWidget;

    33 class IHsDataObserver;

    34 class HsWidgetPublisherImpl;

    35 

    36 /**

    37  * Class allowing access to the Homescreen Publishing Api. 

    38  * Allows creation, update and deletion of widgets, as well as reception of

    39  * information for the occuring events.

    40  * 

    41  * @code

    42  * class ObserverClass : public IHsDataObserver

    43  * {

    44  *      void handleEvent( std::string aWidgetName, 

    45  *			IHsDataObserver::EEvent aEvent)

    46  *      {

    47  *      }

    48  * 

    49  *      void handleItemEvent( std::string aWidgetName,

    50  *        	std::string aWidgetItemName,

    51  *       	IHsDataObserver::EItemEvent aEvent)

    52  *      {

    53  *      }

    54  * }

    55  * 

    56  * ObserverClass* dataObserver = new ObserverClass();

    57  * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );

    58  * HsWidget& widget =  publisher->createHsWidget(

    59  *     "templateName", "widgetName", "uniqueIdentifier" );

    60  * // assuming count and values[] exists

    61  * while (count)

    62  * {

    63  *    widget->setItem( "image", values[count] );

    64  *    count--;

    65  * }

    66  * hsPublisher->publishHsWidget( widget ); 

    67  * @endcode

    68  */

    69 class HsWidgetPublisher

    70     {

    71 public:

    72     /**

    73      * Constructor of the HsWidgetPublisher. Creates an instance of the 

    74      * publisher, which is used to manage Widgets and Widget's Items. 

    75      * Please note that attempt of usage, with aDataObserver = NULL 

    76      * is asserted.

    77      *

    78      * @code

    79 	 * class ObserverClass : public IHsDataObserver

    80 	 * {

    81 	 *      void handleEvent( std::string aWidgetName, 

    82 	 *			IHsDataObserver::EEvent aEvent)

    83 	 *      {

    84 	 *      }

    85 	 * 

    86 	 *      void handleItemEvent( std::string aWidgetName,

    87 	 *        	std::string aWidgetItemName,

    88 	 *       	IHsDataObserver::EItemEvent aEvent)

    89 	 *      {

    90 	 *      }

    91 	 * }       

    92      * 

    93      * ObserverClass* dataObserver = new ObserverClass();

    94      * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );

    95      * @endcode

    96      * 

    97      * Client should not completely rely on exceptions while creating 

    98      * the API. Except for exceptions thrown one should check if

    99      * the memory was allocated properly.

   100      * @code

   101      * 

   102      * ObserverClass* dataObserver = new ObserverClass();

   103      * 

   104      * try 

   105      * {

   106      *     HsWidgetPublisher* hsPublisher = new HsWidgetPublisher(dataObserver);

   107      *     if (hsPublisher)

   108      *     {

   109      *     // do the operations on the API here

   110      *     }

   111      * }

   112      * catch (HsException& exception)

   113      * {

   114      *     int errReason = exception.getReason();

   115      * }

   116      * @endcode

   117      *

   118      * @param aDataObserver Callback interface for handling actions.

   119      * @exception HsPException

   120      */

   121     IMPORT_C HsWidgetPublisher( IHsDataObserver* aDataObserver );

   122     

   123     /**

   124      * Destructor of the HsWidgetPublisher.

   125      *

   126      * @code

   127      * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );

   128      * delete hsPublisher;

   129      * @endcode

   130      * @exception HsException

   131      */

   132     IMPORT_C ~HsWidgetPublisher();

   133     

   134     /**

   135      * Creates a new widget.

   136      * 

   137      * If widget already created, fails and throws a HsException containing

   138      * KErrAlreadyExists error code. May throw HsException with different

   139      * system-wide error codes if error occurs during registration.

   140      * 

   141      * @code

   142      * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );

   143      * HsWidget& widget =  hsPublisher->createHsWidgetWithDesc( 

   144      *     "templateName", "widgetName", "uniqueIdentifier",

   145      *     "A short widget description.", "c:\\data\\Installs\\an_icon.jpg" );

   146      * @endcode

   147      * 

   148      * @param aTemplateName Name of the Template.

   149      * @param aWidgetName Name of the Widget

   150      * @param aIdentifier Unique widget indentifier. It is recommended to use

   151      *     your application's UID3 as the identifier. If your application

   152      *     creates two different HsWidgets, their identifiers must be unique

   153      *     too, in such case consider using UID3 with an extra suffix, e.g.

   154      *     0xE2DA0574_1 for the first widget and 0xE2DA0574_2 for the second

   155      *     one.

   156      * @param aDescription A short widget description (e.g. 'Displays latest

   157      *     news and wheather forecast.') 

   158      * @param aIconLocation A location of a logo icon that will be displayed

   159      *     alongside the short description. There are 4 ways in which icon

   160      *     location can be specified:<BR>

   161      *     1. system path (e.g. c:\\data\\Installs\\icon1.jpg)<BR>

   162      *     2. MIF file (e.g. c:\\data\\Installs\\templateIcons.mif 16384 16385)<BR>

   163      *     3. skin with MIF file fallback

   164      *       (e.g. skin(major_id minor_id):mif(c:\\data\\icons.mif 16386 16387)<BR>

   165      *     4.icon from AppArc (e.g. uid(0x12345678))

   166      * @return The newly created widget. 

   167      * 

   168      * @exception HsException

   169      */

   170     IMPORT_C HsWidget& createHsWidgetWithDesc( std::string aTemplateName, 

   171         std::string aWidgetName, std::string aIdentifier,

   172         std::string aDescription, std::string aIconLocation );

   173     

   174     /**

   175      * DEPRECATED. This method is here only to maintain compatibility with

   176      * legacy widgets. Please use createHsWidgetWithDesc instead of this method.

   177      * 

   178      * Method creates a new widget.

   179      * Attempt to create already existing widget will cause exception 

   180      * with KErrAlreadyExists reason.

   181      * Other exception reasons are possible and are caused by widget 

   182      * registration.

   183      * 

   184      * @code

   185      * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );

   186      * HsWidget& widget =  hsPublisher->createHsWidget( 

   187      *     "templateName", "widgetName", "uniqueIdentifier" );

   188      * @endcode

   189      * @param aTemplateName Name of the Template.

   190      * @param aWidgetName Name of the Widget

   191      * @param aIdentifier Unique identification of the content.

   192      * @return A widget is returned. If no such widget existed a newly

   193      * created one.

   194      * @exception HsException Exception is thrown when with code 

   195      * KErrAlreadyExists 

   196      * when attempting to create a widget that already exists. Other cases 

   197      * when excpetion is thrown include problems with widget registration. 

   198      */

   199     IMPORT_C HsWidget& createHsWidget( std::string aTemplateName, 

   200         std::string aWidgetName,

   201         std::string aIdentifier );

   202 

   203     /**

   204      * Method publishes the provided widget. 

   205      * Widget needs to be published in order for the content 

   206      * to be seen by the HS.

   207      *

   208      * @code

   209      * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );

   210      * HsWidget& widget =  hsPublisher->createHsWidget( 

   211      *     "templateName", "widgetName", "uniqueIdentifier" );

   212      * hsPublisher->publishHsWidget( widget ); 

   213      * @endcode

   214      * @param aWidget Reference to a widget object.

   215      * @exception HsException

   216      */

   217     IMPORT_C void publishHsWidget( HsWidget& aWidget );

   218 

   219     /**

   220      * Method removes a widget.

   221      *

   222      * @code

   223      * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );

   224      * hsPublisher->createHsWidget( 

   225      *     "templateName", "widgetName", "uniqueIdentifier" );

   226      * publisher->removeHsWidget(

   227      *     "templateName", "widgetName", "uniqueIdentifier" );

   228      * @endcode

   229      * @param aTemplateName Name of the Template.

   230      * @param aWidgetName Name of the Widget

   231      * @param aIdentifier Unique identification of the content.

   232      * @exception HsException

   233      */

   234     IMPORT_C void removeHsWidget( std::string aTemplateName, 

   235         std::string aWidgetName,

   236         std::string aIdentifier );

   237     

   238     /**

   239      * Obtains a Widget from Homescreen Publishing Api.

   240      * Attempt of obtaining Widget that was not created cause exception 

   241      * with KErrNotFound rason.

   242      * 

   243      *

   244      * @code

   245      * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );

   246      * hsPublisher->createHsWidget( 

   247      *     "templateName", "widgetName", "uniqueIdentifier" );

   248      * HsWidget& widget = hsPublisher->getHsWidget(

   249      *     "templateName", "widgetName", "uniqueIdentifier" );

   250      * @endcode

   251      * @param aTemplateName Name of the Template.

   252      * @param aWidgetName Name of the Widget

   253      * @param aIdentifier Unique identification of the content.

   254      * @return Error code.

   255      * @exception HsException

   256      */

   257     IMPORT_C HsWidget& getHsWidget( std::string aTemplateName, 

   258         std::string aWidgetName,

   259         std::string aIdentifier );

   260 

   261     

   262 private: //members

   263 

   264     std::auto_ptr<HsWidgetPublisherImpl> mImpl;

   265 

   266     };

   267 }

   268 

   269 #endif  // __HSWIDGETPUBLISHER_H__

   270