Creating a Participant
A participant is a process that publishes and subscribes on a messaging environment (ME), and simply drops every message it does not understand. This page builds one from nothing, one step at a time. Each step first explains what is being done in terms that do not depend on an operating system or a programming language, then shows exactly how it was done in a participant that exists: tx-identity-broker, written in C++ for Windows.
Start a Project
Choose a Language
Any language will do, as long as it can reach the ME the participant is going to join; e.g., if that ME is an MQTT broker, the language needs an MQTT client. IPSME is a set of conventions, not a framework or a standard: it dictates no language, no library and no wire format, and the other participants on the ME never learn what a participant is written in. Libraries that implement the conventions do already exist for several languages; see IPSME for what is available before writing your own.
Create an Initial Project
Start with the smallest thing that can grow into a participant: a program that starts, states its name and version, and keeps running until it is told to quit. The last part matters. A participant only hears messages while it is subscribed, so it is a long-running process from the first version on, not a script that runs and exits.
Lay the project out so that portable code and OS-specific code are kept apart. Everything that will speak protocols is portable and should stay that way. What touches the operating system (here: a clean quit when the console is interrupted or closed) goes in a folder of its own, named after the OS. Files that belong to one build toolchain also get a folder of their own.
Version Control
Put the project under version control from the first file. Ignore what the build produces, what the IDE keeps for itself and what the OS litters. Track the files that define the project, including the build-toolchain files.
Implementation: C++ on Windows
Toolchain: Visual Studio with the v143 platform toolset, C++20, x64. The repository is tx-identity-broker.git; after this step it holds:
tx-identity-broker.git/
|-- .gitignore
|-- msvc/ (1)
| |-- tx-identity-broker.sln
| |-- tx-identity-broker.vcxproj
| |-- tx-identity-broker.vcxproj.filters
| `-- tx-identity-broker.rc (2)
`-- src/
|-- main.cpp (3)
|-- version.h (4)
`-- os_win32/ (5)
|-- Console.h
`-- Console.cpp
| 1 | Visual Studio solution and project. These four files are tracked; the build output next to them (x64/, .vs/, *.user) is ignored. |
| 2 | Resource script; stamps the version onto the executable. |
| 3 | Entrypoint: prints the name and version, then loops until the quit flag is set. |
| 4 | The one place the version is defined; main.cpp and the resource script both read it. |
| 5 | Windows-only. Routes Ctrl+C, Ctrl+Break and the console close to the quit flag through SetConsoleCtrlHandler; the portable signal(SIGINT) would see Ctrl+C alone. |
The version, in one place
src/version.h defines the four version numbers once. The helper macros turn them into the two forms the resource compiler wants, a comma list and a string:
#pragma once
#define VERSION_MAJOR 0
#define VERSION_MINOR 0
#define VERSION_PATCH 1
#define VERSION_BUILD 0
#define VERSION_SUFFIX ""
#define _TOSTR(x) #x
#define TOSTR(x) _TOSTR(x)
#define VER_FILE_VERSION VERSION_MAJOR, VERSION_MINOR, VERSION_PATCH, VERSION_BUILD
#define VER_FILE_VERSION_STR \
TOSTR(VERSION_MAJOR) "." TOSTR(VERSION_MINOR) "." TOSTR(VERSION_PATCH) "-" TOSTR(VERSION_BUILD) VERSION_SUFFIX "\0"
#define VER_PRODUCT_VERSION VER_FILE_VERSION
#define VER_PRODUCT_VERSION_STR VER_FILE_VERSION_STR
msvc/tx-identity-broker.rc includes <windows.h> and "version.h" and holds one VS_VERSION_INFO VERSIONINFO block whose FILEVERSION / PRODUCTVERSION are VER_FILE_VERSION / VER_PRODUCT_VERSION and whose StringFileInfo strings (FileVersion, ProductVersion) are the _STR forms. The file is UTF-8, so it starts with #pragma code_page(65001); without it the copyright sign in LegalCopyright is read in the ANSI code page.
The Windows-only quit handler
src/os_win32/Console.h:
#ifndef OS_WIN32_CONSOLE_H
#define OS_WIN32_CONSOLE_H
#include <atomic>
namespace Console {
// Routes Ctrl+C, Ctrl+Break, console close, logoff and shutdown to b_quit.
bool install_quit_handler(std::atomic<bool>& b_quit);
// main() calls this last. For close/logoff/shutdown the system ends the process the moment the
// handler returns, so the handler waits for this before it does.
void quit_done();
}
#endif // OS_WIN32_CONSOLE_H
src/os_win32/Console.cpp. The handler runs on a thread the system creates, so it only touches an atomic and an event:
#include "Console.h"
#include <windows.h>
static constexpr DWORD kdw_DONE_WAIT_MSEC_ = 4000; // the system allows ~5 s on CTRL_CLOSE_EVENT
static std::atomic<bool>* gp_b_quit_ = nullptr;
static HANDLE gh_done_ = nullptr; // manual-reset event: main() has finished
static BOOL WINAPI _handler_ctrl(DWORD dw_ctrl_type)
{
if (! gp_b_quit_)
return FALSE;
gp_b_quit_->store(true);
switch (dw_ctrl_type) {
case CTRL_C_EVENT:
case CTRL_BREAK_EVENT:
return TRUE; // the process keeps running; main() leaves its loop
default: // CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT, CTRL_SHUTDOWN_EVENT: terminated on return
WaitForSingleObject(gh_done_, kdw_DONE_WAIT_MSEC_);
return TRUE;
}
}
bool Console::install_quit_handler(std::atomic<bool>& b_quit)
{
gh_done_ = CreateEventW(nullptr, TRUE, FALSE, nullptr);
if (! gh_done_)
return false;
gp_b_quit_ = &b_quit;
return SetConsoleCtrlHandler(_handler_ctrl, TRUE) != 0;
}
void Console::quit_done()
{
if (gh_done_)
SetEvent(gh_done_);
}
The entrypoint
src/main.cpp at the end of this step. The participant name is the one it will later carry on every message, so it is spelled as the scoped package name from the start:
#include <atomic>
#include <chrono>
#include <iostream>
#include <thread>
using namespace std::chrono_literals;
#include "version.h"
#include "os_win32/Console.h" // Windows-only: Ctrl+C / Ctrl+Break / console close -> gb_quit_
static constexpr const char* kpsz_PARTICIPANT_ = "@rootintf/tx-identity-broker";
static std::atomic<bool> gb_quit_{ false };
int main()
{
std::cout << kpsz_PARTICIPANT_ << " " << VER_FILE_VERSION_STR << std::endl;
if (! Console::install_quit_handler(gb_quit_)) {
std::cerr << "install_quit_handler failed" << std::endl;
return 1;
}
while (! gb_quit_)
std::this_thread::sleep_for(100ms);
std::cout << "quit" << std::endl;
Console::quit_done();
return 0;
}
The Visual Studio project
The project is a console application. Settings that are not the wizard’s defaults:
| Setting | Value |
|---|---|
Configurations |
`Debug |
x64`, `Release |
x64` |
Platform toolset / standard |
|
Additional include directories |
|
Subsystem |
Console |
Output / intermediate dir |
|
Sources |
|
Settings shared by both configurations live in one unconditioned property group and one item-definition group; only the Debug/Release differences are conditioned on $(Configuration).
Ignores
.gitignore:
## Visual Studio specific files
.vs/
*.suo
*.user
*.userosscache
*.sln.docstates
*.aps
## Build results
x64/
x86/
[Dd]ebug/
[Rr]elease/
*.exe
*.obj
*.pdb
*.ilk
## Windows build output (msvc/): explicit; the generic rules above also match, these state intent.
## Tracked in msvc/: tx-identity-broker.sln, .vcxproj, .vcxproj.filters, tx-identity-broker.rc.
/msvc/x64/
/msvc/Win32/
/msvc/.vs/
/msvc/*.user
## OS files
Thumbs.db
.DS_Store
Connecting to an ME
Pick an IPSME Implementation
The ME is whatever pubsub is readily available where the participant runs, and an implementation of the IPSME side of it (subscribe, publish, deliver) already exists for the common ones: NSDistributedNotificationCenter on macOS, BroadcastChannel in a web browser, D-Bus on Linux and an MQTT broker on Windows. They are the -msgenv- repositories under github.com/IPSME, one per language and ME; ipsme.dev lists them. Pick the one for the ME and the language chosen in the previous step.
Which ME a participant joins is the author’s decision, and nothing else’s. The operating system does not imply it: a participant may just as well join a private ME of its own and reach the platform’s ME through a reflector pair. For that reason the choice is written by hand, in exactly one place, and never derived by a tool.
Each ME also has a pub-<MsgEnv> tool: a command-line participant that publishes one string and prints every message it hears on that ME. Use it to check that the ME is up, to watch what the participants on it are saying, and to see that the messages this participant pushes actually reach the ME. There is one per ME; see pub-<MsgEnv>.
One Bridge, One Responder per Protocol
Hook the ME into the main process through a single bridge. The bridge owns the one subscription to the ME, the participant’s identity, and the chain that every incoming message goes through: decode the delivered unit once, validate the base that all your protocols share, then offer the message to one responder per protocol, most specific reading first. A responder owns everything about its protocol: it validates each message against that protocol’s own definition, handles the ones addressed to this participant, and publishes the messages this participant can send in that protocol. Whatever nobody takes is dropped, silently; that is interest management, the designed behaviour, not an error.
The bridge is constructed exactly once per participant. It subscribes, builds its responders, and may announce (next section). The application reaches the ME only through the responders, and the responders reach the application through a small interface of callbacks the application implements. Nothing above the bridge knows which ME it is running on; swapping the ME means changing the bridge’s one include or import.
Interfaces Generated from Schemas
The messages of one protocol are described once, in a schema: one definition per message, each annotated with the base it extends. The schema file is published byte-exact under its SHA-256, and that hash is the protocol’s identity; two participants speak the same dialect when their hashes match. A project lists the schemas it speaks in a config, each pinned by its hash, and a generator verifies the bytes against the pin and emits, per schema, a typed interface: for every message a validate that checks only the message’s own fields (the base was validated once, upstream in the chain) and a constructor that produces a well-formed message. It also emits an introspection table, interface name to hash, which is exactly what the participant declares about itself on the ME. The whole mechanism is described at Interface Gen.
The same config can generate the participant scaffold: the bridge, one responder per protocol, the application interface and the entrypoint. The scaffold is yours to fill in and is regenerated through a three-way merge, so a later schema change or template change folds into your edits instead of overwriting them. When a schema changes, its hash changes; the pin is updated and everything is regenerated. Nothing per protocol is written by hand.
The Announce
Discovery is a convention about when participants speak up, so they find each other with no registry. Its first half: every participant announces when it comes online. As soon as it is subscribed it publishes an announce saying who it is and what it offers. Who is the sender identity the base of every message already carries: the participant kind and the running instance. What is the list of interfaces it speaks, as name to hash, straight from the introspection table. The announce answers nobody, so its cause is empty. Anyone listening who cares about one of the listed names reacts; everyone else drops it. The hash travels as information: a listener never refuses a speaker because the pin differs, since a dialect you do not speak is what translators are for.
Expect to hear your own messages come back. An ME broadcasts to every subscriber, the publisher included, so the first message the new participant receives is normally its own announce. A handler that is correct for a stranger’s message is correct for the echo; where re-processing would matter, drop your own by the instance in the sender identity, never by the kind.
Implementation: C++ on Windows
The ME is MQTT: an Eclipse Mosquitto broker on localhost:1883, topic IPSME, through cpp-msgenv-MQTT. Prerequisites on the machine: the Mosquitto installer (service running, SDK under C:\Program Files\mosquitto\devel) and vcpkg with nlohmann-json and json-schema-validator installed for x64-windows.
Dependencies as submodules
Four repositories, added as git submodules under src/. They are source, compiled into the participant, and they refer to each other by relative ../<name>.git/ includes, so they must be siblings in one folder, and that folder is the include root.
| Submodule | What it is | Remote |
|---|---|---|
|
The interface generator, and |
|
|
The ME: |
|
|
The base message classes |
|
|
The event log interface the bridge and responders are written against, and an in-memory implementation |
|
git submodule add --name cpp-iface-gen.git git@gitlab.com:interop-protocols/cpp-iface-gen.git src/cpp-iface-gen.git
git submodule add --name cpp-msgenv-MQTT.git git@github.com:IPSME/cpp-msgenv-MQTT.git src/cpp-msgenv-MQTT.git
git submodule add --name cpp-json-msg.git git@gitlab.com:interop-protocols/cpp-json-msg.git src/cpp-json-msg.git
git submodule add --name cpp-EventLog.git git@github.com:IPSME/cpp-EventLog.git src/cpp-EventLog.git
A helper the ME expects
cpp-msgenv-MQTT includes "../g_.hpp" for a DebugPrint, so src/g_.hpp has to exist. It also carries CLASS_NAME, used by the bridge’s publish trace:
#ifndef G__HPP
#define G__HPP
#include <cstdarg>
#include <cstdio>
#include <string>
#include <typeinfo>
#ifdef _WIN32
#include <windows.h>
#endif
// printf-style trace to the debugger (Windows) or stderr (elsewhere)
inline void DebugPrint(const char* psz_format, ...)
{
char ach_buffer[1024];
va_list args;
va_start(args, psz_format);
#ifdef _WIN32
vsnprintf_s(ach_buffer, sizeof(ach_buffer), _TRUNCATE, psz_format, args);
OutputDebugStringA(ach_buffer);
#else
vsnprintf(ach_buffer, sizeof(ach_buffer), psz_format, args);
fputs(ach_buffer, stderr);
#endif
va_end(args);
}
// typeid(...).name() without MSVC's "class " / "struct " prefix
inline std::string demangle(const char* psz_name)
{
std::string str_result = psz_name;
if (str_result.rfind("class ", 0) == 0)
str_result.erase(0, 6);
else if (str_result.rfind("struct ", 0) == 0)
str_result.erase(0, 7);
return str_result;
}
#define CLASS_NAME(var) demangle(typeid(var).name())
#endif // G__HPP
The generator config
ifacegenconfig.json at the repository root. Two schemas: Discovery (the announce and the discover) and Interfaces (the definition of the interfaces map an announce carries). The sha256 of each is the hash shown on its schema page, or sha256sum of the file. The target writes under src/; the schema cache goes next to the config:
{
"schemas": {
"Discovery": { "src": "~/protocols.git/schemas.readonly/schema_Discovery.json", "sha256": "6ddb1ff4885d6f0b427ad39e37200508a3064533d37fa6ec463270e65c85b749" },
"Interfaces": { "src": "~/protocols.git/schemas.readonly/schema_Discovery_objs/schema_Interfaces.json", "sha256": "406727b9b60d79ad00474fcf2affba6aeed7c734abd5f6ebf2542cc173d00f10" }
},
"targets": [
{
"root": "src",
"IPSME": {
"main": "main.cpp",
"object": "App",
"runtime": "native",
"shape": "flat",
"out": "IPSME"
},
"schema-cache": "../schemas",
"out-cpp": "generated",
"prefix": "interface-",
"namespace": "iface_gen",
"msgenv-include": "cpp-msgenv-MQTT.git/IPSME_MsgEnv.h",
"delete": true,
"schemas": [ "Discovery", "Interfaces" ]
}
],
"version": 4
}
msgenv-include is the one hand-written line that selects the ME. The generator copies it verbatim into the scaffold and never derives it.
Build and run the generator
The generator is C++ and is built once, inside its submodule, with the vcpkg toolchain:
cd src/cpp-iface-gen.git
cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=C:/Users/dev/vcpkg.git/scripts/buildsystems/vcpkg.cmake
cmake --build build --config Release
cd ../..
main.cpp from the previous step already exists, and the generator refuses to adopt a file it did not create. Move it aside first, generate, then bring its content back into the generated skeleton:
mv src/main.cpp /tmp/main.step1.cpp
./src/cpp-iface-gen.git/build/Release/iface-gen.exe --config ifacegenconfig.json
The run reports [created] for four scaffold files and writes:
ifacegen-base/src/... the pristine copies the next run merges against; commit them
schemas/<sha256>.json the verified schema bytes, one file per pin
src/generated/interface-Discovery.h iface_gen::Discovery::JSON_MsgDiscover, JSON_EffAnnounce
src/generated/interface-Interfaces.h iface_gen::Interfaces::Interfaces
src/generated/interface-introspection.h iface_gen::introspection::to_json(): { "Discovery": "6ddb...", "Interfaces": "4067..." }
src/Interface_App.hpp the app interface the responders call back into; holds the referer
src/IPSME/IPSME_Bridge.hpp the singleton bridge: subscription, chain, drive loop
src/IPSME/Responder_Discovery.hpp one stub handler per Discovery message, plus the base dispatch
src/main.cpp a stubbed entrypoint
The generator writes LF line endings and normalizes its merge inputs to LF, so the four scaffold files are kept LF. generated/ and schemas/ get a .gitattributes with * text eol=lf from the generator itself.
Fill in the scaffold
Three files are edited; Interface_App.hpp stays as generated, since the responders need no callbacks yet.
src/main.cpp. The step-1 program, with the app, the event log and the bridge added. The instance half of the identity is a fresh UUID per run:
#include <atomic>
#include <chrono>
#include <iostream>
#include <thread>
using namespace std::chrono_literals;
#include "version.h"
#include "os_win32/Console.h"
#include "Interface_App.hpp"
#include "IPSME/IPSME_Bridge.hpp"
#include "cpp-EventLog.git/InMemory_EventLog.h" // a concrete IEventLog for the bridge
static constexpr const char* kpsz_PARTICIPANT_ = "@rootintf/tx-identity-broker";
static std::atomic<bool> gb_quit_{ false };
// the concrete Interface_App: the callbacks the responders invoke on the app (none yet)
class App : public Interface_App {
public:
App(const JSON::JSON_Msg::Referer& referer) : Interface_App(referer) {}
};
int main(int /*argc*/, char** /*argv*/)
{
std::cout << kpsz_PARTICIPANT_ << " " << VER_FILE_VERSION_STR << std::endl;
if (! Console::install_quit_handler(gb_quit_)) {
std::cerr << "install_quit_handler failed" << std::endl;
return 1;
}
// WHO this is, on every message it sends: the participant kind (its package name) + this running instance
JSON::JSON_Msg::Referer referer(kpsz_PARTICIPANT_, JSON::gen_uuid());
App app(referer);
InMemoryMsg eventLog;
auto bridge = IPSME_Bridge::get_instance(&app, &eventLog); // subscribes to the ME, then announces
// drive loop: pump the bridge
while (! gb_quit_) {
std::this_thread::sleep_for(100ms);
bridge->process_msgs();
}
std::cout << "quit" << std::endl;
Console::quit_done();
return 0;
}
src/IPSME/IPSME_Bridge.hpp, two additions. A PUBLISH macro, placed after the generated includes of the ME and the base classes and before the responder includes, so every responder can use it:
#include "../g_.hpp" // CLASS_NAME
// stamp WHO (this participant's referer) on an outgoing message, then publish it on the ME. Used by the responders.
#define PUBLISH(msg_obj) \
do { \
msg_obj.referer(_referer.PARTICIPANT, _referer.INSTANCE); \
std::string str_msg = msg_obj.to_string(); \
printf("%s: publish(%s): [%s]\n", __func__, \
CLASS_NAME(msg_obj).c_str(), str_msg.c_str()); \
_kp_IPSME->publish(str_msg.c_str()); \
} while (0)
And the boot announce, in the bridge constructor right after the generated subscribe and its assert(b_ret):
// BOOT: subscribed, so say who we are and what we speak (an uncaused announce; see Responder_Discovery)
_responder_Discovery->announce();
src/IPSME/Responder_Discovery.hpp. Add #include <cassert>, include the two other generated headers next to interface-Discovery.h, add the using for the loosely bound part, and replace the generated // publish_ … placeholder with the operation:
#include "../generated/interface-Interfaces.h"
#include "../generated/interface-introspection.h"
using Interfaces = iface_gen::Interfaces::Interfaces;
// -----------------------------------------------------
// operations: what this participant can DO in this protocol
// BOOT declaration: an UNCAUSED announce, published right after the bridge subscribed. The envelope says WHO
// (referer); the body says WHAT this participant speaks: its interfaces, name -> schema pin, straight from the
// generated introspection table. Listeners react to the names; the pin is information, never a reason to refuse.
void announce()
{
nlohmann::json json_announce = { { "interfaces", iface_gen::introspection::to_json() } };
assert(Interfaces::validate(json_announce)); // the loosely bound part, on its own definition
JSON_EffAnnounce json_effAnnounce = JSON_EffAnnounce::create_with_cause_merge(nullptr, json_announce);
assert(JSON_EffAnnounce::validate(json_effAnnounce));
PUBLISH(json_effAnnounce);
}
The generated handler stubs stay as they are for now. They print the message they were offered and return false, so the chain goes on to drop it.
Project settings
Added to the Visual Studio project from the previous step:
| Setting | Value |
|---|---|
Compiled sources |
plus |
Additional include directories |
|
Additional library directories |
|
Additional dependencies |
|
Preprocessor definitions |
plus |
Post-build event |
|
where the project defines, with fallbacks so a plain build works without vcpkg’s user-wide integration:
<MosquittoDir Condition="'$(MosquittoDir)'==''">C:\Program Files\mosquitto</MosquittoDir>
<VcpkgRoot Condition="'$(VcpkgRoot)'==''">C:\Users\dev\vcpkg.git\</VcpkgRoot>
<VcpkgTriplet Condition="'$(VcpkgTriplet)'==''">x64-windows</VcpkgTriplet>
<VcpkgTripletDir>$([MSBuild]::EnsureTrailingSlash('$(VcpkgRoot)'))installed\$(VcpkgTriplet)\</VcpkgTripletDir>
<!-- Debug links/copies vcpkg's debug\ flavour of the libraries (the CRT and iterator debug level must match) -->
<VcpkgTripletCfgDir Condition="'$(Configuration)'=='Debug'">$(VcpkgTripletDir)debug\</VcpkgTripletCfgDir>
<VcpkgTripletCfgDir Condition="'$(Configuration)'!='Debug'">$(VcpkgTripletDir)</VcpkgTripletCfgDir>
Build and verify
Build as before. To see the announce reach the ME, start a listener before the participant, in a second shell. The IPSME way is pub-MQTT, the pub-<MsgEnv> tool for this ME. It publishes its string, which the participant drops as not JSON, and keeps printing everything it hears:
pub-MQTT 1 hello
Mosquitto’s own client does the same one level down, on the topic:
mosquitto_sub -h localhost -t IPSME -C 1 -v
./msvc/x64/Release/tx-identity-broker.exe
The participant prints its banner, then its publish trace. Either listener prints the message, which is the one below, pretty-printed; id, dt and the instance half of referer differ on every run:
{
"id": "e7e591d9-a56a-409c-8650-a777999cbc5b",
"referer": [ "@rootintf/tx-identity-broker", "2e1212ca-132f-444f-a476-6234ca9f636e" ],
"dt": "2026-11-18T12:12:00Z",
"_cause": null,
"announce": {
"interfaces": {
"Discovery": "6ddb1ff4885d6f0b427ad39e37200508a3064533d37fa6ec463270e65c85b749",
"Interfaces": "406727b9b60d79ad00474fcf2affba6aeed7c734abd5f6ebf2542cc173d00f10"
}
},
"Discovery": "5"
}
Publishing a message at the running participant shows the receive side; mosquitto_pub below does it, as does pub-MQTT 0 with the same string. A string that is not JSON is dropped without a word. A well-formed discover, for example, reaches the stub and is printed by _handler_msgDiscover:
mosquitto_pub -h localhost -t IPSME -m '{"id":"11111111-1111-4111-8111-111111111111","referer":["@rootintf/test","t-1"],"dt":"2026-11-18T12:00:00Z","discover":{"ttl_msec":3000},"Discovery":"5"}'
One observation about the echo. An outside subscriber receives the announce at once, but the participant’s own copy arrives late: in runs of four seconds it had not come back yet, in runs of five seconds and longer it always had. Anything published afterwards, by this participant or by others, is delivered without that delay. The cause lies in how this ME brings up its two MQTT connections and has not been traced further. Keep it in mind when a handler for the boot announce seems silent during the first seconds.