Control functions

Updated: April 19, 2023

The following set of functions have been provided to permit control of entities, conditions, and actions that are currently configured.

/* control operations                           */
int ham_entity_control(ham_entity_t *ehdl, int command, unsigned flags);
int ham_condition_control(ham_condition_t *chdl, int command, unsigned flags);
int ham_action_control(ham_action_t *ahdl, int command, unsigned flags);

The permitted operations (commands) are:

HENABLE                 /* enable item          */
HDISABLE                /* disable item         */
HADDFLAGS               /* add flag             */
HREMOVEFLAGS            /* remove flag          */
HSETFLAGS               /* set flag to specific */
HGETFLAGS               /* get flag             */

The “enable” and “disable” commands can be used to temporarily unhide/hide an entity, condition, or action.

An entity that is hidden is not removed, but will not be monitored for any conditions. Similarly, a condition that is hidden will never be triggered, while actions that are hidden will not be executed. By default the enable and disable operations do not operate recursively (although the disabling of an entity, will prevent the triggering of any conditions below it, and the disabling of a condition will prevent the execution of the actions in it).

To understand the finer distinctions of the recursive operation of the control functions, refer to the API descriptions for:

The “addflags”, “removeflags”, “setflags”, and “getflags” commands can be used to obtain or modify the flags associated with any of the entities, conditions, or actions. For more details, refer to the API descriptions of the ham_*_control_*() functions.