/* ipmip_buffer.h - ipmip_buffer.h */ /* ****************************************************************************** * HEADER FILE * * Document no: @(#) $Name: VXWORKS_ITER40_2019102207 $ $RCSfile: ipmip_buffer.h,v $ $Revision: 1.9 $ * $Source: /home/interpeak/CVSRoot/ipmip/include/private/ipmip_buffer.h,v $ * $Author: jhorteli $ $Date: 2010-12-07 09:55:01 $ * $State: Exp $ $Locker: $ * * INTERPEAK_COPYRIGHT_STRING * Design and implementation by Joel Hortelius ****************************************************************************** */ #ifndef IPMIP_BUFFER_H #define IPMIP_BUFFER_H /* **************************************************************************** * 1 DESCRIPTION **************************************************************************** * Base implementation of the generic buffer management used in the MIP * products */ /* DESCRIPTION Base implementation of the generic buffer management used in the MIP products. The buffers are used for most everything related to message handling within the MIP system. Both for internal messages and for receiving and sending packets. The data associated with the buffer may be re-allocated or modified internally when using append or get operations, so a pointer in to a buffer MAY NOT be valid after invoking such routines. EXAMPLE These examples show how the various buffer manipulation functions should be used. .CS { Ipmip_buffer_t mybuf; int off; char *data; /@ Initialize the buffer @/ ipmip_buffer_init(&mybuf); /@ Get the next unused 40 bytes from the buffer. Make certain it is zero before providing it to the user @/ data = ipmip_buffer_get_zero(40); /@ Set the 40 bytes to 0x1 @/ ipcom_memset(data, 0x1, 40); /@ Shrink the buffer with 20 bytes @/ ipmip_buffer_shrink(data, 20); /@ Append another 30 bytes, with NULL data. This is the same as ipmip_buffer_get, really. @/ off = ipmip_buffer_append(&mybuf, IP_NULL, 30); /@ Transform the offset value returned to us by ipmip_buffer_append to an appropriate pointer into the buffer @/ data = ipmip_buffer_offset(&mybuf, data); /@ Set those 30 bytes to 0x2 @/ ipcom_memset(data, 0x2, 30); /@ Should print 20 0x1 and 30 0x2. @/ for (off = 0; off < IPMIP_BUFFER_SIZE(&mybuf); off++) { data = ipmip_buffer_offset(&mybuf, off); ipcom_printf("0x%x\n", *data); } /@ Free the resources associated with the buffer @/ ipmip_buffer_release(&mybuf); } .CE */ /* **************************************************************************** * 2 CONFIGURATION **************************************************************************** */ /* **************************************************************************** * 3 INCLUDE FILES **************************************************************************** */ #ifdef __cplusplus extern "C" { #endif /* **************************************************************************** * 4 DEFINES **************************************************************************** */ #define IPMIP_BUFFER_SIZE(buf) ((buf)->offset) #define IPMIP_BUFFER_DATA(buf) ((buf)->head) #define IPMIP_BUFFER_PTR(buf) ((void *)IPMIP_BUFFER_DATA((buf))) #define IPMIP_BUFFER_CURRENT(buf) ((void *)(&(buf)->head[IPMIP_BUFFER_SIZE(buf)])) #define IPMIP_BUFFER_REMAIN(buf) ((buf)->size - (buf)->offset) /* **************************************************************************** * 5 TYPES **************************************************************************** */ typedef struct Ipmip_buffer { Ip_u8 *head; /* Pointer to buffer */ Ip_size_t offset; /* Currently used size */ Ip_size_t size; /* Total size of buffer */ } Ipmip_buffer_t; /* **************************************************************************** * 6 FUNCTIONS **************************************************************************** */ /******************************************************************************* * * ipmip_buffer_init - ipmip_buffer_init * * Initialize a buffer structure. Setup the base parameters. This function does * not allocate any resources, it merely prepares the buffer for use. * * Parameters: * \is * \i buf * A pointer to a dynamic mobility buffer. See ipmip_buffer.h * for more information regarding dynamic buffers and their capabilities. * \ie * * RETURNS: No return value * * ERRNO: * * */ IP_GLOBAL void ipmip_buffer_init ( Ipmip_buffer_t *buf ); /******************************************************************************* * * ipmip_buffer_release - ipmip_buffer_release * * Release any resources associated with a buffer. * * Parameters: * \is * \i buf * A pointer to an initialized dynamic mobility buffer. See ipmip_buffer.h * for more information regarding dynamic buffers and their capabilities. * \ie * * RETURNS: No return value * * ERRNO: * * */ IP_GLOBAL void ipmip_buffer_release ( Ipmip_buffer_t *buf ); /******************************************************************************* * * ipmip_buffer_shrink - ipmip_buffer_shrink * * Shrink the used buffer space to the provided value. Will move the offset * and size pointers to resize the buffer. No memory will be freed by this * function. Any subsequent append or get operation will reuse memory * marked as unused by this routine. * * Parameters: * \is * \i buf * A pointer to an initialized dynamic mobility buffer. See ipmip_buffer.h * for more information regarding dynamic buffers and their capabilities. * \i size * The size of the buffer * \ie * * RETURNS: No return value * * ERRNO: * * */ IP_GLOBAL void ipmip_buffer_shrink ( Ipmip_buffer_t *buf, Ip_size_t size ); /******************************************************************************* * * ipmip_buffer_delete_header - ipmip_buffer_delete_header * * Remove the size first bytes of the buffer. * * Parameters: * \is * \i buf * A pointer to an initialized dynamic mobility buffer. See ipmip_buffer.h * for more information regarding dynamic buffers and their capabilities. * \i size * The size to remove * \ie * * RETURNS: No return value * * ERRNO: * * */ IP_GLOBAL void ipmip_buffer_delete_header ( Ipmip_buffer_t *buf, Ip_size_t size ); /******************************************************************************* * * ipmip_buffer_delete_tail - ipmip_buffer_delete_tail * * Remove the size last bytes of the buffer. Will invoke ipmip_buffer_shrink * with the appropriate parameters. * * Parameters: * \is * \i buf * A pointer to an initialized dynamic mobility buffer. See ipmip_buffer.h * for more information regarding dynamic buffers and their capabilities. * \i size * The size to remove * \ie * * RETURNS: No return value * * ERRNO: * * */ IP_GLOBAL void ipmip_buffer_delete_tail ( Ipmip_buffer_t *buf, Ip_size_t size ); /******************************************************************************* * * ipmip_buffer_reserve - ipmip_buffer_reserve * * Increase the available buffer [allocated memory] with the * provided value if ncessary. If there is not enough memory available to * serve the request, the memory block associated with the buffer will * be re-allocated. * * Parameters: * \is * \i buf * A pointer to an initialized dynamic mobility buffer. See ipmip_buffer.h * for more information regarding dynamic buffers and their capabilities. * \i size * The size to expand with. * \ie * * RETURNS: IP_TRUE if successful * * ERRNO: * * */ IP_GLOBAL Ip_bool ipmip_buffer_reserve ( Ipmip_buffer_t *buf, Ip_size_t size ); /******************************************************************************* * * ipmip_buffer_append - ipmip_buffer_append * * Append data to a buffer pointer. Will invoke ipmip_buffer_reserve if not * enough space is available to serve the request. * * Parameters: * \is * \i buf * A pointer to an initialized dynamic mobility buffer. See ipmip_buffer.h * for more information regarding dynamic buffers and their capabilities. * \i data * Data block * \i size * Size of data block. * \ie * * RETURNS: The offset to the stored data if successful, -1 otherwise. * * ERRNO: * * */ IP_GLOBAL int ipmip_buffer_append ( Ipmip_buffer_t *buf, const void *data, Ip_size_t size ); /******************************************************************************* * * ipmip_buffer_zero - ipmip_buffer_zero * * Append zero data to a buffer pointer. Will reserve a block of size bytes * and guarantee that it is properly memset to 0. * * Parameters: * \is * \i buf * A pointer to an initialized dynamic mobility buffer. See ipmip_buffer.h * for more information regarding dynamic buffers and their capabilities. * \i size * Size of data block. * \ie * * RETURNS: The offset to the stored data if successful, -1 otherwise. * * ERRNO: * * */ IP_GLOBAL int ipmip_buffer_zero ( Ipmip_buffer_t *buf, Ip_size_t size ); /******************************************************************************* * * ipmip_buffer_assign - ipmip_buffer_assign * * Assign the buffer values held by sbuf to dbuf, and * release anything previously held by dbuf. * * Parameters: * \is * \i dbuf * Buffer pointer. * \i sbuf * Buffer pointer * \ie * * RETURNS: No return value * * ERRNO: * */ IP_GLOBAL void ipmip_buffer_assign ( Ipmip_buffer_t *dbuf, Ipmip_buffer_t *sbuf ); /******************************************************************************* * * ipmip_buffer_get - ipmip_buffer_get * * Append size bytes and return the pointer to the * verified block; this pointer is only valid until the next * append call. * Parameters: * \is * \i buf * A pointer to an initialized dynamic mobility buffer. See ipmip_buffer.h * for more information regarding dynamic buffers and their capabilities. * \i size * Size of data block. * \ie * * RETURNS: The pointer * * ERRNO: * * */ IP_GLOBAL void* ipmip_buffer_get ( Ipmip_buffer_t *buf, Ip_size_t size ); /******************************************************************************* * * ipmip_buffer_get_zero - ipmip_buffer_get_zero * * Append size bytes and return the pointer to the * verified block; this pointer is only valid until the next * append call. The memory area will be zeroed * Parameters: * \is * \i buf * A pointer to an initialized dynamic mobility buffer. See ipmip_buffer.h * for more information regarding dynamic buffers and their capabilities. * \i size * Size of data block. * \ie * * RETURNS: The pointer * * ERRNO: * * */ IP_GLOBAL void* ipmip_buffer_get_zero ( Ipmip_buffer_t *buf, Ip_size_t size ); /******************************************************************************* * * ipmip_buffer_offset - ipmip_buffer_offset * * Return the pointer to the offset. This pointer is only valid until * the buffer is modified by an append, reserve or get call. * * Parameters: * \is * \i buf * A pointer to an initialized dynamic mobility buffer. See ipmip_buffer.h * for more information regarding dynamic buffers and their capabilities. * \i offset * The offset * \ie * * RETURNS: The pointer * * ERRNO: * * */ IP_GLOBAL void* ipmip_buffer_offset ( Ipmip_buffer_t *buf, int offset ); #ifdef __cplusplus } #endif #endif /* **************************************************************************** * END OF FILE **************************************************************************** */