/*

* 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