ham_entity(), ham_entity

Create entity placeholder objects in a HAM

Synopsis:

#include <ha/ham.h>

ham_entity_t *ham_entity( const char *ename, 
                          int nd, 
                          unsigned flags);

ham_entity_t *ham_entity_node( const char *ename, 
                          const char *nodename, 
                          unsigned flags);

Arguments:

ename: The name of the entity for which you want to create placeholders.
nd: (ham_entity() only) The node identifier of the targeted remote node.
nodename: (ham_entity_node() only) The targeted remote HAM.
flags: Currently not used.

Library:

libham

Description:

These functions are used to create placeholders for entity objects in a HAM. The ham_entity_node() function is used when a nodename is used to specify a remote HAM instead of a node identifier (nd).

You can use these functions to create entities, and associate conditions and actions with them, before the process associated with an entity is started (or attached). Subsequent ham_attach*() calls by entities can attach to these placeholder and thereby enable conditions and actions when they occur.

The nd variable specifies the node identifier of the remote node at the time the call is made.

Note: Since node identifiers are transient objects, we recommend that the value for nd is obtained at the time of the call, using netmgr_strtond() or another function that converts nodenames into node identifiers.

The ham_entity_node() function takes as a parameter a fully qualified node name (FQNN).

Returns:

An entity handle, or NULL if an error occurred (errno is set).

Errors:

EBADF: Couldn't connect to the HAM.
EINVAL: The name given in ename is invalid (e.g., it contains the “/” character) or is NULL.
ENAMETOOLONG: The name given (in aname) is too long, i.e., it exceeds _POSIX_PATH_MAX (defined in <limits.h>). Note that the combined length of an entity/condition/action name is also limited by _POSIX_PATH_MAX.
ENOMEM: Not enough memory to create a new handle.

In addition to the above errors, the HAM returns any error it encounters while servicing this request.

Classification:

QNX Neutrino

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	No
Thread	Yes

ham_entity(), ham_entity_node()