174 lines
4.0 KiB
C
174 lines
4.0 KiB
C
#ifndef GS_UTIL_BYTEBUFFER_h
|
|
#define GS_UTIL_BYTEBUFFER_h
|
|
/* Copyright (c) 2013-2018 GomSpace A/S. All rights reserved. */
|
|
/**
|
|
@file
|
|
|
|
Byte buffer provides formatting/serialzing of text/binary data. The buffer keeps track of used space, and prevents overrun.
|
|
|
|
The current buffer state can be checked using gs_bytebuffer_state().
|
|
|
|
@dontinclude bytebuffer/bytebuffer_test.c
|
|
@skip TEST_gs_bytebuffer_use_case
|
|
@until }
|
|
*/
|
|
|
|
#include <gs/util/error.h>
|
|
#include <stdarg.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**
|
|
Buffer handle.
|
|
Never access handle members directly.
|
|
*/
|
|
typedef struct {
|
|
/**
|
|
Internal: Pointer to user supplied buffer.
|
|
@see gs_bytebuffer_init()
|
|
*/
|
|
uint8_t * buffer;
|
|
/**
|
|
Internal: Size of user supplied buffer.
|
|
@see gs_bytebuffer_init()
|
|
*/
|
|
size_t size;
|
|
/**
|
|
Internal: Number of bytes used.
|
|
*/
|
|
size_t used;
|
|
/**
|
|
Internal: FUTURE: Committed used
|
|
*/
|
|
size_t committed_used;
|
|
/**
|
|
Internal: flags to keep track of buffer state.
|
|
*/
|
|
uint8_t flags;
|
|
} gs_bytebuffer_t;
|
|
|
|
/**
|
|
Initialize buffer.
|
|
|
|
@param[in] bb handle.
|
|
@param[in] buffer user supplied buffer of \a buffer_size size (bytes). If NULL, the buffer will keep track of required bytes.
|
|
@param[in] buffer_size size of \a buffer.
|
|
@return_gs_error_t
|
|
*/
|
|
gs_error_t gs_bytebuffer_init(gs_bytebuffer_t * bb, void * buffer, size_t buffer_size);
|
|
|
|
/**
|
|
Insert data using vprintf.
|
|
|
|
@param[in] bb handle.
|
|
@param[in] format printf syntax for formatting data
|
|
@param[in] ap variable argument list.
|
|
*/
|
|
void gs_bytebuffer_vprintf(gs_bytebuffer_t * bb, const char * format, va_list ap);
|
|
|
|
/**
|
|
Insert data using printf.
|
|
|
|
@param[in] bb handle.
|
|
@param[in] format printf syntax for formatting data
|
|
*/
|
|
void gs_bytebuffer_printf(gs_bytebuffer_t * bb, const char * format, ...) __attribute__ ((format (__printf__, 2, 3)));
|
|
|
|
/**
|
|
Append data to buffer.
|
|
|
|
@param[in] bb handle.
|
|
@param[in] data data to append to buffer.
|
|
@param[in] length length of data (bytes).
|
|
*/
|
|
void gs_bytebuffer_append(gs_bytebuffer_t * bb, const void * data, size_t length);
|
|
|
|
/**
|
|
Append string to buffer.
|
|
|
|
@param[in] bb handle.
|
|
@param[in] string string to append to buffer.
|
|
*/
|
|
void gs_bytebuffer_append_string(gs_bytebuffer_t * bb, const char * string);
|
|
|
|
/**
|
|
Append string to buffer.
|
|
|
|
@param[in] bb handle.
|
|
@param[in] string string to append to buffer.
|
|
@param[in] max_length max characters to append from \a string.
|
|
*/
|
|
void gs_bytebuffer_append_string_max(gs_bytebuffer_t * bb, const char * string, size_t max_length);
|
|
|
|
/**
|
|
Return buffer as string - enforcing NUL termination.
|
|
|
|
This will always add a NUL termination (zero), which may lead to overflow/truncation of the string.
|
|
The NUL termination is NOT added to \a used count.
|
|
|
|
@param[in] bb handle.
|
|
@param[out] error optional, state of buffer - see gs_bytebuffer_error().
|
|
@return C-string (NUL terminated)
|
|
*/
|
|
char * gs_bytebuffer_get_as_string(gs_bytebuffer_t * bb, gs_error_t * error);
|
|
|
|
/**
|
|
Return buffer state.
|
|
|
|
@param[in] bb handle.
|
|
@return GS_ERROR_OVERFLOW if data has been truncated.
|
|
@return GS_ERROR_DATA in case of error during formatting.
|
|
@return_gs_error_t
|
|
*/
|
|
gs_error_t gs_bytebuffer_get_state(gs_bytebuffer_t * bb);
|
|
|
|
/**
|
|
Return buffer (user supplied).
|
|
|
|
@param[in] bb handle.
|
|
*/
|
|
static inline void * gs_bytebuffer_get_buffer(gs_bytebuffer_t * bb)
|
|
{
|
|
return bb->buffer;
|
|
}
|
|
|
|
/**
|
|
Return buffer size (user supplied).
|
|
|
|
@param[in] bb handle.
|
|
@return buffer size
|
|
*/
|
|
static inline size_t gs_bytebuffer_get_size(gs_bytebuffer_t * bb)
|
|
{
|
|
return bb->size;
|
|
}
|
|
|
|
/**
|
|
Return number of free bytes.
|
|
|
|
@param[in] bb handle.
|
|
@return number of free bytes.
|
|
*/
|
|
static inline size_t gs_bytebuffer_get_free(gs_bytebuffer_t * bb)
|
|
{
|
|
return (bb->size) ? (bb->size - bb->used) : 0;
|
|
}
|
|
|
|
/**
|
|
Return number of used bytes.
|
|
|
|
@param[in] bb handle.
|
|
@return used bytes.
|
|
*/
|
|
static inline size_t gs_bytebuffer_get_used(gs_bytebuffer_t * bb)
|
|
{
|
|
return bb->used;
|
|
}
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
#endif
|