AIW Service Handler API Specification Document
Changes in AIW Service Handler API documentation
2.0 |
08.01.2007 |
Approved |
|
1.0
|
16.02.2006
|
Approved
|
|
Changes in S60 3.2 AIW Service Handler API
2.0 |
Updated for S60 3rd Edition, Feature Pack 2. |
1.0
|
First version
|
PurposeThe 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 descriptionAIW 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.
Use casesThe 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 structureThe 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:
Related APIs
Using AIW Service Handler APIThe most important use cases are described in the sections below.
Creating a Service Handler instanceFor 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 interestsWhen 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 servicesBase 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.
Related APIs
CAiwServiceHandler::AttachL()
Menu servicesMenu 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.
Related APIs
CAiwServiceHandler::AttachMenuL()
Related APIs
Initializing Menu paneMenu 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.
Related APIs
CAiwServiceHandler::HandleSubmenuL() CAiwServiceHandler::InitializeMenuPaneL() DynInitMenuPaneL() EAIWExampleCmdLast ETrue
Executing service commandsAIW 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 commandsBase 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 );
Related APIs
CAiwServiceHandler::ExecuteServiceCmdL()
Menu service commandsThe 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; } } }
Related APIs
CAiwServiceHandler::ExecuteMenuCmdL() CAiwServiceHandler::ExecuteServiceCmdL()
Deleting the Service Handler instanceThe 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 handlingSome 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.
Related APIs
References
References
1. S60 3.2 AIW Generic Parameter API Specification Document |
2. S60 3.2 AIW Criteria API Specification Document
|
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies). All rights reserved. License: EPL
|