Changes

The MAiCpsCommandBuffer interface is introduced. The MAiPluginTool interface is deprecated.

Related APIs
  • MAiCpsCommandBuffer

Purpose

The AI Utilities API is a collection of utility classes used by Idle Framework, Idle Home screen and content publisher plug-ins.

S60 or Symbian Exceptions

This API is valid for all platforms running on S60 release 5.2 or later.

Emulator support

This API is fully supported in the WINSCW emulator environment.

API description

The AI Utilities API is a Library API and its services are used with simple method calls. The Aiutility.h header file has a set of global methods, which can be used to instantiate objects. Interface is provided for the caller. Some classes must be instantiated in the normal way.

API class structure

The CStrParser and CPSPropertyObserver objects are instantiated via global utility functions in aiutility.h. Objects are used through interface classes and deleted by calling the Release() function.


The CAiPluginSettings object is instantiated via global utility function in aiutility.h. Objects are used through interface class and deleted by calling the Release() function.


CContentPriorityMap is created using the normal Symbian methods.CAiCPSCommandBuffer is created by the system and the interface is passed to every instance of WRTDataPlugin and SapiDataPlugin.


Description of the AI Utilities APIs

Class Description Header file

namespace AiUtility

Contains a set of global functions to instantiate utility classes. Interface for the utility class instance is returned to the client.

aiutility.h

MAiPSProperty Observer

Helper interface for Publish and Subscribe property observation.

aipspropertyobserver.h

MAiStrParser

String parser interface provides functions for converting a string into integer and strings between 8 and 16 bit format.

aistrparser.h & aistrcnv.h

MAiContentItem Iterator

See AI Content Model API Specification.

aicontentmodel.h

MAiPlugin Settings

Plug-in settings interface. Settings object owns one setting instance and the type of it. Setting instance is accessed through the settings interface.

aipluginsettings.h

MAiPlugin SettingsItem

Setting item holds the widget settings in key value pairs. Settings are read from the widget XML declaration.

aipluginsettings.h

MAiPlugin ContentItem

Content item holds the widget's dynamic content model items. Content model items are parsed from the widget XML declaration by the system.

aipluginsettings.h

MAiPlugin ConfigurationItem

Configuration item holds the widget's content source binding information. Configuration items are parsed from the widget XML declaration by the system.

aipluginsettings.h

CContent PriorityMap

Content priority map holds the publishing priorities of the UI elements. If the same UI element gets several publishing transactions, the highest priority transaction overrides the rest.

contentprioritymap.h

MAiCPSCommand Buffer

Command buffer interface is used to execute the CPS commands in a performance optimized way. Commands are collected into cache and executed at a suitable time using the CPS's feature of handling the multiple actions in one execute command.

aicpscommandbuffer.h

Related APIs
  • CAiCPSCommandBuffer
  • CAiPluginSettings
  • CContentPriorityMap
  • CPSPropertyObserver
  • CStrParser
  • MAiStrParser

Using the AI Utilities API

The CContentPriorityMap and MAiCPSCommandBuffer objects are created in the normal way. The usage examples for the rest of the APIs are described below.

Property Observer

// Create observer
iBackupRestoreObserver = AiUtility::CreatePSPropertyObserverL(
    TCallBack( BackupRestoreEvent, this ),
    KUidSystemCategory, conn::KUidBackupRestoreKey );

...

// Release in e.g. destructor
Release( iBackupRestoreObserver );

String Parser

// Creating the parser
iStrParser = AiUtility::CreateStrParserL();

...

// Using the parser
const TDesC8& event8(
    aEvent.AttributeValue( XnPropertyNames::action::event::KName ));
HBufC16* event( NULL );
event = iStrParser->CopyToBufferL( event, event8 );

...

//Releasing
Release( iStrParser );

Plug-in settings

MAiPluginSettings* settings( AiUtility::CreatePluginSettingsL() );
CleanupDeletePushL( settings );
MAiPluginSettingsItem& item( settings->AiPluginSettingsItem() );
item.SetPublisherId( aPublisherInfo.Uid() );

TInt32 key( 9 );

item.SetKey( key );
item.SetValueL( KValue(), EFalse );

// Append settings into array.
aSettings.Append( settings );
CleanupStack::Pop( settings );

Error handling

Some methods can leave, for example, if running out of memory. The API follows the standard Symbian error handling practises.

Memory overhead

Implementations should follow the convention to minimize RAM consumption.

Extensions to the API

There are no extensions to the API.

Limitations of the API

There are no limitations in the API.

Related APIs
  • CContentPriorityMap
  • MAiCPSCommandBuffer

References

AI Content Model API Specification