IT_Bus::BinaryBuffer Class Reference

#include <it_bus/binary_buffer.h>

Inheritance diagram for IT_Bus::BinaryBuffer:

List of all members.

---

Detailed Description

Class implementing the binary buffer.

The binary buffer class encapsulates a pointer to a character array, which contains the data content managed by the buffer. An instance of the binary buffer class may, or may not, be responsible for managing the memory allocated to the character array. This behavior is modified through the class' methods.

This class is the superclass for the classes representing the HexBinary and Base64Binary types.

Definition at line 27 of file binary_buffer.h.

Public Member Functions
	BinaryBuffer ()
	No argument constructor.
	BinaryBuffer (const BinaryBuffer &rhs)
	Copy constructor.
virtual	~BinaryBuffer ()
	Destructor.
	BinaryBuffer (String rhs)
	Constructor.
	BinaryBuffer (const char *data, long size=-1)
	Constructor.
void	operator= (const BinaryBuffer &rhs)
	Assignment operator.
void	operator= (String rhs)
	Assignment operator.
BinaryBuffer &	assign (const String &rhs, size_t n)
	Initialize the binary buffer with the string value.
void	operator= (const char *rhs)
	Assigment operator.
BinaryBuffer &	assign (const char *rhs, size_t n)
	Initialize the binary buffer with the contents of the character array.
char	operator[] (long lIndex)
	Indexing operator.
bool	operator== (const BinaryBuffer &rhs) const
	Equality operator.
void	attach (BinaryBuffer &attach_buffer)
	Set the data pointer in this binary buffer to the value in the data pointer in the binary buffer parameter.
void	borrow (const BinaryBuffer &borrow_buffer)
	Set the data pointer within this binary buffer to the value in the data pointer in the binary buffer parameter; both binary buffers point to the same memory allocation.
void	borrow (const char *borrow_data, long size=-1)
	Set the data pointer within this binary buffer to point to a character array.
bool	is_borrowing ()
	Returns true if this binary buffer instance does not assume responsibility for managing the memory allocated to the buffer content.
void	attach_external (char *p, long size, bool borrow=true)
	Set the data pointer within this binary buffer to point to a character array.
void	attach_external_const (const char *p, long size)
	Set the data pointer within this binary buffer to point to a const character array.
void	detach_external ()
	Null the data pointer, effectively emptying the binary buffer.
void	allocate (long size)
	Allocates memory for the binary buffer contents.
void	resize (long size) throw ((IT_Bus::Exception))
	Changes the size of the memory allocation managed by the binary buffer.
void	copy (const char *p, long size=-1)
	Allocates new memory and copies the data content from the memory identfied by the character pointer parameter.
void	clear ()
	Sets the internal pointer to null.
const char *	get_const_pointer () const
	Return the internal pointer to the character array representing the buffer content.
char *	get_pointer () throw ((IT_Bus::Exception))
	Return the internal pointer to the character array representing the buffer content.
long	get_size () const
	Returns the size of the memory allocated to the buffer content.
IT_String	get_it_string () const
	Returns an IT_String initialized with the buffer content.
char *	at (long lIndex)
	Returns a pointer to a specific character in the buffer.
String	substr (long lIndex, long size=-1) const
	Returns a substring from within the buffer.
long	find_binary_buffer (long &dwFindIdx, long dwFindMaxIdx, BinaryBuffer &vvPacketTerminator) const
	Returns the position in the buffer content of the search buffer.
char *	instr (char c, long lIndex=0)
	Returns a pointer to the position in the buffer content of the first occurrence of the search character.
long	find (const char *s, long lIndex=0) const
	Returns the position in the buffer content of the search string.
char *	concat (const char *szThisString, long size=-1)
	Concatenates a character array to the existing buffer content.
bool	empty () const
	Checks if the binary buffer is pointing to content.
String	get_string () const
	Return a String initialized with the buffer content.
Private Attributes
char *	m_data
	The pointer to the character array representing the buffer content.
long	m_size
	The length of the buffer content.
bool	m_just_borrowing
	Flag indicating whether the buffer content is borrowed.
bool	m_borrowed_const
	Flag indicating whether the borrowed content is const.

---

Constructor & Destructor Documentation

IT_Bus::BinaryBuffer::BinaryBuffer (   )

No argument constructor.

IT_Bus::BinaryBuffer::BinaryBuffer (  const BinaryBuffer &  rhs  )

Copy constructor.

IT_Bus::BinaryBuffer::BinaryBuffer (  String  rhs  )

Constructor.

IT_Bus::BinaryBuffer::BinaryBuffer (  const char *  data, long  size = -1 )

Constructor.

---

Member Function Documentation

void IT_Bus::BinaryBuffer::allocate (  long  size  )

Allocates memory for the binary buffer contents. If the binary buffer is not responsible for memory management of its current data, the current memory will not be released and additional memory will be allocated; the binary buffer will be responsible for this newly allocated memory. If the binary buffer is responsible for memory management of its current data, and the current memory allocation is a different size than the requested allocation, then the current memory is released and new memory allocated. The binary buffer will be responsible for this newly allocated memory. If the binary buffer is responsible for memory management of its current data, and the current memory allocation is the same size as the requested allocation, then the current memory is not released. The binary buffer retains responsibility for memory management. Parameters: Long  representing the requested memory allocation.

BinaryBuffer& IT_Bus::BinaryBuffer::assign (  const char *  rhs, size_t  n )

Initialize the binary buffer with the contents of the character array. The character array is copied into newly allocated memory. The binary buffer is responsible for managing this memory. Parameters: Pointer  to the character array. size_t  size of the binary buffer.

BinaryBuffer& IT_Bus::BinaryBuffer::assign (  const String &  rhs, size_t  n )

Initialize the binary buffer with the string value. The string is copied into newly allocated memory. The binary buffer is responsible for managing this memory. Parameters: String  to use in initializing the binary buffer. size_t  size of the binary buffer.

char* IT_Bus::BinaryBuffer::at (  long  lIndex  )

Returns a pointer to a specific character in the buffer. The following invocations return equivalent values. get_const_pointer()[lIndex] get_pointer()[lIndex] Parameters: Long  specifying the position (index) of the desired character. Returns: Pointer to the desired character. Exceptions: Exception  thrown if the index of the desired character is outside the bounds of the buffer.

void IT_Bus::BinaryBuffer::attach (  BinaryBuffer &  attach_buffer  )

Set the data pointer in this binary buffer to the value in the data pointer in the binary buffer parameter. Set the data pointer within the binary buffer parameter to null. If the binary buffer parameter was responsible for the managing the memory allocated to the buffer content, then this binary buffer assumes responsibility for managing the memory. If the binary buffer parameter was not responsible for managing the memory, then this binary buffer does not assume responsibility for the memory allocation. Parameters: BinaryBuffer  instance.

void IT_Bus::BinaryBuffer::attach_external (  char *  p, long  size, bool  borrow = true )

Set the data pointer within this binary buffer to point to a character array. Parameters: Pointer  to the character array. Long  indicating the size of the character array. boolean  indicating whether this binary buffer is borrowing the data content. If false, this binary buffer assumes responsibility for management of the memory allocated for the character array. If true (the default), the binary buffer is not responsible for memory management.

void IT_Bus::BinaryBuffer::attach_external_const (  const char *  p, long  size )

Set the data pointer within this binary buffer to point to a const character array. The binary buffer is not responsible for memory management. Parameters: Pointer  to the character array. Long  indicating the size of the character array.

void IT_Bus::BinaryBuffer::borrow (  const char *  borrow_data, long  size = -1 )

Set the data pointer within this binary buffer to point to a character array. This binary buffer instance does not assume responsibility for managing the memory allocated to the buffer content. Parameters: Pointer  to the character array. Long  indicating the size of the character array. If equal to -1 (the default), the method determines the length of the character array.

void IT_Bus::BinaryBuffer::borrow (  const BinaryBuffer &  borrow_buffer  )

Set the data pointer within this binary buffer to the value in the data pointer in the binary buffer parameter; both binary buffers point to the same memory allocation. This binary buffer instance does not assume responsibility for managing the memory allocated to the buffer content. Parameters: BinaryBuffer  instance.

void IT_Bus::BinaryBuffer::clear (   )

Sets the internal pointer to null. If the binary buffer is responsible for managing the memory allocated to the buffer content, the memory is released.

char* IT_Bus::BinaryBuffer::concat (  const char *  szThisString, long  size = -1 )

Concatenates a character array to the existing buffer content. Since this method requires a resizing of the buffer, it can only be invoked on a binary buffer instance that is responsible for managing the memory allocated to the buffer. The method uses the get_pointer() method, which will throw an exception if this binary buffer instance points to borrowed content. Parameters: Pointer  to the character array. Long  the number of characters to be concatenated to the buffer content. If this value is -1 (the default), the entire character array is concatenated to the buffer content.

void IT_Bus::BinaryBuffer::copy (  const char *  p, long  size = -1 )

Allocates new memory and copies the data content from the memory identfied by the character pointer parameter. The binary buffer is responsible for managing the newly allocated memory. The memory identified by the character pointer is not released. Parameters: Pointer  to the character array to be copied. Long  indicating the number of characters in the data. It this value is -1 (the default), the entire character data array is copied.

void IT_Bus::BinaryBuffer::detach_external (   )

Null the data pointer, effectively emptying the binary buffer. If the binary buffer was responsible for memory management, the buffer gives up that responsibility. The buffer does not, however, release the memory allocated to the content.

bool IT_Bus::BinaryBuffer::empty (   )  const [inline]

Checks if the binary buffer is pointing to content. Returns: bool true if the buffer is pointing to content. Definition at line 422 of file binary_buffer.h.

long IT_Bus::BinaryBuffer::find (  const char *  s, long  lIndex = 0 )  const

Returns the position in the buffer content of the search string. Parameters: Pointer  to the search string. Long  the position within the buffer to begin the search. If this value is zero (the default), the search starts at the beginning of the buffer. Returns: Long corresponding to the point in the buffer content where the search string begins. Exceptions: Exception  thrown if the start position is outside the bounds of the buffer.

long IT_Bus::BinaryBuffer::find_binary_buffer (  long &  dwFindIdx, long  dwFindMaxIdx, BinaryBuffer &  vvPacketTerminator )  const

Returns the position in the buffer content of the search buffer. Parameters: Long  the position within the buffer to begin the search. Long  the position within the buffer to stop the search, even if a match has not been made. A  reference to the search buffer. Returns: Long corresponding to the point in the buffer content where the search buffer begins.

const char* IT_Bus::BinaryBuffer::get_const_pointer (   )  const

Return the internal pointer to the character array representing the buffer content. This version of the method will return the pointer regardless of whether this binary buffer instance is responsible for managing the memory allocated to the buffer content. Returns: Pointer to the buffer content.

IT_String IT_Bus::BinaryBuffer::get_it_string (   )  const

Returns an IT_String initialized with the buffer content. Returns: IT_String of the buffer content.

char* IT_Bus::BinaryBuffer::get_pointer (   )  throw ((IT_Bus::Exception))

Return the internal pointer to the character array representing the buffer content. This version of the method will only return the pointer if this binary buffer instance is responsible for managing the memory allocated to the buffer content. Returns: Pointer to the buffer content. Exceptions: Exception  thrown if the buffer is not responsible for managing the memory allocated to the buffer content and the buffer is const.

long IT_Bus::BinaryBuffer::get_size (   )  const

Returns the size of the memory allocated to the buffer content. Returns: Long.

String IT_Bus::BinaryBuffer::get_string (   )  const

Return a String initialized with the buffer content. Returns: String of the buffer content.

char* IT_Bus::BinaryBuffer::instr (  char  c, long  lIndex = 0 )

Returns a pointer to the position in the buffer content of the first occurrence of the search character. Parameters: char  the search character. Long  the position within the buffer to begin the search. If this value is zero (the default), the search starts at the beginning of the buffer. Returns: Pointer to the location of the first occurrence of the character in the buffer content. Exceptions: Exception  thrown if the start position is outside the bounds of the buffer.

bool IT_Bus::BinaryBuffer::is_borrowing (   )

Returns true if this binary buffer instance does not assume responsibility for managing the memory allocated to the buffer content. Returns: true if the buffer is borrowing the data pointer.

void IT_Bus::BinaryBuffer::operator= (  const char *  rhs  )

Assigment operator. Parameters: Pointer  to character array

void IT_Bus::BinaryBuffer::operator= (  String  rhs  )

Assignment operator. Parameters: String  value

void IT_Bus::BinaryBuffer::operator= (  const BinaryBuffer &  rhs  )

Assignment operator. Parameters: BinaryBuffer  instance

bool IT_Bus::BinaryBuffer::operator== (  const BinaryBuffer &  rhs  )  const

Equality operator. Parameters: BinaryBuffer  instance for the comparison.

char IT_Bus::BinaryBuffer::operator[] (  long  lIndex  )

Indexing operator. Parameters: Long  the index.

void IT_Bus::BinaryBuffer::resize (  long  size  )  throw ((IT_Bus::Exception))

Changes the size of the memory allocation managed by the binary buffer. If the requested allocation size is the same as the current allocation, the method simply returns. If the binary buffer does not currently point to allocated memory, the method allocates the requested memory and returns. The binary buffer will be responsible for this newly allocated memory If the binary buffer is not responsible for memory management of its current data, the current memory will not be released and new memory will be allocated, copies the content currently pointed to by the buffer pointer into the new memory allocation; the binary buffer will be responsible for this newly allocated memory. Otherwise, the method allocates the requested memory, copies the content currently pointed to by the buffer pointer into the new memory allocation, and releases the current memory allocation. The buffer is responsible for managing the new memory allocation. Parameters: Long  which is the requested size of the memory allocation. Exceptions: Exception  thrown if the buffer is not responsible for managing the memory allocated to the buffer content and the buffer is const.

String IT_Bus::BinaryBuffer::substr (  long  lIndex, long  size = -1 )  const

Returns a substring from within the buffer. Parameters: Long  the position within the buffer to begin the substring. Long  the length of the substring. If this value is -1 (the default), the substring is from the start position to the end of the buffer. Exceptions: Exception  thrown if the start position is outside the bounds of the buffer.

---

Member Data Documentation

bool IT_Bus::BinaryBuffer::m_borrowed_const [private]

Flag indicating whether the borrowed content is const. If the borrowed buffer is const, certain operations like get_pointer will throw an exception as you cannot get a non-const-pointer if the content is const Definition at line 458 of file binary_buffer.h.

char* IT_Bus::BinaryBuffer::m_data [private]

The pointer to the character array representing the buffer content. Definition at line 435 of file binary_buffer.h.

bool IT_Bus::BinaryBuffer::m_just_borrowing [private]

Flag indicating whether the buffer content is borrowed. The binary buffer instance is not responsible for managing the memory for borrowed content. Definition at line 448 of file binary_buffer.h.

long IT_Bus::BinaryBuffer::m_size [private]

The length of the buffer content. Definition at line 440 of file binary_buffer.h.

---