pips_entity_attach()

Attach user data to an entity

Synopsis:

#include <pips/publication.h>

int pips_entity_attach(pips_entity_t *const entity,
                       void *const usr_data)

Arguments:

entity: A pointer to the entity to which the user data will be attached
usr_data: An opaque pointer to user-defined data. The caller retains ownership of the data and is responsible for deleting its memory. This argument can be NULL to clear the user data.

Library:

pips-client

Description:

This function attaches the given user data to the current PiPS entity as a convenience for the caller. Internally, PiPS doesn't use the data, but the caller may retrieve the last attached data at any time using pips_entity_get_data().

The caller must ensure that the attached data memory is not deleted or doesn't go out of scope while it's attached to the entity. This could lead to errors when accessing the data at a later time.

Postrequisites

The given user data will replace any data that was previously attached to the entity. This may cause the previous data's memory to be leaked. The caller is responsible for ensuring that the memory is reclaimed as appropriate.

Returns:

EOK: The user data was successfully attached

-1: An error occurred (errno is set)

Errors:

EINVAL: The entity is invalid.