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:

#OCAP.mgrmgr.manager.Signalling=org.cablelabs.impl.manager.signalling.TestSignallingMgr
OCAP.mgrmgr.manager.Signalling=org.cablelabs.impl.manager.signalling.DavicSignallingMgr

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:

ait-<[1-9a-f][0-9a-f]*>.properties

example:   ait-44d.properties

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:

xait.properties

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:

hostapp.properties

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.

version=0

Transport Protocols

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

transport.<i>=<type>
transport.<i>.<field>=<value>

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:

maxtps=<max transport protocols>
maxurls=<max URLS per IP protocol>

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

transport.255=local

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:

C:\MyProjects\OCAPApps\MyApp

becomes:

/C/MyProjects/OCAPApps/MyApp

Services

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

svc.<i>.<field>=<value>

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:

svc.x.service_id=0x012345
svc.x.auto_select=true
svc.x.name=Default Service

Applications

Application specifications have the following form:

app.<i>.<field>=<value>

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:

authorized.<i>=<appid>:<priority>

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.

privcertbytes=[<hex>{40}]
or:
privcertbytes.<i>=<hex>{40}

example --  the following are equivalent:
privcertbytes=0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF

privcertbytes.0=0123456789ABCDEF0123456789ABCDEF01234567
privcertbytes.1=89ABCDEF0123456789ABCDEF0123456789ABCDEF

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:

attribute.<i>.id=<attribute ID>
attribute.<i>.name=<attribute name>

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:

addressing.<i>.<field>=<value>

The following fields are supported:

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:

addressing.<i>.expression.<j>=<logicalExpression>

<logicalExpression> := <logical_comp> | <comparison> | <sec_comparison>
<logical_comp> := TRUE | NOT | AND | OR
<sec_comparison> := S <comparison>
<comparison> := attributeID <comparator> attributeValue
<comparator> := < | <= | > | >= | ==

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.

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 '[' ']'

version=1

transport.0=oc
transport.0.component=6

transport.1=ic
transport.1.url=[http://www.ajax.com/appserver]

app.1.application_identifier=0xcafed00d4d01
app.1.application_control_code=AUTOSTART
app.1.visibility=VISIBLE
app.1.priority=200
app.1.application_name.0=eng,Launcher
app.1.service_bound=false
app.1.initial_class_name=com.ajax.xlet.launcher.LauncherXlet
app.1.base_directory=/app/InbandLauncher
app.1.transport=0
app.1.args.0=showMenu

app.2.application_identifier=0xcafed00d4d02
app.2.application_control_code=PRESENT
app.2.visibility=VISIBLE
app.2.priority=180
app.2.application_name.0=eng,Checkers
app.2.initial_class_name=com.ajax.xlet.games.checkers.CheckersXlet
app.2.base_directory=/app/Checkers
app.2.classpath_extension=/lib/ui;/lib/games
app.2.transport=1
app.2.args.0=player=red

Following is an example of xait.properties:

version=4

transport.0=oc
transport.0.remote=true
transport.0.service=0x3e8
transport.0.component=10

transport.1=oc
transport.1.remote=true
transport.1.service=0x41a
transport.1.component=11

svc.0.service=0x2CAFE
svc.0.auto_select=true
svc.0.name=IMA service

svc.1.service=0x3CAFE
svc.1.auto_select=false
svc.1.name=Games Service

app.0.application_identifier=0x000000016220
app.0.application_control_code=AUTOSTART
app.0.visibility=VISIBLE
app.0.priority=255
app.0.version=0
app.0.service=0x2CAFE
app.0.application_name=IMA
app.0.transport=0
app.0.base_directory=/
app.0.initial_class_name=com.xyz.ima.MonApp

app.1.application_identifier=0x000000016221
app.1.application_control_code=PRESENT
app.1.visibility=VISIBLE
app.1.priority=200
app.1.service=0x2CAFE
app.1.application_name=IMA Helper
app.1.transport=0
app.1.base_directory=/
app.1.initial_class_name=com.xyz.ima.Helper

app.2.application_identifier=0x000000016330
app.2.application_control_code=AUTOSTART
app.2.visibility=VISIBLE
app.2.priority=200
app.2.version=0
app.2.service=0x3CAFE
app.2.application_name=Games Menu
app.2.transport=1
app.2.base_directory=/menu
app.2.initial_class_name=com.xyz.games.MenuXlet

app.3.application_identifier=0xcafed00d4d02
app.3.application_control_code=PRESENT
app.3.visibility=VISIBLE
app.3.priority=199
app.3.application_name=Checkers
app.3.transport=1
app.3.base_directory=/games/Checkers
app.3.initial_class_name=com.ajax.xlet.games.checkers.CheckersXlet