C peer messages
Installation · Integration · Sockets · Messages · Provider · Embed
This local Device example discovers real-time peers and exchanges text over subprotocol 4096 using the shared URMS v1 TEXT/ACK format. Its files are main.c, runtime.c, codec.h and Makefile; the Device bootstrap is described in Integration.
Build and check
Use C11 and a native SDK with peer/subprotocol APIs. The defaults use .. and .. from this directory. Build the adjacent SDK first, or override the two paths as shown below. Run from c/messages:
make self-test
make
./messages-example --self-test
./messages-example --version--self-test checks the golden vectors and malformed-frame rejection without client credentials or live networking. --version reports the SDK version; bindings with native runtime assets also check that they load. Dependency/build steps may download packages.
For an installed native package, supply its include and library directories:
make SDK_ INCLUDE= /absolute/ path/ to/ include SDK_ LIBDIR= /absolute/ path/ to/ libThe CMake build uses the package's urnetwork:: target:
cmake -S . -B build -DCMAKE_ PREFIX_ PATH= /absolute/ path/ to/ sdk-prefix
cmake --build build
./build/messages-example --self-testThe native runtime has POSIX and Windows branches; this example was validated on macOS arm64. On Windows, use the executable/configuration path produced by CMake. C's make self-test checks the shared codec without loading the SDK.
Live two-terminal demo
Provision two distinct top-level clients in the same network through your authenticated backend. Terminal A and terminal B need different scoped JWTs with different client_id claims and different persisted instance UUIDs. Only the backend holds the root JWT; Integration includes the executable allocator.
In terminal A, from this directory, export client A's values and start the receiver:
export URNETWORK_ CLIENT_ JWT= 'scoped-client-jwt-from-your-service'
export URNETWORK_ INSTANCE_ ID= 'persisted-installation-uuid'
./messages-example self
./messages-example peers
./messages-example watchself prints this client's ID and exits. peers prints the current peer snapshot; watch remains running, refreshes on SDK peer notifications, and receives TEXT/returns ACK. Peer output includes SDK metadata, disconnected count and the SDK-derived client color. Start terminal B with its own URNETWORK_ and URNETWORK_, then use A's discovered client ID:
export URNETWORK_ PEER_ CLIENT_ ID= 'client-id-discovered-in-terminal-a'
./messages-example send $URNETWORK_PEER_CLIENT_ID hiThe sender queries the selected peer's supported subprotocols before sending and requires 4096. A failed query, enqueue failure or ACK timeout is reported as a failure. A matching application ACK means the receiver parsed and accepted the TEXT; correlation uses (source client ID, message ID). Use the discovered client ID as the destination, not an instance UUID or display name. For text containing spaces, keep the message in one quoted argument (or inside the quoted Maven/Gradle argument string).
Incoming bytes and retained source identity are copied before the native callback returns; queued work parses frames and sends ACKs outside that callback. Keep subscriptions and Device owners alive through shutdown. Some FFI bridges keep a small callback root until process exit because native close can race a late callback. The protocol defines exact validation, UTF-8 limits, golden bytes and timeout semantics.
Custom protobuf messages
Your own protocol runs on its own subprotocol ID beside URMS; Subprotocols covers choosing the ID, the peer query, receive lifetime, versioning and acknowledgements. The C calls are the ones runtime.c already makes: urnet_, urnet_, urnet_, urnet_ with urnet_, and urnet_. urnet_ returns the counters as JSON, and urnet_ one ID's count.
This sketch carries notes.proto on subprotocol 4097 with protobuf-c. Generate notes.pb-c.c and notes.pb-c.h with protoc -I .., with protobuf-c's protoc-gen-c plugin on the PATH (the older protoc-c command is deprecated), then compile notes.pb-c.c and link libprotobuf-c:
#include "codec.h" /* urms_utf8 */
#include "notes.pb-c.h"
#include "urnetwork_sdk.h"
enum { NOTES_SUBPROTOCOL = 4097, NOTES_MAX_MESSAGE = 4608 };
static bool send_note(uint64_t device, const char *destination, uint64_t id,
char *text) {
Notes__V1__Note note = NOTES__V1__NOTE__INIT;
Notes__V1__Envelope envelope = NOTES__ V1__ ENVELOPE__ INIT;
uint8_t bytes[NOTES_ MAX_ MESSAGE];
size_t n = strlen(text);
if (!id || n > 4096 || !urms_utf8((const uint8_t *)text, n))
return false;
note.message_id = id;
note.text = text;
envelope.kind_case = NOTES__ V1__ ENVELOPE__ KIND_ NOTE;
envelope.note = ¬e;
if (notes__ v1__ envelope__ get_ packed_ size(& envelope) > sizeof bytes)
return false;
n = notes__ v1__ envelope__ pack(& envelope, bytes);
return urnet_ device_ local_ send_ subprotocol_ bytes(
device, NOTES_SUBPROTOCOL, destination, bytes, (int32_t)n);
}
/* On the worker. The urnet_subprotocol_cb refused more than
* NOTES_MAX_MESSAGE bytes and copied source and bytes before returning. */
static void receive_note(uint64_t device, const char *source,
const uint8_t *bytes, size_t n) {
Notes__V1__Envelope *envelope = notes__ v1__ envelope__ unpack(NULL, n, bytes);
if (!envelope)
return; /* malformed: drop and count, never acknowledge */
if (envelope->kind_case == NOTES__ V1__ ENVELOPE__ KIND_ NOTE) {
const Notes__V1__Note *note = envelope->note;
size_t length = strlen(note->text);
/* protobuf-c ends text at its first NUL and does not check UTF-8; a
* repack of the received size shows that nothing was cut off */
if (note->message_id && length <= 4096 &&
urms_utf8((const uint8_t *)note->text, length) &&
notes__ v1__ envelope__ get_ packed_ size(envelope) == n) {
Notes__V1__Ack ack = NOTES__ V1__ ACK__ INIT;
Notes__V1__Envelope reply = NOTES__ V1__ ENVELOPE__ INIT;
uint8_t out[32];
ack.message_id = note->message_id;
reply.kind_case = NOTES__ V1__ ENVELOPE__ KIND_ ACK;
reply.ack = &ack;
urnet_ device_ local_ send_ subprotocol_ bytes(
device, NOTES_ SUBPROTOCOL, source, out,
(int32_ t)notes__ v1__ envelope__ pack(& reply, out));
}
} else if (envelope->kind_case == NOTES__ V1__ ENVELOPE__ KIND_ ACK) {
/* match an outstanding note on (source, envelope->ack->message_ id) */
} /* any other kind_case: no kind this version knows, so drop it */
notes__ v1__ envelope__ free_ unpacked(envelope, NULL);
}Register with urnet_ and keep the subscription handle. Like message in runtime.c, on_note refuses other IDs and oversized messages, copies the bytes and the source string into a queued event, and returns; receive_note runs on the worker. notes__ returns NULL for bytes that are not an Envelope, and every result it returns is freed with notes__.