AIW Criteria API: API description

AIW Criteria API: API description
- Use cases
- API class structure
  - Criteria item resource

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:

Figure 1: Class diagram of the AIW Criteria API

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.

Label	Meaning
`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.