Project

General

Profile

Statistics
| Branch: | Tag: | Revision:

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.&nbsp;
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.&nbsp; 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.&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 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.&nbsp; The top eight bits are reserved for
30
      future use.&nbsp; 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.&nbsp; 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>&nbsp;&nbsp;&nbsp; gdp_gclmd_t&nbsp;&nbsp;&nbsp;&nbsp;
39
        *gdp_gclmd_new(void);</samp></p>
40 26fa111b Eric Allman
    <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 3b0794ad Eric Allman
    <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 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>&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 26fa111b Eric Allman
    <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 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.&nbsp; The API is described above.&nbsp; <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.&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 3b0794ad Eric Allman
    </p>
112
    <h3>On Disk</h3>
113 26fa111b Eric Allman
    <p><i>[[To be written &mdash; 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>