1 aiwservicehandler.h

     1 /*

     2 * Copyright (c) 2003-2005 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * 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

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:     Declares an API for the consumer applications to access the 

    15 *                Application Interworking Framework. 

    16 *

    17 */

    18 

    19 

    20 

    21 

    22 

    23 #ifndef AIW_SERVICE_HANDLER_H

    24 #define AIW_SERVICE_HANDLER_H

    25 

    26 // INCLUDES

    27 #include <barsread.h> 

    28 #include <aiwcommon.h>

    29 

    30 // CONSTANTS

    31 

    32 // MACROS

    33 

    34 // FUNCTION PROTOTYPES

    35 

    36 // FORWARD DECLARATIONS

    37 class CAiwServiceHandlerImpl;

    38 

    39 // CLASS DECLARATION

    40 

    41 /**

    42 * CAiwServiceHandler is the main class of the Application Interworking

    43 * Framework. The Service Handler implements support for dynamically

    44 * loadable service providers which offer services to consumer applications. 

    45 * The Service Handler maps consumers and service providers together via 

    46 * interests and data agreements and hides the consumers from the providers. 

    47 *

    48 * SERVICE is any command or functionality offered by a provider to 

    49 * consumer. The service includes typically menu item UI elements,

    50 * but it can also just an engine type of command which executes specific 

    51 * functionality and reports status back to the consumer.

    52 *

    53 * CONSUMER application accesses interesting services offered by

    54 * service provider(s). The consumer uses only those services in which

    55 * it is interested in. The interest is expressed using a set of criteria

    56 * items.

    57 *

    58 * INTEREST is a list of criteria items.

    59 *

    60 * CRITERIA consists of set of attributes which guide the AIW Framework to use

    61 * only those providers in which the consumer is interested in.

    62 * The criteria consists of following attributes:

    63 *   - Criteria UID (we can allocate pre-defined criteria items).

    64 *   - Service command UID (we can allocate pre-defined commands).

    65 *   - Content MIME type (string).

    66 *   - Additional options (variant data type just in case).

    67 *

    68 * PROVIDER produces those services for a consumer that match the given criteria 

    69 * specified by the consumer. A provider can offer menu items and their command

    70 * handling logic to the consumer applications. A provider can also offer base

    71 * services that don't require any UI elements.

    72 *

    73 * DATA AGREEMENT is an agreement between consumer and provider about parameters 

    74 * needed to be passed in a use case.

    75 *

    76 * @lib ServiceHandler.lib

    77 * @since S60 2.6

    78 */

    79 NONSHARABLE_CLASS(CAiwServiceHandler) : public CBase

    80     {

    81     public:  // Construction & destruction

    82 

    83         /**

    84         * Constructs a Service Handler instance.

    85         */

    86         IMPORT_C static CAiwServiceHandler* NewL();

    87         

    88         /**

    89         * Constructs a Service Handler instance.

    90         */

    91         IMPORT_C static CAiwServiceHandler* NewLC();  

    92 

    93         /** 

    94         * Destructor.

    95         */

    96         IMPORT_C virtual ~CAiwServiceHandler();

    97         

    98     public:  // Management

    99 

   100         /**

   101         * Resets the Service Handler, discards existing interest and unloads 

   102         * corresponding service providers.

   103         */

   104         IMPORT_C void Reset();

   105 

   106         /**

   107         * Returns the amount of providers that fulfil the given criteria.

   108         *

   109         * @param aCriteria Criteria to match.

   110         * @return Number of providers matching the criteria.

   111         */

   112         IMPORT_C TInt NbrOfProviders(const CAiwCriteriaItem* aCriteria);

   113         

   114     public:  // Interest handling

   115         

   116         /**

   117         * Adds the given interest to the Service Handler from a resource and updates 

   118         * possibly existing old interest. Corresponding service providers are loaded.

   119         * If a provider leaves during initialization, it is trapped by the Service Handler.

   120         *

   121         * @param aInterestResourceId ID of the resource containing criteria items.

   122         * @leave KErrNotSupported CCoeEnv is not accessible.

   123         * @see Reset

   124         */

   125         IMPORT_C void AttachL(TInt aInterestResourceId);

   126 

   127         /**

   128         * Adds given interest to the Service Handler from an array of criteria items.

   129         * If a provider leaves during initialization, it is trapped by the Service Handler.

   130         *

   131         * @param aInterest Array of criteria items. Ownership is not transferred.

   132         */

   133         IMPORT_C void AttachL(const RCriteriaArray& aInterest);

   134 

   135         /**

   136         * Gets the currently valid interest in use by the Service Handler.

   137         *

   138         * @param aInterest An array of returned criteria items, may be empty.

   139         *                  Ownership is not transferred, i.e. the objects in the 

   140         *                  array must not be deleted.

   141         */

   142         IMPORT_C void GetInterest(RCriteriaArray& aInterest);

   143 

   144         /**

   145         * Removes given interest from the Service Handler. Corresponding service 

   146         * providers are unloaded.

   147         * 

   148         * @param aInterest Array of returned criteria items, may be empty.

   149         */

   150         IMPORT_C void DetachL(const RCriteriaArray& aInterest);

   151 

   152         /**

   153         * Removes given interest from the Service Handler. Corresponding service 

   154         * providers are unloaded.

   155         * 

   156         * @param aInterestResourceId ID of the resource containing criteria items.

   157         * @leave KErrNotSupported CCoeEnv is not accessible.

   158         */

   159         IMPORT_C void DetachL(TInt aInterestResourceId);

   160         

   161         /**

   162         * Returns criteria by ID.

   163         *

   164         * @param aId Criteria ID.

   165         * @return Criteria item pointer matching the ID. Ownership is not transferred.

   166         */

   167         IMPORT_C const CAiwCriteriaItem* GetCriteria(TInt aId);

   168 

   169         /**

   170         * Returns an empty instance of CAiwGenericParamList class. It can be

   171         * used for example as an input parameter list for the Service Handler's

   172         * API methods. This is just a convenience method and doesn't have

   173         * to be used. If consumer wants to create input list by itself

   174         * it is ok. If this method is used, the Service Handler takes care

   175         * of deleting returned generic parameter list.

   176         *

   177         * @return  An empty instance of CAiwGenericParameter list.

   178         */

   179         IMPORT_C CAiwGenericParamList& InParamListL();

   180 

   181         /**

   182         * Returns an empty instance of CAiwGenericParamList class. The instance can be

   183         * used for example as an output parameter list for Service Handler

   184         * API methods. This is just a convenience method and doesn't have

   185         * to be used. If consumer wants to create output list by itself

   186         * it is ok. If this method is used, Service Handler takes care

   187         * of deleting returned generic parameter list.

   188         *

   189         * @return  An empty instance of CAiwGenericParameter list.

   190         */

   191         IMPORT_C CAiwGenericParamList& OutParamListL();

   192         

   193     public:  // Menu handling

   194 

   195         /**

   196         * Initialises menu pane with service commands from a provider.

   197         * This method must be called upon DynInitMenuPaneL of consumer

   198         * application in order to let the provider to hook its menu items.

   199         *

   200         * @param aMenuPane Handle of the menu pane to initialise.

   201         * @param aMenuResourceId The menu to be attached.

   202         * @param aBaseMenuCmdId Base ID for the Service Handler to generate 

   203         *                       menu IDs for placeholders.

   204         * @param aInParamList Input parameter list for provider's parameters checking.

   205         * @leave KErrNotSupported CCoeEnv is not accessible.

   206         * @leave KErrOverflow Consumer application has too many AIW placeholders in its menu. 

   207         *                     Currently, maximum 16 is supported.

   208         */

   209         IMPORT_C void InitializeMenuPaneL(

   210             CEikMenuPane& aMenuPane,

   211             TInt aMenuResourceId,

   212             TInt aBaseMenuCmdId,

   213             const CAiwGenericParamList& aInParamList);

   214             

   215         /**

   216         * Initialises menu pane with service commands from a provider.

   217         * This method must be called upon DynInitMenuPaneL of consumer

   218         * application in order to let the provider to hook its menu items.

   219         * In normal circumstances, the other variant of this method should be used.

   220         *

   221         * @since S60 3.1

   222         * @param aMenuPane Handle of the menu pane to initialise.

   223         * @param aMenuResourceId The menu to be attached.

   224         * @param aBaseMenuCmdId Base ID for the Service Handler to generate 

   225         *                       menu IDs for placeholders.

   226         * @param aInParamList Input parameter list for provider's parameters checking.

   227         * @param aUseSubmenuTextsIfAvailable If the provider has specified alternative submenu

   228         *                       texts for its menu items, those can be taken into use if this 

   229         *                       parameter is set to ETrue. This should be used only for manually 

   230         *                       created submenus. If using AIW_CASCADE_ID or 

   231         *                       AIW_INTELLIGENT_CASCADE_ID, the AIW framework can automatically 

   232         *                       decide whether to use the submenu texts or not, and this parameter 

   233         *                       has no effect.

   234         * @leave KErrNotSupported CCoeEnv is not accessible.

   235         * @leave KErrOverflow Consumer application has too many AIW placeholders in its menu. 

   236         *                     Currently, maximum 16 is supported.

   237         */

   238         IMPORT_C void InitializeMenuPaneL(

   239             CEikMenuPane& aMenuPane,

   240             TInt aMenuResourceId,

   241             TInt aBaseMenuCmdId,

   242             const CAiwGenericParamList& aInParamList,

   243             TBool aUseSubmenuTextsIfAvailable);            

   244         

   245         /**

   246         * Returns the service command ID associated to the menu command. If found, it means 

   247         * that there is a provider which can handle the menu command. Thus the command 

   248         * handling needs to be routed to the provider via ExecuteMenuCmdL.

   249         *

   250         * @param aMenuCmdId Menu command ID to be mapped to service cmd.

   251         * @return Service command ID, KAiwCmdNone if no ID is found.

   252         * @see ExecuteMenuCmdL

   253         */

   254         IMPORT_C TInt ServiceCmdByMenuCmd(TInt aMenuCmdId) const;

   255 

   256         /**

   257         * Tells the provider to execute a menu command invoked by the consumer.

   258         * Not supported if calling outside UI framework. Use ServiceCmdByMenuCmd to 

   259         * check if there is any provider for the menu command.

   260         *

   261         * @param aMenuCmdId The menu command to be executed.

   262         * @param aInParamList Input data parameters, can be an empty list.

   263         * @param aOutParamList Output data parameters, can be an empty list.

   264         * @param aCmdOptions Options for the command, see TAiwServiceCmdOptions in AiwCommon.hrh.

   265         * @param aCallback Callback for asynchronous command handling, parameter checking, etc.

   266         * @leave KErrArgument Callback is missing when required.

   267         * @leave KErrNotSupported No cmd matches given menu command or CCoeEnv is not accessible.

   268         * @see ServiceCmdByMenuCmd

   269         */

   270         IMPORT_C void ExecuteMenuCmdL(

   271             TInt aMenuCmdId,

   272             const CAiwGenericParamList& aInParamList,

   273             CAiwGenericParamList& aOutParamList,

   274             TUint aCmdOptions = 0,

   275             MAiwNotifyCallback* aCallback= NULL);

   276 

   277         /**

   278         * Attach menu related criteria items to the given menu.

   279         * If a provider leaves during initialization, it is trapped by the Service Handler. 

   280         *

   281         * @param aMenuResourceId      Menu to be attached.

   282         * @param aInterestResourceId  Resource id for the interest list.

   283         * @leave KErrNotSupported     CCoeEnv is not accessible.

   284         */

   285         IMPORT_C void AttachMenuL(TInt aMenuResourceId, TInt aInterestResourceId);

   286 

   287         /**

   288         * Attach menu related criteria items to the given menu.

   289         * If a provider leaves during initialization, it is trapped by the Service Handler. 

   290         *

   291         * @param aMenuResourceId  Menu to be attached.

   292         * @param aReader          Resource reader for the interest list.

   293         * @leave KErrNotSupported CCoeEnv is not accessible.

   294         */

   295         IMPORT_C void AttachMenuL(TInt aMenuResourceId, TResourceReader& aReader);

   296         

   297         /**

   298         * Attach menu related criteria items to the given menu. 

   299         *

   300         * @since S60 3.2

   301         * @param aMenuResourceId  Menu to be attached.

   302         * @param aInterest        Array of criteria items. Ownership is not transferred.

   303         * @leave KErrNotSupported CCoeEnv is not accessible.

   304         */

   305         IMPORT_C void AttachMenuL(TInt aMenuResourceId, const RCriteriaArray& aInterest);   

   306 

   307         /**

   308         * Detach menu related criteria items from the given menu.

   309         * In following cases this method just returns without doing anything:

   310         *   1. If interest resource id is non-zero and CCoeEnv is not accessible.

   311         *   2. If interest resource id is non-zero and there occurs an error when reading

   312         *      the interest (e.g. not enough memory). 

   313         * 

   314         * @param aMenuResourceId      Menu to be detached.

   315         * @param aInterestResourceId  Resource id for the interest list. If NULL, all 

   316         *                             criteria items are detached from the given menu.

   317         */

   318         IMPORT_C void DetachMenu(TInt aMenuResourceId, TInt aInterestResourceId);

   319 

   320         /**

   321         * Checks if there are menu providers attached to given menu id. Consumer 

   322         * application can use this information to decide whether a sub menu 

   323         * containing only AIW items should be hidden or not.

   324         *

   325         * @param  aSubMenuId The menu id to be checked.

   326         * @return ETrue  if there isn't any menu providers attached to this menu.

   327         *         EFalse otherwise. 

   328         */

   329         IMPORT_C TBool IsSubMenuEmpty(TInt aSubMenuId);

   330 

   331         /**

   332         * Returns boolean value indicating whether the given menu contains

   333         * currently attached placeholders.

   334         *

   335         * @param   aMenuResourceId  Resource id of the menu to be queried.

   336         * @return  ETrue  if aMenuResource contains currently attached placeholders.

   337         *          EFalse otherwise. 

   338         */

   339         IMPORT_C TBool IsAiwMenu(TInt aMenuResourceId);

   340 

   341         /**

   342         * Handles AIW submenus. This method should be called from consumer application's 

   343         * DynInitMenuPaneL.

   344         *

   345         * @param  aPane  Menu pane to be handled.

   346         * @return ETrue  if aPane was an AIW submenu and it was handled. 

   347         *                Consumer's DynInitMenuPaneL pane may now return.

   348         *         EFalse if aPane was not an AIW submenu and DynInitMenuPaneL should

   349         *                continue normally.

   350         */

   351         IMPORT_C TBool HandleSubmenuL(CEikMenuPane& aPane);

   352 

   353         /**

   354         * CEikMenuPane uses this method to inform AIF framework that a menu is launched.

   355         * This method does not need to be called by any other component.

   356         *

   357         * @since S60 3.0

   358         */

   359         IMPORT_C static void ReportMenuLaunch();

   360 

   361     public:  // Generic Service Command handling

   362         

   363         /**

   364         * Executes a service command for all providers. Otherwise similar to ExecuteMenuCmdL.

   365         *

   366         * @param aCmdId The command to be executed.

   367         * @param aInParamList Input data parameters, can be an empty list.

   368         * @param aOutParamList Output data parameters, can be an empty list.

   369         * @param aCmdOptions Options for the command, see TAiwServiceCmdOptions in AiwCommon.hrh.    

   370         * @param aCallback Callback for asynchronous command handling, parameter checking, etc.

   371         * @leave KErrArgument Callback is missing when required.

   372         * @leave KErrNotSupported No provider supports the service.

   373         */

   374         IMPORT_C void ExecuteServiceCmdL(

   375             const TInt& aCmdId,

   376             const CAiwGenericParamList& aInParamList,

   377             CAiwGenericParamList& aOutParamList,

   378             TUint aCmdOptions = 0,

   379             MAiwNotifyCallback* aCallback = 0);

   380             

   381     private:

   382         void ConstructL();

   383         CAiwServiceHandler();

   384 

   385     private:

   386         CAiwServiceHandlerImpl* iImpl;

   387     };

   388 

   389 #endif // AIW_SERVICE_HANDLER_H

   390 

   391 // END of File

   392 

   393