The API file supports defining functions, handlers and user defined types. Functions are similar to C functions. They can take input and output parameters, and can return a result. A handler is a special function type that can be registered for callbacks. The API file currently supports a limited number of pre-defined types. There is also support for a number of different user-defined types.

Type Support

The API file currently supports a limited number of pre-defined types. These are:

uint8
uint16
uint32
uint64

int8
int16
int32
int64

string
file

The unsigned and signed integer types are self-explanatory. See Specifying a Function for details on the string type. The file type is used to pass an open file descriptor (fd) as a parameter. This is used for passing an fd between a client and server.

The following user-defined types are supported:

DEFINE
ENUM
REFERENCE

Type definitions can also be shared between API files with USETYPES.

Also, all C types defined in the legato.h file are available. The most commonly used of these is the le_result_t type. This is a temporary measure and will be removed in a future release.

DEFINE

A DEFINE is specified as:

DEFINE <name> = <value>;

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 and can't be explicitly given.

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.

USETYPES

You can share the same type definitions between .api files with USETYPES. For example, suppose the file common.api contains:

DEFINE TEN = 10;

Then the file example.api can use this definition as follows:

USETYPES common.api;

DEFINE twenty = common.TEN + 10;

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. The scalar type refers to anything that's not an array or string (i.e. scalar types do not have a length). These parameters types are supported:

<type> <name> [ ( "IN" | "OUT" ) ]
- scalar type
- defaults to IN if a direction is not specified
<type> <name> "[" [ <minSize> ".." ] <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
<type> <name> "[" <minSize> "]" "OUT"
- an OUT array
- array should be large enough to store minSize elements; if supported by the function implemention, a shorter OUT array can be used.
"string" <name> "[" [ <minSize> ".." ] <maxSize> "]" "IN"
- an IN string
- maxSize specifies the maximum string length allowed,
- optional minSize specifies the minimum string length required
- string length is given as number of characters, excluding any terminating characters
"string" <name> "[" <minSize> "]" "OUT"
- an OUT string
- string should be large enough to store minSize characters; if supported by the function implemention, a shorter OUT string can be used.
- string length is given as number of characters, excluding any terminating characters

The returnType is optional, and if specified, must be a scalar type as described above.

Specifying a Handler

Do this to specify a handler:

HANDLER <handlerType>
{
    HANDLER_PARAMS
    (
        [<parameterList>]
    );
        
    ADD_HANDLER_PARAMS
    (
        [<parameterList>]
    );
}

The parameterList can contain one or more parameters separated by commas, or can be empty if there are no parameters. Currently, the HANDLER_PARAMS parameterList can only be scalar types, as described above for Specifying a Function. All the parameters should be IN parameters. The ADD_HANDLER_PARAMS parameterList can be anything that's valid for a function. ADD_HANDLER_PARAMS does not need to be specified if the parameterList is empty.

See Handlers in C for details on the C code generated from the above handler 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 a 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, will be copied to the appropriate generated files, under the same conditions as function parameter comments.

API File Sample

Here's the common.api file containing just type defintions:

/**
 * Common definitions potentially used across multiple .api files
 */

/**
 * Definition example
 */
DEFINE SOME_VALUE = 5;

/**
 * Example of using previously DEFINEd symbol within an imported file.
 */
DEFINE TEN = SOME_VALUE + 5;

/**
 * Reference example
 */
REFERENCE OpaqueReference;

/**
 * ENUM example
 */
ENUM EnumExample
{
    ZERO,     ///< first enum
    ONE,      ///< second enum
    TWO,      ///< third enum
    THREE     ///< fourth enum
};

Here's the example.api file containing various definitions, and using the types defined in common.api

/**
 * Example API file
 */

USETYPES common;

DEFINE TEN = common.TEN;
DEFINE TWENTY = TEN + common.TEN;
DEFINE SOME_STRING = "some string";


/**
 * Handler definition
 */
HANDLER TestA
{
    ADD_HANDLER_PARAMS ();

    HANDLER_PARAMS
    (
        int32 x   ///< First parameter for the handler
                  ///< Second comment line
    );
};


/**
 * Function takes all the possible kinds of parameters, but returns nothing
 */
FUNCTION allParameters
(
    common.EnumExample a,  ///< first one-line comment
                           ///< second one-line comment
    uint32 b OUT,
    uint32 data[common.TEN] IN,

    uint32 output[TEN] OUT,   ///< some more comments here
    ///< and some comments here as well

    string label [common.TEN..20] IN,
    string response [TWENTY] OUT
    ///< comments on final parameter, first line
    ///< and more comments
);


/**
 * Test file descriptors as IN and OUT parameters
 */
FUNCTION FileTest
(
    file dataFile IN,   ///< file descriptor as IN parameter
    file dataOut OUT    ///< file descriptor as OUT parameter
);