rxp - Roy Cross-Platform data serializing API

#include <roy.h>

RXpEncoder * rxp_encoder_new (void);

char * rxp_encoder_get_buffer (RXpEncoder *encoder, unsigned int *length);

void rxp_encoder_reset (RXpEncoder *encoder);

void rxp_encode_msg_end (RXpEncoder *encoder);

void rxp_encode_type (RXpEncoder *encoder, RXpDataType type);

void rxp_encode_ruint32 (RXpEncoder *encoder, ruint32 value);

void rxp_encode_rint32 (RXpEncoder *encoder, rint32 value);

void rxp_encode_float (RXpEncoder *encoder, float value);

void rxp_encode_double (RXpEncoder *encoder, double value);

void rxp_encode_rbuf (RXpEncoder *encoder, RBuf *value);

void rxp_encode_str (RXpEncoder *encoder, char * str);

void rxp_encode_data (RXpEncoder *encoder, void * data, int len);

void rxp_encoder_free (RXpEncoder *encoder);

RXpDataType rxp_decode_peek_next_type (RXpDecoder *decoder);

RXpDecoder * rxp_decoder_new (char *data, int length);

void rxp_decoder_free (RXpDecoder *decoder);

unsigned int rxp_decoder_msg_length (RXpDecoder *decoder);

void rxp_decoder_reset (RXpDecoder *decoder, char *data, int length);

int rxp_decode_type (RXpDecoder *decoder, RXpDataType *type);

int rxp_decode_rint32 (RXpDecoder *decoder, rint32 *value);

int rxp_decode_ruint32 (RXpDecoder *decoder, ruint32 *value);

int rxp_decode_float (RXpDecoder *decoder, float *value);

int rxp_decode_double (RXpDecoder *decoder, double *value);

int rxp_decode_rbuf (RXpDecoder *decoder, RBuf **value);

int rxp_decode_str (RXpDecoder *decoder, char * buf, int len);

int rxp_decode_data (RXpDecoder *decoder, void * buf, int buflen, int * len);

RXP is used to serialize/reconstruct data of assorted data types. The encoder takes care of all memory allocation. User defined types are also supported.

Each of the rxp_encode_<foo> functions behave identically, appending the given type on the encoder followed by the data itself.

The exceptions to this rule are rxp_encode_type(3), which appends only the given type value to the encoder, and is meant for use with user defined types, and rxp_encode_msg_end(3) which places a special RXP_TYPE_MSG_END token at the end of the buffer.

rxp_ecoder_new(3) creates a new encoder, which you can then start encoding types into.

rxp_encoder_reset(3) clears the encode buffer. This can be used to recycle the encoder for use in a new encode operation.

rxp_encoder_free(3) frees a previously created RXpEncoder structure along with its encode buffer.

rxp_encoder_get_buffer(3) allows you to get the raw buffer and its length when you are done encoding. length is a pointer to the returned length value. Note that when the RXpEncoder structure is freed, the buffer is freed with it.

rxp_decoder_new(3) takes the buffer and length from an RXpEncoder. This initializes a new decoder with that buffer, and allows you to start performing decode operations on it. If you do not know the length of the buffer, you can read the first 4 bytes of the buffer into rxp_decoder_new(3), and then use rxp_decoder_msg_length(3) to get the full length of the message. rxp_decoder_reset(3) may then be used to reset the length to the proper size.

rxp_decoder_reset(3) resets the buffer allowing you to use a new buffer, or to change the length of this buffer.

rxp_decoder_msg_length(3) returns the total decoded length of the encoded data as set in the encoded message (the first 4 bytes of the encoded buffer contains the total encoded message length).

rxp_decoder_free(3) frees the decoder structure, but does not free the data as set with rxp_decoder_new(3) or rxp_decoder_reset(3).

rxp_decode_peek_next_type(3) returns the type of the next encoded datum. This does not advance the current location in the buffer.

The typical method of decoding the buffer is simple. If the exact encoded data is known beforehand, the decode functions can be called in order for each expected type. If the types are not known, the rxp_decode_peek_next_type(3) function should be used to determine which decoding function needs to be called.

The rxp_decode_<foo> functions return 0 on success. On failure, they return any of a number of possible failures: RXP_ERROR_NULL indicates an invalid NULL decoder. RXP_ERROR_LENGTH indicates the decoder does not have enough data in its buffer to decode the requested type. RXP_ERROR_TYPE indicates an error in the encoded data where the type being decoded is not the same as the type in the rxp_decode_<foo> function.

rxp_decode_peek_next_type(3) returns the value of the type on success or 0 on failure.

The defined RXpDataTypes are:

RXP_TYPE_INT32, RXP_TYPE_UINT32, RXP_TYPE_FLOAT, RXP_TYPE_DOUBLE, RXP_TYPE_STR, RXP_TYPE_DATA, RXP_TYPE_RBUF, RXP_TYPE_NULL_RBUF, RXP_TYPE_MSG_END, and RXP_TYPE_USER.

RXP_TYPE_USER is the special type for use in user defined types. Any user defined type should be RXP_TYPE_USER + 1, 2, etc.

These types are returned by the rxp_decode_peek_next_type(3) function.

roy(3)