DEFINE

The value can be a string or an expression evaluated to a numeric value (when the definition is read).

ENUM

An ENUM is specified as:

ENUM <name>
{
[<elementList>]
};

The elementList is a comma separated list of elements. The elements should all be uppper-case. Element values assigned are internally generated. Element values can also be assigned explicitly as below:

ENUM <name>
{
<element1> = 1,
<element2>,
<element3>
};

BITMASK

A BITMASK is a special type of ENUM. It is specified the same way as an ENUM, but the internally generated element values are bit positions, i.e. 0x1, 0x2, 0x4, etc.

REFERENCE

A REFERENCE is specified as:

REFERENCE <name>;

The REFERENCE is used to define a reference to an object. The object reference is mapped to an opaque reference in C and an object instance or similar in other languages.

STRUCT

A structure is used to define a collection of data, similar to a C struct. A STRUCT can contain members of any type, including strings, arrays, and other STRUCTs.

When structured data is passed over an API call, the entire structure is passed every time. For smaller structures this overhead can be minimal. For larger objects it's better to return a reference to the object using the REFERENCE type and use accessor functions to get the properties of the object.

HANDLER

A HANDLER is specified as:

HANDLER <handlerType>
(
[<parameterList>]
);

The parameterList can contain one or more parameters separated by commas, or can be empty if there are no parameters. It can only contain scalar types or string types, as described in Specifying a Function. All the parameters should be IN parameters.

See Handlers in C for details on the C code generated from the above handler definition.

USETYPES

You can share type definitions between .api files with USETYPES. This is commonly referred to as importing, although only the type definitions are imported or used. Any code related definitions in a .api file, e.g. FUNCTION, are ignored. These USETYPES can even be nested.

Note

It is not necessary to include the .api extension when importing. I.e.

USETYPES defn;

is equivalent to

USETYPES defn.api;

As an example of usage, suppose the files defn.api, common.api and example.api are defined as follows:

defn.api

DEFINE FIVE = 5;

common.api

USETYPES defn.api;
DEFINE TEN = defn.FIVE + 5;

example.api

USETYPES common.api;
DEFINE twenty = common.TEN + defn.FIVE + 5;

This example illustrates that nesting causes an implicit USETYPES. Thus, any definitions from defn.api, can be used in example.api, in the same way as if it had explicitly imported defn.api.

Specifying a Function

A function is specified as:

FUNCTION [<returnType>] <name>
(
[<parameterList>]
);

The parameterList can contain one or more parameters separated by commas, or can be empty if there are no parameters. These parameters types are supported:

<type> <name> [ ( "IN" | "OUT" ) ]

scalar type

defaults to IN if a direction is not specified

<type> <name> "[" <maxSize> "]""IN"

an IN array

maxSize specifies the maximum number of elements allowed for the array

optional minSize specifies the minimum number of elements required for the array

[ <minSize> ".." ] is now deprecated. Only <maxSize> needs to be specified.

"string" <name> "[" <maxSize> "]""OUT"

an OUT string

string should be large enough to store maxSize characters; if supported by the function implementation, a shorter OUT string can be used.

string length is given as number of characters, excluding any terminating characters

<handlerType> <name>

a handler (callback) function.

see apiFilesSyntax_handler for info on how to declare a handler.

The returnType is optional, and if specified, can be any type that's not an array, string, or handler.

Warning

Make sure that the function's maxSize is appropriately defined. If the client sends a value that larger then the <maxSize>, an error will be written to the log ((strlen(<name>) | <name>Size) > <maxSize>) and the client will be terminated.

Specifying an Event

Do this to specify an event:

EVENT <eventType>
(
<parameterList>
);

The parameterList can contain one or more parameters separated by commas. It can contain anything that's valid for a function, but it must contain one handler parameter. The parameters are used when registering a handler for the specified event.

See Events in C for details on the C code generated from the above event definition.

Comments

The API file supports both C and C++ comment styles. Comments that use the doxygen formats

/**

to start a multi-line comment or

///<

to start a one line comment receive special processing. Multi-line comments at the start of the API file will be copied directly to the start of the appropriate generated files.

Comments given in the function definition will be copied to the appropriate generated files under the following conditions:

Multi-line comments must start with

/**

Single-line comments must start with

///<

In a block of single-line comments, each line must start with

///<

rather than just the first line. This is different from typical doxygen usage.

If the function definition is preceded by a multi-line comment then this comment will be copied to the appropriate generated files.

If any parameter is followed by a multi-line comment or one or more single line comments, then all these comments will be copied to the appropriate generated files.

If an event or handler definition is preceded by a multi-line comment, then this comment will be copied to the appropriate generated files, under the same conditions as function definitions.

Any comments provided after an element in an ENUM or BITMASK, will be copied to the appropriate generated files, under the same conditions as function parameter comments.

Sample API

Here's the defn.api file containing just type definitions

/**
* Example of nested .api file
*/
DEFINE SIX = 6;

Here's the common.api file containing just type definitions, and using the types defined in defn.api