Octet Buffer Support
[Infrastructure Module]

<<eXtension>> Octet buffer creation, cloning, and deletion. More...

Functions
unsigned char *	DDS_OctetBuffer_alloc (unsigned int size)
	Create a new empty OctetBuffer that can hold up to size octets.
unsigned char *	DDS_OctetBuffer_dup (const unsigned char *buffer, unsigned int size)
	Clone an OctetBuffer.
void	DDS_OctetBuffer_free (unsigned char *buffer)
	Delete an OctetBuffer.

---

Detailed Description

<<eXtension>> Octet buffer creation, cloning, and deletion.

The methods in this class ensure consistent cross-platform implementations for OctetBuffer creation (DDS_OctetBuffer_alloc()), deletion (DDS_OctetBuffer_free()), and cloning (DDS_OctetBuffer_dup()) that preserve the mutable value type semantics. These are to be viewed as methods that define an OctetBuffer class whose data is represented by a 'unsigned char*'.

Conventions

The following conventions govern the memory management of OctetBuffers in RTI Data Distribution Service.

• The DDS implementation ensures that when value types containing OctetBuffers are passed back and forth to the DDS APIs, the OctetBuffers are created/deleted/cloned using the OctetBuffer class methods.
  • Value types containing OctetBuffers have ownership of the contained OctetBuffer. Thus, when a value type is deleted, the contained octet buffer field is also deleted.
• The user must ensure that when value types containing OctetBuffers are passed back and forth to the DDS APIs, the OctetBuffers are created/deleted/cloned using the OctetBuffer class methods.

The representation of an OctetBuffer in C/C++ unfortunately does not allow programs to detect how much memory has been allocated for a OctetBuffer. RTI Data Distribution Service must therefore make some assumptions when a user requests that a OctetBuffer be copied into. The following rules apply when RTI Data Distribution Service is copying into an OctetBuffer.

• If the 'unsigned char*' is NULL, RTI Data Distribution Service will allocate a new OctetBuffer on behalf of the user. To avoid leaking memory, you must ensure that the OctetBuffer will be freed (see Usage below) in C. For C++, the destructor of the valuetype containing the OctetBuffer will free it automatically..
• If the 'unsigned char*' is not NULL, RTI Data Distribution Service will assume that you are managing the OctetBuffer's memory yourself and have allocated enough memory to store the OctetBuffer to be copied. RTI Data Distribution Service will copy into your memory; to avoid memory corruption, be sure to allocate enough of it. Also, do not pass structures containing junk pointers into RTI Data Distribution Service; you are likely to crash.

Usage

This requirement can generally be assured by adhering to the following idiom for manipulating OctetBuffers.

     Always use 
          DDS_OctetBuffer_alloc() to create,
          DDS_OctetBuffer_dup() to clone,
          DDS_OctetBuffer_free() to delete
      a 'unsigned char*' that is passed back and forth between 
      user code and the DDS C/C++ APIs.

Not adhering to this idiom can result in bad pointers, and incorrect memory being freed.

In addition, the user code should be vigilant to avoid memory leaks. It is good practice to:

• Balance occurrences of DDS_OctetBuffer_alloc(), with matching occurrences of DDS_OctetBuffer_free() in the code.
• Finalize value types containing OctetBuffer. In C++ the destructor accomplishes this automatically. in C, explicit "destructor" functions are provided.

---

Function Documentation

unsigned char* DDS_OctetBuffer_alloc

(

unsigned int

size

)

Create a new empty OctetBuffer that can hold up to size octets.

An OctetBuffer created by this method must be deleted using DDS_OctetBuffer_free().

This function will allocate enough memory to hold an OctetBuffer of size octets.

Parameters:

size

<<in>> Size of the buffer.

Returns:

A newly created non-NULL OctetBuffer upon success or NULL upon failure.

unsigned char* DDS_OctetBuffer_dup	(	const unsigned char *	buffer,
		unsigned int	size
	)

Clone an OctetBuffer.

An OctetBuffer created by this method must be deleted using DDS_OctetBuffer_free()

Parameters:

	buffer	<<in>> The OctetBuffer to duplicate.
	size	<<in>> Size of the OctetBuffer to duplicate.

Returns:

If src == NULL or size <0, this method always returns NULL. Otherwise, upon success it returns a newly created OctetBuffer whose value is src; upon failure it returns NULL.

void DDS_OctetBuffer_free

(

unsigned char *

buffer

)

Delete an OctetBuffer.

Precondition:

buffer must be either NULL, or must have been created using DDS_OctetBuffer_alloc(), DDS_OctetBuffer_dup()

Parameters:

buffer

<<in>> The buffer to delete.