Interface management report

This page describes a structure for report documents that describe the interface access and status of APIs of a Symbian OS build.

The reports are in XML, with their structure defined by the DTD given below.

The report structure consists of meta-information about the report itself, followed by lists of named C++ items with their interface access, status, and other identifying information.

The meta-information identifies the OS for which the report was generated: this includes the OS build number, OS release version number, kit type, and company producing the kit.

Items are used in a nested way, so that levels of nesting reflect the C++ scope: e.g. an item element for a member function is nested within an item element for the class.

All items have elements that specify their:

• name

• type (class, function, etc.).

• prototype: This is the text of the item's prototype.

• id: A unique ID, created by an MD5 hash of the item's prototype.

• interface-access: One of publishedPartner, publishedAll, internalTechnology, internalComponent, internalAll, unspecified:

  publishedPartner This is an interface of Symbian OS but it is exposed only internally and to partners. publishedAll This is a public interface of Symbian OS and has many clients. internalTechnology This interface may have clients in other components of its own technology, but is not intended for use by other technologies. This is not a public interface of Symbian OS. internalComponent This interface should have no clients outside its own component. This is not a public interface of Symbian OS. internalAll This interface is definitely intended to have clients in other technologies of the System, but is not intended for use by partners and ISVs. This is not a public interface of Symbian OS. unspecified No access currently specified.

• interface-status: One of: prototype, interim, released, deprecated, removed, unspecified:

  prototype Interface is experimental. May be used in development kits and tools, and in prototype phones for development and evaluation purposes, but not in phones released to end-users. interim Interface is not stabilised yet; this API will be either released or withdrawn in the next release. released Interface has been stabilised and released. Provided it is shipped in an appropriate Release of Symbian OS, it is available for use in real phones intended for release to end-users, and in development kits and tools which support such phones. deprecated Interface is deprecated and is available for backward compatibility reasons only. Interface may in future be withdrawn. removed Interface is no longer supported. unspecified Interface is reserved for Reference / Test components (e.g. TechView) and must not be included in a licensee device.

Global (unnested) items must additionally specify component and other information, which does not vary at the member level. This consists of:

• Header file that declares the item.

• Library to link against to use the item.

• Technology (currently unused)

• Sub-system

• Component

Functions can optionally have an additional field that reports the link signature of the function.

<!-- IM report document element definition.
This consists of document information, followed by lists of named C++ items
with their IM access and other information -->
<!ELEMENT symbian-interface-doc (doc-info, item+)>

<!-- Document information.
This describes the source of the information for the document. -->
<!ELEMENT doc-info (build, release, kit, owner)>

<!-- OS build number -->
<!ELEMENT build (#PCDATA)>
<!-- OS release version number -->
<!ELEMENT release (#PCDATA)>
<!-- Kit type -->
<!ELEMENT kit (#PCDATA)>
<!-- Company that produced the build -->
<!ELEMENT owner (#PCDATA)>

<!-- Item information .
Records IM access for a C++ item. It's intended to be used in a nested way, so that
levels of nesting reflect the C++ scope: e.g. an item element for a member function
is nested within an item element for the class.

Nested item must specify their name, access, and type (class, function, etc.). Unnested
items must additionally specify component and other information (this does not vary at
the member level.) -->
<!ELEMENT item (name, id, prototype, type, interface-access, interface-status, linksig?, header?, 
    library?, technology?, sub-system?, component?, item*)>

<!-- Item name.
The name does not include the scope: this is implied by the item's nesting. -->
<!ELEMENT name (#PCDATA)>

<!-- Item ID.
A unique ID, an MD5 hash of the item's prototype. This allows simple comparision and
tracking of items by programs. -->
<!ELEMENT id (#PCDATA)>

<!-- Item prototype
This is the text of the item's prototype. Text is useful for human readability. -->
<!ELEMENT prototype (#PCDATA)>

<!-- Item type.
One of: class, function, struct, enum, typedef, macro, enum-member, union, data, namespace -->
<!ELEMENT type (#PCDATA)>

<!-- IM access.
One of: publishedPartner, publishedAll, internalTechnology, internalComponent, internalAll, unspecified  -->
<!ELEMENT interface-access (#PCDATA)>

<!-- IM status.
One of: prototype, interim, released, deprecated, removed, unspecified  -->
<!ELEMENT interface-status (#PCDATA)>

<!-Link signature for a function. -->
<!ELEMENT linksig (#PCDATA)>

<!-- Header file that declares the item. -->
<!ELEMENT header (#PCDATA)>

<!-- Library to link against to use the item. -->
<!ELEMENT library (#PCDATA)>

<!-- Technology -->
<!ELEMENT technology (#PCDATA)>

<!-- Sub-system -->
<!ELEMENT sub-system (#PCDATA)>

<!-- Component -->
<!ELEMENT component (#PCDATA)>

Interface Management reports are included as part of the Release Notes on the CustKit.

Note that not all items are yet IM classified.