--- 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 <barsread.h>
-#include <liwcommon.h>
-#include <e32capability.h>
-
-// 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<TInt>& 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