From 8f922d174e08026120363533dbf48349266ee7cb Mon Sep 17 00:00:00 2001 From: Graham Miller Date: Fri, 14 Jan 2011 13:40:52 -0500 Subject: Added tag 0.1 for changeset 74f74c375a95 --- encode.h | 609 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 609 insertions(+) create mode 100644 encode.h (limited to 'encode.h') diff --git a/encode.h b/encode.h new file mode 100644 index 0000000..e3f15f8 --- /dev/null +++ b/encode.h @@ -0,0 +1,609 @@ +#ifndef _ENCODE_H +#define _ENCODE_H + +#include + +/** + * Allocates a new type ID. + * + * Note that this method is not thread-safe. + * + * @return + * An identifier for the representation of a type in a gob stream. + */ +int gob_allocate_type_id(); + +/////////////////////////////////////////////////////////////////////////////// +// Basic Types + +/** + * Encodes an unsigned long long into the specified buffer. + * + * From the gob package documentation: "An unsigned integer is sent one of two + * ways. If it is less than 128, it is sent as a byte with that value. + * Otherwise it is sent as a minimal-length big-endian (high byte first) byte + * stream holding the value, preceded by one byte holding the byte count, + * negated. Thus 0 is transmitted as (00), 7 is transmitted as (07) and 256 + * is transmitted as (FE 01 00). " + * + * @param buf + * The buffer into which to encode the given number. The pointer must point + * to "empty" space in the buffer. + * @param buf_size + * The number of bytes in buf available for writing + * @param ull + * The number to encode + * + * @return + * The number of bytes that would have been written by the encode operation. + * A return value greater than buf_size indicates a partial encode has + * occurred (buffer overflow). + */ +int gob_encode_unsigned_long_long(char *buf, size_t buf_size, unsigned long long ull); + +/** + * Encodes an unsigned int into the specified buffer. + * + * From the gob package documentation: "An unsigned integer is sent one of two + * ways. If it is less than 128, it is sent as a byte with that value. + * Otherwise it is sent as a minimal-length big-endian (high byte first) byte + * stream holding the value, preceded by one byte holding the byte count, + * negated. Thus 0 is transmitted as (00), 7 is transmitted as (07) and 256 + * is transmitted as (FE 01 00). " + * + * @param buf + * The buffer into which to encode the given number. The pointer must point + * to "empty" space in the buffer. + * @param buf_size + * The number of bytes in buf available for writing + * @param i + * The number to encode + * + * @return + * The number of bytes that would have been written by the encode operation. + * A return value greater than buf_size indicates a partial encode has + * occurred (buffer overflow). + */ +int gob_encode_unsigned_int(char *buf, size_t buf_size, unsigned int i); + +/** + * Encodes an int into the specified buffer. + * + * From the gob package documentation: "A signed integer, i, is encoded within + * an unsigned integer, u. Within u, bits 1 upward contain the value; bit 0 + * says whether they should be complemented upon receipt. The encode algorithm + * looks like this: + * + * \code + * uint u; + * if i < 0 { + * u = (^i << 1) | 1 // complement i, bit 0 is 1 + * } else { + * u = (i << 1) // do not complement i, bit 0 is 0 + * } + * encodeUnsigned(u) + * \endcode + * " + * + * @param buf + * The buffer into which to encode the given number. The pointer must point + * to "empty" space in the buffer. + * @param buf_size + * The number of bytes in buf available for writing + * @param i + * The number to encode + * + * @return + * The number of bytes that would have been written by the encode operation. + * A return value greater than buf_size indicates a partial encode has + * occurred (buffer overflow). + */ +int gob_encode_int(char *buf, size_t buf_size, int i); + +/** + * Encodes a long long into the specified buffer. + * + * From the gob package documentation: "A signed integer, i, is encoded within + * an unsigned integer, u. Within u, bits 1 upward contain the value; bit 0 + * says whether they should be complemented upon receipt. The encode algorithm + * looks like this: + * + * \code + * uint u; + * if i < 0 { + * u = (^i << 1) | 1 // complement i, bit 0 is 1 + * } else { + * u = (i << 1) // do not complement i, bit 0 is 0 + * } + * encodeUnsigned(u) + * \endcode + * " + * + * @param buf + * The buffer into which to encode the given number. The pointer must point + * to "empty" space in the buffer. + * @param buf_size + * The number of bytes in buf available for writing + * @param i + * The number to encode + * + * @return + * The number of bytes that would have been written by the encode operation. + * A return value greater than buf_size indicates a partial encode has + * occurred (buffer overflow). + */ +int gob_encode_long_long(char *buf, size_t buf_size, long long i); + +/** + * Encodes a boolean into the specified buffer. + * + * From the gob package documentation: "A boolean is encoded within an unsigned + * integer: 0 for false, 1 for true." + * + * The function takes an int argument and writes false to the stream if + * the int is 0, writes true otherwise. + * + * @param buf + * The buffer into which to encode the given number. The pointer must point + * to "empty" space in the buffer. + * @param buf_size + * The number of bytes in buf available for writing + * @param b + * The boolean to encode, 0 for false, otherwise true + * + * @return + * The number of bytes that would have been written by the encode operation. + * A return value greater than buf_size indicates a partial encode has + * occurred (buffer overflow). + */ +int gob_encode_boolean(char *buf, size_t buf_size, int b); + +/** + * Encodes a boolean into the specified buffer. + * + * From the gob package documentation: "Floating-point numbers are always sent + * as a representation of a float64 value. That value is converted to a uint64 + * using math.Float64bits. The uint64 is then byte-reversed and sent as a + * regular unsigned integer. The byte-reversal means the exponent and + * high-precision part of the mantissa go first. Since the low bits are often + * zero, this can save encoding bytes. For instance, 17.0 is encoded in only + * three bytes (FE 31 40)." + * + * @param buf + * The buffer into which to encode the given number. The pointer must point + * to "empty" space in the buffer. + * @param buf_size + * The number of bytes in buf available for writing + * @param d + * The double to encode + * + * @return + * The number of bytes that would have been written by the encode operation. + * A return value greater than buf_size indicates a partial encode has + * occurred (buffer overflow). + */ +int gob_encode_double(char *buf, size_t buf_size, double d); + +/** + * Encodes a boolean into the specified buffer. + * + * From the gob package documentation: "Strings and slices of bytes are sent as + * an unsigned count followed by that many uninterpreted bytes of the value. " + * + * @param buf + * The buffer into which to encode the given number. The pointer must point + * to "empty" space in the buffer. + * @param buf_size + * The number of bytes in buf available for writing + * @param s + * A zero-terminated (C-style) string to encode + * + * @return + * The number of bytes that would have been written by the encode operation. + * A return value greater than buf_size indicates a partial encode has + * occurred (buffer overflow). + */ +int gob_encode_string(char *buf, size_t buf_size, const char *s); + +/////////////////////////////////////////////////////////////////////////////// +// More complex built-in types + +/** + * Provides the prefix of the array encoding. + * + * From the gob package documentation: "All other slices and arrays are sent as + * an unsigned count followed by that many elements using the standard gob + * encoding for their type, recursively." + * + * This method simply encodes the array count. It is the responsibility of the + * user to encode the appropriate number of elements before a call to + * gob_end_array() + * + * @param buf + * The buffer into which to encode the given number. The pointer must point + * to "empty" space in the buffer. + * @param buf_size + * The number of bytes in buf available for writing + * @param size + * The number of elements in the array to follow + * + * @return + * The number of bytes that would have been written by the encode operation. + * A return value greater than buf_size indicates a partial encode has + * occurred (buffer overflow). + */ +int gob_start_array(char *buf, size_t buf_size, size_t size); + +/** + * Provides the suffix of the array encoding. + * + * From the gob package documentation: "All other slices and arrays are sent as + * an unsigned count followed by that many elements using the standard gob + * encoding for their type, recursively." + * + * Note that this method currently always returns 0, but is provided for + * symmetry with gob_start_array(). + * + * @param buf + * The buffer into which to encode the given number. The pointer must point + * to "empty" space in the buffer. + * @param buf_size + * The number of bytes in buf available for writing + * + * @return + * The number of bytes that would have been written by the encode operation. + * A return value greater than buf_size indicates a partial encode has + * occurred (buffer overflow). + */ +int gob_end_array(char *buf, size_t buf_size); + +/** + * Provides the prefix of the slice encoding. + * + * From the gob package documentation: "All other slices and arrays are sent as + * an unsigned count followed by that many elements using the standard gob + * encoding for their type, recursively." + * + * This method simply encodes the slice count. It is the responsibility of the + * user to encode the appropriate number of elements before a call to + * gob_end_array() + * + * @param buf + * The buffer into which to encode the given number. The pointer must point + * to "empty" space in the buffer. + * @param buf_size + * The number of bytes in buf available for writing + * @param size + * The number of elements in the slice to follow + * + * @return + * The number of bytes that would have been written by the encode operation. + * A return value greater than buf_size indicates a partial encode has + * occurred (buffer overflow). + */ +int gob_start_slice(char *buf, size_t buf_size, size_t size); + +/** + * Provides the suffix of the slice encoding. + * + * From the gob package documentation: "All other slices and arrays are sent as + * an unsigned count followed by that many elements using the standard gob + * encoding for their type, recursively." + * + * Note that this method currently always returns 0, but is provided for + * symmetry with gob_start_slice(). + * + * @param buf + * The buffer into which to encode the given number. The pointer must point + * to "empty" space in the buffer. + * @param buf_size + * The number of bytes in buf available for writing + * + * @return + * The number of bytes that would have been written by the encode operation. + * A return value greater than buf_size indicates a partial encode has + * occurred (buffer overflow). + */ +int gob_end_slice(char *buf, size_t buf_size); + +/** + * Provides the prefix of the struct encoding. + * + * From the gob package documentation: "Structs are sent as a sequence of + * (field number, field value) pairs. The field value is sent using the + * standard gob encoding for its type, recursively. If a field has the zero + * value for its type, it is omitted from the transmission. The field + * number is defined by the type of the encoded struct: the first field of + * the encoded type is field 0, the second is field 1, etc. ... Finally, + * after all the fields have been sent a terminating mark denotes the end + * of the struct. That mark is a delta=0 value, which has representation (00)." + * + * Note that this method currently always returns 0, but is provided for + * symmetry with gob_end_struct(). + * + * @param buf + * The buffer into which to encode the given number. The pointer must point + * to "empty" space in the buffer. + * @param buf_size + * The number of bytes in buf available for writing + * + * @return + * The number of bytes that would have been written by the encode operation. + * A return value greater than buf_size indicates a partial encode has + * occurred (buffer overflow). + */ +int gob_start_struct(char *buf, size_t buf_size); + +/** + * Provides the suffix of the struct encoding. + * + * From the gob package documentation: "Structs are sent as a sequence of + * (field number, field value) pairs. The field value is sent using the + * standard gob encoding for its type, recursively. If a field has the zero + * value for its type, it is omitted from the transmission. The field + * number is defined by the type of the encoded struct: the first field of + * the encoded type is field 0, the second is field 1, etc. ... Finally, + * after all the fields have been sent a terminating mark denotes the end + * of the struct. That mark is a delta=0 value, which has representation (00)." + * + * This method simply encodes the 00 delta value. + * + * @param buf + * The buffer into which to encode the given number. The pointer must point + * to "empty" space in the buffer. + * @param buf_size + * The number of bytes in buf available for writing + * + * @return + * The number of bytes that would have been written by the encode operation. + * A return value greater than buf_size indicates a partial encode has + * occurred (buffer overflow). + */ +int gob_end_struct(char *buf, size_t buf_size); + +/////////////////////////////////////////////////////////////////////////////// +// Type declarations + +/** + * Encodes the prefix of a type definition. + * + * From the gob package documentation: "To define a type, the encoder chooses + * an unused, positive type id and sends the pair (-type id, encoded-type) + * where encoded-type is the gob encoding of a wireType description, + * constructed from these types ..." + * + * This method encodes the type id and the offset into the wireType struct. + * Note that the definition of wireType differs from that in the documentation + * in that it has several fields, of which it appears only one ever has + * a value. + * + * /code + * type wireType struct { + * arrayT *arrayType + * sliceT *sliceType + * structT *structType + * mapT *mapType + * } + * /endcode + * + * The client is responsible for encoding the value of an arrayT sliceT + * structT or mapT, before a call to gob_end_type_definition() + * + * @param buf + * The buffer into which to encode the given number. The pointer must point + * to "empty" space in the buffer. + * @param buf_size + * The number of bytes in buf available for writing + * @param id + * The (positive) type id, as returned from gob_allocate_type_id() + * @param type + * One of GOB_ARRAYTYPE_ID, GOB_SLICETYPE_ID, GOB_STRUCTTYPE_ID, + * GOB_MAPTYPE_ID + * + * @return + * The number of bytes that would have been written by the encode operation. + * A return value greater than buf_size indicates a partial encode has + * occurred (buffer overflow). + */ +int gob_start_type_definition(char *buf, size_t buf_size, int id, int type); + +/** + * Encodes the suffix of a type definition. + * + * From the gob package documentation: "To define a type, the encoder chooses + * an unused, positive type id and sends the pair (-type id, encoded-type) + * where encoded-type is the gob encoding of a wireType description, + * constructed from these types ..." + * + * This method simply calls gob_end_struct() to end the wireType struct + * definition. + * + * @param buf + * The buffer into which to encode the given number. The pointer must point + * to "empty" space in the buffer. + * @param buf_size + * The number of bytes in buf available for writing + * + * @return + * The number of bytes that would have been written by the encode operation. + * A return value greater than buf_size indicates a partial encode has + * occurred (buffer overflow). + */ +int gob_end_type_definition(char *buf, size_t buf_size); + +/** + * Encodes the prefix of a structType definition. + * + * This method encodes the prefix of a structType, including the + * entire commonType, where the definitions are as follows: + * + * /code + * type commonType { + * name string // the name of the struct type + * _id int // the id of the type, repeated for so it's inside the type + * } + * + * type structType struct { + * commonType + * field []*fieldType // the fields of the struct. + * } + * /endcode + * + * The client is responsible for encoding the field slice before a call to + * gob_end_struct_type(). + * + * @param buf + * The buffer into which to encode the given number. The pointer must point + * to "empty" space in the buffer. + * @param buf_size + * The number of bytes in buf available for writing + * @param name + * A zero-terminated (C-style) string representing the name of the struct + * type. + * @param type + * The id of the type as returned by gob_allocate_type_id() + * + * @return + * The number of bytes that would have been written by the encode operation. + * A return value greater than buf_size indicates a partial encode has + * occurred (buffer overflow). + */ +int gob_start_struct_type(char *buf, size_t buf_size, const char *name, int id); + +/** + * Encodes the suffix of a structType definition. + * + * This method simply calls gob_end_struct() to end the structType struct. + * + * @param buf + * The buffer into which to encode the given number. The pointer must point + * to "empty" space in the buffer. + * @param buf_size + * The number of bytes in buf available for writing + * + * @return + * The number of bytes that would have been written by the encode operation. + * A return value greater than buf_size indicates a partial encode has + * occurred (buffer overflow). + */ +int gob_end_struct_type(char *buf, size_t buf_size); + +/** + * Encodes the commonType struct (usually should not be called explicitly). + * + * This method encodes an entire instance of the commonType struct. Because + * this struct is part of the prefix of other types, it typically is called + * only indirectly through a method like gob_start_struct_type(). + * + * @param buf + * The buffer into which to encode the given number. The pointer must point + * to "empty" space in the buffer. + * @param buf_size + * The number of bytes in buf available for writing + * @param name + * A zero-terminated (C-style) string representing the name of the struct + * type. + * @param id + * The id of the type as returned by gob_allocate_type_id() + */ +int gob_encode_common_type(char *buf, size_t buf_size, const char *name, int id); + +/** + * Encodes the fieldType struct. + * + * This method encodes an entire instance of the fieldType struct, as defined: + * + * /code + * type fieldType struct { + * name string // the name of the field. + * id int // the type id of the field, which must be already defined + * } + * /endcode + * + * @param buf + * The buffer into which to encode the given number. The pointer must point + * to "empty" space in the buffer. + * @param buf_size + * The number of bytes in buf available for writing + * @param name + * A zero-terminated (C-style) string representing the name of the struct + * type. + * @param id + * The id of the type either returned by gob_allocate_type_id() or as defined + * in gob.h + */ +int gob_encode_field_type(char *buf, size_t buf_size, const char *name, int id); + +/** + * Encodes the arrayType struct. + * + * This method encodes an entire instance of the arrayType struct, as defined: + * + * /code + * type commonType { + * name string // the name of the struct type + * _id int // the id of the type, repeated for so it's inside the type + * } + * + * type arrayType struct { + * commonType + * Elem typeId + * Len int + * } + * /endcode + * + * @param buf + * The buffer into which to encode the given number. The pointer must point + * to "empty" space in the buffer. + * @param buf_size + * The number of bytes in buf available for writing + * @param name + * A zero-terminated (C-style) string representing the name of the array + * type. + * @param id + * The id of the array type itself, as returned by gob_allocate_type_id() + * @param type_id + * The id of the type of the elements of the array, as returned by + * gob_allocate_type_id() or as defined in gob.h. + * @param len + * The length of the array. + * + */ +int gob_encode_array_type(char *buf, size_t buf_size, const char *name, int id, int type_id, int len); + +/** + * Encodes the sliceType struct. + * + * This method encodes an entire instance of the sliceType struct, as defined: + * + * /code + * type commonType { + * name string // the name of the struct type + * _id int // the id of the type, repeated for so it's inside the type + * } + * + * type sliceType struct { + * commonType + * Elem typeId + * } + * /endcode + * + * @param buf + * The buffer into which to encode the given number. The pointer must point + * to "empty" space in the buffer. + * @param buf_size + * The number of bytes in buf available for writing + * @param name + * A zero-terminated (C-style) string representing the name of the array + * type. + * @param id + * The id of the slice type itself, as returned by gob_allocate_type_id() + * @param type_id + * The id of the type of the elements of the slice, as returned by + * gob_allocate_type_id() or as defined in gob.h. + * + */ +int gob_encode_slice_type(char *buf, size_t buf_size, const char *name, int id, int elem_type); + +#endif + -- cgit v1.2.3