/*
* Copyright (c) {Year(s)} {Copyright owner}.
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of the "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.symbianfoundation.org/legal/sfl-v10.html".
*
* Initial Contributors:
* {Name} {Company} ? Initial contribution
*
* Contributors:
* {Name} {Company} ? {{Description of contribution}}
*
* Description:
* {{Description of the file}}
*
*/


#ifndef __HSPUBLISHER_H__
#define __HSPUBLISHER_H__

//  System includes 
#include <e32base.h>	
#include <fbs.h>

// User includes

// Forward declarations
class CHsPublisherImpl;
class MHsWidgetObserver;

//  Constants

//  Class Definitions
NONSHARABLE_CLASS( CHsPublisher ) : public CBase
    {
public:
    // constructors and destructor

    /**
     * Constructor
     * 
     * @param aObserver Widget observer interface
     * @param aEnablePersist ETrue if publisher wants to save published data to SQL database for later usage.
     *        This option should be used with caution as it taxes runtime performance and resources.               
     */
    static CHsPublisher* NewL( 
        MHsWidgetObserver& aObserver, 
        TBool aEnablePersist = EFalse );
    
    /**
     * Constructor
     * 
     * @param aObserver Widget observer interface
     * @param aEnablePersist ETrue if publisher wants to save published data to SQL database for later usage.
     *        This option should be used with caution as it taxes runtime performance and resources.                
     */
    static CHsPublisher* NewLC(            
        MHsWidgetObserver& aObserver,
        TBool aEnablePersist = EFalse );
        
    /**
     * Destructor
     */
    ~CHsPublisher();

public:
    // new functions
    
    /**
     * Publishes text to a <text> element in widget
     * 
     * @param aWidgetId Widget Id identifying the widget instance.
     * @param aElementId Element id identifying the text element in the widget.
     * @param aText Text to set.     
     * @return System wide error code.
     */
    TInt PublishText( 
        const TDesC& aWidgetId, 
        const TDesC8& aElementId, 
        const TDesC& aText );

    /**
     * Publishes image to an <image> element in widget
     * 
     * @param aWidgetId Widget Id identifying the widget instance.
     * @param aElementId Element id identifying the iamge element in the widget.
     * @param aImage Image to set.
     * @param aMask Mask to set. 
     * @return System wide error code.
     */    
    TInt PublishImage( 
        const TDesC& aWidgetId, 
        const TDesC8& aElementId,
        const CFbsBitmap* aImage,
        const CFbsBitmap* aMask );

    /**
     * Publishes image to an <image> element in widget
     * 
     * @param aWidgetId Widget Id identifying the widget instance.
     * @param aElementId Element id identifying the image element in the widget.
     * @param aImageHandle Image handle.
     * @param aMaskHandle Mask handle.
     * @return System wide error code.
     */        
    TInt PublishImage( 
        const TDesC& aWidgetId,      
        const TDesC8& aElementId, 
        TInt aImageHandle, 
        TInt aMaskHandle );

    /**
     * Publishes image to an <image> element in the widget.
     * 
     * @param aWidgetId Widget Id identifying the widget instance.
     * @param aElementId Element id identifying the image element in the widget.
     * @param aSource Source for the image. Supported source formats are:
     * - Filesystem path, i.e. _LIT( KMyImagePath, "c:\\data\\Installs\\MyWidget\\image.jpg");
     * - skin(<majorId> <minorId>), i.e. _LIT( KMySkinImage, "skin(270501603 8586)" );
     * - mif(<MifFileName.mif> <bitmapId> <maskId>), i.e. _LIT( KMyMifImage, "mif(c:\\data\\Installs\\MyWidget\\mymwidget.mif 16384 16385" );
     */                
    TInt PublishImage( 
        const TDesC& aWidgetId,           
        const TDesC8& aElementId, 
        const TDesC& aSource );
    
    /**
     * Publishes stream to a <data> element in widget
     * 
     * @param aWidgetId Widget Id identifying the widget instance.
     * @param aElementId Element id identifying the data element in the widget.
     * @param aStream The stream as descriptor.         
     * @return System wide error code.
     */            
    TInt PublishStream(
        const TDesC& aWidgetId,
        const TDesC8& aElementId,
        const TDesC8& aStream );

    /**
     * Cleans published text from a <text> element.
     * 
     * @param aWidgetId Widget Id identifying the widget instance.
     * @param aElementId Element id identifying the data element in the widget.
     * @return System wide error code.     
     */
    TInt CleanText( const TDesC& aWidgetId,    
        const TDesC8& aElementId );

    /**
     * Cleans published image from an <image> element.
     * 
     * @param aWidgetId Widget Id identifying the widget instance.
     * @param aElementId Element id identifying the data element in the widget.
     * @return System wide error code.     
     */    
    TInt CleanImage( const TDesC& aWidgetId,    
        const TDesC8& aElementId );
    
    /**
     * Starts a publish transaction. Transaction must be committed  
     * with CommitTransaction method.
     * 
     * @param aWidget Widget Id identifying the transaction for widget instance.
     * @return System wide error code.
     */                
    TInt StartTransaction( 
        const TDesC& aWidgetId );
    
    /**
     * Commits the publish transaction and flushes changes to Homescreen.
     * 
     * @param aWidget Widget Id identifying the transaction for the widget instance.
     * @return System wide error code.
     */            
    TInt CommitTransaction( 
        const TDesC& aWidgetId );    
       
private:
    // private constructors
    
    /**
     * C++ default constructor
     */
    CHsPublisher();
    
    /**
     * 2nd phase constructor
     */
    void ConstructL( 
        MHsWidgetObserver& aObserver,
        TBool aEnablePersist );
    
private:
    // data
        
    /** HS publisher implementation, owned */
    CHsPublisherImpl* iImpl;
    };

#endif  // __HSPUBLISHER_H__

// End of file