The GDP supports a limited amount of write-once per-GCL metadata.
It can be added when a GCL is created and is thenceforth immutable.
Each piece of GCL metadata consists of a name, a data length, and
(optionally) some data. Any typing information is implied by the
Names are exactly four bytes. All names with the high-order octet
set to zero are reserved for use by the system. It is recommended
that application defined names be exactly four ASCII characters, e.g.,
'ABCD' (which is equal to 0x41424344). Note that numeric constants
should be used, since the valid C constant 'ABCD' might be represented as
0x44434241 on some architectures; it is the numeric constant which defines
the name. The name that is all zeros is reserved to indicate "end of
list". [[Registration of codes is To Be Done.]]
Lengths are three bytes packed into a four byte integer, representing the
number of octets in the data. The top eight bits are reserved for
future use. They must be zero when sent and ignored on receipt.
Data is a series of opaque bytes. It might be encrypted, at the
discretion of the application.
The metadata interface is as follows:
void gdp_gclmd_free(gdp_gclmd_t *gmd);
const void *data);
const void **data);
These routines allocate and free a data structure (which will be
dynamically expanded if needed), add a new metadata field with the
indicated name, length, and value (the data will be copied), and return a
field at a given index (the data is not copied).
To create a new GCL with metadata an application should create a new data
gdp_gclmd_new, populate it using
send it as a parameter to
gdp_gcl_create, and then free the
To access metadata in an existing GCL an application needs to fetch the
This fetches the metadata into memory (if it is not already there) and
passes a metadata structure back. This structure can then be
gdp_gclmd_get. [[Who owns the
metadata, i.e., who has to do gdp_gclmd_free?]]
There are potentially three different representations for metadata:
in-memory, on-the-wire, and on-disk.
The internal representation is opaque as far as the client program is
concerned, with all interaction done by function calls in deference to
alternate language bindings. The API is described above. [[Details
To Be Done.]]
When sent over the network, all integers are sent in network byte order
(big-endian) as is standard for network protocols. The
representation for each metadatum is a four-octet integer name. If
that is zero then no more metadata fields are present and no more data is
sent. If non-zero, the name is followed by a four-octet length which
is immediately followed by that number of bytes of data. Note that
the integers are not guaranteed to be word aligned.
[[To be written — really need to document everything, not just
metadata, probably in another document.]]