S60 Menu Content Service APIChanges in S60 5.2 Menu Content Service API documentation
Contents
PurposeThe main purpose of the Menu Content Service is to enable reading and editing menu content. API descriptionThe 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 environmentThe key relationships between the Menu Content Service Server and the components in its environment are shown below: 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. Services requiredThe following services of the Symbian OS infrastructure are required: From the Symbian OS subsystems
The following services of the Domestic OS infrastructure are required: From the Domestic OS subsystems
Services providedThe following services of the SW IF are provided: SW IF
API class structureThe 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. InterfacesBoth the public and internal interfaces used or supported by the Menu Content Service are depicted below: Public interfaces The first layer of the Menu Content Service includes the following public client API classes:
Internal interfaces The Menu Content Service Server is divided into two layers:
Related APIs
Menu ClientThe 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 (
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 (
Related APIs
Menu ServerWhile 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:
Menu EngineCMenuEngObjectFactoryProxy routes requests to appropriate classes
(
The Menu Engine supports the following functionalities:
The Menu Engine is a state machine.
Related APIs
Run-time content explorationIn 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 utilityThe 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
(
Related APIs
MenuSatInterface APIThe
The offered API (
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
Cache mechanismIn 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
Related APIs
Using the Menu Content Service APIOperationsThe 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 sessionsThe 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
Related APIs
Retrieving dataAfter the
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 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
Modifying and creating dataIf some information about an item (i.e. attribute) is modified or created,
the changes are not stored until
Related APIs
Operation of the Menu Engine as a state machineAbove are depicted all possible states of the Menu Engine that is implemented as an active object.
Run-time exploration of applicationsThe 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. Use casesRead menu contentThe 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 itemsThe 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 itemsThe 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 contentThe client may want to observe changes in the menu content and get a notification when a change occurs. Such a change can be:
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 itemThe 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 itemThe 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 itemThe Menu Content Service Client queries the SAT properties (attributes) of menu items. The Menu Content Service Client gets the queried attributes. Use multiple menu contentsThe 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 contentThe Menu Content Service Client instructs the Menu Content Service Server to make modifications in the menu content. Fails if:
The Menu Content Service Server processes the request. Add itemA 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 itemThe given menu item (by ID) is deleted. The menu item is deleted after the asynchronous operation is completed. Move itemsAn item is moved in a folder to a new position or to a new folder. The object is in the new place. Manage item attributesThe 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 flagsThe 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 applicationWhen 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 mediaIf 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 contentThe 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 contentThe 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 captionThe client requests the short caption, long caption and title caption information for a given menu item. Display indicator on running applicationsThe client wants to determine whether an application is running. Handle commandsDifferent 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 URLDifferent item types can have handlers which handle commands sent to them. In this case the Browser application is opened with the provided URL. HandlersFrom the design perspective, the handlers are part of the Menu Content Service client API.
Each command is dispatched to the appropriate plugin via the
Related APIs
Backup and RestoreThe Menu Content Service participates in B&R. It requires passive backup. The whole Menu Content Service Server private directory is backed up including:
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
Related APIs
VariationContent 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.
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies). All rights reserved. License: EPL
|











