/*

 * Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies). 

 * All rights reserved.

 * This component and the accompanying materials are made available

 * 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

 * which accompanies this distribution, and is available

 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

 *

 * Initial Contributors:

 * Nokia Corporation - initial contribution.

 *

 * Contributors:

 *

 * Description:  Updates applications and icons in Operator Tile.

 *

 */

 // This file defines the API for hswidgetpublisher.dll

 #ifndef __HSWIDGETPUBLISHER_H__

 #define __HSWIDGETPUBLISHER_H__

 //  Include Files

 #include <cctype>

 #include <memory>

 #include <string>

 namespace Hs {

 //  Class Definitions

 class HsWidget;

 class IHsDataObserver;

 class HsWidgetPublisherImpl;

 /**

  * Class allowing access to the Homescreen Publishing Api. 

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

  * information for the occuring events.

  * 

  * @code

  * class ObserverClass : public IHsDataObserver

  * {

  *      void handleEvent( std::string aWidgetName, 

  *			IHsDataObserver::EEvent aEvent)

  *      {

  *      }

  * 

  *      void handleItemEvent( std::string aWidgetName,

  *        	std::string aWidgetItemName,

  *       	IHsDataObserver::EItemEvent aEvent)

  *      {

  *      }

  * }

  * 

  * ObserverClass* dataObserver = new ObserverClass();

  * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );

  * HsWidget& widget =  publisher->createHsWidget(

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

  * // assuming count and values[] exists

  * while (count)

  * {

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

  *    count--;

  * }

  * hsPublisher->publishHsWidget( widget ); 

  * @endcode

  */

 class HsWidgetPublisher

     {

 public:

     /**

      * Constructor of the HsWidgetPublisher. Creates an instance of the 

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

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

      * is asserted.

      *

      * @code

 	 * class ObserverClass : public IHsDataObserver

 	 * {

 	 *      void handleEvent( std::string aWidgetName, 

 	 *			IHsDataObserver::EEvent aEvent)

 	 *      {

 	 *      }

 	 * 

 	 *      void handleItemEvent( std::string aWidgetName,

 	 *        	std::string aWidgetItemName,

 	 *       	IHsDataObserver::EItemEvent aEvent)

 	 *      {

 	 *      }

 	 * }       

      * 

      * ObserverClass* dataObserver = new ObserverClass();

      * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );

      * @endcode

      * 

      * Client should not completely rely on exceptions while creating 

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

      * the memory was allocated properly.

      * @code

      * 

      * ObserverClass* dataObserver = new ObserverClass();

      * 

      * try 

      * {

      *     HsWidgetPublisher* hsPublisher = new HsWidgetPublisher(dataObserver);

      *     if (hsPublisher)

      *     {

      *     // do the operations on the API here

      *     }

      * }

      * catch (HsException& exception)

      * {

      *     int errReason = exception.getReason();

      * }

      * @endcode

      *

      * @param aDataObserver Callback interface for handling actions.

      * @exception HsPException

      */

     IMPORT_C HsWidgetPublisher( IHsDataObserver* aDataObserver );

     /**

      * Destructor of the HsWidgetPublisher.

      *

      * @code

      * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );

      * delete hsPublisher;

      * @endcode

      * @exception HsException

      */

     IMPORT_C ~HsWidgetPublisher();

     /**

      * Method creates a new widget.

      * Attempt to create already existing widget will cause exception 

      * with KErrAlreadyExists reason.

      * Other exception reasons are possible and are caused by widget 

      * registration.

      * 

      * @code

      * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );

      * HsWidget& widget =  hsPublisher->createHsWidget( 

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

      * @endcode

      * @param aTemplateName Name of the Template.

      * @param aWidgetName Name of the Widget

      * @param aIdentifier Unique identification of the content.

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

      * created one.

      * @exception HsException Exception is thrown when with code 

      * KErrAlreadyExists 

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

      * when excpetion is thrown include problems with widget registration. 

      */

     IMPORT_C HsWidget& createHsWidget( std::string aTemplateName, 

         std::string aWidgetName,

         std::string aIdentifier );

     /**

      * Method publishes the provided widget. 

      * Widget needs to be published in order for the content 

      * to be seen by the HS.

      *

      * @code

      * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );

      * HsWidget& widget =  hsPublisher->createHsWidget( 

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

      * hsPublisher->publishHsWidget( widget ); 

      * @endcode

      * @param aWidget Reference to a widget object.

      * @exception HsException

      */

     IMPORT_C void publishHsWidget( HsWidget& aWidget );

     /**

      * Method removes a widget.

      *

      * @code

      * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );

      * hsPublisher->createHsWidget( 

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

      * publisher->removeHsWidget(

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

      * @endcode

      * @param aTemplateName Name of the Template.

      * @param aWidgetName Name of the Widget

      * @param aIdentifier Unique identification of the content.

      * @exception HsException

      */

     IMPORT_C void removeHsWidget( std::string aTemplateName, 

         std::string aWidgetName,

         std::string aIdentifier );

     /**

      * Obtains a Widget from Homescreen Publishing Api.

      * Attempt of obtaining Widget that was not created cause exception 

      * with KErrNotFound rason.

      * 

      *

      * @code

      * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );

      * hsPublisher->createHsWidget( 

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

      * HsWidget& widget = hsPublisher->getHsWidget(

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

      * @endcode

      * @param aTemplateName Name of the Template.

      * @param aWidgetName Name of the Widget

      * @param aIdentifier Unique identification of the content.

      * @return Error code.

      * @exception HsException

      */

     IMPORT_C HsWidget& getHsWidget( std::string aTemplateName, 

         std::string aWidgetName,

         std::string aIdentifier );

 private: //members

     std::auto_ptr<HsWidgetPublisherImpl> mImpl;

     };

 }

 #endif  // __HSWIDGETPUBLISHER_H__