API Files

This topic contains detailed info about how APIs can use Legato's interface definition language (IDL). Legato's IDL helps apps be written in multiple, different programming languages.


Also see

Syntax
C Language Support


Related info

ifgen
Definition Files
Extend helloWorld

Overview

Legato components can provide APIs for other components to use. It can be done conventionally by writing a C header file to define the interface. But a C header file can only be used by components also written in C, and functions defined in a C header file can only be implemented by C code. C compilers won't generate IPC code, so unless you write your own, your API implementation and its user are forced to run inside the same process. This can severely limit the reusability of components and can force using a programming language not ideally suited to a particular problem domain or developer skillset. It also leaves inter-process communication (IPC) to be implemented manually, which can be time-consuming and fraught with bugs and security issues.

To simplify things, Legato has an IDL similar to C that helps define APIs so they can be used in multiple, different programming languages.

These IDL files are called API (.api) files.

They're processed by the ifgen tool that generates function definitions and IPC code in an implementation language chosen by the component writer. Most of the time, developers don't need to know much about ifgen, because it's automatically run by other build tools, as needed.

An API client:

  • import the API into their component (add the .api file to the api: subsection of the requires: section of the component's Component.cdef file)
  • include/import the generated code into their program (e.g., in C: #include "interfaces.h")
  • call the functions in the API

This automatically will do IPC connection opening/closing, message buffer allocation/release, message passing, synchronization between client and server threads/processes, and sandbox security access control.

An API server:

  • export the API from their component (add the .api file to the api: subsection of the provides: section of the component's Component.cdef file)
  • include/import the generated code into their program (e.g., in C: #include "interfaces.h")
  • implement the functions in the API

The server's functions are called automatically when the client calls the auto-generated client-side versions of those functions.