AIW Generic Parameter API Specification
Contents |
1 Overview
The purpose of AIW Generic Parameter API is to offer the means for handling AIW generic parameters to the AIW consumer applications. The generic parameters are used for transferring data between AIW consumers and providers.
| API category | public |
| API type | c++ |
| Existed since | Legacy S60 3.2 |
| API libraries | servicehandler.lib |
| Location | /sf/mw/classicui/classicui_pub/aiw_generic_parameter_api
|
| Buildfiles | /sf/mw/classicui/classicui_pub/aiw_generic_parameter_api/group/bld.inf
|
1.1 Description
AIW Generic Parameter API can be categorized as a library API, i.e. it provides standalone implementation units (classes, methods, functions) that are used by the client. The API is used by method calls (interface uses only local objects).
An AIW generic parameter is a pair of semantic id and variant value. Semantic id tells the purpose of the parameter. Variant value contains the data format information and the actual value. This API offers the means for creating a parameter object, setting its variant value and semantic id, etc.
1.2 Use Cases
The main use cases of this API are the following:
- Creating a generic parameter list with basic types
- Creating a generic parameter list with provider specific objects.
1.3 Class Structure
| Classes | Files |
|---|---|
|
/epoc32/include/mw/AiwGenericParam.h
TAiwGenericParam /epoc32/include/mw/AiwGenericParam.h
TAiwVariant /epoc32/include/mw/AiwVariant.h
/epoc32/include/mw/AiwGenericParam.hrh, /epoc32/include/mw/AiwGenericParam.inl, /epoc32/include/mw/AiwVariant.inl, /epoc32/include/mw/AiwVariantType.hrh
The class structure of AIW Generic Parameter API classes with some of the most important methods is shown in Figure 1:
The TAiwGenericParam object contains a single AIW generic
parameter. These objects may then be collected to a CAiwGenericParamList ,
which can be passed to the AIW providers e.g. via CAiwServiceHandler::ExecuteMenuCmdL() or CAiwServiceHandler::ExecuteServiceCmdL() .
A single generic parameter object contains a semantic id and a variant
object. A semantic id can for example be an error code or a landmark. See
enumeration TGenericParamId in AiwGenericParam.hrh for
possible values.
The variant object is of type TAiwVariant . It consists
of a data format and the actual value. The data format can be e.g. integer,
UID or a descriptor. See AiwVariantType.hrh for a complete list.
A "data agreement" is an important definition here. It is a contract between AIW provider and consumer to define the parameters required to execute a certain AIW service command. A data agreement describes the provider's input and output parameters, and also event parameters if the AIW service is asynchronous. Note also that these data agreements and other necessary information for executing individual AIW service commands are provider specific.
Some data agreements require that an instance of a certain custom class or struct is passed between the consumer and provider. For example, the Map&Navigation provider uses that approach.
2 Using The API
The most important use cases are creating generic parameter lists to be passed to the AIW providers. The first use case is a basic case, and the second is a more advanced one and specific to a certain AIW service provider.
2.1 Creating a generic parameter list with basic types
The example code here demonstrates how to create a generic parameter list and fill it with file name (descriptor) and error code (integer) items. This is the way how to pass the most common types of parameters to the AIW providers that do not need provider specific objects.
#include <AiwGenericParam.h>
// Create a list and put it into the cleanup stack. CAiwGenericParamList* list = CAiwGenericParamList::NewLC();
// Set up and append file name parameter. _LIT(KMyFileName, "c:\\data\\testfile.txt"); TFileName filename(KMyFileName); TAiwGenericParam param(EGenericParamFile); param.Value().Set(filename); list->AppendL(param);
// Set up and append error code parameter. param.Reset(); param.SetSemanticId(EGenericParamError); param.Value().Set(KErrNotFound); list->AppendL(param);
// The list can now be passed e.g. by calling Service Handler's ExecuteMenuCmdL() or // ExecuteServiceCmdL().
// Pop and destroy the list when it is not needed anymore. CleanupStack::PopAndDestroy(list);
There may be as many items as required on the list with the same semantic
id. The receiving application uses iterator methods in the CAiwGenericParamList class
for accessing data items on the list.
The AIW framework contains convenience methods for creating input and output lists. By using the lists, the consumer application does not have to take care of allocating the list from a heap or deleting it afterwards. The only limitation is that only one input and one output list can be requested simultaneously. If more are required, the consumer application must create and delete them by itself. The methods for creating input and output lists are defined as follows:
CAiwGenericParamList& CAiwServiceHandler::InParamListL(); CAiwGenericParamList& CaiwServiceHandler::OutParamListL();
2.2 Creating a generic parameter list with provider specific objects
If a provider specific class or struct needs to be transferred between
a consumer and a provider, it needs to be serialized by using e.g. a TPtrC8 or TPckg type
before adding it to a generic parameter list. The variant type id EVariantTypeDesC8 should
be used for these kind of parameters. It should also be noted that the AIW
framework does not support passing pointers. See Map and Navigation AIW provider
documentation for an example.
2.3 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.
3 Glossary
3.1 Definitions
| Data agreement | A contract between service provider and consumer defining
what is required to execute a service command. This includes e.g. input and output parameters. |
4 References
| 1. S60 Map and Navigation AIW API Specification Document |