Changes

No changes.

Purpose

The purpose of the AI Plug-in Management API is to provide a collection of functions and definitions for controlling content publisher plug-in life-cycle, i.e. loading and destroying plug-ins, and suspending and resuming publishing.

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

AI Plug-in Management API can be categorized as a framework API. It provides interfaces that clients of the API implement as well as the enumerations and constant definitions that are shared between the clients and UI Controllers. The clients of this API are the instances implementing the content publisher plug-ins. The implementations must meet the requirements of ECom architecture as the Idle Framework (Idle FW) loads the instances using ECom.

The main interface is a content publisher interface that provides Idle Framework with lifetime control over the content publishers as well as information passing from attached content observers in the form of settings and events. In addition, the AI Plug-in Management API contains a publisher information interface that encapsulates required information of a content publisher.

Use cases

The most important use cases of the AI Plug-in Management API are:

  • Defining the way of how Idle FW controls content publisher plug-ins’ lifetime (i.e. create and destroy)

  • Defining the way of how Idle FW controls the state of the content publishers (i.e. suspend and resume)

  • Defining the way of how event handling is executed between Idle FW and content publishers (handle event)

API class structure

A simplified class diagram of the Plug-in Management API is shown below.


CHsContentPublisher is the main interface of the Plug-in Management API and an ECom plug-in interface. This interface provides the Idle FW with lifetime and resource guidance control over the content publisher plug-ins. Publisher clients must implement this class. THsPublisherInfo encapsulates the required information of a publisher shared between Idle FW and UI Controllers.

Related APIs
  • CHsContentPublisher
  • THsPublisherInfo

Using the AI Plug-in Management API

Content publisher clients implement the CAiContentPublisher ECom interface and adapt their specific plug-in to the rules set by that interface. All the functions need not be implemented, but only those which are relevant for the client.

The following functions are provided:

  • Start(TStartReason) is called after a content publisher is constructed and configured. The plug-in goes into the Idle state. Possible start reasons are: ESystemStartup - the device is booted up; EPageStartup - Home screen page is activated; EPluginStartup - The plug-in is added to Home screen.

  • Stop(TStopReason) is called before a content publisher is destroyed. The plug-in is not allowed to publish its content and it should free all resources. Possible stop reasons are: ESystemShutdown - The device is shutting down; EPageShutdown - Home screen page is deactivated; EPluginShutdown - The plug-in is removed from Home screen.

  • After a call to Resume(), the content publisher is allowed to publish its content and consume system resources.

  • After a call to Suspend(), the content publisher is not allowed to publish its content. Timers and other system resources should be freed when applicable.

  • SetOnline() / SetOffline() is used to tell the content publisher whether it is allowed to use network connection or not.

  • SubscribeL(MAiContentObserver) is called for all content observers the AI FW manages. The content publisher maintains a registry of subscribers and publishes data to all of them when new content is available and publishing is allowed. MAiContentObserver is described in more detail in AI Content Model API Specification.

  • ConfigureL(RAiSettingsItemArray) is used to pass all settings defined by content observer to a content publisher. Mutual agreement is needed by publisher and observer about the used settings.

  • SetProperty() / GetProperty() is used to transfer properties between the Idle FW and the content publisher.

  • HandleEvent() is called by the Idle FW when the content publisher must handle an event.

  • HasMenuItem() is called by the Idle FW to query whether the content publisher has a menu item or not.

Calls to the above methods may come in any order and, therefore, no assumptions should be made in content publisher implementation about the order of the plug-in state guiding method calls.

Use cases

Starting a plug-in

A sequence diagram of a content publisher plug-in creation is shown below.


UI Controller first calls Idle FW, which starts an active object for loading a content publisher(s) asynchronously. A plug-in itself is constructed through the ECom interface, as depicted in the diagram. Once the plug-in is created, the Idle FW calls SubScribeL(), ConfigureL(), StartL(), Resume() and SetOffline() through the CHsContentPublisher interface.

Related APIs
  • CHsContentPublisher

Deleting a plug-in

A sequence diagram of a content publisher plug-in destruction is shown below.


UI Controller first calls Idle FW, which starts an active object for destroying a content publisher plug-in asynchronously. The Idle FW stops the plug-in by calling Suspend() and StopL() through the CHsContentPublisher interface. Finally, the plug-in instance is destroyed.

Related APIs
  • CHsContentPublisher

Handling a plug-in state

Handling content publisher state changes is rather straightforward. Idle FW listens to events (for example from UI Controller or Window Server) and calls the content publisher plug-in through the CHsContentPublisher interface.

Related APIs
  • CHsContentPublisher

Error handling

The API uses standard Symbian error handling practises. However, content publisher developer should pay extra attention to the error handling. If construction of a content publisher fails, the whole widget is interpreted as a faulty widget and it is removed from the screen and also from the Home screen view configuration. Furthermore, if a content publisher crashes, it makes the whole Home screen process to crash.

Memory overhead

Implementations should follow the convention to minimize RAM consumption.

Extensions to the API

Although CHsContentPublisher supports extending via the TAny* Extension(TUid aUid) method, no extensions have currently been implemented.

Related APIs
  • CHsContentPublisher

Limitations of the API

There are no limitations in the API

Related APIs
  • CAiContentPublisher
  • ConfigureL(RAiSettingsItemArray)
  • EPageShutdown
  • EPageStartup
  • EPluginShutdown
  • EPluginStartup
  • ESystemShutdown
  • ESystemStartup
  • HandleEvent()
  • HasMenuItem()
  • MAiContentObserver
  • Resume()
  • SetOffline()
  • SetOnline()
  • Start(TStartReason)
  • Stop(TStopReason)
  • SubscribeL(MAiContentObserver)
  • Suspend()

References

AI Content Model API Specification