AI Content Model API
Changes in AI Content Model API documentation
| Version |
Date |
Status |
Description |
|
1.0
|
08.06.2010
|
Approved
|
|
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
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
CHsContentPublisherMAiContentObserverMAiContentRequest
Related APIs
MAiContentObserverMAiContentRequest
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:
Related APIs
MAiContentObserverResume()
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
KErrNotFoundKErrNotSupported
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
CleanMAiContentObserverPublish()PublishPtr()SetProperty()aContentaIndexaPluginaTxId