diff -r 7aa6007702af -r 61b27eec6533 serviceapifw_plat/liw_service_handler_api/inc/liwservicehandler.h --- a/serviceapifw_plat/liw_service_handler_api/inc/liwservicehandler.h Fri Apr 16 15:54:49 2010 +0300 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,457 +0,0 @@ -/* -* 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 "Eclipse Public License v1.0" -* which accompanies this distribution, and is available -* at the URL "http://www.eclipse.org/legal/epl-v10.html". -* -* Initial Contributors: -* Nokia Corporation - initial contribution. -* -* Contributors: -* -* Description: Declares an API for the consumer applications to access the -* Language Interworking Framework. -* -*/ - - - - - - - -#ifndef LIW_SERVICE_HANDLER_H -#define LIW_SERVICE_HANDLER_H - -// INCLUDES -#include -#include -#include - -// CONSTANTS - -// MACROS - -// FUNCTION PROTOTYPES - -// FORWARD DECLARATIONS -class CLiwServiceHandlerImpl; - -class CRTSecMgrScriptSession; - - -enum TLiwLoadStatus -{ - KLiwUnknown = -5, - KLiwMetaDataInvalidFormat, //-4 - KLiwInvalidVersionSpecification, //-3 - KLiwVersionOutOfRange, //-2 - KLiwSecurityAccessCheckFailed, //-1 - KLiwServiceLoadSuccess, //0 - KLiwServiceAlreadyLoaded //1 - - //..Other possible error codes -}; - - -// CLASS DECLARATION - -/** -* CLiwServiceHandler is the main class of the Language 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 LIW 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 Series 60 2.6 -*/ -NONSHARABLE_CLASS(CLiwServiceHandler) : public CBase - { - public: // Construction & destruction - - /** - * Constructs a Service Handler instance. - */ - IMPORT_C static CLiwServiceHandler* NewL(); - - /** - * Constructs a Service Handler instance. - */ - IMPORT_C static CLiwServiceHandler* NewLC(); - - /** - * Destructor. - */ - IMPORT_C virtual ~CLiwServiceHandler(); - - 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 CLiwCriteriaItem* 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 TInt 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 CLiwCriteriaItem* GetCriteria(TInt aId); - - /** - * Returns an empty instance of CLiwGenericParamList 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 CLiwGenericParameter list. - */ - IMPORT_C CLiwGenericParamList& InParamListL(); - - /** - * Returns an empty instance of CLiwGenericParamList 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 CLiwGenericParameter list. - */ - IMPORT_C CLiwGenericParamList& 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 LIW placeholders in its menu. - * Currently, maximum 16 is supported. - */ - IMPORT_C void InitializeMenuPaneL( - CEikMenuPane& aMenuPane, - TInt aMenuResourceId, - TInt aBaseMenuCmdId, - const CLiwGenericParamList& 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. - * - * @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 LIW_CASCADE_ID or - * LIW_INTELLIGENT_CASCADE_ID, the LIW 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 LIW placeholders in its menu. - * Currently, maximum 16 is supported. - */ - IMPORT_C void InitializeMenuPaneL( - CEikMenuPane& aMenuPane, - TInt aMenuResourceId, - TInt aBaseMenuCmdId, - const CLiwGenericParamList& 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, - * KNullServiceCmd is returned if no service command exists. - * @return Service command ID, KLiwCmdNone 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 TLiwServiceCmdOptions in LiwCommon.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 CLiwGenericParamList& aInParamList, - CLiwGenericParamList& aOutParamList, - TUint aCmdOptions = 0, - MLiwNotifyCallback* 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. - * - * @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); - - /** - * Attach menu related criteria items to the given menu. - * - * @param aMenuEntries List of menu command ids, ids not related to interests may be set to 0. - * @param aMenuResourceId Menu to be attached. - * @param aInterest Interest list. - */ - IMPORT_C void AttachMenuL(RArray& aMenuEntries, TInt aMenuResourceId, 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 LIW 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 IsLiwMenu(TInt aMenuResourceId); - - /** - * Handles LIW submenus. This method should be called from consumer application's - * DynInitMenuPaneL. - * - * @param aPane Menu pane to be handled. - * @return ETrue if aPane was an LIW submenu and it was handled. - * Consumer's DynInitMenuPaneL pane may now return. - * EFalse if aPane was not an LIW 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 Series 60 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 TLiwServiceCmdOptions in LiwCommon.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 CLiwGenericParamList& aInParamList, - CLiwGenericParamList& aOutParamList, - TUint aCmdOptions = 0, - MLiwNotifyCallback* aCallback = 0); - - /** - * Executes a service command. - * - * @param aCmd The criteria item containing the service command and content type - * @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 TLiwServiceCmdOptions in LiwCommon.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 CLiwCriteriaItem& aCmd, - const CLiwGenericParamList& aInParamList, - CLiwGenericParamList& aOutParamList, - TUint aCmdOptions = 0, - MLiwNotifyCallback* aCallback = 0); - - /** - * Gets provider command ID by dynamic command ID. - * - * @since Series 60 3.0 - * @param aMenuCmdId The consumer's menu command ID generated by LIW framework. - * This can be get e.g. from consumer's HandleCommandL(). - * @return Found provider menu command ID, KErrNotFound if not found. - */ - IMPORT_C TInt MenuCmdId(TInt aMenuCmdId) const; - - IMPORT_C TInt AttachL(const RCriteriaArray& aInterest,CRTSecMgrScriptSession& aSecMgrScriptSession); - - /** - * Lists available service implementations - * - * @param aFilterItem - * @param aProviderList - * - * @return none - */ - IMPORT_C void QueryImplementationL(RCriteriaArray& aFilterItem, RCriteriaArray& aProviderList); - - private: - void ConstructL(); - CLiwServiceHandler(); - - private: - CLiwServiceHandlerImpl* iImpl; - }; - -#endif // LIW_SERVICE_HANDLER_H - -// END of File