--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/epoc32/include/hswidgetpublisher.h	Tue Mar 16 16:12:26 2010 +0000
@@ -0,0 +1,227 @@
+/*
+* 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__
+