ham_action_handle()
Get a handle to an action in a condition in an entity
Synopsis:
#include <ha/ham.h>
ham_action_t *ham_action_handle(int reserved,
const char *ename,
const char *cname,
const char *aname,
unsigned flags);
Arguments:
- reserved
- Set this argument to 0.
- ename
- The name of the entity.
- cname
- The name of the condition.
- aname
- The name of the action.
- flags
- Currently not used.
Library:
libham
Description:
The ham_action_handle() function returns a handle to an action (aname) in a condition (cname) in an entity (ename).
You can pass the handle obtained from this function to other functions that expect a handle (e.g., ham_action_remove() or ham_action_handle_free()).
The handle returned is opaque — its contents are internal to the library.
There are no flags defined at this time.
Returns:
A valid ham_action_t, or NULL if an error occurred (errno is set).
Errors:
- EINVAL
- The name given in ename, cname, or aname is invalid (e.g., it
contains the
character), or cname or aname is NULL./ - ENAMETOOLONG
- The name given 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 action of the name aname in a condition cname defined in an entity ename in the HAM's current context.
- ENOMEM
- Not enough memory to create a new handle.
Classification:
| Safety: | |
|---|---|
| Cancellation point | No |
| Signal handler | No |
| Thread | Yes |
Caveats:
A call to ham_action_handle() and a subsequent use of the handle returned in a call such as ham_action_remove() 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_action*() functions will return an error (ENOENT) that the action in the condition doesn't exist in the given entity.