GDP GCL Metadata

Eric Allman, Ubiquitous Swarm Lab, U.C. Berkeley
Draft Document Version 0.10, 2015-01-23

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 name.

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.

Sending and Accessing Metadata

The metadata interface is as follows:

    gdp_gclmd_t     *gdp_gclmd_new(void);

    void            gdp_gclmd_free(gdp_gclmd_t *gmd);

    EP_STAT         gdp_gclmd_add(gdp_gclmd_t *gmd,
                            gdp_gclmd_id_t id,
                            size_t len,
                            const void *data);

    EP_STAT         gdp_gclmd_get(gdp_gclmd_t *gmd,
                            int index,
                            gdpd_gclmd_id_t *id,
                            size_t *len,
                            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 structure using gdp_gclmd_new, populate it using gdp_gclmd_add, send it as a parameter to gdp_gcl_create, and then free the metadata using gdp_gclmd_free.

To access metadata in an existing GCL an application needs to fetch the metadata:

    EP_STAT         gdp_gcl_getmetadata(gdp_gcl_t *gcl,
                            gdp_gclmd_t **gmdp);

This fetches the metadata into memory (if it is not already there) and passes a metadata structure back.  This structure can then be interrogated using gdp_gclmd_get[[Who owns the metadata, i.e., who has to do gdp_gclmd_free?]]

Representation

There are potentially three different representations for metadata: in-memory, on-the-wire, and on-disk.

In-Memory

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.]]

On-The-Wire

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.

On Disk

[[To be written — really need to document everything, not just metadata, probably in another document.]]