Purpose
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 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.
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.
API class structure
The classes of AIW Criteria API are shown in Figure 1:
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.
Criteria item resource
The following table gives a detailed description of the fields in a criteria
item resource.
|
|
|
|
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.
|
Related APIs
-
AIW_OPTIONS_ROM_ONLY
-
KAiwClassBase
-
KAiwClassMenu
-
maxProviders
Related APIs
-
CAiwCriteriaItem
-
CBase
-
MAiwNotifyCallback
-
RCriteriaArray
Using AIW Criteria API
See the use cases below.
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.
Related APIs
-
AIW_INTELLIGENT_CASCADE_ID
-
AIW_LOCK_SUBMENU_TITLE
-
MENU_PANE
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).
Related APIs
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
...
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.
Related APIs
-
ExecuteMenuCmdL()
-
ExecuteServiceCmdL()
-
HandleNotifyL()
-
KAiwEventCanceled
-
KAiwOptCancel
Related APIs
-
CAiwServiceHandler::ExecuteMenuCmdL()
-
CAiwServiceHandler::ExecuteServiceCmdL()
-
HandleNotifyL()
-
KAiwEventCompleted
-
KAiwOptASyncronous
-
MAiwNotifyCallback
-
MAiwNotifyCallback::HandleNotifyL()
-
aCallback
-
aCmdOptions
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.
Related APIs
