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 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.

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:


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.


RTI Data Distribution Service C++ API Version 4.5e Copyright © 23 Oct 2011 Real-Time Innovations, Inc