AIW Service Handler API Specification

Contents

1 Overview

The purpose of the AIW Service Handler API is to offer the core functionality of the Application Interworking framework to the AIW consumer applications. This is done by using a Service Handler object, which is the core of the AIW framework.


API categorypublic
API typec++
Existed sinceLegacy S60 3.2
API librariesservicehandler.lib
Location/sf/mw/classicui/classicui_pub/aiw_service_handler_api
Buildfiles/sf/mw/classicui/classicui_pub/aiw_service_handler_api/group/bld.inf


1.1 Description

AIW Service Handler API offers the main access to the AIW framework functionality.

AIW Service Handler API is a library API. From the AIW consumer application point of view, it can be categorized as a method call API. AIW Service Handler API hides the complexity of resolving and calling the AIW providers, which are implemented as ECom plug-ins.

1.2 Use Cases

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

1.3 Class Structure

Summary of API classes and header files
ClassesFiles
CAiwServiceHandler /epoc32/include/mw/AiwServiceHandler.h

The main class of AIW Service Handler API is called CAiwServiceHandler . This class is the main entity of the AIW framework. Each AIW consumer application should create an instance of that class, which can then be used for attaching application's interest, initializing the AIW menu items, and executing the AIW service commands. The CAiwServiceHandler and some of its most important methods are illustrated in Figure 1:

Class diagram of AIW Service Handler API
Class diagram of AIW Service Handler API

2 Using The API

The most important use cases are described in the sections below.

2.1 Creating a Service Handler instance

For using AIW Service Handler API, the consumer application needs first to create a Service Handler instance. 

// Create a service handler instance.
iServiceHandler = CAiwServiceHandler::NewL();

2.2 Attaching interests

When the Service Handler instance exists, the consumer application's interest must be attached to it before AIW service commands can be executed. Attach needs usually be done only once, and a good place for it is the consumer application's ConstructL() method.

2.2.1 Base services

Base service interests can be attached by using CAiwServiceHandler::AttachL() . 

// Attach base service interests.
iServiceHandler->AttachL(R_AIWEXAMPLE_BASEINTEREST);

The interest is defined in a resource file, see AIW Criteria API for details.

2.2.2 Menu services

Menu service interests can be attached by using CAiwServiceHandler::AttachMenuL() . 

iServiceHandler->AttachMenuL(R_AIWEXAMPLE_MENU, R_AIWEXAMPLE_MENUINTEREST);

A menu pane and an interest containing menu related criteria items need to be defined in a resource file, see AIW Criteria API for details.

2.3 Initializing Menu pane

Menu pane containing AIW menu items needs to be initialized. This is done in consumer application's DynInitMenuPaneL() method. See example below: 

void CAIWExampleAppUi::DynInitMenuPaneL( TInt aResourceId, CEikMenuPane *aMenuPane )
    {
    // First, offer menu pane to AIW framework. It might be the case, that the
    // user is opening an AIW submenu. In this case, the AIW handles the menu.
    if ( iServiceHandler->HandleSubmenuL( *aMenuPane ) )
        {
        return;
        }

    // Add your normal (non-AIW) menu initialisation code here...

    // Let AIW provider add its menu items to the menu.
    iServiceHandler->InitializeMenuPaneL(
        *aMenuPane,
        aResourceId,
        EAIWExampleCmdLast,
        iServiceHandler->InParamListL());
    }

In this case, the menu may contain an AIW submenu (i.e. a submenu containing only AIW menu items). The submenu is handled by the AIW framework, so if CAiwServiceHandler::HandleSubmenuL() returns ETrue , nothing needs to be done.

The actual menu pane initialization is done by CAiwServiceHandler::InitializeMenuPaneL() . Note that the EAIWExampleCmdLast should be defined as the last enumeration value, the Service Handler uses it as the basis of the menu command ids it generates.

2.4 Executing service commands

AIW service commands can be executed by calling CAiwServiceHandler::ExecuteServiceCmdL() for base services, and CAiwServiceHandler::ExecuteMenuCmdL() for menu services. The methods are blocking by default. However, it is also possible that a provider works asynchronously. In that case, the consumer can implement a callback method, which is called when the provider finishes, for example. See AIW Criteria API for more details of asynchronous service calls.

2.4.1 Base service commands

Base service commands can be executed by calling CAiwServiceHandler::ExecuteServiceCmdL() . An example is shown below (see AIW Generic Parameter API how to set up input parameters): 

iServiceHandler->ExecuteServiceCmdL(
    KAiwCmdMnShowMap,                  // The service command.
    inParamList,                       // Input parameter list.
    iServiceHandler->OutParamListL(),  // No output parameters used.
    0,                                 // No options used.
    NULL);                             // No need for callback
);

2.4.2 Menu service commands

The consumer application's "AppUI" class has a callback method HandleCommandL(TInt aCommand). When it is called, the consumer application should first try to identify if the command is a normal menu command. If the command is not recognized, it should be forwarded to the AIW framework. This is usually done in the default branch of the switch statement. 

void CAIWExampleAppUi::HandleCommandL(TInt aCommand)
    {
    switch(aCommand)
        {
        case ESomeNonAIWCommand:
            {
            // Execute command.
            // ...
            break;
            }
        case EEikCmdExit:
            {
            Exit();
            break;
            }
        default:
            {
            // Forward the command id to AIW, i.e. execute AIW menu
            // service command.
            iServiceHandler->ExecuteMenuCmdL(
                aCommand,
                iServiceHandler->InParamListL()     // No input parameters
                iServiceHandler->OutParamListL(),   // No output parameters
                0,                                  // No options used.
                NULL);                              // No need for callback
            break;
            }
        }
    }

2.5 Deleting the Service Handler instance

The Service Handler instance needs to be deleted when it is not used anymore. Usually this is done in the destructor of the consumer application. 

// Delete the service handler instance.
delete iServiceHandler;

2.6 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.

3 References

References
1. S60 3.2 AIW Generic Parameter API Specification Document
2. S60 3.2 AIW Criteria API Specification Document