Integrating AI Gateway Module with Linux applications

info

Don't forget to generate your AI Gateway Module API Key and download the Library from the Developers dashboard first.

On Linux, the AI Gateway Module service is provided for ARM64, ARMv7, X64, and X86 architectures using bionic, GNU, or musl C libraries.

Extract the Archive

After downloading aigw.tar.gz, open a terminal in its directory and run:

tar -xzf aigw.tar.gz

This command recreates the top-level directory structure as it was archived, including one folder per architecture (e.g., arm64-musl/, x64-glibc/). It also preserves symbolic links by default, so SONAME symlinks remain intact.

Archive Contents

Inside each architecture directory, you will find:

lib/: Contains shared object files (.so extensions) and their associated SONAME symlinks (e.g., libaigw.so → libaigw.so.1).
include/: Contains public header file (.h extensions), used by applications to compile against the AI Gateway Module’s function definitions.
lib/pkgconfig/: Contains the aigw.pc file, which pkg-config uses to expose compiler (--cflags) and linker (--libs) flags.
lib/cmake/aigw/: Contains aigwConfig.cmake and version file, enabling CMake’s find_package(aigw CONFIG) to locate AI Gateway Module targets.

Install into Your Prefix

From inside the chosen architecture folder, install all components to the standard system prefix with:

sudo cp -a . /usr/local/

With this command you recursively copy files and directories, preserving symbolic links. /usr/local is defined by the Filesystem Hierarchy Standard as the location for administrator-installed software.

After copying shared libraries into /usr/local/lib, update the dynamic linker cache:

sudo ldconfig

ldconfig scans directories in /etc/ld.so.conf (including /usr/local/lib), rebuilds /etc/ld.so.cache, and sets up necessary links so applications can locate libaigw.so.* at runtime.

If you prefer to install under a non-standard prefix like a directory under your home (for example, $HOME/.local/aigw), then after copying the files you need to export the following variables so your system and build tools still locate the Module service:

cp -a . ~/.local/aigw/
export LD_LIBRARY_PATH="$HOME/.local/aigw/lib:$LD_LIBRARY_PATH"
export CPATH="$HOME/.local/aigw/include:$CPATH"

LD_LIBRARY_PATH tells the dynamic linker where to look for shared libraries.
CPATH adds include directories for GCC/Clang compilers.

Building with the Module service

gcc
pkg-config
CMake

Using gcc only

You can build your application with AI Gateway Module service by explicitly specifying the correct compiler and linker flags:

gcc main.c -I/usr/local/include -L/usr/local/lib -laigw -o app

-I adds header search directories, -L adds library paths, and -l links the shared library.

Using pkg-config

To build your application with AI Gateway Module service you can use pkg-config to read aigw.pc and provide the correct compiler and linker flags:

gcc main.c $(pkg-config --cflags --libs aigw) -o app

If AI Gateway Module service was installed under a non-standard prefix (for example, $HOME/.local/aigw) export the following variable:

export PKG_CONFIG_PATH="$HOME/.local/aigw/lib/pkgconfig:$PKG_CONFIG_PATH"

Using CMake (Config mode)

To locate AI Gateway Module service add the following line to your projects CMakeLists.txt file:

find_package(aigw REQUIRED CONFIG)

To build your application with AI Gateway Module service add the following line to your projects CMakeLists.txt file:

target_link_libraries(app PRIVATE aigw::aigw)

If AI Gateway Module service was installed under a non-standard prefix (for example, $HOME/.local/aigw), export the following variable:

export CMAKE_PREFIX_PATH="$HOME/.local/aigw:$CMAKE_PREFIX_PATH"

Running the Sample Application

The archive has also a sample included. After installing the AI Gateway Module service as described above, change into this directory:

cd samples/linux

Choose your preferred build method below and make sure you have build tools installed.

Manual
Make
CMake

Using gcc only

In the terminal run:

gcc -pthread main.c -laigw -o app
./app

Using Makefile

In the terminal run:

make
./app

The Makefile internally uses pkg-config, so make sure you have it installed.

Using CMake (Config mode)

In the terminal run:

mkdir build
cmake -S . -B build
cmake --build build
./build/app

CMake must be installed on your system.

Function reference

note

aigw_start() and aigw_stop() are non-blocking. Internally, starting and stopping the AI Gateway Module service are asynchronous operations, so there can be a slight delay before the action takes effect.

`aigw_init`

Initialize the Module service.

int32_t aigw_init(const char *api_key);

Parameters

Name	Type	Description
`api_key`	`const char*`	Your API key provided by AI Gateway Module.

Returns

0 on success; otherwise a negative error code.

Remarks

If the service is already initialized and a different API key is provided, the old instance is terminated and a new one is initialized.
If the service is already initialized and the same API key is provided, the function call effectively does nothing.
api_key is copied by the Module; its memory does not need to remain valid after the call returns.

note

It is required to call this function before any other Module service function.

`aigw_start`

Start the Module service.

int32_t aigw_start(int32_t *state);

Parameters

Name	Type	Description
`state`	`int32_t*`	Out: consent state. Set to `1` if user consent was previously given, otherwise `0`.

Returns

0 on success; otherwise a negative error code.

Remarks

Checks whether explicit user consent was given before. The current consent state is returned via *state.
If consent was previously given, the Module service starts. If not, the service does not start and *state is set to 0.
If the service is already running, the function call effectively does nothing.

note

It is recommended to obtain user consent before starting the Module service.

`aigw_stop`

Stop the Module service.

int32_t aigw_stop(void);

Returns

0 on success; otherwise a negative error code.

Remarks

Stops the Module service if it is running.
If the service is not running, this function does nothing.

note

It is recommended to stop the Module service before closing your application so the service shuts down cleanly.

`aigw_identify`

Get the Module service identifier.

int32_t aigw_identify(char *data, size_t *size);

Parameters

Name	Type	Description
`data`	`char*`	Buffer to receive a NUL-terminated ASCII string. If not `NULL`, the function writes up to `size` bytes and sets `size` to the number of bytes actually written.
`size`	`size_t*`	In/out. If `data` is `NULL`, on return `size` is set to the number of bytes required to store the full NUL-terminated string. If `data` is not `NULL`, on return `size` is set to the number of bytes actually written.

Returns

0 on success; otherwise a negative error code.

Remarks

The identifier is stable across runs on the device.
Use the two-call pattern to retrieve the full value: call with data == NULL to get required size (in bytes), allocate that many bytes, then call again with data and size.
The returned string is NUL-terminated and plain ASCII.
If the provided buffer (data/*size) is smaller than required, the string is truncated to fit (ensuring NUL termination when *size > 0), *size is set to the number of bytes actually written, and the function returns 0.

`aigw_is_running`

Check if the Module service is running.

int32_t aigw_is_running(int32_t *state);

Parameters

Name	Type	Description
`state`	`int32_t*`	Out: set to `1` if the service is running, otherwise `0`.

Returns

0 on success; otherwise a negative error code.

`aigw_opt_in`

Provide user consent.

int32_t aigw_opt_in(void);

Returns

0 on success; otherwise a negative error code.

Remarks

Persists that user consent was given and informs the Module service that it may start.
Subsequent calls to aigw_start() will be allowed to start the service.

`aigw_opt_out`

Revoke user consent.

int32_t aigw_opt_out(void);

Returns

0 on success; otherwise a negative error code.

Remarks

Persists that user consent was revoked and informs the Module service that it should stop if running.
Subsequent calls to aigw_start() will not be allowed to start the service.

`aigw_is_opted_in`

Check whether user consent was given.

int32_t aigw_is_opted_in(int32_t *state);

Parameters

Name	Type	Description
`state`	`int32_t*`	Out: set to `1` if consent was given, otherwise `0`.

Returns

0 on success; otherwise a negative error code.

Remarks

Returns the stored consent state via *state.

`aigw_log`

Enable logging for the Module service.

int32_t aigw_log(const char *dir);

Parameters

Name	Type	Description
`dir`	`const char*`	Directory where log files will be stored. If `NULL` or empty, logs are created in the current working directory.

Returns

0 on success; otherwise a negative error code.

Remarks

Enables logging and writes logs to the specified directory (created if it does not exist).
Logs are also written to standard output.
Subsequent calls to aigw_log() create a new log file in the specified directory.

`aigw_mute`

Disable logging for the Module service.

int32_t aigw_mute(void);

Returns

0 on success; otherwise a negative error code.

Remarks

Disables logging: closes any open log file and stops writing to standard output.
Existing log files are not deleted and can be inspected for debugging.

Extract the Archive​

Archive Contents​

Install into Your Prefix​

Building with the Module service​

Using gcc only​

Using pkg-config​

Using CMake (Config mode)​

Running the Sample Application​

Using gcc only​

Using Makefile​

Using CMake (Config mode)​

Function reference​

aigw_init​

Parameters​

Returns​

Remarks​

aigw_start​

Parameters​

Returns​

Remarks​

aigw_stop​

Returns​

Remarks​

aigw_identify​

Parameters​

Returns​

Remarks​

aigw_is_running​

Parameters​

Returns​

aigw_opt_in​

Returns​

Remarks​

aigw_opt_out​

Returns​

Remarks​

aigw_is_opted_in​

Parameters​

Returns​

Remarks​

aigw_log​

Parameters​

Returns​

Remarks​

aigw_mute​

Returns​

Remarks​

Extract the Archive

Archive Contents

Install into Your Prefix

Building with the Module service

Using gcc only

Using pkg-config

Using CMake (Config mode)

Running the Sample Application

Using gcc only

Using Makefile

Using CMake (Config mode)

Function reference

`aigw_init`

Parameters

Returns

Remarks

`aigw_start`

Parameters

Returns

Remarks

`aigw_stop`

Returns

Remarks

`aigw_identify`

Parameters

Returns

Remarks

`aigw_is_running`

Parameters

Returns

`aigw_opt_in`

Returns

Remarks

`aigw_opt_out`

Returns

Remarks

`aigw_is_opted_in`

Parameters

Returns

Remarks

`aigw_log`

Parameters

Returns

Remarks

`aigw_mute`

Returns

Remarks