Changes

This is a new API.

Purpose

The main purpose of the Menu Content Service is to enable reading and editing menu content.

Constraints

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

Classification and release information

This API is a domain API and was first published in S60 release 5.1. This document is valid from S60 release 5.2 onwards.

Emulator support

This API is fully supported in the WINSCW emulator environment.

API description

The Menu Content Service is a service used for defining and managing the content for the S60 Application Menu. It also extends to the possibility of managing several configurations at the same time. Menu Content Service enables reading and editing menu content, launching and uninstalling applications or opening links and URLs. The data is stored in XML files. Clients may access the menu content using the Service API.

Component environment

The key relationships between the Menu Content Service Server and the components in its environment are shown below:

Component environment.


Component environment.

The Menu Content Service manages the client-server interactions and supports an interface for the clients. Beside the services of the Symbian OS (such as File Server), the Menu Content Service uses the services of the XML Content Framework (XCFW) that helps keep the menu content in XML format.

Use cases

The use cases of the Menu Content Service are shown below:

Use cases.


Use cases.

Services required

The following services of the Symbian OS infrastructure are required:

From the Symbian OS subsystems

API Description

Base

Base Symbian services.

Application Architecture

ApaInfo (short name, long name etc.)

Content Access Framework

DRM protection status.

Window Server

Events indicating the change about the running applications.

ECom

Menu operations are dispatched to the appropriate ECom item handler plugins.

The following services of the Domestic OS infrastructure are required:

From the Domestic OS subsystems

API Description

Avkon Icon Utils

The full path and name of the icon file of the application is asked.

Java registry

The path of the Java midlets is asked to determine the DRM protection status.

Widget Registry

Information about running widgets is fetched from the Widget Registry.

SAT

Fetch information about SAT application name, icon and visibility.

Services provided

The following services of the SW IF are provided:

SW IF

API Description Protected

Menu Content Service client API

Client classes (session, item, helper, etc.) are provided to communicate with the Menu Content Service Server. Set and get menu structure and menu item properties. It supports data that is missing in the Menu Content Service and querying it from other S60 or Symbian subsystems. Also the list of running applications can be got.

No

Menu Content Service item handler plugin API

This API defines the ECom interface used to execute different commands on menu items.

No

Menu Content Service icon utility

This interface enables icons fetching.

No

Menu Content Service SAPI

Service API interface to operate Menu Content Service data.

No

SAT Interface

Interface for fetching information about the SAT application name, icon and visibility.

No

API class structure

The design is based on the client-server architecture. A client uses the Menu Content Service client API to fetch and modify data provided by the server. The server stores the data in XML files. If desired data is not provided in the XML it is queried from the surrounding subsystems (Symbian or S60) that are not defined in the menu content XML. Example: If the application title name is not specified in the XML it is queried from Symbian AppArc.

Abstraction layers.


Abstraction layers.

Interfaces

Both the public and internal interfaces used or supported by the Menu Content Service are depicted below:

Interfaces of the Menu Content Service.


Interfaces of the Menu Content Service.

Public interfaces

The first layer of the Menu Content Service includes the following public client API classes:

  • RMenu

  • CMenuFilter

  • TMenuItem

  • CMenuItem

  • RMenuNotifier

  • CMenuOperation

  • CMenuHandler and CMenuHandlerPlugin

  • CMcsSatHandler

  • McsIconUtility

Internal interfaces

The Menu Content Service Server is divided into two layers:

  • The Menu Server that interacts with the Menu Content Service Client manages its requests and the instantiation and usage of the Menu Engines. The requests are encapsulated into the Menu Operation API that is then handled by the Menu Engine. The asynchronous events are given to the Menu Server for further handling through the Menu Engine Observer API. The Menu Engine Visitor API allows the server to visit the nodes and control the traversal.

  • The Menu Engine. Each Menu Engine manages one given menu content, e.g. one XML file, and schedules and executes the requests arriving from the Menu Server. The Menu Server sees it through the Menu Engine API.

Related APIs
  • CMcsSatHandler
  • CMenuFilter
  • CMenuHandler
  • CMenuHandlerPlugin
  • CMenuItem
  • CMenuOperation
  • McsIconUtility
  • RMenu
  • RMenuNotifier
  • TMenuItem

Menu Client

Menu Client overview.


Menu Client overview.

The Menu Content Service client has an open session of type RMenu. This object is used by the other objects and sometimes the client to send commands to the Menu Content Service Server. The server then executes the given operations and a result ( CMenuOperation -derived class if the request is asynchronous) is returned to the client.

The Menu Content Service client service defines an API to handle menu operations. Both the data and functional APIs are available to be used by any other application which needs the menu functionality.

The Menu Content Service client API consists of a session class ( RMenu) and other classes that use RMenu to communicate with the Menu Content Service Server. The client has the following structure:

Menu Client design.


Menu Client design.

Related APIs
  • CMenuOperation
  • RMenu

Menu Server

Menu Server design.


Menu Server design.

While sessions to the menu are implemented as traditional client-server sessions, the menu items are not subsessions of these sessions. The menu items do not have additional representation in the server except the DOM node they are stored in.

The subsessions are used for the following features:

  • A stream buffer for transferring larger amounts of data through the IPC boundary.

  • A notifier for delivering notifications of changes of the menu content.

  • Operations for managing asynchronous editing requests of the clients. Read requests are always synchronous.

Menu Server architecture.


Menu Server architecture.

Menu Engine

Menu Engine design.


Menu Engine design.

CMenuEngObjectFactoryProxy routes requests to appropriate classes ( CMenuEngObjectFactory and CMenuEngLegacyObjectFactory – not shown in the figure above) depending on the state of the iParsingInLegacyFormat data member. These classes create a CMenuEngObject instance.

The Menu Engine supports the following functionalities:

  • Managing the DOM tree that represents the menu defined by one specific XML file.

  • Managing the asynchronous load/save operations of the XCFW.

  • Executing the operations given by the Menu Server.

  • Notifying the observers about changes in the menu content or completion of operations previously scheduled.

  • Allowing traversing the menu tree with the visitor interface.

The Menu Engine is a state machine.

Related APIs
  • CMenuEngLegacyObjectFactory
  • CMenuEngObjectFactory

Run-time content exploration

In order to enable run-time content exploration, the Menu Content Service Server provides several scanners. They are responsible for the Menu Content Service content updating and for sending notifications if the content changes.

Icon utility

The Menu Content Service Icon utility enables to get the icon or skin information (e.g. the icon ID and the file path) and passes it to the Avkon utilities ( AknIconUtils and AknsUtils) in order to load and return the raw bitmaps.

Related APIs
  • AknIconUtils
  • AknsUtils

MenuSatInterface API

The MenuSatInterface interface is a separate interface library (MenuInterface.dll). To use it, an application links the library and uses the APIs.

The offered API ( CMenuSATInterface) includes two functions:

  • MakeSatUiVisible( TBool aVisible, const TDesC& aName, TUint8 aIconInfoId ); - Shows or hides the SIM Services application (SAT UI).

  • MakeSatUiVisible( TBool aVisible, const TDesC& aName=KnullDesC()); - Overloaded version of the above.

The API is implemented using Publish and Subscribe. If the Menu Content Service is running when these functions are called, it is notified immediately by the Publish and Subscribe Notify mechanism. If the Menu Content Service is not running, it sees the call next time it is started in initialization when it checks the key values. In this case, it only sees the last call, which is the only meaningful call.

Related APIs
  • CMenuSATInterface
  • MenuSatInterface

Cache mechanism

In order to provide fast access to the data stored in the Menu Content Service, the server implements a cache mechanism. It is implemented in the CMcsCacheHandler class. The CMenuSrvEng class object contains a cache handler object. When data is fetched from the Menu Content Service, the server first checks if the fetched attribute is stored in the cache and returns this value. If there is no such item in the cache, the server fetches it from the XML file or from the environment and adds this value to the cache. If any of the attributes stored in the cache are changed, they are also removed from the cache. This value is updated in the cache when it is fetched for the next time.

Related APIs
  • CMcsCacheHandler
  • CMenuSrvEng

Using the Menu Content Service API

Operations

The operations of interest are described below. The Menu Content Service client API provides different features. Only some generic operations are described here to demonstrate the logic of the client API.

Initializing sessions

The Menu Content Service client library provides RMenu. It is the session handler used to maintain the connection between the client and server. A session can be intialized with RMenu::OpenL which takes the name of the menu. This menu is an XML stored on the server’s side.

                        RMenu mcsSession;
                        mcsSession.OpenL( _L( "menudata" ) );
                        /* ... */
                        mcsSession.Close();    
                        
Related APIs
  • RMenu::OpenL

Retrieving data

After the RMenu session is set up, the client can retrieve a variety of data from the server, i.e., a list of items conforming to a given set of criteria. Attributes of those items are provided by an open CMenuItem.

The SAPI interface provides the GetList operation. During the GetList operation a list of items together with the required attributes is fetched from the Menu Content Service and an output list is built as a flat or a tree. The GetList operation is done on the server side. The SAPI service passes a serialized parameter list to the Menu Content Service Server and subsequently the server gets all required items with required attributes and builds proper output list. Next, the output list is serialized and sent to the SAPI service

GetList operation.


GetList operation.

As depicted above, GetList requires two client/server calls. In the first one the server builds the output list, serializes it and sends its size to the client. In the second one the serialized list is sent to the client.

Related APIs
  • CMenuItem
  • RMenu

Modifying and creating data

If some information about an item (i.e. attribute) is modified or created, the changes are not stored until CMenuItem::SaveL is called. This means that every operation that changes a node must be saved.

Related APIs
  • CMenuItem::SaveL

Operation of the Menu Engine as a state machine

Menu Engine States


Menu Engine States

Above are depicted all possible states of the Menu Engine that is implemented as an active object.

  • The Menu Engine loads the menu content with the help of XCFW from the RAM, which is the data cage of the Menu Content Service Server on drive C.

  • If loading the menu content from the RAM fails, it loads the content from the ROM, which is the data cage of the Menu Content Service Server on drive Z.

  • If loading the menu content from the ROM succeeds, it is started to be saved to the RAM.

  • When saving the menu content succeeds, the Menu Engine is ready to execute the next operation from the scheduled operations queue.

  • If the executed operation changes the menu content, then it is persisted to the RAM.

  • If the executed operation does not change the menu content, then the Menu Engine is ready to execute the next operation.

  • If there are no more operations in the queue, the engine goes to the Ready state.

Run-time exploration of applications

The application scanner observes the changes in the list of installed applications and - when notified - it adds newly found applications to the menu content. If an application can already be found in the menu content, it is not modified. If the installed applications have not been found in the menu content, the application scanner adds the application to it. The clients of the Menu Content Service are notified about the changes in the menu content. When a removable media is inserted or removed, the list of installed applications may change, thus it may induct modifications in the menu content by the application scanner.

Refreshing the list of the running applications

The list of the running applications is refreshed when the notification about its change is received.

Refreshing the list of the running appli...


Refreshing the list of the running applications

Use cases

Read menu content

The Menu Content Service Client queries the data stored in the menu content. More than one Menu Content Service Client (in different processes) is capable of querying the data. The required data is transferred to the client.

Get list of menu items

The Menu Content Service Client queries the list of menu items stored in the menu content. The required data is transferred to the client. The different menu items can be identified.

Get list of specific menu items

The Menu Content Service Client wants a subset of the menu items, e.g. defined by filter criteria such as a list of all folders. The list of relevant menu items is transferred to the client. The different menu items can be identified.

Observer changes in menu content

The client may want to observe changes in the menu content and get a notification when a change occurs. Such a change can be:

  • A change in the structure when reordering the menu.

  • Adding or deleting menu items.

  • Modifications of menu item attributes (even adding or removing them).

The Menu Content Service Client may be interested in changes in the whole menu or in a part of it (such as a folder). The Menu Content Service Client gets the relevant notifications.

Read attributes of menu item

The Menu Content Service Client queries detailed properties (attributes) of the menu items. The list of the available attributes is not defined by the Menu Content Service Server. The Menu Content Service Client gets the queried attributes.

Read DRM attribute of menu item

The Menu Content Service Client queries the DRM attribute of the menu items. The Menu Content Service Client gets the queried attributes.

Read SAT attributes of menu item

The Menu Content Service Client queries the SAT properties (attributes) of menu items. The Menu Content Service Client gets the queried attributes.

Use multiple menu contents

The Menu Content Service Client can identify which menu content it wants to read or edit. Client applications have the possibility to define and deliver their own menu content. It must also be ensured that the menu content can be accessed by multiple Menu Content Service Clients, thus concurrent menu content handling must be provided. The Menu Content Service Client’s desired operation is outdone on the desired menu content. Concurrency is handled.

Edit (write) menu content

The Menu Content Service Client instructs the Menu Content Service Server to make modifications in the menu content. Fails if:

  • The item is locked and change is not possible.

  • The folder is locked and adding new items is not possible.

  • The item ID is specified but no such ID exists.

The Menu Content Service Server processes the request.

Add item

A new menu item is created and appropriate flags or attributes are added. A new menu item is created. The created item is accessible after asynchronous operation completed.

Remove item

The given menu item (by ID) is deleted. The menu item is deleted after the asynchronous operation is completed.

Move items

An item is moved in a folder to a new position or to a new folder. The object is in the new place.

Manage item attributes

The attributes of an item can be added, deleted and modified, etc. The changes are apparent after the item is saved. If the item is saved, the new and changed attributes are stored.

Manage item flags

The flags of an item can be changed or retrieved. The changes are apparent after the item is saved. If the item is saved, the changed attributes are stored.

Install or uninstall application

When an application is installed or uninstalled, the menu content is updated accordingly. The menu content contains the application that has been installed and it does not contain the application that has been uninstalled (or it contains the uninstalled application with an indication).

Insert or remove removable media

If the removable media is inserted to the device that contains applications that were installed to the device, the applications must be explored automatically and inserted to the menu. If the removable media is removed from the device that contains installed applications, they are removed from the menu or marked as missing. The menu content contains the application that has been inserted and it does not contain the application that has been removed (or it contains it with an indication).

Load menu content

The XCFW parses the menu content and requests the Menu Content Service Server to build the run-time in-memory representation of the content.

Save menu content

The XCFW requests the Menu Content Service Server to support the elements and element attributes (with their values) stored in the run-time in-memory representation of the content for persisting.

Display icon

The client requests an icon bitmap buffer and mask buffer.

Display caption

The client requests the short caption, long caption and title caption information for a given menu item.

Display indicator on running applications

The client wants to determine whether an application is running.

Handle commands

Different item types can have handlers that handle commands sent to them (e.g. open). For example, an application can be started or removed by the handler of menu:application.

Open URL

Different item types can have handlers which handle commands sent to them. In this case the Browser application is opened with the provided URL.

Open link

Different item types can have handlers which handle commands sent to them. In this case a link is opened.

Launch application

Launch an application with the UID provided by the menu item.

Remove application

Uninstall an application with the UID provided by the menu item.

Handlers

From the design perspective, the handlers are part of the Menu Content Service client API. Each command is dispatched to the appropriate plugin via the CMenuHandlerEng class (this is part of the client library). No server calls are needed in order to execute a command.

Related APIs
  • CMenuHandlerEng

Backup and Restore

The Menu Content Service participates in B&R. It requires passive backup. The whole Menu Content Service Server private directory is backed up including:

  • The menu content(s).

  • The MMC history.

  • Central Repository keys.

It does not require reboot after restore, because the Menu Content Service Server is terminated before a restore and thus it is restarted later anyway when the first RMenu session is opened and the restored menu content is re-read.

Related APIs
  • RMenu

Variation

Content variation is done using XML. The XML is handled by the XML Content Framework (XCFW). It enables the definition of the menu structure and the items that appear in the menu of the different client applications of the Menu Content Service. Content definition means delivering the initial menu content of the client application at factory-time.

The Menu Content Service does not deliver pre-defined menu content. The client applications are responsible for delivering the menu content (the XML and localization DTD files).

It also supports the delivery of localized strings together with the XML content.

The initial content files must be present in the ROM in the private folder of the Menu Content Service: \private\200113DD\content\.

Each client application is responsible for customizing its menu content.

Exception handling

The leave mechanism of the Symbian OS environment is used to handle unrecoverable error conditions.

Extensions to the API

There are no extensions to the API.

Limitations of the API

There are no limitations to the API.