ham_entity_handle(), ham_entity_handle_node()

Updated: October 28, 2024

Get a handle to an entity

Synopsis:

#include <ha/ham.h>

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

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

Arguments:

nd
(ham_entity_handle() only) The node identifier of the targeted remote node. 0/ND_LOCAL_NODE is the default case.
nodeame
(ham_entity_handle_node() only) The targeted remote HAM. If NULL is specified for nodename, then it will be ignored.
ename
The name of the entity to which the function returns a handle.
flags
Currently not used.

Library:

libham

Description:

The ham_entity_handle() function returns a handle to an entity (ename). The handle can then be passed to other functions that expect a handle to an entity (such as ham_condition() or ham_entity_handle_free()).

Note: To get a handle for a global entity, pass NULL for ename.

The handle returned is opaque; its contents are internal to the library.

If a node (nd) is specified, the handle is to an entity/condition/action combination that refers to a process on that remote node. The ham_entity_handle_node() function is used when a nodename is used to specify a remote HAM instead of a node identifier (nd).

There are no flags defined at this time.

Returns:

A valid ham_entity_t, or NULL if an error occurred (errno is set).

Errors:

EINVAL
The name given in ename is invalid (e.g., it contains the / character).
ENAMETOOLONG
The name given (in ename) 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.
ENOENT
There's no entity by this name defined in the current context of the HAM.
ENOMEM
Not enough memory to create a new handle.

Classification:

QNX Neutrino

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

Caveats:

A call to ham_entity_handle() and a subsequent use of the handle returned in a call such as ham_condition() are completely asynchronous. Therefore, a valid action/condition/entity may no longer exist when the handle is used at a later time.

In such an event, the ham_condition*() functions will return an error (ENOENT) that the action in the condition doesn't exist in the given entity.