Nokia N97 SDK
Example Applications Guide

AIWConsumerBasics

1. About this Example
2. Architecture
3. Design and Implementation


1. About this Example

This Application Interworking (AIW) example application demonstrates how to use the AIW Consumer APIs. These APIs are used for requesting the Help AIW Provider to display an application specific context sensitive help file.

The instructions of using the application are simple. The user should open the Options menu, which contains "Show Help" menu item. This menu item is inserted by the AIW Help Provider. Selecting that item creates a request to the AIW Help provider to show the help content. This request goes first to the AIW Framework, which then forwards it to the relevant providers (the Help provider in this case).

The example application demonstrates also the attach/detach functionality of the AIW Framework. Numeric keys '1' and '2' can be used to attach and detach so called AIW interest to the AIW Framework. When the consumer's interest is attached, the Help provider can add its menu item to the Options menu. In the other hand, when the interest is not attached, only an AIW placeholder for the Help command is shown in the menu. The attach status and the number of attached providers is also shown in the main view of the example application.

The service provider, which does the actual help launching, is in normal circumstances the AIW Help Provider. As all AIW providers, it is an ECOM plugin, and should exist by default in the SDK environment. Because of the nature of the AIW Framework, there may also exist other AIW providers offering the help service. In that case, the additional services are also displayed as menu items in the Options menu. On the other hand, if there are no help providers in the environment, no AIW menu items are displayed in the menu.

1.1. APIs demonstrated

This example application demonstrates the use of the following APIs:


1.2. Prerequisites

This example requires a familiarity with the Application Interworking Framework.


2. Architecture

AIWConsumerBasics application is a standalone executable UI application. It acts as an AIW consumer application, i.e. it uses the services offered by the AIW provider modules (ECOM plugins) via the AIW Framework.

3. Design and Implementation

3.1 Capabilities

This application does not require any capabilities.

Note that the required capabilities are provider specific. This means that the AIW Framework does not exactly state which capabilities are required for a consumer application, but these depend on the AIW providers used. Using the Help AIW provider does not require any capabilities.

3.2 Defining an AIW interest in the project resource file

One of the first steps of making AIW consumer application is to define the AIW services that the application is interested in. In AIW terms, this is called as interest. Interest is a list of criteria items, which in turn contain fields like criteria Id, AIW service command, content type and options. The interest of the example application is defined in AIWConsumerBasics.rss file, in R_AIWCONSUMERBASICS_MENUINTEREST resource. The interest contains only items for menu services, i.e. the application is not interested in using so called base services.

This application is interested in showing help content, so the corresponding AIW command is KAiwCmdHelp. This command is used in the criteria item. The criteria id for this menu service is EAIWConsumerBasicsHelpPlaceholder, and is used for mapping the criteria item to a menu item. The content type is not needed, and therefore a wildcard type ("*") can be used.

3.3 Defining placeholders for AIW menu in the project resource file

The resource structure MENU_PANE defines the menu of the application. It contains an ordinary (non-AIW) menu item for exiting the application, but it also contains an AIW menu placeholder, in which the AIW providers can add their menu items.

3.4 Creating Service Handler instance and attaching the interest to the AIW Framework

For using AIW services, an instance of CAiwServiceHandler is needed. It is dynamically allocated in CAIWConsumerBasicsAppUi::ConstructL() method. The next thing to do is to attach all interests to the AIW Framework. This is done by calling Service Handler's AttachMenuL(). If we would like to use AIW base services, the AttachL() method should be called for them.

3.5 Initializing menus

For enabling the AIW providers to display their menu items in the consumer application, the Options menu must be initialised. This is done in CAIWConsumerBasicsAppUi::DynInitMenuPaneL(), which is called every time when a menu (or a submenu) is opened.

An important issue to note is that if the user is opening a submenu, which includes only AIW menu items, it must be handled by the AIW Framework. Therefore, Service Handler's HandleSubmenuL() method is called first. Only if this method returns EFalse, we should continue the menu initialization. (In this application we don't have an AIW submenus, so this call is actually not needed. However, it is needed if using automatic AIW submenus with AIW_CASCADE_ID or AIW_INTELLIGENT_CASCADE_ID flags, so it is left for a reference.)

After HandleSubmenuL() call, it is possible to add application specific initialization code. Finally, the Service Handler's InitializeMenuPaneL() method should be called for AIW menus. This method allows the providers to replace the application's menu placeholders with their AIW menu items.

3.6 Executing AIW menu services

In Symbian environment, HandleCommandL() method is called each time when the user selects a menu item from the options menu. This is also the case when an AIW menu item is selected. The AIW commands cannot be recognized by the example application, so all the unidentified commands need to be forwarded to the AIW Framework.

Usually, only the ExecuteMenuCmdL() method needs to be called for an AIW (i.e. unidentified) command. However, in this example application, we need to set up the help parameters every time before calling the ExecuteMenuCmdL(). These kind of initialisations might be quite time consuming. To avoid this problem, the AIW Framework introduces a method called ServiceCmdByMenuCmd(). By using it, it is possible to obtain the AIW service command id by the menu command id. With that information, it is possible to make the parameter data initialisation only if the user is actually going to execute the KAiwCmdHelp command.

3.7 Setting up a generic parameter list

A generic parameter list containing the required help parameters is set up in method CAIWConsumerBasicsAppUi::SetupGenericParamListL().

When executing the Help AIW service command, two parameters need to be passed to the Help provider. These parameters are the help context UID and the help context string. To transfer these values, we need to create two TAiwGenericParam objects with semantic Id EGenericParamHelpItem. The parameter values are packed in TAiwVariant objects, which are automatically given some TVariantTypeId value. In this case, the required values are EVariantTypeTUid (for context UID) and EVariantTypeDesC (for context string). The TAiwGenericParam objects are then appended to a generic parameter list, which is transferred to the Help AIW provider via Service Handler's ExecuteMenuCmdL().

3.9 Destruction

When exiting the example application, the Service Handler object must be deleted in the application's destructor.

© Nokia 2009

Back to top