williamr@2: /*
williamr@2: * Copyright (c) 2003-2005 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@4: * under the terms of "Eclipse Public License v1.0"
williamr@2: * which accompanies this distribution, and is available
williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description:     Declares an API for the consumer applications to access the 
williamr@2: *                Application Interworking Framework. 
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: #ifndef AIW_SERVICE_HANDLER_H
williamr@2: #define AIW_SERVICE_HANDLER_H
williamr@2: 
williamr@2: // INCLUDES
williamr@2: #include <barsread.h> 
williamr@4: #include <AiwCommon.h>
williamr@2: 
williamr@2: // CONSTANTS
williamr@2: 
williamr@2: // MACROS
williamr@2: 
williamr@2: // FUNCTION PROTOTYPES
williamr@2: 
williamr@2: // FORWARD DECLARATIONS
williamr@2: class CAiwServiceHandlerImpl;
williamr@2: 
williamr@2: // CLASS DECLARATION
williamr@2: 
williamr@2: /**
williamr@2: * CAiwServiceHandler is the main class of the Application Interworking
williamr@2: * Framework. The Service Handler implements support for dynamically
williamr@2: * loadable service providers which offer services to consumer applications. 
williamr@2: * The Service Handler maps consumers and service providers together via 
williamr@2: * interests and data agreements and hides the consumers from the providers. 
williamr@2: *
williamr@2: * SERVICE is any command or functionality offered by a provider to 
williamr@2: * consumer. The service includes typically menu item UI elements,
williamr@2: * but it can also just an engine type of command which executes specific 
williamr@2: * functionality and reports status back to the consumer.
williamr@2: *
williamr@2: * CONSUMER application accesses interesting services offered by
williamr@2: * service provider(s). The consumer uses only those services in which
williamr@2: * it is interested in. The interest is expressed using a set of criteria
williamr@2: * items.
williamr@2: *
williamr@2: * INTEREST is a list of criteria items.
williamr@2: *
williamr@2: * CRITERIA consists of set of attributes which guide the AIW Framework to use
williamr@2: * only those providers in which the consumer is interested in.
williamr@2: * The criteria consists of following attributes:
williamr@2: *   - Criteria UID (we can allocate pre-defined criteria items).
williamr@2: *   - Service command UID (we can allocate pre-defined commands).
williamr@2: *   - Content MIME type (string).
williamr@2: *   - Additional options (variant data type just in case).
williamr@2: *
williamr@2: * PROVIDER produces those services for a consumer that match the given criteria 
williamr@2: * specified by the consumer. A provider can offer menu items and their command
williamr@2: * handling logic to the consumer applications. A provider can also offer base
williamr@2: * services that don't require any UI elements.
williamr@2: *
williamr@2: * DATA AGREEMENT is an agreement between consumer and provider about parameters 
williamr@2: * needed to be passed in a use case.
williamr@2: *
williamr@2: * @lib ServiceHandler.lib
williamr@2: * @since S60 2.6
williamr@2: */
williamr@2: NONSHARABLE_CLASS(CAiwServiceHandler) : public CBase
williamr@2:     {
williamr@2:     public:  // Construction & destruction
williamr@2: 
williamr@2:         /**
williamr@2:         * Constructs a Service Handler instance.
williamr@2:         */
williamr@2:         IMPORT_C static CAiwServiceHandler* NewL();
williamr@2:         
williamr@2:         /**
williamr@2:         * Constructs a Service Handler instance.
williamr@2:         */
williamr@2:         IMPORT_C static CAiwServiceHandler* NewLC();  
williamr@2: 
williamr@2:         /** 
williamr@2:         * Destructor.
williamr@2:         */
williamr@2:         IMPORT_C virtual ~CAiwServiceHandler();
williamr@2:         
williamr@2:     public:  // Management
williamr@2: 
williamr@2:         /**
williamr@2:         * Resets the Service Handler, discards existing interest and unloads 
williamr@2:         * corresponding service providers.
williamr@2:         */
williamr@2:         IMPORT_C void Reset();
williamr@2: 
williamr@2:         /**
williamr@2:         * Returns the amount of providers that fulfil the given criteria.
williamr@2:         *
williamr@2:         * @param aCriteria Criteria to match.
williamr@2:         * @return Number of providers matching the criteria.
williamr@2:         */
williamr@2:         IMPORT_C TInt NbrOfProviders(const CAiwCriteriaItem* aCriteria);
williamr@2:         
williamr@2:     public:  // Interest handling
williamr@2:         
williamr@2:         /**
williamr@2:         * Adds the given interest to the Service Handler from a resource and updates 
williamr@2:         * possibly existing old interest. Corresponding service providers are loaded.
williamr@2:         * If a provider leaves during initialization, it is trapped by the Service Handler.
williamr@2:         *
williamr@2:         * @param aInterestResourceId ID of the resource containing criteria items.
williamr@2:         * @leave KErrNotSupported CCoeEnv is not accessible.
williamr@2:         * @see Reset
williamr@2:         */
williamr@2:         IMPORT_C void AttachL(TInt aInterestResourceId);
williamr@2: 
williamr@2:         /**
williamr@2:         * Adds given interest to the Service Handler from an array of criteria items.
williamr@2:         * If a provider leaves during initialization, it is trapped by the Service Handler.
williamr@2:         *
williamr@2:         * @param aInterest Array of criteria items. Ownership is not transferred.
williamr@2:         */
williamr@2:         IMPORT_C void AttachL(const RCriteriaArray& aInterest);
williamr@2: 
williamr@2:         /**
williamr@2:         * Gets the currently valid interest in use by the Service Handler.
williamr@2:         *
williamr@2:         * @param aInterest An array of returned criteria items, may be empty.
williamr@2:         *                  Ownership is not transferred, i.e. the objects in the 
williamr@2:         *                  array must not be deleted.
williamr@2:         */
williamr@2:         IMPORT_C void GetInterest(RCriteriaArray& aInterest);
williamr@2: 
williamr@2:         /**
williamr@2:         * Removes given interest from the Service Handler. Corresponding service 
williamr@2:         * providers are unloaded.
williamr@2:         * 
williamr@2:         * @param aInterest Array of returned criteria items, may be empty.
williamr@2:         */
williamr@2:         IMPORT_C void DetachL(const RCriteriaArray& aInterest);
williamr@2: 
williamr@2:         /**
williamr@2:         * Removes given interest from the Service Handler. Corresponding service 
williamr@2:         * providers are unloaded.
williamr@2:         * 
williamr@2:         * @param aInterestResourceId ID of the resource containing criteria items.
williamr@2:         * @leave KErrNotSupported CCoeEnv is not accessible.
williamr@2:         */
williamr@2:         IMPORT_C void DetachL(TInt aInterestResourceId);
williamr@2:         
williamr@2:         /**
williamr@2:         * Returns criteria by ID.
williamr@2:         *
williamr@2:         * @param aId Criteria ID.
williamr@2:         * @return Criteria item pointer matching the ID. Ownership is not transferred.
williamr@2:         */
williamr@2:         IMPORT_C const CAiwCriteriaItem* GetCriteria(TInt aId);
williamr@2: 
williamr@2:         /**
williamr@2:         * Returns an empty instance of CAiwGenericParamList class. It can be
williamr@2:         * used for example as an input parameter list for the Service Handler's
williamr@2:         * API methods. This is just a convenience method and doesn't have
williamr@2:         * to be used. If consumer wants to create input list by itself
williamr@2:         * it is ok. If this method is used, the Service Handler takes care
williamr@2:         * of deleting returned generic parameter list.
williamr@2:         *
williamr@2:         * @return  An empty instance of CAiwGenericParameter list.
williamr@2:         */
williamr@2:         IMPORT_C CAiwGenericParamList& InParamListL();
williamr@2: 
williamr@2:         /**
williamr@2:         * Returns an empty instance of CAiwGenericParamList class. The instance can be
williamr@2:         * used for example as an output parameter list for Service Handler
williamr@2:         * API methods. This is just a convenience method and doesn't have
williamr@2:         * to be used. If consumer wants to create output list by itself
williamr@2:         * it is ok. If this method is used, Service Handler takes care
williamr@2:         * of deleting returned generic parameter list.
williamr@2:         *
williamr@2:         * @return  An empty instance of CAiwGenericParameter list.
williamr@2:         */
williamr@2:         IMPORT_C CAiwGenericParamList& OutParamListL();
williamr@2:         
williamr@2:     public:  // Menu handling
williamr@2: 
williamr@2:         /**
williamr@2:         * Initialises menu pane with service commands from a provider.
williamr@2:         * This method must be called upon DynInitMenuPaneL of consumer
williamr@2:         * application in order to let the provider to hook its menu items.
williamr@2:         *
williamr@2:         * @param aMenuPane Handle of the menu pane to initialise.
williamr@2:         * @param aMenuResourceId The menu to be attached.
williamr@2:         * @param aBaseMenuCmdId Base ID for the Service Handler to generate 
williamr@2:         *                       menu IDs for placeholders.
williamr@2:         * @param aInParamList Input parameter list for provider's parameters checking.
williamr@2:         * @leave KErrNotSupported CCoeEnv is not accessible.
williamr@2:         * @leave KErrOverflow Consumer application has too many AIW placeholders in its menu. 
williamr@2:         *                     Currently, maximum 16 is supported.
williamr@2:         */
williamr@2:         IMPORT_C void InitializeMenuPaneL(
williamr@2:             CEikMenuPane& aMenuPane,
williamr@2:             TInt aMenuResourceId,
williamr@2:             TInt aBaseMenuCmdId,
williamr@2:             const CAiwGenericParamList& aInParamList);
williamr@4: 
williamr@2:         /**
williamr@2:         * Initialises menu pane with service commands from a provider.
williamr@2:         * This method must be called upon DynInitMenuPaneL of consumer
williamr@2:         * application in order to let the provider to hook its menu items.
williamr@2:         * In normal circumstances, the other variant of this method should be used.
williamr@2:         *
williamr@2:         * @since S60 3.1
williamr@2:         * @param aMenuPane Handle of the menu pane to initialise.
williamr@2:         * @param aMenuResourceId The menu to be attached.
williamr@2:         * @param aBaseMenuCmdId Base ID for the Service Handler to generate 
williamr@2:         *                       menu IDs for placeholders.
williamr@2:         * @param aInParamList Input parameter list for provider's parameters checking.
williamr@2:         * @param aUseSubmenuTextsIfAvailable If the provider has specified alternative submenu
williamr@2:         *                       texts for its menu items, those can be taken into use if this 
williamr@2:         *                       parameter is set to ETrue. This should be used only for manually 
williamr@2:         *                       created submenus. If using AIW_CASCADE_ID or 
williamr@2:         *                       AIW_INTELLIGENT_CASCADE_ID, the AIW framework can automatically 
williamr@2:         *                       decide whether to use the submenu texts or not, and this parameter 
williamr@2:         *                       has no effect.
williamr@2:         * @leave KErrNotSupported CCoeEnv is not accessible.
williamr@2:         * @leave KErrOverflow Consumer application has too many AIW placeholders in its menu. 
williamr@2:         *                     Currently, maximum 16 is supported.
williamr@2:         */
williamr@2:         IMPORT_C void InitializeMenuPaneL(
williamr@2:             CEikMenuPane& aMenuPane,
williamr@2:             TInt aMenuResourceId,
williamr@2:             TInt aBaseMenuCmdId,
williamr@2:             const CAiwGenericParamList& aInParamList,
williamr@2:             TBool aUseSubmenuTextsIfAvailable);            
williamr@2:         
williamr@2:         /**
williamr@4:         * Initialises menu pane with service commands from a provider.
williamr@4:         * This method must be called upon DynInitMenuPaneL of consumer
williamr@4:         * application in order to let the provider to hook its menu items.
williamr@4:         * In normal circumstances, the other variant of this method should be used.
williamr@4:         *
williamr@4:         * @since S60 3.1
williamr@4:         * @param aMenuPane Handle of the menu pane to initialise.
williamr@4:         * @param aMenuResourceId The menu to be attached.
williamr@4:         * @param aBaseMenuCmdId Base ID for the Service Handler to generate 
williamr@4:         *                       menu IDs for placeholders.
williamr@4:         * @param aInParamList Input parameter list for provider's parameters checking.
williamr@4:         * @param aUseSubmenuTextsIfAvailable If the provider has specified alternative submenu
williamr@4:         *                       texts for its menu items, those can be taken into use if this 
williamr@4:         *                       parameter is set to ETrue. This should be used only for manually 
williamr@4:         *                       created submenus. If using AIW_CASCADE_ID or 
williamr@4:         *                       AIW_INTELLIGENT_CASCADE_ID, the AIW framework can automatically 
williamr@4:         *                       decide whether to use the submenu texts or not, and this parameter 
williamr@4:         *                       has no effect.
williamr@4:         * @param aSetAsItemSpecific Added commands are marked as item specific.
williamr@4:         * @leave KErrNotSupported CCoeEnv is not accessible.
williamr@4:         * @leave KErrOverflow Consumer application has too many AIW placeholders in its menu. 
williamr@4:         *                     Currently, maximum 16 is supported.
williamr@4:         */
williamr@4:         IMPORT_C void InitializeMenuPaneL(
williamr@4:             CEikMenuPane& aMenuPane,
williamr@4:             TInt aMenuResourceId,
williamr@4:             TInt aBaseMenuCmdId,
williamr@4:             const CAiwGenericParamList& aInParamList,
williamr@4:             TBool aUseSubmenuTextsIfAvailable,
williamr@4:             TBool aSetAsItemSpecific);
williamr@4: 
williamr@4:         /**
williamr@2:         * Returns the service command ID associated to the menu command. If found, it means 
williamr@2:         * that there is a provider which can handle the menu command. Thus the command 
williamr@2:         * handling needs to be routed to the provider via ExecuteMenuCmdL.
williamr@2:         *
williamr@2:         * @param aMenuCmdId Menu command ID to be mapped to service cmd.
williamr@2:         * @return Service command ID, KAiwCmdNone if no ID is found.
williamr@2:         * @see ExecuteMenuCmdL
williamr@2:         */
williamr@2:         IMPORT_C TInt ServiceCmdByMenuCmd(TInt aMenuCmdId) const;
williamr@2: 
williamr@2:         /**
williamr@2:         * Tells the provider to execute a menu command invoked by the consumer.
williamr@2:         * Not supported if calling outside UI framework. Use ServiceCmdByMenuCmd to 
williamr@2:         * check if there is any provider for the menu command.
williamr@2:         *
williamr@2:         * @param aMenuCmdId The menu command to be executed.
williamr@2:         * @param aInParamList Input data parameters, can be an empty list.
williamr@2:         * @param aOutParamList Output data parameters, can be an empty list.
williamr@2:         * @param aCmdOptions Options for the command, see TAiwServiceCmdOptions in AiwCommon.hrh.
williamr@2:         * @param aCallback Callback for asynchronous command handling, parameter checking, etc.
williamr@2:         * @leave KErrArgument Callback is missing when required.
williamr@2:         * @leave KErrNotSupported No cmd matches given menu command or CCoeEnv is not accessible.
williamr@2:         * @see ServiceCmdByMenuCmd
williamr@2:         */
williamr@2:         IMPORT_C void ExecuteMenuCmdL(
williamr@2:             TInt aMenuCmdId,
williamr@2:             const CAiwGenericParamList& aInParamList,
williamr@2:             CAiwGenericParamList& aOutParamList,
williamr@2:             TUint aCmdOptions = 0,
williamr@2:             MAiwNotifyCallback* aCallback= NULL);
williamr@2: 
williamr@2:         /**
williamr@2:         * Attach menu related criteria items to the given menu.
williamr@2:         * If a provider leaves during initialization, it is trapped by the Service Handler. 
williamr@2:         *
williamr@2:         * @param aMenuResourceId      Menu to be attached.
williamr@2:         * @param aInterestResourceId  Resource id for the interest list.
williamr@2:         * @leave KErrNotSupported     CCoeEnv is not accessible.
williamr@2:         */
williamr@2:         IMPORT_C void AttachMenuL(TInt aMenuResourceId, TInt aInterestResourceId);
williamr@2: 
williamr@2:         /**
williamr@2:         * Attach menu related criteria items to the given menu.
williamr@2:         * If a provider leaves during initialization, it is trapped by the Service Handler. 
williamr@2:         *
williamr@2:         * @param aMenuResourceId  Menu to be attached.
williamr@2:         * @param aReader          Resource reader for the interest list.
williamr@2:         * @leave KErrNotSupported CCoeEnv is not accessible.
williamr@2:         */
williamr@2:         IMPORT_C void AttachMenuL(TInt aMenuResourceId, TResourceReader& aReader);
williamr@2:         
williamr@2:         /**
williamr@2:         * Attach menu related criteria items to the given menu. 
williamr@2:         *
williamr@2:         * @since S60 3.2
williamr@2:         * @param aMenuResourceId  Menu to be attached.
williamr@2:         * @param aInterest        Array of criteria items. Ownership is not transferred.
williamr@2:         * @leave KErrNotSupported CCoeEnv is not accessible.
williamr@2:         */
williamr@2:         IMPORT_C void AttachMenuL(TInt aMenuResourceId, const RCriteriaArray& aInterest);   
williamr@2: 
williamr@2:         /**
williamr@2:         * Detach menu related criteria items from the given menu.
williamr@2:         * In following cases this method just returns without doing anything:
williamr@2:         *   1. If interest resource id is non-zero and CCoeEnv is not accessible.
williamr@2:         *   2. If interest resource id is non-zero and there occurs an error when reading
williamr@2:         *      the interest (e.g. not enough memory). 
williamr@2:         * 
williamr@2:         * @param aMenuResourceId      Menu to be detached.
williamr@2:         * @param aInterestResourceId  Resource id for the interest list. If NULL, all 
williamr@2:         *                             criteria items are detached from the given menu.
williamr@2:         */
williamr@2:         IMPORT_C void DetachMenu(TInt aMenuResourceId, TInt aInterestResourceId);
williamr@2: 
williamr@2:         /**
williamr@2:         * Checks if there are menu providers attached to given menu id. Consumer 
williamr@2:         * application can use this information to decide whether a sub menu 
williamr@2:         * containing only AIW items should be hidden or not.
williamr@2:         *
williamr@2:         * @param  aSubMenuId The menu id to be checked.
williamr@2:         * @return ETrue  if there isn't any menu providers attached to this menu.
williamr@2:         *         EFalse otherwise. 
williamr@2:         */
williamr@2:         IMPORT_C TBool IsSubMenuEmpty(TInt aSubMenuId);
williamr@2: 
williamr@2:         /**
williamr@2:         * Returns boolean value indicating whether the given menu contains
williamr@2:         * currently attached placeholders.
williamr@2:         *
williamr@2:         * @param   aMenuResourceId  Resource id of the menu to be queried.
williamr@2:         * @return  ETrue  if aMenuResource contains currently attached placeholders.
williamr@2:         *          EFalse otherwise. 
williamr@2:         */
williamr@2:         IMPORT_C TBool IsAiwMenu(TInt aMenuResourceId);
williamr@2: 
williamr@2:         /**
williamr@2:         * Handles AIW submenus. This method should be called from consumer application's 
williamr@2:         * DynInitMenuPaneL.
williamr@2:         *
williamr@2:         * @param  aPane  Menu pane to be handled.
williamr@2:         * @return ETrue  if aPane was an AIW submenu and it was handled. 
williamr@2:         *                Consumer's DynInitMenuPaneL pane may now return.
williamr@2:         *         EFalse if aPane was not an AIW submenu and DynInitMenuPaneL should
williamr@2:         *                continue normally.
williamr@2:         */
williamr@2:         IMPORT_C TBool HandleSubmenuL(CEikMenuPane& aPane);
williamr@2: 
williamr@2:         /**
williamr@2:         * CEikMenuPane uses this method to inform AIF framework that a menu is launched.
williamr@2:         * This method does not need to be called by any other component.
williamr@2:         *
williamr@2:         * @since S60 3.0
williamr@2:         */
williamr@2:         IMPORT_C static void ReportMenuLaunch();
williamr@2: 
williamr@2:     public:  // Generic Service Command handling
williamr@2:         
williamr@2:         /**
williamr@2:         * Executes a service command for all providers. Otherwise similar to ExecuteMenuCmdL.
williamr@2:         *
williamr@2:         * @param aCmdId The command to be executed.
williamr@2:         * @param aInParamList Input data parameters, can be an empty list.
williamr@2:         * @param aOutParamList Output data parameters, can be an empty list.
williamr@2:         * @param aCmdOptions Options for the command, see TAiwServiceCmdOptions in AiwCommon.hrh.    
williamr@2:         * @param aCallback Callback for asynchronous command handling, parameter checking, etc.
williamr@2:         * @leave KErrArgument Callback is missing when required.
williamr@2:         * @leave KErrNotSupported No provider supports the service.
williamr@2:         */
williamr@2:         IMPORT_C void ExecuteServiceCmdL(
williamr@2:             const TInt& aCmdId,
williamr@2:             const CAiwGenericParamList& aInParamList,
williamr@2:             CAiwGenericParamList& aOutParamList,
williamr@2:             TUint aCmdOptions = 0,
williamr@2:             MAiwNotifyCallback* aCallback = 0);
williamr@2:             
williamr@2:     private:
williamr@2:         void ConstructL();
williamr@2:         CAiwServiceHandler();
williamr@2: 
williamr@2:     private:
williamr@2:         CAiwServiceHandlerImpl* iImpl;
williamr@2:     };
williamr@2: 
williamr@2: #endif // AIW_SERVICE_HANDLER_H
williamr@2: 
williamr@2: // END of File
williamr@2: 
williamr@2: