42.2 Special QosPolicy Handling Considerations for C

Many QosPolicy structures contain variable-length sequences to store their parameters. In the C++, C# and Java languages, the memory allocation related to sequences are handled automatically through constructors/destructors and overloaded operators. However, the C language is limited in what it provides to automatically handle memory management. Thus, Connext provides functions and macros in C to initialize, copy, and finalize (free) QosPolicy structures defined for Entities.

In the C language, it is not safe to use an Entity’s QosPolicy structure declared in user code unless it has been initialized first. In addition, user code should always finalize an Entity’s QosPolicy structure to release any memory allocated for the sequences–even if the Entity’s QosPolicy structure was declared as a local, stack variable.

Thus, for a general Entity’s QosPolicy, Connext will provide:

• DDS_<Entity>Qos_INITIALIZER This is a macro that should be used when a DDS_<Entity>Qos structure is declared in a C application.

struct DDS_<Entity>Qos qos = DDS_<Entity>Qos_INITIALIZER;

• DDS_<Entity>Qos_initialize() This is a function that can be used to initialize a DDS_<Entity>Qos structure instead of the macro above.

struct DDS_<Entity>Qos qos;
DDS_<Entity>QOS_initialize(&qos);

• DDS_<Entity>Qos_finalize() This is a function that should be used to finalize a DDS_<Entity>Qos structure when the structure is no longer needed. It will free any memory allocated for sequences contained in the structure.

struct DDS_<Entity>Qos qos = DDS_<Entity>Qos_INITIALIZER;
...
<use qos>
...
// now done with qos
DDS_<Entity>QoS_finalize(&qos);

• DDS<Entity>Qos_copy() This is a function that can be used to copy one DDS_<Entity>Qos structure to another. It will copy the sequences contained in the source structure and allocate memory for sequence elements if needed. In the code below, both dstQos and srcQos must have been initialized at some point earlier in the code.

DDS_<Entity>QOS_copy(&dstQos, &srcQos);