ham_entity_control()

Updated: May 06, 2022

Perform control operations on an entity object in a HAM

Synopsis:

#include <ha/ham.h>

int ham_entity_control( ham_entity_t *ehdl,
                        int command,
                        unsigned flags);

Arguments:

ehdl
The HAM entity handle.
command
The command to perform. See below.
flags
Any flag that is valid for the corresponding entity can be used when ham_entity_control() is being used to set flags. See below.

Library:

libham

Description:

The ham_entity_control() function can be used to control the state of an entity object in a HAM. This function is designed to be extensible with additional commands. Currently, the following commands are defined:

HENABLE
Enable the item.
HDISABLE
Disable the item.
HADDFLAGS
Add the flags.
HREMOVEFLAGS
Remove the flags.
HSETFLAGS
Set the flags to the given value.
HGETFLAGS
Get the current flags.

When an entity item is enabled (the default), any event that occurs in relation to this event will trigger appropriate conditions and actions related to the entity. If an entity item is disabled, no events relating to that entity will be reacted to. If an entity is disabled, all conditions and actions under it are also disabled. Individual conditions and actions can be enabled and disabled using the corresponding control functions for conditions and actions, respectively.

The HADDFLAGS, HREMOVEFLAGS, and HSETFLAGS commands can be used to modify the set of flags associated with the entity being controlled. Add flags and remove flags are used to either add to or remove from the current set of flags, the specified set of flags (as given in flags). The set flags function is called when the current set of flags is to be replaced by flags.

Flags

Any flag that is valid for the corresponding entity can be used when ham_entity_control() is being used to set flags.

For the HENABLE and HDISABLE commands:

HRECURSE
Applies the command recursively.

Returns:

For enable, disable, add flags, remove flags, and set flags functions:

0
Success.
-1
An error occurred (errno is set).

For get flags function

flags
Success.
-1
An error occurred (errno is set).

Errors:

EBADF
Couldn't connect to the HAM.
EINVAL
The command or flags variable is invalid.

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