Application Interworking Framework: Application Interworking framework design

The following sections describe the most important concepts of AIW framework in the perspective of using the AIW Consumer APIs.

Menu and base services

AIW services are divided into service classes. There are two service classes supported: menu and base.

Menu service class (KAiwClassMenu) is for service providers capable of adding menu items directly to the consumer application’s menu. Base service class (KAiwClassBase) is an UI independent abstract service class. It can be used for implementing functionality, which is not directly tied to any UI component.

Interest, criteria items and placeholders

A criteria item specifies one AIW service that a consumer application is interested in using. An array of criteria items is called interest. Consumer application’s interest is defined in its resource file. AIW framework uses criteria items to find out if there are suitable service providers available and then initializes the requested providers.

Menu service class is related to UI components, i.e. to the consumer application's menu items. The binding is done using the id field of a criteria item. The id represents a menu placeholder, i.e. an empty menu item in the consumer application's menu, where the provider can place its menu items.

An example showing a consumer application's interest is shown below:

RESOURCE AIW_INTEREST r_mytestapp_interest
    {
    items =
        {
        // This application is interested in showing help context from its menu.
        AIW_CRITERIA_ITEM
            {
            id              = EMyCriteriaItemId; // Should be matched to a menu placeholder.
            serviceCmd      = KAiwCmdHelp;       // AIW service command.
            serviceClass    = KAiwClassMenu;     // AIW service class (either menu or base).
            contentType     = "*";               // Content MIME type.
            maxProviders    = 3;                 // Maximum number of providers (optional).
            }
        };
    }

This example means that the consumer application wants that the provider modules offering "show help" services should place their menu commands to the consumer application's menu. At most three providers may add their menu items to the consumer menu.

The interest in this example contains only one criteria item. As stated previously, the interest might contain multiple criteria items as well. Both menu and base service criteria items can be included in one AIW_INTEREST resource, but in most cases they should be separated in their own interests.

Resolving service providers

The AIW framework uses the following algorithm for resolving correct service providers matching with a criteria item. It uses custom ECom resolver for the task.

At the first stage, the custom resolver asks ECom framework to find all the ECom plug-ins whose interface UID value matches with the service class attribute defined by criteria item. In other words, ECom framework returns all menu or base service providers depending which one is defined in the consumer's criteria.

At the second stage, the custom resolver goes through the initial list of candidate modules to see if any part of their content type strings matches with the criteria item’s content type. A list of providers meeting this condition is returned to the Service Handler.

At the third stage, Service Handler selects those providers that implement the service command defined by the criteria item.

In addition, there exists a criteria item option to allow only ROM based providers. It is also checked during the execution of the algorithm. See AIW Criteria API for details.

Binding criteria items to menu resources

If the consumer application wants to make the menu service commands visible in its menu, it needs to bind the criteria items to menu resources. The consumer application's MENU_PANE resource may contain both normal (non-AIW) and AIW menu items. An example is shown below:

RESOURCE MENU_PANE r_mytestapp_menu
    {
    items =
        {
        MENU_ITEM
            {
            command = EMyCriteriaItemId; // An AIW menu item.
            txt = "<AIW Placeholder>";   // This text will not be shown in UI.
            },
        MENU_ITEM
            {
            command = EAknSoftkeyExit;   // A normal menu item.
            txt = "Exit";
            }
        };
    }

Note that the example above does not mean that there would always be two menu items in the Options menu. This is because the AIW framework can add zero, one or several menu items to the EMyCriteriaItemId placeholder. In addition, the consumer application may freely make several criteria items to use the same criteria item id.

Attaching services

The consumer application must attach its interest to the AIW framework. AIW framework has its own attach methods for each service type (CAiwServiceHandler::AttachL() for base services and CAiwServiceHandler::AttachMenuL() for menu services). Interest may also be detached if it is no longer needed or the consumer application needs to free resources. When detaching menu services, the consumer application must be sure that the menu in question is not activated until the interest is attached again. This is because detaching menu services make placeholder items visible in the menu. Attaching AIW services is a relatively slow operation, so it should be done only once, for example at the application start up.

Base service handling

After the base services have been attached, they are ready to be used. Base service commands are executed using CAiwServiceHandler::ExecuteServiceCmdL() method. Service Handler checks the base service command given as a parameter in HandleServiceCmdL(), and forwards the call to all those attached providers that implement the service command in question. Note the limitations with base services: the MIME type is not checked anymore in this phase, and the call may go to multiple providers.

Menu initialization

Menu panes containing AIW placeholders must be initialized in the consumer application's DynInitMenuPaneL() method by calling CAiwServiceHandler::InitializeMenuPaneL(). AIW framework then removes the placeholder items and inserts the provider menu items to correct positions. AIW framework automatically adds the placeholder’s service command(s) to input parameters list, so the receiving provider knows what service command it is initializing.

Menu command handling

The consumer application does not know in advance how many menu providers are attached to each criteria item. Consumer application does not care about mapping menu command ids at all, it just has to forward the menu command to the Service Handler module in case it notices that it does not recognize the menu command id in its HandleCommandL() method. This is done by calling CAiwServiceHandler::ExecuteMenuCmdL().

Submenus

Consumer application may want to place provider menu items to a submenu. There are two possible ways to do this.

First, the application can create a separate submenu definition and include the placeholder item in it. The submenu is then used as a normal cascade menu and passed to the AIW framework as previously described.

The second, a more sophisticated way is to let the AIW framework take care of submenu handling. In this case the consumer application does not have to define a separate submenu structure, but the AIW framework creates the submenu object dynamically. The consumer application simply tells the AIW framework that provider menu items should be placed into a submenu. This is achieved by placing a predefined submenu constant to the cascade field in the placeholder menu item. Here is an example of submenu placeholder:

MENU_ITEM
    {
    command = EMyCriteriaItemId;
    txt = "Help menu";
    cascade = AIW_CASCADE_ID;
    }

There are two possible submenu constants, defined in the following table:

Submenu title

In a basic case, the title of the AIW submenu is a string given in the placeholder item’s ‘txt’ field. For localization reasons, it is good if the provider is able to define the submenu title. Otherwise every consumer application must define and localize the title string separately. For that reason, the AIW framework has a mechanism for menu providers to suggest a submenu title in case a consumer wants to place their menu items into the submenu.

Since there can be several providers attached to a single placeholder and they may all suggest a different title, we must define the rules to decide which title is used. The AIW framework uses the following algorithm:

• If none of the attached providers suggest a submenu title, the original placeholder text is used.
• The title suggested by the default provider is used if the default provider is available and it suggests a submenu title. For more information about default providers, refer to AIW Criteria API.
• If default provider is not defined or available, and there are several other providers suggesting a title, the title is randomly selected from the set of the suggested titles.

The consumer application may reject the suggested title and use the original placeholder text instead. The provider titles are rejected by setting a reject bit in the placeholder’s cascade field. Here is an example of a placeholder rejecting provider titles:

MENU_ITEM
    {
    command = EMyCriteriaItemId;
    txt = "Help menu";
    cascade = AIW_CASCADE_ID | AIW_LOCK_SUBMENU_TITLE;
    }

Parameter passing

AIW framework uses a generic parameter list for passing data between consumers and providers. Items on the generic parameter list have a semantic id value, which defines the type of data the item holds. The semantic id might indicate that the parameter is e.g. a error code, landmark or a help item parameter.

For example code how to use generic parameters, see AIW Generic Parameter API.

Implementing a consumer application

An AIW consumer application has a relatively small number of responsibilities. It is quite easy to make a new AIW consumer application or convert an existing application to use AIW. Once that work is done, it is easy to add more placeholders later if required.

Consumer application has the following responsibilities.

• Define the interest list in a resource file.
• Add placeholders for menu services to correct positions in the menu resource.
• Attach each interest list. Do this only once at the application start up, if possible.
• Call CAiwServiceHandler::InitializeMenuPaneL() from application's DynInitMenuPaneL() method for menus containing AIW placeholders. Also, call CAiwServiceHandler::HandleSubmenuL() at the beginning of DynInitMenuPaneL() if the consumer application uses AIW submenus.
• Forward the unhandled menu service commands to the Service Handler in the application's HandleCommandL() method.