Overview

Purpose

helloworld-binding is a minimal AFB Binding V4 example intended to demonstrate the core mechanisms required to implement an AFB service in a redpesk environment.

The project is deliberately small so that the binding lifecycle, API implementation and test strategy remain easy to identify in the source code.

The sample demonstrates:

• an AFB V4 API and verbs;
• request parameter conversion and typed replies;
• binding lifecycle handling with mainctl;
• event creation and publication;
• per-client context management and event subscription;
• equivalent C and C++ implementations;
• functional validation with afb-test-py and redtest integration.

Architecture

The binding exposes the helloworld API through afb-binder.

                 +----------------------+
                 |      AFB client      |
                 | afb-client / tests   |
                 +----------+-----------+
                            |
                            | AFB requests / events
                            v
                 +----------------------+
                 |      afb-binder      |
                 +----------+-----------+
                            |
                            v
                 +----------------------+
                 | helloworld-binding.so|
                 |                      |
                 | API: helloworld      |
                 | - hello              |
                 | - sum                |
                 | - info               |
                 |                      |
                 | Event: verb_called   |
                 +----------------------+

The binding itself does not depend on external hardware. It can therefore be executed on a development host, in a redpesk development environment (like using the localbuilder), or on a redpesk target (QEMU, aarch64 or x86_64 target).

Shared API contract

The service exposes:

• API helloworld;
• verb hello;
• verb sum;
• verb info;
• event helloworld/verb_called.

The C/C++, Python and Rust samples expose the same public verbs and event and keep the same essential request semantics. Language-specific implementation details are intentionally not part of the shared API contract.

The C and C++ implementations keep their native AFB/json-c conversion behavior for hello. The sum verb uses signed 64-bit wrapping semantics, matching the shared contract used by the Python and Rust samples.

The info verb is implemented explicitly from the static metadata stored in src/info_verb.json.

Binding lifecycle

The binding registers a mainctl callback. During the AFB initialization stage, this callback creates the verb_called event used by the sample.

If the event cannot be created, the initialization fails. Other lifecycle stages are accepted without additional processing.

Client context and events

The sample uses the AFB request context to keep a small per-client state indicating whether the client is already subscribed to the verb_called event.

When a client calls hello or sum for the first time, the binding:

1. creates the client context;
2. subscribes the client to verb_called;
3. pushes an event containing the name of the called verb.

Subsequent calls reuse the existing client context and subscription.

C and C++ implementations

The same API is implemented in:

• src/helloworld.c, using the AFB C API;
• src/helloworld.cpp, using the AFB C++ wrapper.

The C implementation is built by default. The C++ implementation can be selected with the CMake CPP option.

This makes the project useful as a compact reference when comparing both AFB programming interfaces.

redpesk integration

The project includes RPM packaging, an application manifest and redtest support so that the same sample can be used from local development through package deployment and validation on redpesk.

For platform-level topics such as creating a redpesk project, building applications and managing targets, refer to the redpesk developer getting started guide.

Project layout

The main project files are organized as follows:

src/                            C and C++ binding implementations
rpconfig/manifest.yml           redpesk application manifest
redtest/run-redtest             redtest entry point
redtest/tests.py                functional tests
docs/                           project documentation
helloworld-binding.spec         RPM packaging
CMakeLists.txt                  CMake build configuration