RTI Connext C API Version 7.3.0

<<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. More...
 
unsigned char * DDS_OctetBuffer_dup (const unsigned char *buffer, unsigned int size)
 Clone an OctetBuffer. More...
 
void DDS_OctetBuffer_free (unsigned char *buffer)
 Delete an OctetBuffer. More...
 

Detailed Description

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

The functions 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 functions 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 Connext.

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 Connext must therefore make some assumptions when a user requests that a OctetBuffer be copied into. The following rules apply when RTI Connext 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,
a 'unsigned char*' that is passed back and forth between
user code and the DDS C/C++ APIs.
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.
unsigned char * DDS_OctetBuffer_alloc(unsigned int size)
Create a new empty OctetBuffer that can hold up to size octets.

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

◆ DDS_OctetBuffer_alloc()

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

◆ DDS_OctetBuffer_dup()

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

Clone an OctetBuffer.

   An OctetBuffer created by this function 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 function always returns NULL. Otherwise, upon success it returns a newly created OctetBuffer whose value is src; upon failure it returns NULL.

◆ DDS_OctetBuffer_free()

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.