1NAL_DECODE_UINT32(2) distcache NAL_DECODE_UINT32(2)
2
6 NAL_decode_uint32, NAL_decode_uint16, NAL_decode_char, NAL_decode_bin,
7 NAL_encode_uint32, NAL_encode_uint16, NAL_encode_char, NAL_encode_bin -
8 libnal serialisation functions
9
11 #include <libnal/nal.h>
12 int NAL_decode_uint32(const unsigned char **bin, unsigned int *bin_len,
14 unsigned long *val);
15 int NAL_decode_uint16(const unsigned char **bin, unsigned int *bin_len,
16 unsigned int *val);
17 int NAL_decode_char(const unsigned char **bin, unsigned int *bin_len,
18 unsigned char *val);
19 int NAL_decode_bin(const unsigned char **bin, unsigned int *bin_len,
20 unsigned char *val, unsigned int val_len);
21 int NAL_encode_uint32(unsigned char **bin, unsigned int *bin_len,
23 const unsigned long val);
24 int NAL_encode_uint16(unsigned char **bin, unsigned int *bin_len,
25 const unsigned int val);
26 int NAL_encode_char(unsigned char **bin, unsigned int *bin_len,
27 const unsigned char val);
28 int NAL_encode_bin(unsigned char **bin, unsigned int *bin_len,
29 const unsigned char *val, const unsigned int val_len);
30
32 NAL_decode_uint32(), NAL_decode_uint16(), and NAL_decode_char() attempt
33 to parse different sized integer values from the data pointed to by
34 *bin (both bin and bin_len are passed by reference). If bin_len indi‐
35 cates there is sufficient data to successfully parse a value, then the
36 value will be stored in val, *bin will be incremented to point to the
37 next unparsed byte of data, and *bin_len will be decremented to indi‐
38 cate how much unparsed data remains.
39 NAL_decode_bin() follows the semantics of the other decode functions
41 except that it decodes a block of binary data of length val_len.
42 NAL_encode_uint32(), NAL_encode_uint16(), and NAL_encode_char() attempt
44 to encode different sized integer values to the located pointed to by
45 *bin (again, both bin and bin_len are passed by reference). If bin_len
46 indicates there is sufficient room to successfully encode a value, val
47 will be stored at *bin, *bin will be incremented to point to the next
48 unused byte of storage, and *bin_len will be decremented to indicate
49 how much unused storage remains.
50 NAL_encode_bin() follows the semantics of the other encode functions
52 except that it encodes a block of binary data of length val_len.
53
55 All the encode and decode functions return non-zero for success or zero
56 for failure. On failure, bin and bin_len are left unchanged.
57
59 The reason for passing bin and bin_len by reference to all these func‐
60 tions is to allow (de)serialisation of complex structures to be built
61 up more easily without unnecessary work by the caller. The return value
62 still indicates whether an encoding or decoding was successful, but the
63 caller will not need to increment bin nor decrement bin_len after suc‐
64 cess before continuing to encode or decode further data.
65
67 Assume we wish to pass a data structure between applications running on
68 different machines (and potentially on different architectures), and
69 the data structure is defined as follows;
70 #define MAX_DATA_SIZE 4096
72 typedef struct st_some_data_t {
73 unsigned char is_active; /* boolean */
74 unsigned char buffer[MAX_DATA_SIZE];
75 unsigned int buffer_used;
76 } some_data_t;
77 We could define two functions for encoding and decoding an object of
79 this type such that they could be serialised and transferred over a
80 connection. The most elegant way to build serialisation of objects is
81 to create functions that use the same form of prototype as the libnal
82 serialisation functions, this way serialisation of complex objects can
83 be performed recursively by serialisation of aggregated types. Although
84 the built-in libnal serialisation functions leave bin and bin_len
85 unchanged on failure, it is generally not worth bothering to preserve
86 this property at higher-levels - these examples do not attempt this.
87 An encoding function would thus look like;
89 int encode_some_data(unsigned char **bin, unsigned int *bin_len,
91 const some_data_t *val)
92 {
93 if(
94 /* Encode the "is_active" boolean */
95 !NAL_encode_char(bin, bin_len, val->is_active) ⎪⎪
96 /* Encode the used data */
97 !NAL_encode_uint16(bin, bin_len, val->buffer_used) ⎪⎪
98 ((val->buffer_used > 0) &&
99 !NAL_encode_bin(bin, bin_len, val->buffer, val->buffer_used)))
100 return 0;
101 return 1;
102 }
103 Note that other types that include some_data_t objects could implement
105 serialisation using encode_some_data() in the same way that
106 encode_some_data() uses the lower-level libnal functions. A correspond‐
107 ing decode function follows.
108 int decode_some_data(const unsigned char **bin, unsigned int *bin_len,
110 some_data_t *val)
111 {
112 if(
113 /* Decode the "is_active" boolean */
114 !NAL_decode_char(bin, bin_len, &val->is_active) ⎪⎪
115 /* Decode the used data */
116 !NAL_decode_uint16(bin, bin_len, &val->buffer_used) ⎪⎪
117 /* [TODO: check 'val->buffer_used' is acceptable here] */
118 ((val->buffer_used > 0) &&
119 !NAL_decode_bin(bin, bin_len, val->buffer, val->buffer_used)))
120 return 0;
121 return 1;
122 }
123 The above examples would be simpler still if a wrapper function were
125 first written to serialise length-prefixed blocks of data. Such func‐
126 tions are not included in libnal because they can vary on what range of
127 sizes are appropriate, what size encoding to use for a length-prefix,
128 whether dynamic allocation should be used on decoding, etc. The above
129 examples use a static buffer and encode the length prefix as 16-bits.
130
132 NAL_ADDRESS_new(2) - Functions for the NAL_ADDRESS type.
133 NAL_CONNECTION_new(2) - Functions for the NAL_CONNECTION type.
135 NAL_LISTENER_new(2) - Functions for the NAL_LISTENER type.
137 NAL_SELECTOR_new(2) - Functions for the NAL_SELECTOR type.
139 distcache(8) - Overview of the distcache architecture.
141 http://www.distcache.org/ - Distcache home page.
143
145 This toolkit was designed and implemented by Geoff Thorpe for Crypto‐
146 graphic Appliances Incorporated. Since the project was released into
147 open source, it has a home page and a project environment where devel‐
148 opment, mailing lists, and releases are organised. For problems with
149 the software or this man page please check for new releases at the
150 project web-site below, mail the users mailing list described there, or
151 contact the author at geoff@geoffthorpe.net.
152 Home Page: http://www.distcache.org
1541.4.5 2004.03.23 NAL_DECODE_UINT32(2)