Changes

Property and event handler extensions do not exist in S60 release 5.2 and later.

Purpose

The AI Content Model API is a domain provides a framework for content publisher plug-ins. The API provides an observer interface, which the plug-ins can call to render their content on the screen. The Content Request interface can be used to force refreshing or suspending the content publisher plug-in's specific content.

S60 or Symbian OS 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 Content Model API provides a framework for content publisher plug-ins. Plug-in implementations respond to Idle Framework (Idle FW) events, such as start, stop, resume, and suspend. The MAiContentObserver API is provided to render data on the screen. The MAiContentRequest API is provided to force refreshing or suspending of a particular content item. Content items are defined in the content publisher plug-in's content model.

Use cases

The Content Model API use cases include publishing, publishing transactions and cleaning. These functions are invoked through the MAiContentObserver interface.

Related APIs
  • MAiContentObserver

API class structure


Active Idle content publishers derive from CHsContentPublisher. The content publishers notify their content change through the MAiContentObserver interface. The interface is passed to the plug-in through the CHsContentPublisher::SubsribeL( MAiContentObserver& aObserver ) function. A data plug-in may derive from MAiContentRequest, which allows the UI controller to refresh or suspend a particular content or resource item.

Related APIs
  • CHsContentPublisher
  • MAiContentObserver
  • MAiContentRequest
Related APIs
  • MAiContentObserver
  • MAiContentRequest

Using the Content Model API

The Content Model API is used by the content publishers to inform the Active Idle framework about modifications in content and/or state. Content publishers use the MAiContentObserver interface and invoke the provided functions to publish content.

  • After a call to StartTransaction( TInt aTxId ), plug-ins are allowed to commit changes. aTxId is the Transaction ID.

  • Commit( TInt aTxId ) closes the transaction accepting the changes.

  • CancelTransaction( TInt aTxId ) closes the transaction canceling the changes.

  • CanPublish( CHsContentPublisher& aPlugin, TInt aContent, TInt aIndex ) checks if the content can be published. aPlugin is a data plug-in implementation. aContent is an identification of the content selector and aIndex is the index of the content item.

  • Publish() functions have different kind of parameters, allowing content to be published. Resource, descriptor, file and pointer contents can be published.

  • PublishPtr() function allows a pointer to be published based on the MIME type parameter.

  • Clean( CHsContentPublisher& aPlugin, TInt aContent, TInt aIndex ) is called when nothing should be published on the UI. Published content is shown until Clean is called.

  • Extension( TUid aUid ) returns interface extension. Reserved for future use.

  • SetProperty() functions are used for setting properties to the plug-in. See the headers for more detailed information.

Use Case: Content publishing transaction

A typical publishing use case is depicted below. The Idle Framework calls Resume() when the content publisher is allowed to publish its content. The actual publishing is performed by calling the MAiContentObserver interface.

The content publisher may publish based on any chosen criteria. Typical cases are for example:

  • Resume signal (called by the Idle Framework)

  • Data change

  • Timer expiration


Related APIs
  • MAiContentObserver
  • Resume()

Error handling

Some methods can leave, for example, if running out of memory. This API uses standard Symbian error handling practises, including for example using cleanup stack and trap harness.

  • Starting or committing a transaction may return KErrNotSupported - UI Controller does not support transactions, meaning that the content is rendered every time when Publish is called.

  • Committing a transaction can also return KErrNotFound - transaction with matching ID has not been started.

Related APIs
  • KErrNotFound
  • KErrNotSupported

Memory overhead

Implementations should follow the convention to minimize RAM consumption.

Extensions to the API

The MAiContentObserver implementations may provide additional extensions by implementing the Extension() function. The Extension() function returns a TAny* pointer, which has to be interpreted by the users of the API.

Related APIs
  • Extension()
  • MAiContentObserver

Limitations of the API

None.

Related APIs
  • Clean
  • MAiContentObserver
  • Publish()
  • PublishPtr()
  • SetProperty()
  • aContent
  • aIndex
  • aPlugin
  • aTxId

Glossary

Abbreviations

None.

Definitions

None.

References

None.