AIW Service Handler API: Using AIW Service Handler API

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

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();

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.

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.

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.

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.

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.

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 
);

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;
            }
        }
    }

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;

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.