Type Support
Specifying a Function
Specifying a Handler
Interface File Sample

The interface file currently supports defining two types of interface objects:

functions
handlers

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 interface file currently supports a limited number of pre-defined types. For additional types, support to include C types is available.

The interface 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 interface file will be copied directly to the appropriate generated files.

See Specifying a Function and Specifying a Handler for details on how comments are copied.

Type Support

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

uint8
uint16
uint32
uint64

int8
int16
int32
int64

string

The unsigned and signed integer types are self-explanatory. See Specifying a Function for details on the string type.

There is currently no support for defining additional types within the interface file. See C Language Support for details on how to include C types, which can be used anywhere that the pre-defined types are used.

Also, all C types defined in the legato.h file are available. The most commonly used of these is the le_result_t type.

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.

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 "///<". Unlike typical doxygen usage, if there are a number of single line comments, each line must start with "///<", rather than just the first line.
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.

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.

Comments given for a handler definition are not currently copied to the appropriate generated files.

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

Interface File Sample

Here's a sample file:

/**
 * Example interface file
 */

/**
 * Handler definition
 */
HANDLER TestA
{
    HANDLER_PARAMS
    (
        int32 x
    );
        
    ADD_HANDLER_PARAMS ();
};

/**
 * Function takes all the possible kinds of parameters, but returns nothing
 */
FUNCTION allParameters
(
    int32 a,  ///< first one-line comment
              ///< second one-line comment
    uint32 b OUT,
    uint32 data[10] IN,
    uint32 output[10] OUT,
    string label [10..20] IN,
    string response [20] OUT
);

/**
 * This function fakes an event so the handler will be callled.  
 * Only needed for testing.  Would never exist on a real system.
 */
FUNCTION TriggerTestA
(
);