diff options
Diffstat (limited to 'include/AEEBufBound.h')
| -rw-r--r-- | include/AEEBufBound.h | 568 |
1 files changed, 568 insertions, 0 deletions
diff --git a/include/AEEBufBound.h b/include/AEEBufBound.h new file mode 100644 index 0000000..4146ba6 --- /dev/null +++ b/include/AEEBufBound.h @@ -0,0 +1,568 @@ +/* +* Copyright (c) 2017, The Linux Foundation. All rights reserved. +* All rights reserved. +* +* Redistribution and use in source and binary forms, with or without +* modification, are permitted provided that the following conditions are met: +* +* 1. Redistributions of source code must retain the above copyright notice, +* this list of conditions and the following disclaimer. +* +* 2. Redistributions in binary form must reproduce the above copyright notice, +* this list of conditions and the following disclaimer in the documentation +* and/or other materials provided with the distribution. +* +* 3. Neither the name of the copyright holder nor the names of its contributors +* may be used to endorse or promote products derived from this software without +* specific prior written permission. +* +* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE +* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +* POSSIBILITY OF SUCH DAMAGE. +*/ +#ifndef AEEBUFBOUND_H +#define AEEBUFBOUND_H +/*============================================================================== + +FILE: AEEBufBound.h + +SERVICES: + BufBound APIs + +GENERAL DESCRIPTION: + BufBound provides a "bounded buffer" API that facilitates + measuring strings or character output. It's design accomodates + the implementation of functions that can have the same exact logic + for measuring and outputting char buffer content. + +REVISION HISTORY: + Fri Aug 08 17:38:29 2003: Created + +==============================================================================*/ + +typedef struct BufBound +{ + char *pcBuf; /* original buffer */ + char *pcWrite; /* write pointer */ + char *pcEnd; /* first illegal write pointer */ +} BufBound; + +#ifdef __cplusplus +extern "C" { +#endif /* #ifdef __cplusplus */ + +extern void BufBound_Init(BufBound *me, char *pBuf, int nLen); +extern void BufBound_Write(BufBound *me, const char *pc, int nLen); +extern void BufBound_Putc(BufBound *me, char c); +extern void BufBound_Putnc(BufBound *me, char c, int nCount); +extern void BufBound_ForceNullTerm(BufBound *me); +extern void BufBound_Puts(BufBound *me, const char *cpsz); +extern void BufBound_Advance(BufBound *me, int nLen); +extern void BufBound_WriteLE(BufBound *me, + const void *pvSrc, int nSrcSize, + const char *pszFields); +extern void BufBound_WriteBE(BufBound *me, + const void *pvSrc, int nSrcSize, + const char *pszFields); +extern int BufBound_BufSize(BufBound *me); +extern int BufBound_Left(BufBound *me); +extern int BufBound_ReallyWrote(BufBound *me); +extern int BufBound_Wrote(BufBound *me); + +static __inline int BufBound_IsFull(BufBound *me) +{ + return (BufBound_Left(me) <= 0); +} + +// Deprecated: +static __inline int BufBound_IsCounter(BufBound *me) +{ + return BufBound_BufSize(me) == 0; +} + +#ifdef __cplusplus +} +#endif /* #ifdef __cplusplus */ + + +/*===================================================================== +======================================================================= +DATA STRUCTURE DOCUMENTATION +======================================================================= + +BufBound + +Description: + An BufBound keeps track of whether appending to a bounded buffer + has overflowed. + +Definition: + typedef struct BufBound + { + char* pcBuf; + char* pcWrite; + char* pcEnd; + } BufBound; + +Members: + pcBuf: original start pointer + pcWrite: current write location + pcEnd: first illegal write position + +See Also: + BufBound Interface + +======================================================================= +INTERFACE DOCUMENTATION +======================================================================= +BufBound Interface + + BufBound is a statically-linked interface. + + BufBound provides functions for safely appending to a character buffer. On + initialization, the buffer start address and size are provided. Subsequent + write operations are checked against the buffer bounds. + + Once the buffer bounds are exceeded, no bytes will be written but the + BufBound will continue to increment its internal "write pointer" to reflect + the number of bytes that would have been written (had the bounds not been + exceeded). + + When initialized with a buffer size of zero, a BufBound simply counts the + number of bytes that would be required to contain the result. This design + accommodates implementations that use the same logic for generating output + and measuring the space required for generated output. + + BufBound protects clients from numerical overflow by limiting the write + pointer to a maximum offset of INT_MAX from the start of the buffer. + Functions that write data into the buffer safely ignore negative size inputs + (Write and Putnc). + +======================================================================= +BufBound_Init() + +Description: + initialize a BufBound for appending to a buffer + +Prototype: + + void BufBound_Init(BufBound *me, char *pBuf, int nLen); + +Parameters: + me: the BufBound + pBuf: the bounded buffer + nLen: size of pBuf, in bytes + +Return Value: + None + +Comments: + None + +Side Effects: + None + +See Also: + None + +======================================================================= + +BufBound_Write() + +Description: + Appends some number of bytes to a BufBound, if possible. + + When a negative size is passed, it is safely treated as zero. + +Prototype: + + void BufBound_Write(BufBound *me, const char *pc, int nLen); + +Parameters: + me: the BufBound + pc: pointer to bytes to append + int nLen: number of bytes to write + +Return Value: + None + +Comments: + If the BufBound has overflowed, no bytes are written, but pcWrite is + *always* advanced by nLen. + +Side Effects: + None + +See Also: + None + +======================================================================= + +BufBound_Advance() + +Description: + + Moves the write pointer. Advance is like a relative seek operation. It + does not change the contents of the buffer, so when using a forward seek + (positive advance) be careful of advancing over uninitialized data. + + Negative numbers will decrease the write pointer down to 0 (the start of + the buffer) and not below. Positive numbers will increase the write + pointer up to offset INT_MAX and not beyond. + +Prototype: + + void BufBound_Advance(BufBound *me, int nDelta); + +Parameters: + me: the BufBound + int nLen: number of bytes to advance + +Return Value: + None + +Comments: + None + +Side Effects: + None + +See Also: + None + +======================================================================= + +BufBound_Putc() + +Description: + Appends one byte to a BufBound, if possible. + +Prototype: + + void BufBound_Putc(BufBound *me, char c); + +Parameters: + me: the BufBound + c: the byte + +Return Value: + None + +Comments: + If the BufBound has overflowed, no byte is written, but pcWrite is + *always* advanced by 1. + +Side Effects: + None + +See Also: + None + + +======================================================================= + +BufBound_Putnc() + +Description: + Appends a byte to a BufBound repeatedly. + + When a negative size is passed, it is safely treated as zero. + +Prototype: + + void BufBound_Putnc(BufBound *me, char c, int nCount); + +Parameters: + me: the BufBound + c: the byte + nCount: number of times to append c + +Return Value: + None + +Comments: + If the BufBound has overflowed, no byte is written, but pcWrite is + *always* advanced by nCount. + +Side Effects: + None + +See Also: + None + + +======================================================================= + +BufBound_ForceNullTerm() + +Description: + Appends a null terminating character to a BufBound, if possible. + If the BufBound has overflowed, the last legal location is + set to '\0'. + +Prototype: + void BufBound_ForceNullTerm(BufBound *me); + +Parameters: + me: the BufBound + +Return Value: + None + +Comments: + pcWrite is *always* advanced by 1. + +Side Effects: + None + +See Also: + None + + +======================================================================= + +BufBound_Puts() + +Description: + Appends a null-terminated string to a BufBound, if possible + +Prototype: + + void BufBound_Puts(BufBound *me, const char* cpsz); + +Parameters: + me: the BufBound + cpsz: the string to append + +Return Value: + +Comments: + If the BufBound has overflowed, no bytes are written, but pcWrite is + *always* advanced by strlen(cpsz). + +Side Effects: + None + +See Also: + None + + +======================================================================= + +BufBound_BufSize() + +Description: + Returns the size of the buffer owned by the BufBound. This is + the same as the number passed to BufBound_Init (MAXed with zero). + +Prototype: + + int BufBound_IsCounter(BufBound* me); + +Parameters: + me: the BufBound + +Return Value: + 1 if the BufBound is a counter, 0 otherwise + +Comments: + None + +Side Effects: + None + +See Also: + None + + +======================================================================= + +BufBound_Left() + +Description: + Returns the number of bytes the BufBound can still accomodate, + without overflowing. If overflow has occurred, it will return + a negative number. + +Prototype: + + int BufBound_Left(BufBound* me); + +Parameters: + me: the BufBound + +Return Value: + The number of bytes the BufBound can still accomodate, + without overflowing. + +Comments: + The return value may be negative, if overflow has already occurred. + +Side Effects: + None + +See Also: + None + + +======================================================================= + +BufBound_ReallyWrote() + +Description: + Returns the number of bytes actually written to the BufBound, + not including any overflow. + +Prototype: + + int BufBound_ReallyWrote(BufBound* me); + +Parameters: + me: the BufBound + +Return Value: + The number of bytes actually written to the BufBound, + not including any overflow. + +Comments: + None + +Side Effects: + None + +See Also: + None + + +======================================================================= + +BufBound_Wrote() + +Description: + + Returns the number of bytes written to the BufBound, including any + overflow, up to INT_MAX. + +Prototype: + + int BufBound_Wrote(BufBound* me); + +Parameters: + me: the BufBound + +Return Value: + + The number of bytes written to the BufBound, including any overflow. + +Comments: + None + +Side Effects: + None + +See Also: + None + + +======================================================================= + +BufBound_IsFull() + +Description: + Tests whether an AEEBuffBound has overflowed. + +Prototype: + + int BufBound_IsFull(BufBound* me); + +Parameters: + me: the BufBound + +Return Value: + 1 if the BufBound has overflowed, 0 otherwise + +Comments: + None + +Side Effects: + None + +See Also: + None + +======================================================================= + +BufBound_WriteLE() + +Description: + + Writes data while translating numeric values between host byte ordering and + "little endian" byte ordering. + + The input buffer is treated as an array of structures. The 'abySizes' + parameter describes the sizes of fields in the structure. + + When the host byte ordering matches the target byte ordering (little + endian) this operation is equivalent to BufBound_Write(). + +Prototype: + + void BufBound_WriteLE(BufBound* me, + const void *pvSrc, int nSrcSize, + const unsigned char *pszFields); + +Parameters: + me: the BufBound + pvSrc: the source buffer + nSrcSize: number of bytes to copy from the source buffer + pszFields: Description of the fields that comprise the source data, + as defined in std_CopyLE. + +Return Value: + None + +See Also: + BufBound_WriteBE, std_CopyLE + +======================================================================= + +BufBound_WriteBE() + +Description: + + BufBounf_WriteBE() has the same semantics as BufBound_WriteLE() except it + copies between host byte ordering and big-endian ("network") byte order. + + See BufBound_WriteLE() for more details. + + +Prototype: + + void BufBound_WriteBE(BufBound* me, + const void *pvSrc, int nSrcSize, + const unsigned char *pszFields); + +Parameters: + me: the BufBound + pvSrc: the source buffer + nSrcSize: number of bytes to copy from the source buffer + pszFields: Description of the fields that comprise the source data, + as defined in std_CopyLE. + +Return Value: + None + +See Also: + BufBound_WriteLE, std_CopyBE + +======================================================================= */ +#endif /* #ifndef AEEBUFBOUND_H */ + |