ham_condition_state()
Attach a condition associated with a state transition
Synopsis:
#include <ha/ham.h> ham_condition_t *ham_condition_state( ham_entity_t *ehdl, const char *cname, unsigned fromstate, unsigned tostate, unsigned flags );
Arguments:
- ehdl
- The HAM entity handle.
- cname
- The name of the condition to trigger when the entity specified by ehdl changes from fromstate to tostate.
- fromstate
- The state from which you want the entity to change.
- tostste
- The state to which you want the entity to change.
- flags
- Standard flags that are applicable for conditions are also valid here. See below.
Library:
libham
Description:
This condition is triggered when the specified entity changes from a state matching fromstate to a state matching tostate. CONDSTATEANY can be used to specify a wildcard signifying any STATE. The matching of states is based on either an explicit match or special conditions explained in the Flags section below.
The ehdl argument is an entity handle obtained either:
-
from a ham_attach*() call or a ham_entity*() call
or:
- by calling ham_entity_handle*() with an existing entity name. Since conditions are associated with entities, the entity handle (ehdl) must be available before you can add conditions.
Flags
Standard flags that are applicable for conditions are also valid here. (See ham_condition() for more details). In addition, the following flags are also defined:
/* special condition flags */
HCONDSTATEFROMSET /* from state is a set */
HCONDSTATETOSET /* to state is a set */
HCONDSTATEFROMINV /* invert from state set */
HCONDSTATETOINV /* invert to state set */
States can be given using:
- individual values
- the wildcard CONDSTATEANY
- bitmaps that allow several states to be referred to collectively as sets.
If fromstate or tostate refers to a set, the corresponding flag HCONDSTATEFROMSET or HCONDSTATETOSET must be set.
If you want fromstate or tostate
to refer to the logical negation of a set of states define
HCONDSTATEFROMINV or HCONDSTATETOINV in flags.
This would logically invert the set of states specified
(equivalent to saying any state other than this set
).
Returns:
A condition handle, or NULL if an error occurred (errno is set).
Errors:
- EBADF
- Couldn't connect to the HAM.
- EEXIST
- The name provided for the condition already exists.
- EINVAL
-
The handle, type, or name given 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:The combined name length of an entity, condition, or action 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:
Safety: | |
---|---|
Cancellation point | No |
Signal handler | No |
Thread | Yes |