Function dds_get_children

Function Documentation

dds_return_t dds_get_children(dds_entity_t entity, dds_entity_t *children, size_t size)

Get entity children.

This operation returns the children that the entity contains. For instance, it will return all the Topics, Publishers and Subscribers of the Participant that was used to create those entities (when that Participant is provided here).

This functions takes a pre-allocated list to put the children in and will return the number of found children. It is possible that the given size of the list is not the same as the number of found children. If less children are found, then the last few entries in the list are untouched. When more children are found, then only ‘size’ number of entries are inserted into the list, but still complete count of the found children is returned. Which children are returned in the latter case is undefined.

When supplying NULL as list and 0 as size, you can use this to acquire the number of children without having to pre-allocate a list.

When a reader or a writer are created with a participant, then a subscriber or publisher are created implicitly. When used on the participant, this function will return the implicit subscriber and/or publisher and not the related reader/writer.

Parameters

  • entity – [in] Entity from which to get its children.

  • children – [out] Pre-allocated array to contain the found children.

  • size – [in] Size of the pre-allocated children’s list.

Return values

  • >=0 – Number of found children (can be larger than ‘size’).

  • DDS_RETCODE_ERROR – An internal error has occurred.

  • DDS_RETCODE_BAD_PARAMETER – The children parameter is NULL, while a size is provided.

  • DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.

  • DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

Number of children or an error code.