ACCESS Developer Network | Manifest File Reference | Element, Bundle, Application, Applications, Preference

An ACCESS Linux Platform native bundle is represented as a folder—or as a .bar file, which is a single file that contains an image of that folder—which contains a manifest file named Manifest.xml at its root. A manifest specifies a set of properties associated with the bundle. The manifest file uses an XML format to specify those properties.

While the contents of a given manifest can be somewhat generic and of interest largely to the executable inside the bundle, there are a couple of properties that are relied upon by various ACCESS Linux Platform components.

Manifest File Structure ^TOP^

A manifest file should be in this form:

<manifest name="foo.bar"> 
	<a> 
		<b>1</b> 
		<c>2</c> 
	</a> 
	<a> 
		<x></x> 
	</a> 
	<other> 
		<somevalue/> 
	</other> 
</manifest>

Any elements within the manifest at the third level ("b", "c", and "x" in the above example) are registered as bundle properties. Specifically, in the above example the following would be registered:

Property	"Which"	Key	Value
a	0	b	1
a	0	c	2
a	1	x	""
other	0	some value	""

To retrieve the value of a bundle property, supply the property name, "which" value, and key to alp_bundle_property_value().

Any second-level elements not containing third-level elements, or any elements otherwise not conforming, are ignored for the purpose of generating bundle properties. They don't prevent the bundle from being accepted, however.

IMPORTANT: Element names and values (properties, keys, and values) are case-sensitive.

The <manifest> Element ^TOP^

The manifest file must have an outermost <manifest> element, which can have these attributes:

name: this attribute is the only one which is required. It contains the name of the bundle. It should not start with "bar:"; that part of the name is implied.
version: the version of the bundle itself. Do not confuse this with the version of the application or preference panel, which is specified using the <about> element. This attribute is optional, and if present should be an integer. If not present, the bundle's version is assumed to be 0.
arch: this attribute is optional, and if present should be a string indicating which architecture this bundle is intended for.
desired_filename: this attribute is optional, and if present indicates the file name which should be used to convert the bundle to an image file. The name given will have the .bar extension appended to it.
searchpath: this attribute is optional. If present, it should be a string in the form of a set of colon-separated path prefixes, potentially containing "^l" to indicate a locale fill-point. This affects how localized resources are searched for. If not present, it defaults to "/rsc/^l/:/".
textdomain: this attribute is optional. If present, it defines the default gettext domain applied to code running from this bundle. It should be a string potentially containing "^n"or "^N". The former is mapped to the bundle name without the scheme prepended (for instance, "com.companyname.appname"), while the latter is mapped to the complete bundle name (such as "bar:com.companyname.appname"). If not present, this attribute defaults to "bar-^n".
bindtextdomain: this attribute is optional. If present, it defines the directory to which the gettext domain is bound. It should be a string which defines a path relative to the base of the bundle. If not present, this attribute defaults to "rsc".

Resource File Paths ^TOP^

The resource files associated with ACCESS Linux Platform native bundles map directly to the contents of the bundle's folder. A path starting with a slash is a "fixed path", and matches only that exact file within the bundle: /rsc/MyView.xml. A path starting without a slash is looked up through the locale search path, which can translate "MyView.xml" into "/rsc/en_US/MyView.xml", as appropriate.

Note that the use of a leading slash to distinguish fixed paths from localized paths means that you might need to use two slashes in URL syntax:

bar:com.access.apps.memo//my/filename

There is one "magic" resource syntax specifically supported by ACCESS Linux Platform native bundles. The translation syntax is:

^t/Some string

This path will be retrieved by taking the part of the path after the slash, and feeding it through gettext() to perform a translation to the current locale. The result of the translation is considered the "contents" of the resource.

In URL syntax:

bar:com.access.apps.memo/^t/MemoPad

Applications and Preference Panels ^TOP^

While there are a number of properties that can be used in an application's manifest file, most applications have manifests that look something like this:

<manifest name="com.access.apps.sample"> 
	<application> 
		<name>Sample</name> 
		<icon>icon_sample.png</icon> 
  </application> 
</manifest>

The <application> Element ^TOP^

Applications and preference panels both use an <application> second-level element. Additional information about the application—most importantly, the application's version number—is specified using a separate element: see "The <about> Element" for details.

The following third-level elements have meaning to various ACCESS Linux Platform components when they fall within the <application> element:

name: Specifies the application name to display in the launcher, or the name of the preference panel. Unless the application is marked as "hidden," this element should be supplied.
icon: Path to the file containing the application's or preference panel's icon. See "Resource File Paths" for information on specifying this path. Unless the application is marked as "hidden," this element should be supplied (although it is not strictly required, if you don't supply an icon the Launcher will only display the application's name; the space allocated for the icon will be left blank).
backgrounding: Specifies the behavior of the application or preference panel when the Application Server launches another application or preference panel as primary. This element can have one of four values: unsupported, required, supported, or preferred.
default-category: Specifies the launcher category for the application. If this element is not specified, the application is "unfiled".
Default_env: Specifies environment variables and the values to which they should be set prior to running the application or preference panel. Specify each variable and value using the form "variable=value;" as shown in this example:
description: A textual description of the preference panel or application. This element should be supplied for preference panels. The application launcher currently does nothing with the contents of the description element, so this element isn't necessary for applications.
enable-theme: Indicates whether or not the theming engine should be employed when rendering the user interface elements of the application or preference panel. Theming is enabled by default, so omitting this element is equivalent to specifying a value of true.
entry: Specifies the entry point for the application or preference panel. Normally the shared object is loaded and then execution begins at alp_main(); this element allows you to specify an alternate entry point. Programmatically you can determine the entry point of the currently-running code with alp_bundle_acquire_entrypoint().
FindVersion: Set this element to 1.0 to make this application's data searchable using ACCESS Linux Platform's system-wide find feature.
hidden: Prevents the application or preference panel from being shown in the launcher. Note that applications that are marked "hidden" still show up in the jump list; see the jump-list element for information on keeping an application out of the jump list.
jump-list: The jump list is a list of recently-used or particularly important applications. Applications are normally placed into the jump list at the time they become the primary application. You can use the jump-list element to change this behavior, forcing an application to always appear in the jump list (supply a value of always) or preventing it from ever appearing in the jump list (supply a value of never). Note that this element is for use with applications only; preference panels never appear in the jump list.
prefpanel: Indicates that this is a preference panel. The default value for this element is false; omitting this element entirely indicates that this is an application.
transient: Transient applications are ones that should be go away (either shut down or move to the background) when the primary application changes. Transient applications are separate applications that appear to be part of the current application. For example, preference panels are typically marked as transient. If the main application opens a preference panel, both should go away if the user switches to another main application while the panel is still open.
vendor: Allows you to identify the vendor of the application or preference panel.

The <about> Element ^TOP^

The <about> element allows you to specify information that is to appear in the application's About dialog and in the Launcher. This element is optional.

The following third-level elements have meaning to various ACCESS Linux Platform components when they fall within the <about> element:

version: Specifies the version of the application or preference panel. If the <version> element is omitted, an About dialog displayed with alp_about_dialog_run() won't present any version information. Note that this version differs from the version specified in the manifest element; the manifest element version specifies the version of the bundle itself. In order to specify the version of your application you need to follow the <application> element with an <about> element that contains a <version> element.
copyright: The copyright notice to be associated with the application. About dialogs displayed using alp_about_dialog_run() will include the specified copyright notice. If the <copyright> element is omitted, an About dialog displayed with alp_about_dialog_run() won't present a copyright notice.
logo: Path to the file containing the icon to be displayed in the application's About dialog. See "Resource File Paths" for information on specifying this path.

IMPORTANT: If this element is omitted, and if the About dialog is displayed by calling alp_about_dialog_run(), an ACCESS logo will be displayed in the About dialog.

<logo>memocorp.png</logo>

vendor: The name of the application's vendor.

The <notifications> Element ^TOP^

The <notifications> element, which lies outside of the <application> element, enables the application to receive a notification when the application is registered with the Application Manager server. Registration happens when the application is installed to the device. Thus, by specifying this element your application is executed when it is first installed (not as the primary application, however). This allows you to initialize settings or create application databases before the application is executed by the user for the first time. It is also where many applications register for additional notifications.

The <notifications> element should be specified as shown here:

<notifications> 
	<register/> 
</notifications>

The <extractor> Element ^TOP^

An extractor is a third-party library (either a stand alone bundle or part of an application) that extracts metadata from a media file of a particular type. Here is a sample extractor manifest:

<extractor> 
	<library>libalp_vrecorder.so</library> 
</extractor> 
<extractor_for> 
	<extension>wav</extension> 
	<mimetype>audio/x-wav</mimetype> 
</extractor_for> 
<supplemental_for> 
	<extension>ogg</extension> 
	<mimetype>audio/ogg</mimetype> 
</supplemental_for>

One or more <extractor_for>, <supplemental_for>, or <thumbnailer_for> elements must follow the <extractor> element.

Each <extractor_for> element tells the cataloger that the extractor wishes to be called for a specific filetype. There should be one <extractor_for> element for each mime type supported by the extractor.

If an extractor can perform supplemental extraction, using the alp_extractor_process_file() entrypoint, it should have one or more <supplemental_for> elements. Such an extractor supplements the regular extractor and is run after the regular extractor to add any additional information to the metadata as necessary. Typically these are created by OEMs.

A <thumbnailer_for> element specifies that the extractor can generate a thumbnail or preview, usually in a format such as GIF or JPEG. Extractors that generate thumbnails must export the alp_extractor_generate_thumbnail() entrypoint.

The following third-level elements apply to the <extractor> element:

library: The standard bundle name of the extractor. This element is required.

The following third-level elements apply to the <extractor_for>, <supplemental_for>, and <thumbnailer_for> elements. Both <extension> and <mimetype> are required in each case.

extension: A required element that specifies the supported filename extension. For instance, "wav" indicates that the extractor supports WAV files.
mimetype: A required element that specifies the supported mime type. For instance, "audio/x-wav".

The <export> Element ^TOP^

The <export> element is primarily used when a bundle wants to export a shared library for others to use (use a <reference> element—described under "The <reference> Element"—to reference the exported shared library). The <export> element can also be used to indicate that one or more directories and .jar files be added to the CLASSPATH environment variable while the bundle is open.

Bundles can contain shared libraries as well as applications. A bundle can export more than one library, and a given library can be exported with multiple names. Consider the following simple manifest file:

<manifest name="package.test"> 
	<export><library>lib/somelib.so</library></export> 
	<export><library>lib/somelib.so</library><as>fred.so</as></export> 
</manifest>

lib/somelib.so is a path within a bundle. It can be an arbitrary shared library that has been placed into the bundle. As directed by the first <export> element in the above example, the Bundle Manager will place a symbolic link named somelib.so into a common shared library path whenever theÃ¾package.test bundle is open.

The second <export> element shows how you can override the exported name of the shared library. In this example, the name in the shared library path will be fred.so, which will be a symbolic link to lib/somelib.so inside the bundle.

As demonstrated in the sample manifest file, above, the <export> element can appear multiple times within a single manifest, if needed. Any bundle can export a shared library.

The following third-level elements apply to the <export> element:

library: Causes a library exported from this bundle to be made available whenever the bundle is open. Other bundles reference this library through the use of a <reference> element. This element is required in order to export a shared library.
as: This optional element specifies the name to be used for the exported library. If this element is not included, the library is exported using the actual name of the library (which specified by the <library> element).
classpath: Adds an entry (either a folder or .jar file) to the CLASSPATH environment variable while the bundle is open.

The <reference> Element ^TOP^

The <reference> element indicates that this bundle has a dependency upon another bundle. It is typically used when another bundle exports a needed shared library. When this bundle is opened, the Bundle Manager will automatically open any referenced bundles.

The <reference> element can be used in any bundle; it is not limited to bundles that contain applications.

Here is a sample manifest that references another bundle:

<manifest name="bundle.a"> 
	<reference> 
		<to>bar:bundle.b</to> 
	</reference> 
</manifest>

The above demonstrates a mandatory reference. Upon opening this bundle, bar:bundle.b is automatically opened. If it cannot be opened, then the open of bundle.a itself fails.

The following illustrates an optional reference:

<manifest name="bundle.a"> 
	<reference> 
		<to>bar:bundle.c</to><optional/> 
	</reference> 
</manifest>

This bundle will be opened even if the named target bundle is not available.

The following third-level elements apply to the <reference> element:

to: Names a bundle to be opened when this bundle is opened.
optional: Indicates that the referenced bundle is optional; whether or not the referenced bundle can be opened, this bundle will be opened. Without this element, if the referenced bundle cannot be opened, this bundle will fail to open.