CCircBuf Class Reference

Implements a circular buffer. More...

#include <CircBuf.h>

Inheritance diagram for CCircBuf:

[legend]Collaboration diagram for CCircBuf:


Public Member Functions
BOOL	Init ()
	Initializes the circular buffer.
BOOL	WaitData (DWORD dwTimeout=INFINITE)
	Waits for data to be written to the circular buffer.
HANDLE	GetDataReadyHandle ()
	Returns a pointer to the data ready event handle.
BOOL	GetWriteView (DWORD dwView, DWORD dwOffset, DWORD dwSize, LPBYTE *pBuf, LPDWORD pdwSize)
	Returns a view of the buffer with respect to the write pointer.
BOOL	GetReadView (DWORD dwView, DWORD dwOffset, DWORD dwSize, LPBYTE *pBuf, LPDWORD pdwSize)
	Returns a view of the buffer with respect to the read pointer.
DWORD	NormalizePtr (DWORD dwPtr, DWORD dwMax)
	Wraps the specified pointer.
BOOL	AdvanceReadPtr (long lStep)
	Advances the read pointer.
BOOL	AdvanceWritePtr (long lStep)
	Advances the write pointer.
void	Defrag ()
	Defragments the circular buffer.
DWORD	EnsureWriteSpace (DWORD dwSize, DWORD dwReadPtr, DWORD dwWritePtr, DWORD dwMax)
	Ensures space is available for write by growing buffer if needed.
DWORD	Resize (DWORD dwNewSize)
	Resizes the buffer without losing the data within.
BOOL	Read (LPSTR pStr, DWORD dwMax)
	Read a string from the buffer.
BOOL	Write (LPCTSTR pStr)
	Write a string to the buffer.
DWORD	GetMaxWrite ()
	Returns the maximum amount of data that can be written to the buffer.
DWORD	GetMaxRead ()
	Returns the maximum amount of data that can be read from the buffer.
void	Destroy ()
	Releases all resources associated with the circular buffer.
BOOL	Write (void const *pBuf, DWORD dwSize, LPDWORD pdwPtr, DWORD dwEncode=0)
	Writes specified data to the circular buffer.
virtual BOOL	Write (void const *pBuf, DWORD dwSize, DWORD dwEncode=0)
	Writes specified data to the circular buffer.
void	InitPoke ()
	Used for revokable writing to buffer.
void	CancelPoke ()
	Cancels a poke operation.
BOOL	Poke (void const *pBuf, DWORD dwSize, DWORD dwEncode=0)
	Pokes data into the buffer.
BOOL	EndPoke ()
	Committs the poked data to the buffer.
DWORD	GetPokeSize ()
	Returns the size of currently poked data.
virtual BOOL	OnWrite ()
	Called when data is written to the circular buffer.
BOOL	Read (LPVOID pBuf, DWORD dwMax, LPDWORD pdwRead, LPDWORD pdwPtr, DWORD dwEncode=0)
	Call to read and remove data from the circular buffer.
virtual BOOL	Read (LPVOID pBuf, DWORD dwMax, LPDWORD pdwRead, DWORD dwEncode=0)
	Call to read and remove data from the circular buffer.
BOOL	Peek (LPVOID pBuf, DWORD dwMax, LPDWORD pdwRead, long lOffset=0, DWORD dwEncode=0)
	Call to read data from the buffer without removing it.
BOOL	Allocate (DWORD dwSize)
	Pre allocates the specified amount of data for the circular buffer.
	CCircBuf (BOOL bSync=TRUE, DWORD dwSize=0, BOOL bAutoGrow=TRUE)
	Constructor.
virtual	~CCircBuf ()
	Destructor.
void	SetReadPtr (DWORD dwPtr)
	Sets the position of the read pointer.
DWORD	GetReadPtr ()
	Returns the position of the read pointer.
void	SetWritePtr (DWORD dwPtr)
	Sets the position of the write pointer.
DWORD	GetWritePtr ()
	Returns the position of the write pointer.
	operator CTlLock * ()
	Returns a pointer for the buffers thread locking class.
void	SetMaxSize (DWORD dwMaxSize)
	Sets the maximum size the buffer can grow.
DWORD	GetMaxSize ()
	Returns the maximum size the buffer can grow.
void	SetAutoGrow (BOOL b)
	Enables / disables the auto resizing feature of CCircBuf.
BOOL	GetAutoGrow ()
	Returns the auto grow status.
BOOL	IsEmpty ()
	Provides a quick way to check for read data availability.
void	DataReady ()
	Call this function to signal that data is ready to be read.
BOOL	Empty ()
	Empties the circular buffer.
virtual BOOL	OnInspectRead (DWORD dwBlock, LPBYTE pBuf, DWORD dwSize)
	Over-ride to implement read block inspection.
virtual BOOL	OnInspectWrite (DWORD dwBlock, LPBYTE pBuf, DWORD dwSize)
	Over-ride to implement write block inspection.
virtual BOOL	OnEncode (DWORD dwType, DWORD dwBlock, LPBYTE pBuf, DWORD dwSize)
virtual BOOL	OnDecode (DWORD dwType, DWORD dwBlock, LPBYTE pBuf, DWORD dwSize)
DWORD	GetBufferSize ()
	Returns the size of the buffer.
Static Public Member Functions
static DWORD	AdvancePtr (DWORD dwPtr, long lStep, DWORD dwMax)
	Advances a pointer.
static BOOL	GetView (DWORD dwView, DWORD dwPtr, DWORD dwSize, LPBYTE pRing, DWORD dwMax, LPBYTE *pBuf, LPDWORD pdwSize)
	Returns the desired view of a specified data segment.
static DWORD	GetMaxWrite (DWORD dwReadPtr, DWORD dwWritePtr, DWORD dwMax)
	Returns the maximum amount of data that can be written to the buffer.
static DWORD	GetMaxRead (DWORD dwReadPtr, DWORD dwWritePtr, DWORD dwMax)
	Returns the maximum amount of data that can be read from the buffer.

Detailed Description

Implements a circular buffer.

This class encapsulates the functionality of a cicular buffer. It is specifically designed for buffering serial and network communications. It has hooks for supporting packetizing, compression, and encryption. Efficiency is maintained by allowing inplace operations on the data through the use of views.

Member Function Documentation

DWORD CCircBuf::AdvancePtr ( DWORD dwPtr,

long lStep,

DWORD dwMax

) [static]

Advances a pointer.

Parameters:

[in] dwPtr - Current pointer value

[in] lStep - Amount to add to pointer

[in] dwMax - Maximum size of buffer

Returns:
New pointer value

See also:

BOOL CCircBuf::AdvanceReadPtr ( long lStep ) [inline]

Advances the read pointer.

Parameters:

[in] lStep - Number of bytes to advance read pointer.

Returns:
Non-zero if success, otherwise zero.

See also:

BOOL CCircBuf::AdvanceWritePtr ( long lStep ) [inline]

Advances the write pointer.

Parameters:

[in] lStep - Number of bytes to advance write pointer

Returns:
Non-zero if success

See also:

BOOL CCircBuf::Allocate ( DWORD dwSize )

Pre allocates the specified amount of data for the circular buffer.

Parameters:

[in] dwSize - Number of bytes to allocate.

Returns:
Non-zero if success

See also:

void CCircBuf::CancelPoke ( ) [inline]

Cancels a poke operation.

See also:
InitPoke(), Poke(), EndPoke(), GetPokeSize()

void CCircBuf::Defrag ( )

Defragments the circular buffer.
Resets read and write pointers to zero if buffer is empty. This attempts to keep the buffer from wrapping

BOOL CCircBuf::Empty ( ) [inline]

Empties the circular buffer.

Returns:
Non-zero if success.

BOOL CCircBuf::EndPoke ( ) [inline]

Committs the poked data to the buffer.

Returns:
Non-zero if success

See also:
InitPoke(), CancelPoke(), Poke(), GetPokeSize()

DWORD CCircBuf::EnsureWriteSpace ( DWORD dwSize,

DWORD dwReadPtr,

DWORD dwWritePtr,

DWORD dwMax

)

Ensures space is available for write by growing buffer if needed.

Parameters:

[in] dwSize - Number of bytes required.

[in] dwReadPtr - Position of read pointer.

[in] dwWritePtr - Position of write pointer.

[in] dwMax - Maximum size of buffer.

Checks to ensure the specified amount of space is available for writing. If it is not, the function creates it without losing data that is in the buffer.

Returns:
Space available

See also:

BOOL CCircBuf::GetAutoGrow ( ) [inline]

Returns the auto grow status.

Returns:
Non-zero if auto-grow is enabled.

See also:
SetAutoGrow(), SetMaxSize(), GetMaxSize()

DWORD CCircBuf::GetBufferSize ( ) [inline]

Returns the size of the buffer.

Returns:
Total size of the circular buffer

DWORD CCircBuf::GetMaxRead ( ) [inline]

Returns the maximum amount of data that can be read from the buffer.

Returns:
Number of bytes that can be read

DWORD CCircBuf::GetMaxRead ( DWORD dwReadPtr,

DWORD dwWritePtr,

DWORD dwMax

) [static]

Returns the maximum amount of data that can be read from the buffer.

Parameters:

[in] dwReadPtr - Position of read pointer.

[in] dwWritePtr - Position of write pointer.

[in] dwMax - Total size of circular buffer

Returns:
Number of bytes that can be read

See also:

DWORD CCircBuf::GetMaxSize ( ) [inline]

Returns the maximum size the buffer can grow.

Returns:
Returns the maximum size for the circular buffer.

See also:
GetAutoGrow(), SetAutoGrow(), SetMaxSize()

DWORD CCircBuf::GetMaxWrite ( ) [inline]

Returns the maximum amount of data that can be written to the buffer.

Returns:
Number of bytes that can be written

DWORD CCircBuf::GetMaxWrite ( DWORD dwReadPtr,

DWORD dwWritePtr,

DWORD dwMax

) [static]

Returns the maximum amount of data that can be written to the buffer.

Parameters:

[in] dwReadPtr - Position of read pointer.

[in] dwWritePtr - Position of write pointer.

[in] dwMax - Total size of circular buffer

Returns:
Number of bytes that can be written

See also:

DWORD CCircBuf::GetPokeSize ( ) [inline]

Returns the size of currently poked data.

Returns:
Number of bytes currently poked

See also:
InitPoke(), CancelPoke(), Poke(), EndPoke()

DWORD CCircBuf::GetReadPtr ( ) [inline]

Returns the position of the read pointer.

Returns:
read pointer position

BOOL CCircBuf::GetReadView ( DWORD dwView,

DWORD dwOffset,

DWORD dwSize,

LPBYTE * pBuf,

LPDWORD pdwSize

) [inline]

Returns a view of the buffer with respect to the read pointer.

Parameters:

[in] dwView - Index of the view to return.

[in] dwOffset - Offset from the read pointer of data segment.

[in] dwSize - Total size of data segment

[out] pBuf - Pointer receives pointer to start of view

[out] pdwSize - Receives the size of this view.

To view all of data segment, call with dwView set to 0, increment on each call until GetReadView() returns zero.

Returns:
Non-zero if success.

See also:
GetWriteView

BOOL CCircBuf::GetView ( DWORD dwView,

DWORD dwPtr,

DWORD dwSize,

LPBYTE pRing,

DWORD dwMax,

LPBYTE * pBuf,

LPDWORD pdwSize

) [static]

Returns the desired view of a specified data segment.

Parameters:

[in] dwView - Index of the view to return.

[in] dwPtr - Offset of the start of the segment.

[in] dwSize - Total size of the segment.

[in] pRing - Pointer to the start of the buffer.

[in] dwMax - Size of the buffer

[out] pBuf - Pointer to start of view

[out] pdwSize - Size of this view segment.

Returns:
Non-zero if success

See also:

DWORD CCircBuf::GetWritePtr ( ) [inline]

Returns the position of the write pointer.

Returns:
write pointer position

BOOL CCircBuf::GetWriteView ( DWORD dwView,

DWORD dwOffset,

DWORD dwSize,

LPBYTE * pBuf,

LPDWORD pdwSize

) [inline]

Returns a view of the buffer with respect to the write pointer.

Parameters:

[in] dwView - Index of the view to return.

[in] dwOffset - Offset from the write pointer of data segment.

[in] dwSize - Total size of data segment

[out] pBuf - Pointer receives pointer to start of view

[out] pdwSize - Receives the size of this view.

To view all of data segment, call with dwView set to 0, increment on each call until GetWriteView() returns zero.

Returns:
Non-zero if success.

See also:
GetReadView

BOOL CCircBuf::Init ( )

Initializes the circular buffer.

Returns:
Non-zero if success.

See also:

void CCircBuf::InitPoke ( ) [inline]

Used for revokable writing to buffer.
Used for putting data into the buffer without committing it. Usefull if you may fail while writing multi-part data.

See also:
CancelPoke(), Poke(), EndPoke(), GetPokeSize()

BOOL CCircBuf::IsEmpty ( ) [inline]

Provides a quick way to check for read data availability.

Returns:
Non-zero if data can be read from the buffer.

DWORD CCircBuf::NormalizePtr ( DWORD dwPtr,

DWORD dwMax

)

Wraps the specified pointer.

Parameters:

[in] dwPtr - Pointer position

[in] dwMax - Maximum buffer position

The pointer may point to the byte after the buffer, this wraps it

Returns:
Returns dwPtr wrapped to dwMax

See also:

virtual BOOL CCircBuf::OnDecode ( DWORD dwType,

DWORD dwBlock,

LPBYTE pBuf,

DWORD dwSize

) [inline, virtual]

Parameters:

[in] dwType - Type of encoding to perform

[in] dwBlock - Index of block

[in] pBuf - Pointer to data

[in] dwSize - Size of buffer in pBuf

Returns:
Non-zero if success

See also:

virtual BOOL CCircBuf::OnEncode ( DWORD dwType,

DWORD dwBlock,

LPBYTE pBuf,

DWORD dwSize

) [inline, virtual]

Parameters:

[in] dwType - Type of encoding to perform

[in] dwBlock - Index of block

[in] pBuf - Pointer to data

[in] dwSize - Size of buffer in pBuf

Returns:
Non-zero if success

See also:

virtual BOOL CCircBuf::OnInspectRead ( DWORD dwBlock,

LPBYTE pBuf,

DWORD dwSize

) [inline, virtual]

Over-ride to implement read block inspection.

Parameters:

[in] dwBlock - Index of block

[in] pBuf - Pointer to data

[in] dwSize - Size of buffer in pBuf

Returns:
Non-zero if success

See also:

virtual BOOL CCircBuf::OnInspectWrite ( DWORD dwBlock,

LPBYTE pBuf,

DWORD dwSize

) [inline, virtual]

Over-ride to implement write block inspection.

Parameters:

[in] dwBlock - Index of block

[in] pBuf - Pointer to data

[in] dwSize - Size of buffer in pBuf

Returns:
Non-zero if success

See also:

Reimplemented in CDataPacket.

virtual BOOL CCircBuf::OnWrite ( ) [inline, virtual]

Called when data is written to the circular buffer.

Returns:
Non-zero if success
Over-ride this function to provide write data handling.

See also:

Reimplemented in CNetMsg.

BOOL CCircBuf::Peek ( LPVOID pBuf,

DWORD dwMax,

LPDWORD pdwRead,

long lOffset = 0,

DWORD dwEncode = 0

)

Call to read data from the buffer without removing it.

Parameters:

[in] pBuf - Buffer that receives peeked data

[in] dwMax - Size of the buffer in pBuf

[in] pdwRead - Number of bytes read into pBuf

[in] lOffset - Offset from read pointer to start

[in] dwEncode - Optional data decoding

Returns:
Non-zero if success.

See also:

Reimplemented in CFifoSync.

BOOL CCircBuf::Poke ( void const * pBuf,

DWORD dwSize,

DWORD dwEncode = 0

) [inline]

Pokes data into the buffer.

Parameters:

[in] pBuf - Data to poke into write buffer

[in] dwSize - Size of pBuf

[in] dwEncode - Optional data encoding

Returns:
Non-zero if success

See also:
InitPoke(), CancelPoke(), EndPoke(), GetPokeSize()

BOOL CCircBuf::Read ( LPVOID pBuf,

DWORD dwMax,

LPDWORD pdwRead,

DWORD dwEncode = 0

) [virtual]

Call to read and remove data from the circular buffer.

Parameters:

[out] pBuf - Buffer to receive read data.

[in] dwMax - Size of buffer in pBuf

[out] pdwRead - Receives number of bytes read

[in] dwEncode - Optional decoding

Returns:
Non-zero if success, otherwise zero.

See also:

Reimplemented in CFifoSync.

BOOL CCircBuf::Read ( LPVOID pBuf,

DWORD dwMax,

LPDWORD pdwRead,

LPDWORD pdwPtr,

DWORD dwEncode = 0

)

Call to read and remove data from the circular buffer.

Parameters:

[out] pBuf - Buffer to receive read data.

[in] dwMax - Size of buffer in pBuf

[out] pdwRead - Receives number of bytes read

[out] pdwPtr - Receives read pointer

[in] dwEncode - Optional decoding

Returns:
Non-zero if success, otherwise zero.

See also:

BOOL CCircBuf::Read ( LPSTR pStr,

DWORD dwMax

)

Read a string from the buffer.

Parameters:

[in] pStr - Buffer to hold string

[in] dwMax - Size of buffer in pStr.

Returns:
Non-zero if success

See also:

DWORD CCircBuf::Resize ( DWORD dwNewSize )

Resizes the buffer without losing the data within.

Parameters:

[in] dwNewSize - New size for circular buffer

Returns:
New size of buffer

See also:

void CCircBuf::SetAutoGrow ( BOOL b ) [inline]

Enables / disables the auto resizing feature of CCircBuf.

Parameters:

[in] b - Non-zero to enable resizing, zero to disable.

Sets auto grow enable / disable. If auto grow is enabled, the buffer will automatically resized to accomidate any write less than m_dwMaxSize.

See also:
GetAutoGrow(), SetMaxSize(), GetMaxSize()

void CCircBuf::SetMaxSize ( DWORD dwMaxSize ) [inline]

Sets the maximum size the buffer can grow.

Parameters:

[in] dwMaxSize - Sets the maximum size for the circular buffer

Warning:
This should really be set to something reasonable!

See also:
SetAutoGrow(), SetAutoGrow(), SetMaxSize()

void CCircBuf::SetReadPtr ( DWORD dwPtr ) [inline]

Sets the position of the read pointer.

Parameters:

[in] dwPtr - New value for read pointer.

void CCircBuf::SetWritePtr ( DWORD dwPtr ) [inline]

Sets the position of the write pointer.

Parameters:

[in] dwPtr - New value for write pointer.

BOOL CCircBuf::WaitData ( DWORD dwTimeout = INFINITE )

Waits for data to be written to the circular buffer.

Parameters:

[in] dwTimeout - Maximum number of milliseconds to wait for data.

Returns:
Non-zero if data was received before timeout expired.

See also:

virtual BOOL CCircBuf::Write ( void const * pBuf,

DWORD dwSize,

DWORD dwEncode = 0

) [inline, virtual]

Writes specified data to the circular buffer.

Parameters:

[in] pBuf - Pointer to buffer containing data to be written.

[in] dwSize - Size of the buffer in pBuf.

[in] dwEncode - Optional encoding

Returns:
Non-zero on success

See also:

Reimplemented in CFifoSync.

BOOL CCircBuf::Write ( void const * pBuf,

DWORD dwSize,

LPDWORD pdwPtr,

DWORD dwEncode = 0

)

Writes specified data to the circular buffer.

Parameters:

[in] pBuf - Pointer to buffer containing data to be written.

[in] dwSize - Size of the buffer in pBuf.

[in] pdwPtr - Write pointer position

[in] dwEncode - Optional encoding

Returns:
Non-zero on success.

See also:

BOOL CCircBuf::Write ( LPCTSTR pStr )

Write a string to the buffer.

Parameters:

[in] pStr - String value to write to buffer

Returns:
Non-zero if success.

See also:

The documentation for this class was generated from the following files:

inc/CircBuf.h
CircBuf.cpp

CCircBuf Class Reference

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation