AIW Criteria API Specification

1 Overview

The purpose of AIW Criteria API is to offer the definitions and classes for utilizing the AIW criteria items and interests. An interest is an array of criteria items, and it defines what AIW services the consumer application is interested in using. The AIW services are, in turn, offered by the AIW service providers.

API category	public
API type	c++
Existed since	Legacy S60 3.2
API libraries	servicehandler.lib
Location	`/sf/mw/classicui/classicui_pub/aiw_criteria_api`
Buildfiles	`/sf/mw/classicui/classicui_pub/aiw_criteria_api/group/bld.inf`

1.1 Description

AIW Criteria API can be categorized as a library API, and it is one of the AIW Consumer APIs. The API provides some resource structures, enumerations and classes for AIW consumers to manage their criteria items and interests.

This API offers a class encapsulating a criteria item and a definition for a criteria item array. The consumers may use these items to manage their interests.

This API also defines several enumerations. These include the AIW service commands, service command options, service classes, event codes for asynchronous AIW services, and resource definitions for defining AIW criteria items in resource files.

1.2 Use Cases

The most important use cases of AIW Criteria API are the following:

Defining the consumer's interest in a resource file
Defining the consumer's interest dynamically
Making asynchronous service calls.

1.3 Class Structure

Summary of API classes and header files
Classes	Files

CAiwCriteriaItem /epoc32/include/mw/AiwCommon.h MAiwNotifyCallback /epoc32/include/mw/AiwCommon.h No classes/epoc32/include/mw/AiwCommon.hrh, /epoc32/include/mw/AiwCommon.rh

The classes of AIW Criteria API are shown in Figure 1:

Class diagram of the AIW Criteria API

The class CAiwCriteriaItem encapsulates an AIW criteria item. The class is derived from CBase , and it mostly contains getters and setters for different criteria item fields.

Criteria item instances can be collected to a specific RCriteriaArray , which is a typedef of a pointer array containing CAiwCriteriaItem pointers. This forms the consumer application's AIW interest.

MAiwNotifyCallback is an abstract callback interface for handling asynchronous AIW service calls.

1.3.1 Criteria item resource

The following table gives a detailed description of the fields in a criteria item resource.

Label	Meaning
LONG id	Criteria id number. This field is used for binding the criteria item to a placeholder. Several criteria items may have the same criteria id. In such case one placeholder can refer to several criteria items. The criteria item id can be any selected number as long as connections to placeholders are not mixed up with each other.
LONG serviceCmd	Defines the AIW service command id for this criteria.
LTEXT8 contentType	Specifies the requested content type.
LONG serviceClass	Specifies service class for this criteria. Possible values are `KAiwClassBase` and `KAiwClassMenu` .
LONG defaultProvider	Default provider is the first provider that is allowed to insert its menu items to the menu. If no default provider is defined or the default provider is not available in the system, the order of provider menu items in the menu is random. Together with `maxProviders` field the consumer application can force Service Handler to override other providers and use a specific provider if available.
BYTE maxProviders	This value defines the maximum number of providers that can be attached to this criteria item. If there are more matching providers available than the value given in this field, the group of selected providers is random (with one exception, see the previous item).
BYTE loadOptions	Specifies load options for criteria. The following load options bits are defined: `AIW_OPTIONS_ROM_ONLY` Only ROM based providers can be attached to this criteria.

2 Using The API

See the use cases below.

2.1 Defining the consumer's interest in a resource file

The consumer's interest is usually defined in a resource file. An example case containing menu and base service interests is shown below:

#include <AiwCommon.rh>

RESOURCE AIW_INTEREST r_aiwexample_menuinterest
    {
    items =
        {
        AIW_CRITERIA_ITEM
            {
            id = EAIWExampleHelpPlaceholder;
            serviceCmd = KAiwCmdHelp;
            contentType = "*";
            serviceClass = KAiwClassMenu;
            }
        };
    }

RESOURCE AIW_INTEREST r_aiwexample_baseinterest
    {
    items =
        {
        AIW_CRITERIA_ITEM
            {
            id = EAIWExampleBaseServiceId;
            serviceCmd = KAiwCmdMnShowMap;
            contentType = "application/x-landmark";
            serviceClass = KAiwClassBase;
            }
        };
    }

In this example, only one criteria item is defined per each interest, but there could be more as well, separated by comma.

The first criteria item refers to a menu service, i.e. the corresponding AIW provider(s) are supposed to add menu item(s) to the consumer application's menu. The second one refers to a base service. Using base service commands do not require any menus. The id enumerations should be defined in the consumer application's HRH file.

The menu items for menu services are defined in a MENU_PANE resource. An example is given below:

RESOURCE MENU_PANE r_aiwexample_menu
    {
    items =
        {
        MENU_ITEM
            {
            command = EAIWExampleHelpPlaceholder;
            txt = "Help submenu";
            cascade = AIW_INTELLIGENT_CASCADE_ID | AIW_LOCK_SUBMENU_TITLE;
            },
        MENU_ITEM
            {
            command = EAknSoftkeyExit;
            txt = "Exit";
            }
        };
    }

In this example, the first item is an AIW menu item and the second is a normal menu item. AIW_INTELLIGENT_CASCADE_ID tells that the AIW framework should place the AIW menu items in a submenu, if the provider(s) offer several AIW menu items. If there is only menu item available, it is located at the main level.

AIW_LOCK_SUBMENU_TITLE tells the AIW framework that the consumer defined string "Help submenu" should be used if the submenu exists. This means that if some provider suggests a submenu title, it will be ignored.

2.2 Defining the consumer's interest dynamically

The interest may also be defined dynamically. See example below:

// Create AIW service handler
CAiwServiceHandler* serviceHandler = CAiwServiceHandler::NewLC();

// Create AIW interest
RCriteriaArray interest;
CleanupClosePushL(interest);
_LIT8(KContentTypeLandmark, "application/x-landmark");
CAiwCriteriaItem* criteria = CAiwCriteriaItem::NewLC(KAiwCmdMnShowMap, KAiwCmdMnShowMap, KContentTypeLandmark);

// We are using a base service.
TUid base;
base.iUid = KAiwClassBase;
criteria->SetServiceClass(base);

User::LeaveIfError(interest.Append(criteria));

// Attach the interest to the AIW framework.
serviceHandler->AttachL(interest);

...
// Execute AIW commands etc.
...

// Pop and destroy when not any more needed.
CleanupStack::PopAndDestroy(3); // criteria, interest, servicehandler

In this example, the KAiwCmdMnShowMap constant is used also as a criteria item id. This approach is also OK, the consumer can decide the id it uses (and for base services the criteria item id is quite meaningless).

2.3 Making asynchronous service calls

Some AIW service providers might support asynchronous service calls. This might be the case e.g. in such situations, where the processing takes so much time that the provider cannot return immediately.

In such case the consumer should derive from class MAiwNotifyCallback and implement its MAiwNotifyCallback::HandleNotifyL() method. When the consumer calls either the CAiwServiceHandler::ExecuteMenuCmdL() or CAiwServiceHandler::ExecuteServiceCmdL() , it should set the aCallback pointer to the M class in question and also set the aCmdOptions to KAiwOptASyncronous . The service provider may then call that callback method with e.g. KAiwEventCompleted when finished. See AiwCommon.hrh for a list of possible event codes.

An example how to derive from MAiwNotifyCallback is shown below:

#include <AiwCommon.rh>
...
class CMyConsumerApp : public MAiwNotifyCallback
    {
    ...
    public:
        // From MAiwNotifyCallback
        virtual TInt HandleNotifyL(
            TInt aCmdId,
            TInt aEventId,
            CAiwGenericParamList& aEventParamList,
            const CAiwGenericParamList& aInParamList);
    ...

The implementation for HandleNotifyL() could look like the following:

TInt CMyConsumerApp::HandleNotifyL(
    TInt /*aCmdId*/,
    TInt aEventId,
    CAiwGenericParamList& /*aEventParamList*/,
    const CAiwGenericParamList& /*aInParamList*/)
    {
    // Service command (aCmdId) can be checked here, if necessary.

    // Check the event code.
    switch (aEventId)
        {
        case KAiwEventCanceled:
            {
            // Handle cancellation...
            break;
            }
        case KAiwEventCompleted:
            {
            // Handle completion...
            break;
            }
        ...
        // Other event codes can be handled here as well.
        ...
        default:
            break;
        }

    return KErrNone;
    }

Asynchronous command handing can be requested as shown below:

void CMyConsumerApp::HandleCommandL(TInt aCommand)
    {
    ...
    // Execute AIW menu service command asynchronously. Remember to check from
    // the provider documentation whether it supports asynchronous command handling.
    // No input and output paramters are used in this example. Check from the
    // provider documentation whether those are required.
    iServiceHandler->ExecuteMenuCmdL(
        aCommand,                           // The menu command
        iServiceHandler->InParamListL(),    // No input parameters used
        iServiceHandler->OutParamListL(),   // No output parameters used
        KAiwOptASyncronous,                 // Asynchronous command handling requested
        this );                             // MAiwNotifyCallback pointer
    ...

2.3.1 Cancelling an asynchronous service command

Some AIW service providers might support cancelling an asynchronous service command execution. To cancel a command, the ExecuteMenuCmdL() or ExecuteServiceCmdL() should be called with exactly the same parameters as was used to start the command, but with the exception that the cancel option bit KAiwOptCancel must be set. See the following example:

    iServiceHandler->ExecuteMenuCmdL(
        aCommand,                           // The menu command
        iServiceHandler->InParamListL(),    // No input parameters used
        iServiceHandler->OutParamListL(),   // No output parameters used
        KAiwOptASyncronous|KAiwOptCancel,   // Cancel requested.
        this );                             // MAiwNotifyCallback pointer

If the service provider supports cancel functionality and cancelling was successful, it will call the consumer's HandleNotifyL() with KAiwEventCanceled . This callback is synchronous. Refer to the provider documentation whether it supports the cancel functionality.

2.4 Error handling

Some methods may leave, for example if running out of memory. Normal Symbian OS error handling practises should be used, including e.g. using cleanup stack and TRAP harness.