Search Within Space:

File-Based Application Signaling

The OCAP implementation supports an alternate form of application signalling through Java properties files. This format is always used to describe resident host device manufacturer applications (hostapps). For development and testing activities, this format can also be used to represent inband application signalling (AIT) and out-of-band MSO application signalling (XAIT).

The SignallingManager implementation determines whether the stack will use normal network-based (DavicSignallingMgr) or .properties-based (TestSignallingMgr) application signalling. The DavicSignallingMgr implementation (com.vidiom.impl.manager.signalling package), which supports true OCAP application signalling, is the default. You can modify the signalling implementation used by the stack by modifying the following manager definition in the final.properties file:

Just uncomment the manager that you want to use and comment out the other. NOTE: File-based signaling is always used for resident application signaling! The signaling manager only describes handling of in-band (AIT) and out-of-band (XAIT) signaling

Types Of Signaling

There are three forms of file-based signaling. They are:

  • AIT
  • XAIT
  • Hostapps

All signaling files must reside somewhere in the JVM system classpath as defined in the mpeenv.ini file.

AIT

The AIT form is used to describe in-band application signalling. All AIT files must be named as such:

There may be one or more AIT files present in the system classpath. As long as a particular service is selected, the implementation will watch for changes to its associated ait-XXXX.properties file (useful for testing signaling version changes). The ait form is comprised of the following information:

  • version
  • transport protocols
  • applications
  • external authorization

XAIT

The XAIT form is used to describe MSO abstract services and their associated unbound applications. There can only be one XAIT file in the system classpath and it must be named as such:

The implementation will watch for changes to the xait.properties file (useful for testing signaling version changes). The XAIT form is comprised of the following information:

  • version
  • transport protocols
  • services
  • applications
  • privileged certificate hash(es)

Hostapps

The hostapp form is used to describe resident host device applications. The implementation will read a hostapp.properties file at bootup and populate the services database based upon its contents. There can only be one hostapps file in the system class back and it must be named as such:

The hostapp.properties can contain the exact same information as the xait.properties.

Fields

Below of the detailed descriptions of the various fields that can appear in signaling files. The symbol <i> indicates that multiple entries are supported (always starting at 0).

Version

A version definition is required to document the version of the application signalling. Signalling updates are only acknowledged with a change of version. If no definition is provided, then the following implicit entry is assumed.

Transport Protocols

Transport protocols describe the methods for delivering application content to the stack.

With the following supported types:

  • oc
  • ip
  • ic
  • local

    field

    Description

    Type

    remote

    Boolean; indicates remote protocol

    oc, ip

    service

    Service id, only if remote=true

    oc, ip

    component

    Principal component tag for OC

    oc

    alignment

    Alignment indicator

    ip

    url.<i>

    URL

    ip

    url

    URL

    ic

    The default maximum of 32 transport protocols and or 32 URLs per IP protocol can be overridden with:

By default, if no transport protocols are defined, an implicit local protocol is defined:

The local transport is an RI-specific mechanism that allows you to place apps in your local filesystem instead on OCAP-defined transports. Note that the local transport always has an index of 255, regardless of the index used in the definition. I.e., the app.<i>.transport must reference 255 to get the local transport. At this time, you can not use the local transport in combination with other transports. If you want to use the local transport, you must remove all other transport definitions from your signaling file.

When using the local transport, your application base_directory should be modified to indicate the absolute path to the application base directory in your local file system. On Windows, only use "/" in your pathnames, not "\". Also, you must transform the drive letter designation into something more POSIX-like. <drive_letter>: should become /<drive_letter>. For example:

Services

Abstract service specifications (only valid in xait.properties or hostapp.properties forms) have the following format:

field

Description

Required/Default Value

service_id

Service id (hostapps: 0x010000-0x01FFFF) (xait: 0x020000-0xFFFFFF)

required

auto_select

Boolean; whether service is autoselect

false

name

Service name

required

If an application definition in a hostapp.properties does not include an app.<i>.service field, then an implicit definition corresponding to the following is included:

Applications

Application specifications have the following form:

field

Description

Required/Default Value

Form

application_identifier

App ID (48-bit hex)

required

all

application_control_code

One of PRESENT, AUTOSTART, KILL, REMOTE

required

all

application_name

English language name

null

all

application_name.<i>

Language-specific name expressed as <lang>,<name>

null

all

service_bound

Boolean; indicates if app is service bound

true

all

version

Integer application version, higher number indicates newer version

0

XAIT, Hostapps

visibility

One of INVISIBLE, VISIBLE, VISIBLE-TO-APPS-ONLY

required

all

priority

Application priority (255=Mon App, 100-254=Unbound, 1-200=Bound)

required

all

icon_locator

Path relative to base_directory for icons

null

all

icon_flags

Icon flags as appropriate for AppIcon

none

all

initial_class_name

Fully qualified name of initial xlet class

required

all

base_directory

Base directory for application

required

all

classpath_extension

Semi-colon separated list of classpath extension directories

null

all

args.<i>

Xlet arguments

none

all

transport

Comma-separated list of transport protocol indices

local

all

service

Abstract service identifier

required for xait; 0x012345 default for hostapp

XAIT,Hostapps

storage_priority

Application storage priority

0

XAIT,Hostapps

launch_order

Application launch order

0

XAIT,Hostapps

app_profiles.<j>.profile

Supported profile (hex or int)

Not required, default 0x102

all

app_profiles.<j>.version_major

Supported profile (hex or int)

Not required, default 0x1

all

app_profiles.<j>.version_minor

Supported profile (hex or int)

Not required, default 0x1

all

app_profiles.<j>.version_micro

Supported profile (hex or int)

Not required, default 0x1

all

api.<i>

Desired "registered api"

none

XAIT

address_label.<i>

Integer; Application adressing labels

none

AIT, XAIT

application_mode

One of LEGACY, NORMAL, CROSSENVIRONMENT, BACKGROUND, PAUSED

LEGACY

AIT, XAIT

Note: registration of an app profile requires profile, major, minor and micro to be defined. Multiple profiles may be registered (starting with index j=0).

External Authorization

Any number of external authorization specifications can be included (the default maximum of 32 can be overridden via a maxauth definition). The specification includes an application identifier and a priority. Application identifiers with an AID of 0xFFFE and 0xFFFF have the same wildcard meaning as for the AIT. The format is as follows:

Privileged Certificates

Any number of "privileged certificate hashes" may be included (the default maximum of 32 can be overridden via a maxprivcert definition). The privileged certificate hashes may be specified as a single long hexadecimal string representing multiples of 20 bytes or as individual entries.

Attribute Mapping Descriptor

For addressable X/AIT, any number of attribute mapping descriptors can be specified (the default maximum of 32 can be overridden using a maxattr definition). Attribute mapping descriptors are specified using the following form:

Addressing Descriptor

For addressable X/AIT, Any number of addressing descriptors can be specified (the default maximum of 32 can be overridden using a maxaddr definition). Addressing descriptors are specified using the following form:

The following fields are supported:

field

Description

Required/Default

group

Integer; Addressing group ID

required

label

Integer; Application addressing label

required

priority

Integer; Addressing descriptor priority

required

expression.<j>

See next section

required

Addressing Expression

Each addressing descriptor must contain at least one evaluation expression. At most 32 expressions can be specified for each addressing descriptor. Expressions are specified using the following form:

NOTE: attributeID is the ID from the corresponding attribute mapping descriptor. Addressing expressions should be specified in the order that they should be pushed on to the operation stack (See OCAP-1.1.1 11.2.2.5.1 Addressing Descriptor)

Maximum Number of Entries

In general, the maximum number of any type of entry is 32 (actually, the maximum index for any type of entry). This can be overridden with an additional property.

property

description

default

maxauth

Number of authorization entries

32

maxtp

Number of transport entries

32

maxurl

Number of urls in an IP transport

32

maxapps

Number of app entries

32

privcert

Number of privcertbytes entries

32

maxattr

Numberof attribute mapping descriptors

32

maxaddr

Number of addressing descriptors

32

Example

Following is an example ait-44d.properties file: NOTE: This Wiki is putting '[' ']' around the interaction channel protocol URLs. The actual URLs SHOULD NOT be surrounded by '[' ']'

Following is an example of xait.properties:

Labels
  • None