--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/serviceapifw_plat/liw_service_handler_api/inc/liwservicehandler.h Mon Mar 30 12:51:20 2009 +0300
@@ -0,0 +1,457 @@
+/*
+* 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