cloudevents.h File Reference

The CloudEvents envelope: the structured-mode JSON build and the binary-mode header read. More...

#include "protocore_config.h"

Go to the source code of this file.

Detailed Description

The CloudEvents envelope: the structured-mode JSON build and the binary-mode header read.

CloudEvents is a CNCF specification, not an IETF one. Everything here follows CloudEvents Version 1.0.2 and its two companion documents: the JSON Event Format for CloudEvents Version 1.0.2 and the HTTP Protocol Binding for CloudEvents Version 1.0.2.

The core specification, section "Context Attributes", splits the attributes an event carries into "REQUIRED Attributes" - id, source, specversion, type - and "OPTIONAL Attributes" - datacontenttype, dataschema, subject, time. Section "Event Data" gives the payload, which "will be encapsulated within `data`". specversion is written for the caller: the section by that name states a producer "MUST use a value of `1.0` when referring to this version of the specification", so every envelope built here carries ::PROTOCORE_CLOUDEVENTS_SPECVERSION.

The HTTP Protocol Binding sec 1.3 names the content modes, and this module covers two of the three:

• Structured Content Mode (sec 3.2): the whole event is one JSON object in the message body, and sec 3.2.1 requires the Content-Type to be the event format's media type, which the JSON Event Format sec 3 fixes at ::PROTOCORE_CLOUDEVENTS_MEDIA_TYPE. CloudEventsNs::build_structured writes that object into a caller buffer.
• Binary Content Mode (sec 3.1): sec 3.1.3.1 maps every context attribute to an HTTP header "with the same name as the attribute name but prefixed with `ce-`", sec 3.1.1 carries datacontenttype in Content-Type instead, and sec 3.1.2 makes the message body the data byte-sequence. CloudEventsNs::read_binary takes an inbound message's attributes off those headers.

Batched Content Mode (sec 3.3) and its application/cloudevents-batch+json media type are not built here.

Emitting a binary-mode event from a handler is the response headers plus the body, so no call covers it: add ce-id, ce-source, ce-type and ce-specversion, and write the data as the body.

Every string is referenced, never copied, so what a caller sets has to outlive the call that reads it.

The module exports one symbol, CloudEvents. Everything in cloudevents.c has internal linkage.

Author

Douglas Quigg (dstroy0)

Date

2026

Definition in file cloudevents.h.