diff -r 666f914201fb -r 2fe1408b6811 epoc32/include/mw/aiwservicehandler.h --- a/epoc32/include/mw/aiwservicehandler.h Tue Nov 24 13:55:44 2009 +0000 +++ b/epoc32/include/mw/aiwservicehandler.h Tue Mar 16 16:12:26 2010 +0000 @@ -1,1 +1,393 @@ -aiwservicehandler.h +/* +* 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 +#include + +// 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 + +