/*
* Copyright (c) 2003-2005 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:     Declares an API for the consumer applications to access the 
*                Application Interworking Framework. 
*
*/





#ifndef AIW_SERVICE_HANDLER_H
#define AIW_SERVICE_HANDLER_H

// INCLUDES
#include <barsread.h> 
#include <aiwcommon.h>

// CONSTANTS

// MACROS

// FUNCTION PROTOTYPES

// FORWARD DECLARATIONS
class CAiwServiceHandlerImpl;

// CLASS DECLARATION

/**
* CAiwServiceHandler is the main class of the Application Interworking
* Framework. The Service Handler implements support for dynamically
* loadable service providers which offer services to consumer applications. 
* The Service Handler maps consumers and service providers together via 
* interests and data agreements and hides the consumers from the providers. 
*
* SERVICE is any command or functionality offered by a provider to 
* consumer. The service includes typically menu item UI elements,
* but it can also just an engine type of command which executes specific 
* functionality and reports status back to the consumer.
*
* CONSUMER application accesses interesting services offered by
* service provider(s). The consumer uses only those services in which
* it is interested in. The interest is expressed using a set of criteria
* items.
*
* INTEREST is a list of criteria items.
*
* CRITERIA consists of set of attributes which guide the AIW Framework to use
* only those providers in which the consumer is interested in.
* The criteria consists of following attributes:
*   - Criteria UID (we can allocate pre-defined criteria items).
*   - Service command UID (we can allocate pre-defined commands).
*   - Content MIME type (string).
*   - Additional options (variant data type just in case).
*
* PROVIDER produces those services for a consumer that match the given criteria 
* specified by the consumer. A provider can offer menu items and their command
* handling logic to the consumer applications. A provider can also offer base
* services that don't require any UI elements.
*
* DATA AGREEMENT is an agreement between consumer and provider about parameters 
* needed to be passed in a use case.
*
* @lib ServiceHandler.lib
* @since S60 2.6
*/
NONSHARABLE_CLASS(CAiwServiceHandler) : public CBase
    {
    public:  // Construction & destruction

        /**
        * Constructs a Service Handler instance.
        */
        IMPORT_C static CAiwServiceHandler* NewL();
        
        /**
        * Constructs a Service Handler instance.
        */
        IMPORT_C static CAiwServiceHandler* NewLC();  

        /** 
        * Destructor.
        */
        IMPORT_C virtual ~CAiwServiceHandler();
        
    public:  // Management

        /**
        * Resets the Service Handler, discards existing interest and unloads 
        * corresponding service providers.
        */
        IMPORT_C void Reset();

        /**
        * Returns the amount of providers that fulfil the given criteria.
        *
        * @param aCriteria Criteria to match.
        * @return Number of providers matching the criteria.
        */
        IMPORT_C TInt NbrOfProviders(const CAiwCriteriaItem* aCriteria);
        
    public:  // Interest handling
        
        /**
        * Adds the given interest to the Service Handler from a resource and updates 
        * possibly existing old interest. Corresponding service providers are loaded.
        * If a provider leaves during initialization, it is trapped by the Service Handler.
        *
        * @param aInterestResourceId ID of the resource containing criteria items.
        * @leave KErrNotSupported CCoeEnv is not accessible.
        * @see Reset
        */
        IMPORT_C void AttachL(TInt aInterestResourceId);

        /**
        * Adds given interest to the Service Handler from an array of criteria items.
        * If a provider leaves during initialization, it is trapped by the Service Handler.
        *
        * @param aInterest Array of criteria items. Ownership is not transferred.
        */
        IMPORT_C void AttachL(const RCriteriaArray& aInterest);

        /**
        * Gets the currently valid interest in use by the Service Handler.
        *
        * @param aInterest An array of returned criteria items, may be empty.
        *                  Ownership is not transferred, i.e. the objects in the 
        *                  array must not be deleted.
        */
        IMPORT_C void GetInterest(RCriteriaArray& aInterest);

        /**
        * Removes given interest from the Service Handler. Corresponding service 
        * providers are unloaded.
        * 
        * @param aInterest Array of returned criteria items, may be empty.
        */
        IMPORT_C void DetachL(const RCriteriaArray& aInterest);

        /**
        * Removes given interest from the Service Handler. Corresponding service 
        * providers are unloaded.
        * 
        * @param aInterestResourceId ID of the resource containing criteria items.
        * @leave KErrNotSupported CCoeEnv is not accessible.
        */
        IMPORT_C void DetachL(TInt aInterestResourceId);
        
        /**
        * Returns criteria by ID.
        *
        * @param aId Criteria ID.
        * @return Criteria item pointer matching the ID. Ownership is not transferred.
        */
        IMPORT_C const CAiwCriteriaItem* GetCriteria(TInt aId);

        /**
        * Returns an empty instance of CAiwGenericParamList class. It can be
        * used for example as an input parameter list for the Service Handler's
        * API methods. This is just a convenience method and doesn't have
        * to be used. If consumer wants to create input list by itself
        * it is ok. If this method is used, the Service Handler takes care
        * of deleting returned generic parameter list.
        *
        * @return  An empty instance of CAiwGenericParameter list.
        */
        IMPORT_C CAiwGenericParamList& InParamListL();

        /**
        * Returns an empty instance of CAiwGenericParamList class. The instance can be
        * used for example as an output parameter list for Service Handler
        * API methods. This is just a convenience method and doesn't have
        * to be used. If consumer wants to create output list by itself
        * it is ok. If this method is used, Service Handler takes care
        * of deleting returned generic parameter list.
        *
        * @return  An empty instance of CAiwGenericParameter list.
        */
        IMPORT_C CAiwGenericParamList& OutParamListL();
        
    public:  // Menu handling

        /**
        * Initialises menu pane with service commands from a provider.
        * This method must be called upon DynInitMenuPaneL of consumer
        * application in order to let the provider to hook its menu items.
        *
        * @param aMenuPane Handle of the menu pane to initialise.
        * @param aMenuResourceId The menu to be attached.
        * @param aBaseMenuCmdId Base ID for the Service Handler to generate 
        *                       menu IDs for placeholders.
        * @param aInParamList Input parameter list for provider's parameters checking.
        * @leave KErrNotSupported CCoeEnv is not accessible.
        * @leave KErrOverflow Consumer application has too many AIW placeholders in its menu. 
        *                     Currently, maximum 16 is supported.
        */
        IMPORT_C void InitializeMenuPaneL(
            CEikMenuPane& aMenuPane,
            TInt aMenuResourceId,
            TInt aBaseMenuCmdId,
            const CAiwGenericParamList& aInParamList);
            
        /**
        * Initialises menu pane with service commands from a provider.
        * This method must be called upon DynInitMenuPaneL of consumer
        * application in order to let the provider to hook its menu items.
        * In normal circumstances, the other variant of this method should be used.
        *
        * @since S60 3.1
        * @param aMenuPane Handle of the menu pane to initialise.
        * @param aMenuResourceId The menu to be attached.
        * @param aBaseMenuCmdId Base ID for the Service Handler to generate 
        *                       menu IDs for placeholders.
        * @param aInParamList Input parameter list for provider's parameters checking.
        * @param aUseSubmenuTextsIfAvailable If the provider has specified alternative submenu
        *                       texts for its menu items, those can be taken into use if this 
        *                       parameter is set to ETrue. This should be used only for manually 
        *                       created submenus. If using AIW_CASCADE_ID or 
        *                       AIW_INTELLIGENT_CASCADE_ID, the AIW framework can automatically 
        *                       decide whether to use the submenu texts or not, and this parameter 
        *                       has no effect.
        * @leave KErrNotSupported CCoeEnv is not accessible.
        * @leave KErrOverflow Consumer application has too many AIW placeholders in its menu. 
        *                     Currently, maximum 16 is supported.
        */
        IMPORT_C void InitializeMenuPaneL(
            CEikMenuPane& aMenuPane,
            TInt aMenuResourceId,
            TInt aBaseMenuCmdId,
            const CAiwGenericParamList& aInParamList,
            TBool aUseSubmenuTextsIfAvailable);            
        
        /**
        * Returns the service command ID associated to the menu command. If found, it means 
        * that there is a provider which can handle the menu command. Thus the command 
        * handling needs to be routed to the provider via ExecuteMenuCmdL.
        *
        * @param aMenuCmdId Menu command ID to be mapped to service cmd.
        * @return Service command ID, KAiwCmdNone if no ID is found.
        * @see ExecuteMenuCmdL
        */
        IMPORT_C TInt ServiceCmdByMenuCmd(TInt aMenuCmdId) const;

        /**
        * Tells the provider to execute a menu command invoked by the consumer.
        * Not supported if calling outside UI framework. Use ServiceCmdByMenuCmd to 
        * check if there is any provider for the menu command.
        *
        * @param aMenuCmdId The menu command to be executed.
        * @param aInParamList Input data parameters, can be an empty list.
        * @param aOutParamList Output data parameters, can be an empty list.
        * @param aCmdOptions Options for the command, see TAiwServiceCmdOptions in AiwCommon.hrh.
        * @param aCallback Callback for asynchronous command handling, parameter checking, etc.
        * @leave KErrArgument Callback is missing when required.
        * @leave KErrNotSupported No cmd matches given menu command or CCoeEnv is not accessible.
        * @see ServiceCmdByMenuCmd
        */
        IMPORT_C void ExecuteMenuCmdL(
            TInt aMenuCmdId,
            const CAiwGenericParamList& aInParamList,
            CAiwGenericParamList& aOutParamList,
            TUint aCmdOptions = 0,
            MAiwNotifyCallback* aCallback= NULL);

        /**
        * Attach menu related criteria items to the given menu.
        * If a provider leaves during initialization, it is trapped by the Service Handler. 
        *
        * @param aMenuResourceId      Menu to be attached.
        * @param aInterestResourceId  Resource id for the interest list.
        * @leave KErrNotSupported     CCoeEnv is not accessible.
        */
        IMPORT_C void AttachMenuL(TInt aMenuResourceId, TInt aInterestResourceId);

        /**
        * Attach menu related criteria items to the given menu.
        * If a provider leaves during initialization, it is trapped by the Service Handler. 
        *
        * @param aMenuResourceId  Menu to be attached.
        * @param aReader          Resource reader for the interest list.
        * @leave KErrNotSupported CCoeEnv is not accessible.
        */
        IMPORT_C void AttachMenuL(TInt aMenuResourceId, TResourceReader& aReader);
        
        /**
        * Attach menu related criteria items to the given menu. 
        *
        * @since S60 3.2
        * @param aMenuResourceId  Menu to be attached.
        * @param aInterest        Array of criteria items. Ownership is not transferred.
        * @leave KErrNotSupported CCoeEnv is not accessible.
        */
        IMPORT_C void AttachMenuL(TInt aMenuResourceId, const RCriteriaArray& aInterest);   

        /**
        * Detach menu related criteria items from the given menu.
        * In following cases this method just returns without doing anything:
        *   1. If interest resource id is non-zero and CCoeEnv is not accessible.
        *   2. If interest resource id is non-zero and there occurs an error when reading
        *      the interest (e.g. not enough memory). 
        * 
        * @param aMenuResourceId      Menu to be detached.
        * @param aInterestResourceId  Resource id for the interest list. If NULL, all 
        *                             criteria items are detached from the given menu.
        */
        IMPORT_C void DetachMenu(TInt aMenuResourceId, TInt aInterestResourceId);

        /**
        * Checks if there are menu providers attached to given menu id. Consumer 
        * application can use this information to decide whether a sub menu 
        * containing only AIW items should be hidden or not.
        *
        * @param  aSubMenuId The menu id to be checked.
        * @return ETrue  if there isn't any menu providers attached to this menu.
        *         EFalse otherwise. 
        */
        IMPORT_C TBool IsSubMenuEmpty(TInt aSubMenuId);

        /**
        * Returns boolean value indicating whether the given menu contains
        * currently attached placeholders.
        *
        * @param   aMenuResourceId  Resource id of the menu to be queried.
        * @return  ETrue  if aMenuResource contains currently attached placeholders.
        *          EFalse otherwise. 
        */
        IMPORT_C TBool IsAiwMenu(TInt aMenuResourceId);

        /**
        * Handles AIW submenus. This method should be called from consumer application's 
        * DynInitMenuPaneL.
        *
        * @param  aPane  Menu pane to be handled.
        * @return ETrue  if aPane was an AIW submenu and it was handled. 
        *                Consumer's DynInitMenuPaneL pane may now return.
        *         EFalse if aPane was not an AIW submenu and DynInitMenuPaneL should
        *                continue normally.
        */
        IMPORT_C TBool HandleSubmenuL(CEikMenuPane& aPane);

        /**
        * CEikMenuPane uses this method to inform AIF framework that a menu is launched.
        * This method does not need to be called by any other component.
        *
        * @since S60 3.0
        */
        IMPORT_C static void ReportMenuLaunch();

    public:  // Generic Service Command handling
        
        /**
        * Executes a service command for all providers. Otherwise similar to ExecuteMenuCmdL.
        *
        * @param aCmdId The command to be executed.
        * @param aInParamList Input data parameters, can be an empty list.
        * @param aOutParamList Output data parameters, can be an empty list.
        * @param aCmdOptions Options for the command, see TAiwServiceCmdOptions in AiwCommon.hrh.    
        * @param aCallback Callback for asynchronous command handling, parameter checking, etc.
        * @leave KErrArgument Callback is missing when required.
        * @leave KErrNotSupported No provider supports the service.
        */
        IMPORT_C void ExecuteServiceCmdL(
            const TInt& aCmdId,
            const CAiwGenericParamList& aInParamList,
            CAiwGenericParamList& aOutParamList,
            TUint aCmdOptions = 0,
            MAiwNotifyCallback* aCallback = 0);
            
    private:
        void ConstructL();
        CAiwServiceHandler();

    private:
        CAiwServiceHandlerImpl* iImpl;
    };

#endif // AIW_SERVICE_HANDLER_H

// END of File