gdp / doc / developer / gdp-gob-metadata.html @ master
History | View | Annotate | Download (6.05 KB)
1 | 3b0794ad | Eric Allman | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
---|---|---|---|
2 | <html>
|
||
3 | <head>
|
||
4 | 26fa111b | Eric Allman | <meta content="text/html; charset=UTF-8" http-equiv="content-type"> |
5 | 3b0794ad | Eric Allman | <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 | 16dcce04 | Eric Allman | Draft Document Version 0.10, 2015-01-23<br>
|
11 | 3b0794ad | Eric Allman | </h4>
|
12 | 26fa111b | Eric Allman | <p>The GDP supports a limited amount of write-once per-GCL metadata. |
13 | It can be added when a GCL is created and is thenceforth immutable.<br>
|
||
14 | 3b0794ad | Eric Allman | </p>
|
15 | <p>Each piece of GCL metadata consists of a name, a data length, and
|
||
16 | 26fa111b | Eric Allman | (optionally) some data. Any typing information is implied by the
|
17 | name.<br>
|
||
18 | 3b0794ad | Eric Allman | </p>
|
19 | 26fa111b | Eric Allman | <p>Names are exactly four bytes. All names with the high-order octet |
20 | set to zero are reserved for use by the system. It is recommended
|
||
21 | that application defined names be exactly four ASCII characters, e.g., |
||
22 | 'ABCD' (which is equal to 0x41424344). 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. The name that is all zeros is reserved to indicate "end of
|
||
26 | list". <i>[[Registration of codes is To Be Done.]]</i><br> |
||
27 | 3b0794ad | Eric Allman | </p>
|
28 | 26fa111b | Eric Allman | <p>Lengths are three bytes packed into a four byte integer, representing the
|
29 | number of octets in the data. The top eight bits are reserved for
|
||
30 | future use. They must be zero when sent and ignored on receipt.<br> |
||
31 | 3b0794ad | Eric Allman | </p>
|
32 | 26fa111b | Eric Allman | <p>Data is a series of opaque bytes. It might be encrypted, at the |
33 | discretion of the application.<br>
|
||
34 | 3b0794ad | Eric Allman | </p>
|
35 | <h2>Sending and Accessing Metadata</h2> |
||
36 | <p>The metadata interface is as follows:<br> |
||
37 | </p>
|
||
38 | <p><samp> gdp_gclmd_t |
||
39 | *gdp_gclmd_new(void);</samp></p> |
||
40 | 26fa111b | Eric Allman | <p><samp> void |
41 | gdp_gclmd_free(gdp_gclmd_t *gmd);</samp></p> |
||
42 | 3b0794ad | Eric Allman | <p><samp> EP_STAT |
43 | gdp_gclmd_add(gdp_gclmd_t *gmd,<br> |
||
44 | |
||
45 | |
||
46 | gdp_gclmd_id_t id,<br> |
||
47 | |
||
48 | |
||
49 | size_t len,<br> |
||
50 | |
||
51 | |
||
52 | const void *data);<br> |
||
53 | </samp></p> |
||
54 | <p><samp> EP_STAT |
||
55 | gdp_gclmd_get(gdp_gclmd_t *gmd,<br> |
||
56 | |
||
57 | |
||
58 | int index,<br> |
||
59 | |
||
60 | |
||
61 | gdpd_gclmd_id_t *id,<br> |
||
62 | |
||
63 | |
||
64 | size_t *len,<br> |
||
65 | |
||
66 | |
||
67 | 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 | 26fa111b | Eric Allman | 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 | 3b0794ad | Eric Allman | </p>
|
74 | 26fa111b | Eric Allman | <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 | 3b0794ad | Eric Allman | </p>
|
79 | 26fa111b | Eric Allman | <p>To access metadata in an existing GCL an application needs to fetch the
|
80 | metadata:<br>
|
||
81 | 3b0794ad | Eric Allman | </p>
|
82 | <p><samp> EP_STAT |
||
83 | gdp_gcl_getmetadata(gdp_gcl_t *gcl,<br> |
||
84 | |
||
85 | |
||
86 | gdp_gclmd_t **gmdp); </samp></p> |
||
87 | 26fa111b | Eric Allman | <p>This fetches the metadata into memory (if it is not already there) and
|
88 | passes a metadata structure back. This structure can then be
|
||
89 | interrogated using <code>gdp_gclmd_get</code>. <i>[[Who owns the |
||
90 | metadata, i.e., who has to do gdp_gclmd_free?]]</i><br> |
||
91 | 3b0794ad | Eric Allman | <samp></samp></p> |
92 | <h2>Representation</h2> |
||
93 | 26fa111b | Eric Allman | <p>There are potentially three different representations for metadata:
|
94 | in-memory, on-the-wire, and on-disk.<br>
|
||
95 | 3b0794ad | Eric Allman | </p>
|
96 | <h3>In-Memory<br> |
||
97 | </h3>
|
||
98 | 26fa111b | Eric Allman | <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. The API is described above. <i>[[Details |
||
101 | To Be Done.]]</i><br> |
||
102 | 3b0794ad | Eric Allman | </p>
|
103 | <h3>On-The-Wire</h3> |
||
104 | 26fa111b | Eric Allman | <p>When sent over the network, all integers are sent in network byte order
|
105 | (big-endian) as is standard for network protocols. The
|
||
106 | representation for each metadatum is a four-octet integer name. If
|
||
107 | that is zero then no more metadata fields are present and no more data is |
||
108 | sent. If non-zero, the name is followed by a four-octet length which
|
||
109 | is immediately followed by that number of bytes of data. Note that
|
||
110 | the integers are not guaranteed to be word aligned.<br>
|
||
111 | 3b0794ad | Eric Allman | </p>
|
112 | <h3>On Disk</h3> |
||
113 | 26fa111b | Eric Allman | <p><i>[[To be written — really need to document everything, not just |
114 | 3b0794ad | Eric Allman | metadata, probably in another document.]]</i><br> |
115 | </p>
|
||
116 | <h3> </h3> |
||
117 | </body>
|
||
118 | </html> |