Common API C++

namespace Capi

The capi component, short for Common API C++, encapsulates the autogenerated code of the Common API C++ framework generators from the relevant Franca IDL and deployment files and links the shared libraries generated from these to the client and server executable targets of the application.

Tooling, Runtimes and Libraries

The development container already has the Common API C++ generators, runtimes, libraries and dependencies available, they are located in the usr/local/capicpp folder, as shown in the folder structure below. To understand the full setup it is recommended to look at the .devcontainer/DockerFile file.

/usr/local/capicpp
├── core-runtime
├── core-tools
├── dbus-patched
├── dbus-runtime
├── dbus-tools
├── someip-runtime
├── someip-tools
└── vsomeip

The core-runtime, dbus-runtime and someip-runtime subfolders contain the Common API C++ core, D-Bus and SOME/IP runtimes and their shared libraries for linking.

The core-tools, dbus-tools and someip-tools subfolders contain the Common API C++ core, D-Bus and SOME/IP generators to generate code from the .fidl and .fdepl files.

The dbus-patched subfolder contains the compiled D-Bus library with the necessary patches from Common API C++ already applied, this one is only used for linking with shared libraries in dbus-runtime. The vsomeip folder contains the vsomeip shared libraries for the SOME/IP runtime binding.

For convenience and as shown in the snippet below, the generator tools are also available in the PATH environment variable. There are also other environments variables for relevant installation directories.

PS > commonapi-core-generator --version
Version:      3.2.15
Build id:     20240402
Architecture: 64 Bit

PS > commonapi-dbus-generator --version
Version:      3.2.15
Build id:     20240402
Architecture: 64 Bit

PS > commonapi-someip-generator --version
Version:      3.2.15
Build id:     20240402
Architecture: 64 Bit

PS > $ENV:CAPICPP_CORE_TOOLS_DIR
/usr/local/capicpp/core-tools

PS > $ENV:CAPICPP_DBUS_TOOLS_DIR
/usr/local/capicpp/dbus-tools

PS > $ENV:CAPICPP_SOMEIP_TOOLS_DIR
/usr/local/capicpp/someip-tools

PS > $ENV:CAPICPP_CORE_RUNTIME_DIR
/usr/local/capicpp/core-runtime

PS > $ENV:CAPICPP_DBUS_RUNTIME_DIR
/usr/local/capicpp/dbus-runtime

PS > $ENV:CAPICPP_SOMEIP_RUNTIME_DIR
/usr/local/capicpp/someip-runtime

PS > $ENV:CAPICPP_DBUS_DIR
/usr/local/capicpp/dbus-patched

PS > $ENV:CAPICPP_VSOMEIP_DIR
/usr/local/capicpp/vsomeip

Generation of Source Code

The folder src/third_party/capi_gen in the repository contains all the input Franca .fidl and .fdepl files needed by the Common API C++ core, D-Bus and SOME/IP generators to generate source code from in the respective gen folders. The configuration files are also kept in this folder. The detailed folder structure is shown below.

src/third_party/capi_gen
├── dbus
│   ├── commonapi-dbus.ini
│   ├── commonapi.ini
│   └── gen
│       ├── common
│       ├── proxy
│       └── stub
├── fidl
│   ├── app.dbus.fdepl
│   ├── app.fidl
│   ├── app.someip.fdepl
│   └── gen
│       ├── common
│       ├── proxy
│       ├── skel
│       └── stub
└── someip
    ├── commonapi-someip.ini
    ├── commonapi.ini
    ├── gen
    │   ├── common
    │   ├── proxy
    │   └── stub
    └── vsomeip.json

In the fidl subfolder, the files app.fidl, app.dbus.fdepl and app.someip.fdepl are the Franca language files with the interface definition and deployment details for D-Bus and SOME/IP runtime bindings. The gen folder contains the source code generated by the Common API C++ core generator, commonapi-core-generator.

In the dbus subfolder, the files commonapi.ini and commonapi-dbus.ini folder are the configuration files suitable for the D-Bus runtime binding. The gen folder contains the source code generated by the Common API C++ D-Bus generator, commonapi-dbus-generator.

In the someip subfolder, the files commonapi.ini, commonapi-someip.ini and vsomeip.json folder are the configuration files suitable for the SOME/IP runtime binding and vsomeip library. The gen folder contains the source code generated by the Common API C++ SOME/IP generator, commonapi-someip-generator.

The generation of code can be done manually, or simply by executing the following script, which already takes care of handling the directories and doing error checking.

./manage.ps1 commonapi-gen

class Runtime

Singleton that provides generic functionality related to the Common API C++ runtime for the application.

Public Functions

~Runtime(void)

Class destructor.

Utils::Error::ID get_runtime(std::shared_ptr<CommonAPI::Runtime> &ptr) const

Gets a pointer to the Common API C++ runtime.

Parameters:

ptr – [out] The pointer retrieved.

Returns:

Identifier for the error.

Utils::Error::ID set_properties(const std::map<std::string, std::string> &props) const

Sets the values of one or multiple properties.

Known properties used internally by the framework are:

  • LogApplication and LogContext to configure logging.

  • LibraryBase to configure library runtime bindings when not found via other means.

Check the source code of the runtime bindings for details on how these properties are used.

Parameters:

props – [in] Names and values for each property.

Returns:

Identifier for the error.

Utils::Error::ID get_properties(const std::vector<std::string> &names, std::map<std::string, std::string> &props) const

Gets the value of one or multiple properties.

Parameters:

  • names – [in] Names of the properties to obtain.

  • props – [out] Names and values for each property.

Returns:

Identifier for the error.

Public Static Functions

static Runtime &get_instance(void)

Retrieves the instance associated to the singleton class.

Returns:

The singleton instance.

template<typename Stub>
class ServiceBase : public Stub

Base implementation for a service, each service maps to a single Common API C++ stub.

Template Parameters:

Stub – The Common API C++ stub type this service maps to.

Subclassed by App::Server::AppService

Public Functions

inline ~ServiceBase(void) override

Class Destructor.

inline Utils::Error::ID start(void)

Starts the service in the Common API C++ runtime.

Returns:

Identifier for the error.

inline Utils::Error::ID stop(void)

Stops the service in the Common API C++ runtime.

Returns:

Identifier for the error.

Public Static Functions

template<typename Service, typename ...ServiceTArgs>
static inline std::shared_ptr<Service> make(const std::string &domain, const std::string &instance, const std::string &connection, ServiceTArgs... ServiceFArgs)

Generate a new instance of the service as a shared pointer.

Template Parameters:

  • Service – The type of service create, this is, the derived service from the base service.

  • ServiceTArgs – The type of parameters to forward to the initialization of the shared pointer.

Parameters:

  • domain – [in] Domain identifier for the service.

  • instance – [in] Instance identifier for the service.

  • connection – [in] Connection identifier for the service.

  • ServiceFArgs – [in] Service specific parameters.

Returns:

The shared pointer with the instance or nullptr on error.

Protected Functions

inline ServiceBase(const std::string &domain, const std::string &instance, const std::string &connection)

Class constructor, refer to Utils::Capi::Priv::ServiceBase::make for details on the parameters.

Protected Attributes

std::string domain

Domain identifier.

std::string instance

Instance identifier.

std::string connection

Connection identifier.

bool registered

true if service has been registered and false otherwise.

using Utils::Capi::AppServiceBase = Priv::ServiceBase<v0_1::commonapi::app::AppStubDefault>

Application service base type.

template<typename AppService>
class Server

The implementation of the server, all the services.

Template Parameters:

AppService – The application service, with the Common API C++ hooks implemented.

Public Functions

inline explicit Server(const std::shared_ptr<AppService> &app)

Class constructor.

Parameters:

app – [in] Application service instance.

inline virtual ~Server(void)

Class Destructor.

inline Utils::Error::ID start(void)

Starts the server.

Returns:

Identifier for the error.

inline Utils::Error::ID stop(void)

Stops the server.

Returns:

Identifier for the error.

Public Members

std::shared_ptr<AppService> app

Application service.

template<template<typename...> typename Proxy, typename ...AttributeExtensions>
class ClientBase

Base implementation for a client, each client maps to a single Common API C++ proxy.

Template Parameters:

  • Proxy – The Common API C++ proxy type this client maps to.

  • AttributeExtensions – Attribute extensions for Proxy, if any.

Subclassed by App::Client::AppClient

Public Functions

inline virtual ~ClientBase(void)

Class Destructor.

inline Utils::Error::ID start(void)

Starts the client.

Returns:

Identifier for the error.

inline Utils::Error::ID stop(void)

Stops the client.

Returns:

Identifier for the error.

Public Static Functions

template<typename Client, typename ...ClientTArgs>
static inline std::shared_ptr<Client> make(const std::string &domain, const std::string &instance, const std::string &connection, ClientTArgs... ClientFArgs)

Generate a new instance of the client as a shared pointer.

Template Parameters:

  • Client – The type of client create, this is, the derived client from the base client.

  • ClientTArgs – The type of parameters to forward to the initialization of the shared pointer.

Parameters:

  • domain – [in] Domain identifier for the client.

  • instance – [in] Instance identifier for the client.

  • connection – [in] Connection identifier for the client.

  • ClientFArgs – [in] Client specific parameters.

Returns:

The shared pointer with the instance or nullptr on error.

Protected Functions

inline ClientBase(const std::string &domain, const std::string &instance, const std::string &connection)

Class constructor.

Parameters:

  • domain – [in] Domain identifier for the service.

  • instance – [in] Instance identifier for the service.

  • connection – [in] Connection identifier for the service.

Protected Attributes

std::string domain

Domain identifier.

std::string instance

Instance identifier.

std::string connection

Connection identifier.

std::shared_ptr<Proxy<AttributeExtensions...>> proxy

Proxy instance.

using Utils::Capi::AppClientBase = Priv::ClientBase<v0_1::commonapi::app::AppProxy>

Application client base type.

template<typename AppClient>
class Client

The implementation of all the clients.

Template Parameters:

AppClient – The application client, with the Common API C++ hooks implemented.

Public Functions

inline explicit Client(const std::shared_ptr<AppClient> &app)

Class constructor.

Parameters:

app – [in] Application client instance.

inline virtual ~Client(void)

Class Destructor.

inline Utils::Error::ID start(void)

Starts the client.

Returns:

Identifier for the error.

inline Utils::Error::ID stop(void)

Stops the client.

Returns:

Identifier for the error.

Public Members

std::shared_ptr<AppClient> app

Application client.