Marshal buffer interfaces and classes

This section describes the buffer class used for marshaling data to a buffer when creating an operation request or a reply message. It also describes the buffer class used for extracting data from a received operation request or reply message.

CORBA::MarshalInBuffer

class CORBA::MarshalInBuffer : public VISistream

This class represents a stream buffer that allows IDL types to be read from a buffer. Interceptor methods that you implement may used this class. Go to “Portable Interceptor interfaces and classes for C++” for more information on the interceptor interfaces.

The CORBA::MarshalInBuffer class is used on the client side to extract the data associated with a reply message. It is used on the server side to extract the data associated with an operation request. This class provides a wide range of methods for retrieving various types of data from the buffer.

This class also provides several static methods for testing and manipulating CORBA::MarshalInBuffer pointers.

A CORBA::MarshalInBuffer_var class is also offered. It provides a wrapper that automatically manages the contained object.

Include file

The mbuf.h file should be included when you use this class. This file gets included in corba.h. So, you don't have to include mbuf.h separately.

CORBA::MarshalInBuffer constructors/destructors

CORBA::MarshalInBuffer(char *read_buffer, CORBA::ULong length, CORBA::Boolean release_flag=0, CORBA::ULong start_offset=0, CORBA::Boolean byte_order = CORBA::ByteOrder);

This is the default constructor.

Parameter	Description
read_buffer	The buffer where the marshaled data will actually be stored.
length	The maximum number of bytes that may be stored in read_buffer.
release_flag	If set to TRUE, the memory associated with read_buffer is freed when this object is destroyed. The default value is FALSE.
start_offset	The starting offset wherein data is written in the read_buffer. The default value is 0.
byte_order	Set this to TRUE to indicate that little-endian byte ordering is being used. Set to FALSE to indicate that big-endian byte ordering is being used.

virtual ~CORBA::MarshalInBuffer();

This is the default destructor. The buffer memory associated with this object is released if the release_flag is set to TRUE. The release_flag may be set when the object is created or by invoking the release_flag method, described in “void release_flag(CORBA::Boolean val);” on page 267.

CORBA::MarshalInBuffer methods

char *buffer() const;

Returns a pointer to the buffer associated with this object.

void byte_order(CORBA::Boolean val) const;

Sets the byte ordering for this message buffer.

Parameter	Description
val	Set this to TRUE to indicate that little-endian byte ordering is being used. Set to FALSE to indicate that big-endian byte ordering is being used.

CORBA::Boolean byte_order() const;

Returns TRUE if the buffer uses little-endian byte ordering. FALSE is returned if big-endian byte ordering is used.

CORBA::ULong curoff() const;

Returns the current offset within the buffer associated with this object.

virtual VISistream& get(char& data);

virtual VISistream& get(unsigned char& data);

These methods allow you to retrieve a single character from the buffer at the current location.

This method returns a pointer to the location within the buffer immediately following the end of the data that was just retrieved.

Parameter	Description
data	The location where the retrieved char or unsigned char is to be stored.

virtual VISistream& get(<data_type> data, unsigned size);

These methods allow you to retrieve a sequence of data from the buffer at the current location. There is a separate method for each of the listed target data types.

This method returns a pointe to the location within the buffer immediately following the end of the data that was just retrieved.

Parameter	Description
data	The location where the retrieved data is to be stored.
	The supported target data types are:
	char*	float*
	unsigned char*	double*
	short*	long double*
	unsigned short*	VISLongLong*
	int*	VISULongLong*
	unsigned int*	wchar_t*
	long*
	unsigned long*
size	The number of the specified data types to be retrieved.

virtual VISistream& getCString(char* data, unsigned maxlen);

This method allows you to retrieve a character string from the buffer at the current location. It returns a pointer to the location within the buffer immediately following the end of the data that was just retrieved.

Parameter	Description
data	The location where the retrieved character string is to be stored.
maxlen	The maximum number of characters to be retrieved.

virtual int is_available(unsigned long size);

Returns 1 if the specified size is less than or equal to the size of the buffer associated with this object.

Parameter	Description
size	Number of bytes that need to fit within this buffer.

virtual CORBA::ULong length() const;

Returns the total number of bytes in this object's buffer.

virtual void new_encapsulation() const;

Resets the starting offset within the buffer to 0.

void release_flag(CORBA::Boolean val);

Enables or disables the automatic freeing of buffer memory when this object is destroyed.

Parameter	Description
val	If val is set to TRUE, the buffer memory for this object will be freed when this object is destroyed. If val is set to FALSE, the buffer will not be freed when this object is destroyed.

CORBA::Boolean release_flag() const;

Returns TRUE if the automatic freeing of this object's buffer memory is enabled, otherwise FALSE is returned.

void reset();

Resets the starting offset, current offset and seek position to zero.

void rewind();

Resets the seek position to zero.

CORBA::ULong seekpos(CORBA::ULong pos);

Sets the current offset to the value contained in pos. If pos specifies an offset that is greater than the size of the buffer, a CORBA::BAD_PARAM exception is raised.

static CORBA::MarshalInBuffer *_duplicate(CORBA::MarshalInBuffer_ptr ptr);

Returns a duplicate pointer to the object pointed to by ptr and increments this object's reference count.

static CORBA::MarshalInBuffer *_nil();

Returns a NULL pointer of type CORBA::MarshalInBuffer.

static void _release(CORBA::MarshalInBuffer_ptr ptr);

Reduces the reference count of the object pointed to by ptr. When the reference count reaches 0, the object is destroyed. If the object's release_flag was set to TRUE when the object was constructed, the buffer associated with the object is freed.

CORBA::MarshalInBuffer operators

virtual VISistream&operator>>(<data_type> data);

This stream operator allows you retrieve a sequence of data of the specified source data_type at the current location.

This method returns a pointer to the location within the buffer immediately following the end of the data that was just written.

Parameter	Description
data	The data to be written to the buffer.
	The supported source data types are:
	char*&	long&
	char&	unsigned long&
	unsigned char&	float&
	short&	double&
	unsigned short&	long double&
	int&	wchar_t*&
	unsigned int&	wchar_t&

CORBA::MarshalOutBuffer

class CORBA::MarshalOutBuffer : public VISostream

This class represents a stream buffer that allows IDL types to be written to a buffer and may be used by interceptor methods that you implement. Go to “VisiBroker Interceptor and object wrapper interfaces and classes for C++”, for more information on the interceptor interfaces.

The CORBA::MarshalOutBuffer class is used on the client side to marshal the data associated with an operation request. It is used on the server side to marshal the data associated with a reply message. This class provides a wide range of methods for adding various types of data to the buffer or for retrieving what was written from the buffer.

This class provides several static methods for testing and manipulating CORBA::MarshalOutBuffer pointers.

A CORBA::MarshalOutBuffer_var class is also offered. It provides a wrapper that automatically manages the contained object.

Include file

The mbuf.h file should be included when you use this class. This file gets included in corba.h. So, you don't have to separately include mbuf.h.

CORBA::MarshalOutBuffer constructors/destructors

CORBA::MarshalOutBuffer(CORBA::ULong initial_size = 255, CORBA::Boolean release_flag = 0, CORBA::ULong start_offset = 0);

Creates a marshalOutBuffer of size initial_size. The MarshalOutBuffers are capable of resizing themselves during a put operation. When there is not enough space in the buffer to hold all the data written to it, the size of the buffer doubles.

Parameter	Description
initial_size	The initial size of the buffer associated with this object. The default size is 255 bytes.
release_flag	If set to TRUE, the memory associated with read_buffer is freed when this object is destroyed. The default value is FALSE.
start_offset	Set the starting offset within the buffer. Defaults to 0, that is starting from the very beginning of the buffer.

CORBA::MarshalOutBuffer(char *read_buffer, CORBA::ULong len, CORBA::Boolean release_flag=0, CORBA::ULong start_offset = );

Creates an object with the specified buffer, buffer length and release flag value.

Parameter	Description
read_buffer	The buffer where the marshaled data will actually be stored.
length	The maximum number of bytes that may be stored in read_buffer.
release_flag	If set to TRUE, the memory associated with read_buffer is freed when this object is destroyed. The default value is FALSE.
start_offset	Set the starting offset within the buffer. Defaults to 0, that is starting from the very beginning of the buffer.

virtual ~CORBA::MarshalOutBuffer();

This is the default destructor. The buffer memory associated with this object is released if the release_flag is set to TRUE. The release_flag may be set when the object is created or by invoking the release_flag method, described in “CORBA::Boolean release_flag() const;” on page 268.

CORBA::MarshalOutBuffer methods

char *buffer() const;

Returns a pointer to the buffer associated with this object.

CORBA::ULong curoff() const;

Returns the current offset within the buffer associated with this object.

virtual CORBA::ULong length() const;

Returns the total number of bytes in this object's buffer.

virtual void new_encapsulation() const;

Resets the starting offset within the buffer to zero.

virtual VISostream& put(char data);

Adds a single character to the buffer at the current location.

This method returns a pointer to the location within the buffer immediately following the end of the data that was just added.

Parameter	Description
data	The char to be stored.

virtual VISostream& put(const <data_type> data, unsigned size);

These methods allow you to store a sequence of data in the buffer at the current location.

This method returns a pointer to the location within the buffer immediately following the end of the data that was just added.

Parameter	Description
data	The data is to be stored.
	The supported source data types are:
	char*	float*
	unsigned char*	double*
	short*	long double*
	unsigned short*	VISLongLong*
	int*	VISULongLong*
	unsigned int*	wchar_t*
	long*
	unsigned long*
size	The number of the specified data types to be stored.

virtual VISostream& putCString(const char* data);

This method allows you to store a character string into the buffer at the current location. It returns a pointer to the location within the buffer immediately following the end of the data that was just added.

Parameter	Description
data	The character string to be stored.

void release_flag(CORBA::Boolean val);

Enables or disables the automatic freeing of buffer memory when this object is destroyed.

Parameter	Description
val	If val is set to TRUE, the buffer memory for this object will be freed when this object is destroyed. If val is set to FALSE, the buffer will not be freed when this object is destroyed

CORBA::Boolean release_flag() const;

Returns TRUE if the automatic freeing of this object's buffer memory is enabled, otherwise returns FALSE.

void reset();

Resets the starting offset, current offset and seek position to zero.

void rewind();

Resets the seek position to zero.

CORBA::ULong seekpos(CORBA::ULong pos);

Sets the current offset to the value contained in pos. If pos specifies an offset that is greater than the size of the buffer, a CORBA::BAD_PARAM exception is raised.

static CORBA::MarshalOutBuffer *_duplicate(CORBA::MarshalOutBuffer_ptr ptr);

Returns a duplicate pointer to this object pointed to by ptr and increments this object's reference count.

static CORBA::MarshalOutBuffer *_nil();

Returns a NULL pointer of type CORBA::MarshalOutBuffer.

static void _release(CORBA::MarshalOutBuffer_ptr ptr);

Reduces the reference count of the object pointed to by ptr. If the reference count is then zero, the object is destroyed. If the object's release_flag was set to TRUE when it was constructed, the buffer associated with the object is freed.

CORBA::MarshalOutBuffer operators

virtual VISostream& operator<<(<data_type> data);

This stream operator allows you to add data of the specified data_type to the buffer at the current location.

This method returns a pointer to the location within the buffer immediately following the end of the data that was just written.

Parameter	Description
data	The data to be obtained to the buffer.
	The supported data types are:
	const char*	float
	char	double
	unsigned char	long double
	short	VISLongLong
	unsigned short	VISULongLong
	int	wchar_t*
	unsigned int	wchar_t
	long
	unsigned long