You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
568 lines
13 KiB
568 lines
13 KiB
/**
|
|
* Copyright (c) 2019, The Linux Foundation. All rights reserved.
|
|
*
|
|
* Redistribution and use in source and binary forms, with or without
|
|
* modification, are permitted provided that the following conditions are
|
|
* met:
|
|
* * Redistributions of source code must retain the above copyright
|
|
* notice, this list of conditions and the following disclaimer.
|
|
* * 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.
|
|
* * Neither the name of The Linux Foundation 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 "AS IS" AND ANY EXPRESS OR IMPLIED
|
|
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
|
|
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT
|
|
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER 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 */
|
|
|