Contents

• Purpose
• API description
  • Use cases
  • API class structure
• Using AIW Service Handler API
  • Creating a Service Handler instance
  • Attaching interests
    • Base services
    • Menu services
  • Initializing Menu pane
  • Executing service commands
    • Base service commands
    • Menu service commands
  • Deleting the Service Handler instance
  • Error handling
• Glossary
  • Abbreviations
  • Definitions
• References

Use cases

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

• Creating a Service Handler instance

• Attaching interests

  • Base services

  • Menu services

• Initializing menu pane

• Executing service commands

  • Base service commands

  • Menu service commands

• Deleting the Service Handler instance

API class structure

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:

• CAiwServiceHandler

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.

              
               // Attach base service interests. 
               

               iServiceHandler->AttachL(R_AIWEXAMPLE_BASEINTEREST);
              
             

              
               iServiceHandler->AttachMenuL(R_AIWEXAMPLE_MENU, R_AIWEXAMPLE_MENUINTEREST);
              
             

• ConstructL()

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.

• CAiwServiceHandler::HandleSubmenuL()
• CAiwServiceHandler::InitializeMenuPaneL()
• DynInitMenuPaneL()
• EAIWExampleCmdLast
• ETrue

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.

              
               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 
               

               );
              
             

              
               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;
               

                           }
               

                       }
               

                   }
              
             

• CAiwServiceHandler::ExecuteMenuCmdL()
• CAiwServiceHandler::ExecuteServiceCmdL()

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 platform error handling practises should be used, including e.g. using cleanup stack and TRAP harness.

• TRAP

Abbreviations

None.

Definitions

None.