# Syntax

Source: [https://docs.qualcomm.com/doc/80-41102-3/topic/api_files_syntax.html](https://docs.qualcomm.com/doc/80-41102-3/topic/api_files_syntax.html)

TelAF API files support defining functions, events, handlers as well as custom
            user-defined types.

[Functions](https://docs.qualcomm.com/doc/80-41102-3/topic/api_files_syntax.html#concept.api_files_syntax__section_qzb_zhv_v5b) are similar to C functions. They
            take input and output parameters, and return a result.

The API file currently supports:

- pre-defined types
- user-defined types

## Type Support

Pre-defined Types:

    uint8
    uint16
    uint32
    uint64
    
    int8
    int16
    int32
    int64
    
    double
    
    string
    
    bool
    
    file
    
    le_result_t
    le_onoff_t
    Copy to clipboard

The `uint` and `int` types are basic data integer
                types.

The `double` type is an 8 byte floating-point data type.

The `string` type is a data type used to store text.

The `bool` type is a data type used to store boolean values (true,
                false).

The `file` type is used to pass an open file descriptor as a parameter
                between a client and server.

The le\_result\_t and le\_onoff\_t types from legato.h can also be used in API files.

User-defined types:

- DEFINE
- ENUM
- BITMAP
- REFERENCE
- HANDLER
- STRUCT

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

## DEFINE

A DEFINE is specified as:

    DEFINE <name> = <value>;Copy to clipboard

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>]
    };Copy to clipboard

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

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

## 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>;Copy to clipboard

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 STRUCT is specified as:

    STRUCT <name>
    {
        <type> <name>;                ///< Simple structure member
        string <name>[<maxSize>];     ///< String structure member
        <type> <name>[<maxSize>];     ///< Array structure member
        ...
    };Copy to clipboard

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>]
    );Copy to clipboard

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](https://docs.qualcomm.com/doc/80-41102-3/topic/api_files_syntax.html#concept.api_files_syntax__section_qzb_zhv_v5b). All the parameters
                should be IN parameters.

## 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; Copy to clipboard

is equivalent
                        to

    USETYPES defn.api; Copy to clipboard

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

defn.api

    DEFINE FIVE = 5;Copy to clipboard

common.api

    USETYPES defn.api;
    
    DEFINE TEN = defn.FIVE + 5;Copy to clipboard

example.api

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

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>]
    );Copy to clipboard

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" ) ] Copy to clipboard

- scalar type
- defaults to IN if a direction is not specified

    <type> <name> "[" <maxSize> "]""IN"Copy to clipboard

- 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

                    - **Deprecated:**

                        - [ &lt;minSize&gt; ".." ] is now deprecated. Only &lt;maxSize&gt; needs to be
                        specified.

    <type> <name> "[" <maxSize> "]""OUT"Copy to clipboard

- an OUT array
- array should be large enough to store `maxSize` of elements; if
                    supported by the function implementation, a shorter OUT array can be used.

    "string" <name> "[" <maxSize> "]""IN"Copy to clipboard

- an IN string
- `maxSize` specifies the maximum string length allowed,
- string length is given as number of characters, excluding any terminating
                    characters

                    - **Deprecated:**

                        - [ &lt;minSize&gt; ".." ] is now deprecated. Only &lt;maxSize&gt; needs to be
                        specified.

    "string" <name> "[" <maxSize> "]""OUT"Copy to clipboard

- 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> Copy to clipboard

- 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 &lt;maxSize&gt;, an
                        error will be written to the log ((strlen(&lt;name&gt;) | &lt;name&gt;Size) &gt;
                        &lt;maxSize&gt;) and the client will be terminated.

## Specifying an Event

Do this to specify an event:

    EVENT <eventType>
    (
        <parameterList>
    );Copy to clipboard

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.

## Comments

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

    /** Copy to clipboard

to start a multi-line comment or

    ///< Copy to clipboard

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

        /** Copy to clipboard
- Single-line comments must start
                    with

        ///< Copy to clipboard
- In a block of single-line comments, each line must start
                    with

        ///< Copy to clipboard

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;Copy to clipboard

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

    /**
     * Common definitions potentially used across multiple .api files
     */
    
    USETYPES defn;

    /**
     * Definition example
     */
    DEFINE FOUR = 4;
    
    /**
     * Example of using previously DEFINEd symbol within an imported file.
     */
    DEFINE TEN = FOUR + defn.SIX;
    
    /**
     * Reference example
     */
    REFERENCE OpaqueReference;
    
    /**
     * ENUM example
     */
    ENUM EnumExample
    {
        ZERO,     ///< first enum
        ONE,      ///< second enum
        TWO,      ///< third enum
        THREE     ///< fourth enum
    };
    
    /**
     * BITMASK example
     */
    BITMASK BitMaskExample
    {
        BIT0,     ///< first
        BIT1,     ///< second
        BIT2,     ///< third
    };Copy to clipboard

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

    /**
     * Example API file
     */
    
    // The .api suffix is optional
    USETYPES defn;
    USETYPES common.api;

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

    /**
     * Handler definition
     */
    HANDLER TestAHandler
    (
        int32 x   ///< First parameter for the handler
                  ///< Second comment line
    );

    /**
     * This event provides an example of an EVENT definition
     */
    EVENT TestA
    (
        uint32 data,          ///< Used when registering the handler i.e. it is
                              ///< passed into the generated ADD_HANDLER function.
        TestAHandler handler
    );

    /**
     * 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
    );
    
    /**
     * Function that takes a handler parameter
     */
    FUNCTION int32 UseCallback
    (
        uint32 someParm IN,
        handler TestAHandler
    );Copy to clipboard

**Parent Topic:** [API files](https://docs.qualcomm.com/doc/80-41102-3/topic/api_files.html)

Last Published: Apr 23, 2025

[Previous Topic
API files](https://docs.qualcomm.com/bundle/publicresource/80-41102-3/topics/api_files.md) [Next Topic
C language support](https://docs.qualcomm.com/bundle/publicresource/80-41102-3/topics/api_files_c.md)