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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.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      * Method creates a new widget.

   136      * Attempt to create already existing widget will cause exception 

   137      * with KErrAlreadyExists reason.

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

   139      * registration.

   140      * 

   141      * @code

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

   143      * HsWidget& widget =  hsPublisher->createHsWidget( 

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

   145      * @endcode

   146      * @param aTemplateName Name of the Template.

   147      * @param aWidgetName Name of the Widget

   148      * @param aIdentifier Unique identification of the content.

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

   150      * created one.

   151      * @exception HsException Exception is thrown when with code 

   152      * KErrAlreadyExists 

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

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

   155      */

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

   157         std::string aWidgetName,

   158         std::string aIdentifier );

   159 

   160     /**

   161      * Method publishes the provided widget. 

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

   163      * to be seen by the HS.

   164      *

   165      * @code

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

   167      * HsWidget& widget =  hsPublisher->createHsWidget( 

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

   169      * hsPublisher->publishHsWidget( widget ); 

   170      * @endcode

   171      * @param aWidget Reference to a widget object.

   172      * @exception HsException

   173      */

   174     IMPORT_C void publishHsWidget( HsWidget& aWidget );

   175 

   176     /**

   177      * Method removes a widget.

   178      *

   179      * @code

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

   181      * hsPublisher->createHsWidget( 

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

   183      * publisher->removeHsWidget(

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

   185      * @endcode

   186      * @param aTemplateName Name of the Template.

   187      * @param aWidgetName Name of the Widget

   188      * @param aIdentifier Unique identification of the content.

   189      * @exception HsException

   190      */

   191     IMPORT_C void removeHsWidget( std::string aTemplateName, 

   192         std::string aWidgetName,

   193         std::string aIdentifier );

   194     

   195     /**

   196      * Obtains a Widget from Homescreen Publishing Api.

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

   198      * with KErrNotFound rason.

   199      * 

   200      *

   201      * @code

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

   203      * hsPublisher->createHsWidget( 

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

   205      * HsWidget& widget = hsPublisher->getHsWidget(

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

   207      * @endcode

   208      * @param aTemplateName Name of the Template.

   209      * @param aWidgetName Name of the Widget

   210      * @param aIdentifier Unique identification of the content.

   211      * @return Error code.

   212      * @exception HsException

   213      */

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

   215         std::string aWidgetName,

   216         std::string aIdentifier );

   217 

   218     

   219 private: //members

   220 

   221     std::auto_ptr<HsWidgetPublisherImpl> mImpl;

   222 

   223     };

   224 }

   225 

   226 #endif  // __HSWIDGETPUBLISHER_H__

   227