Project

General

Profile

Statistics
| Branch: | Tag: | Revision:

gdp / doc / developer / gdp-gob-metadata.html @ master

History | View | Annotate | Download (6.05 KB)

1 
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 
<html>
3 
  <head>
4 
    <meta content="text/html; charset=UTF-8" http-equiv="content-type">
5 
    <title>GDP GCL Metadata</title>
6 
  </head>
7 
  <body>
8 
    <h1>GDP GCL Metadata</h1>
9 
    <h4>Eric Allman, Ubiquitous Swarm Lab, U.C. Berkeley<br>
10 
      Draft Document Version 0.10, 2015-01-23<br>
11 
    </h4>
12 
    <p>The GDP supports a limited amount of write-once per-GCL metadata.&nbsp;
13 
      It can be added when a GCL is created and is thenceforth immutable.<br>
14 
    </p>
15 
    <p>Each piece of GCL metadata consists of a name, a data length, and
16 
      (optionally) some data.&nbsp; Any typing information is implied by the
17 
      name.<br>
18 
    </p>
19 
    <p>Names are exactly four bytes.&nbsp; All names with the high-order octet
20 
      set to zero are reserved for use by the system.&nbsp; It is recommended
21 
      that application defined names be exactly four ASCII characters, e.g.,
22 
      'ABCD' (which is equal to 0x41424344).&nbsp; Note that numeric constants
23 
      should be used, since the valid C constant 'ABCD' might be represented as
24 
      0x44434241 on some architectures; it is the numeric constant which defines
25 
      the name.&nbsp; The name that is all zeros is reserved to indicate "end of
26 
      list".&nbsp; <i>[[Registration of codes is To Be Done.]]</i><br>
27 
    </p>
28 
    <p>Lengths are three bytes packed into a four byte integer, representing the
29 
      number of octets in the data.&nbsp; The top eight bits are reserved for
30 
      future use.&nbsp; They must be zero when sent and ignored on receipt.<br>
31 
    </p>
32 
    <p>Data is a series of opaque bytes.&nbsp; It might be encrypted, at the
33 
      discretion of the application.<br>
34 
    </p>
35 
    <h2>Sending and Accessing Metadata</h2>
36 
    <p>The metadata interface is as follows:<br>
37 
    </p>
38 
    <p><samp>&nbsp;&nbsp;&nbsp; gdp_gclmd_t&nbsp;&nbsp;&nbsp;&nbsp;
39 
        *gdp_gclmd_new(void);</samp></p>
40 
    <p><samp>&nbsp;&nbsp;&nbsp; void&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
41 
        &nbsp;&nbsp;&nbsp; gdp_gclmd_free(gdp_gclmd_t *gmd);</samp></p>
42 
    <p><samp>&nbsp;&nbsp;&nbsp; EP_STAT&nbsp;&nbsp;&nbsp;
43 
        &nbsp;&nbsp;&nbsp;&nbsp; gdp_gclmd_add(gdp_gclmd_t *gmd,<br>
44 
        &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
45 
        &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
46 
        &nbsp;&nbsp;&nbsp; gdp_gclmd_id_t id,<br>
47 
        &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
48 
        &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
49 
        &nbsp;&nbsp;&nbsp; size_t len,<br>
50 
        &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
51 
        &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
52 
        &nbsp;&nbsp;&nbsp; const void *data);<br>
53 
      </samp></p>
54 
    <p><samp>&nbsp;&nbsp;&nbsp; EP_STAT&nbsp;&nbsp;&nbsp;
55 
        &nbsp;&nbsp;&nbsp;&nbsp; gdp_gclmd_get(gdp_gclmd_t *gmd,<br>
56 
        &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
57 
        &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
58 
        &nbsp;&nbsp;&nbsp; int index,<br>
59 
        &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
60 
        &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
61 
        &nbsp;&nbsp;&nbsp; gdpd_gclmd_id_t *id,<br>
62 
        &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
63 
        &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
64 
        &nbsp;&nbsp;&nbsp; size_t *len,<br>
65 
        &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
66 
        &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
67 
        &nbsp;&nbsp;&nbsp; const void **data);<br>
68 
      </samp></p>
69 
    <p>These routines allocate and free a data structure (which will be
70 
      dynamically expanded if needed), add a new metadata field with the
71 
      indicated name, length, and value (the data will be copied), and return a
72 
      field at a given index (the data is <em>not</em> copied).<br>
73 
    </p>
74 
    <p>To create a new GCL with metadata an application should create a new data
75 
      structure using <code>gdp_gclmd_new</code>, populate it using <code>gdp_gclmd_add</code>,
76 
      send it as a parameter to <code>gdp_gcl_create</code>, and then free the
77 
      metadata using <code>gdp_gclmd_free</code>.<br>
78 
    </p>
79 
    <p>To access metadata in an existing GCL an application needs to fetch the
80 
      metadata:<br>
81 
    </p>
82 
    <p><samp>&nbsp;&nbsp;&nbsp; EP_STAT&nbsp;&nbsp;&nbsp;
83 
        &nbsp;&nbsp;&nbsp;&nbsp; gdp_gcl_getmetadata(gdp_gcl_t *gcl,<br>
84 
        &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
85 
        &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
86 
        &nbsp;&nbsp;&nbsp; gdp_gclmd_t **gmdp); </samp></p>
87 
    <p>This fetches the metadata into memory (if it is not already there) and
88 
      passes a metadata structure back.&nbsp; This structure can then be
89 
      interrogated using <code>gdp_gclmd_get</code>.&nbsp; <i>[[Who owns the
90 
        metadata, i.e., who has to do gdp_gclmd_free?]]</i><br>
91 
      <samp></samp></p>
92 
    <h2>Representation</h2>
93 
    <p>There are potentially three different representations for metadata:
94 
      in-memory, on-the-wire, and on-disk.<br>
95 
    </p>
96 
    <h3>In-Memory<br>
97 
    </h3>
98 
    <p>The internal representation is opaque as far as the client program is
99 
      concerned, with all interaction done by function calls in deference to
100 
      alternate language bindings.&nbsp; The API is described above.&nbsp; <i>[[Details
101 
        To Be Done.]]</i><br>
102 
    </p>
103 
    <h3>On-The-Wire</h3>
104 
    <p>When sent over the network, all integers are sent in network byte order
105 
      (big-endian) as is standard for network protocols.&nbsp; The
106 
      representation for each metadatum is a four-octet integer name.&nbsp; If
107 
      that is zero then no more metadata fields are present and no more data is
108 
      sent.&nbsp; If non-zero, the name is followed by a four-octet length which
109 
      is immediately followed by that number of bytes of data.&nbsp; Note that
110 
      the integers are not guaranteed to be word aligned.<br>
111 
    </p>
112 
    <h3>On Disk</h3>
113 
    <p><i>[[To be written &mdash; really need to document everything, not just
114 
        metadata, probably in another document.]]</i><br>
115 
    </p>
116 
    <h3> </h3>
117 
  </body>
118 
</html>