/* IBM_PROLOG_BEGIN_TAG */ /* This is an automatically generated prolog. */ /* */ /* bos720 src/bos/usr/include/ice_api.h 1.5 */ /* */ /* Licensed Materials - Property of IBM */ /* */ /* Restricted Materials of IBM */ /* */ /* COPYRIGHT International Business Machines Corp. 2009,2011 */ /* All Rights Reserved */ /* */ /* US Government Users Restricted Rights - Use, duplication or */ /* disclosure restricted by GSA ADP Schedule Contract with IBM Corp. */ /* */ /* IBM_PROLOG_END_TAG */ /* @(#)27 1.5 src/bos/usr/include/ice_api.h, libice, bos720 7/14/11 20:15:12 */ #ifndef __ICE_API_H__ #define __ICE_API_H__ #include #ifdef __cplusplus extern "C" { #endif /** * Status codes which can be returned by ice_* method calls. */ typedef enum { ICE_STATUS_OK = 0, ICE_STATUS_ACTION_FAILURE, ICE_STATUS_NON_COMPLIANT, ICE_STATUS_UNSUPPORTED_RULE, ICE_STATUS_EINVAL, ICE_STATUS_ENOMEM, ICE_STATUS_ENOENT, ICE_STATUS_NON_COMPLIANT_OTHER /* Additional status codes returned here */ } ice_status_t; /** * Types of ICE rules. */ typedef enum { ICE_TYPE_BOOL, ICE_TYPE_INT, ICE_TYPE_LONG, ICE_TYPE_FLOAT, ICE_TYPE_DOUBLE, ICE_TYPE_STR, ICE_TYPE_TIME } ice_type_t; /** * Boolean type. */ typedef enum { ICE_FALSE = 0, ICE_TRUE } ice_bool_t; /** * The types of values that can be specified for an ICE policy rule. */ typedef union { ice_bool_t bval; int ival; long long lval; float fval; double dval; char *sval; time_t tval; } ice_value_t; /** * Definition of an ICE policy rule. */ typedef struct { ice_type_t type; char *name; ice_value_t value; } ice_rule_t; typedef struct { /* Status of checking the rule's current value */ ice_status_t status; /* Command which was used to set the value (optional). */ char *command; /* Exit code (if a command was used to set the value). */ int exit_code; /* Log area for more detailed information. (i.e. stdout/stderr) */ char *log; } ice_action_result_t; /** * Result of ice_policy_action for an individual rule. */ typedef struct { /* * Rule for this entry. The value will be set to the current value * if ICE_ACTION_CHECK was specified. */ ice_rule_t *rule; /* * Result of setting a new value for the rule */ ice_action_result_t *result; } ice_result_entry_t; /** * Result of ice_policy_action method. */ typedef struct { ice_result_entry_t **entries; int num_entries; } ice_result_t; /** * ICE Policy object. */ typedef struct { /* Number of rules in the policy */ int num_rules; /* Policy data - Internal use only */ void *data; } ice_policy_t; /** * ICE Policy iterator */ typedef struct { ice_rule_t *rule; void *data; } ice_policy_iterator_t; /** * Creates an ICE Policy and stores it in the policy variable. * The policy should be freed with ice_policy_free after it is * no longer needed. * * @param policy Location where policy should be stored. * @return Status of policy creation. */ ice_status_t ice_policy_create(ice_policy_t **policy); /** * Creates an ICE policy consisting of all of the currently * supported rules on the platform. All of the value fields * of the rules are uninitialized. The policy should be * freed with ice_policy_free after it is no longer needed. * * @param policy Location where policy should be stored. * @return Status of policy creation. */ ice_status_t ice_policy_create_all_rules(ice_policy_t **policy); /** * Frees the dynamic memory used by the ICE policy. * * @param policy Policy to be freed. */ void ice_policy_free(ice_policy_t *policy); /** * Adds the specified rule to the policy. If an existing rule with the * same rule identifier exists in the policy, it is replaced. * * @param policy Policy to add rule to. * @param rule Rule to be added to the policy * @return Status of policy modification. */ ice_status_t ice_policy_add_rule(ice_policy_t *policy, ice_rule_t *rule); /** * Removes the rule with the specified identifier from the policy. * * @param policy Policy to remove rule from. * @param rule_id Rule identifier to remove from policy. * @return Removed rule (should be free'd with ice_rule_free()). */ ice_rule_t* ice_policy_remove_rule(ice_policy_t *policy, const char *rule_id); /** * Optional callback function which can be called after each action * against a policy rule (for status indicator, etc.). If the function * returns anything but ICE_STATUS_OK, the overall operation is aborted. */ typedef ice_status_t (*ice_action_cb)(const ice_policy_t *policy, ice_result_entry_t *result); /** * Performs an action on the specified policy. * ice_policy_check: the ice_result_t structure will contain an entry * for each rule in the policy with the ice_result_t[i].rule.value * set to the current value of the rule on the system. * ice_policy_enforce: each policy rule in the specified policy is set * on the system. * * @param policy Policy containing rules to check/set on the system. * * @param result Result variable to store results of check/enforce * operation. Results must be freed with ice_result_free() * after use. * @param callback Optional callback to used which is called after each * rule in the policy has been processed. If the callback * returns a status other than ICE_STATUS_OK, the action is * aborted and the callback status is returned. * @return ICE_STATUS_OK If all policy actions were successful, or * ICE_STATUS_ACTION_FAILURE if any failures were encountered. If * any other return codes are returned, the result variable will * not be set. */ ice_status_t ice_policy_check (const ice_policy_t *policy, ice_result_t **result, ice_action_cb callback); ice_status_t ice_policy_enforce (const ice_policy_t *policy, ice_result_t **result, ice_action_cb callback); /** * For every rule in the policy, returns the default value as defined by * the system. * * @param policy Policy containing rules to get default values for. * * @param result Result variable to store results of retrieving default * values. Results must be freed with ice_result_free() * after use. * @return ICE_STATUS_OK If all values retrieved successfully, or * ICE_STATUS_ACTION_FAILURE if failed to retrieve values for * any rules in the policy. * If any other return codes are returned, * the result variable will not be set. */ ice_status_t ice_policy_get_defaults (const ice_policy_t *policy, ice_result_t **result); /** * Frees all dynamic memory used by an ice_result_t object returned from a * call to ice_policy_action(). * * @param result Result array from a call to ice_policy_action. */ void ice_result_free(ice_result_t *result); /* * Utility methods to create an ice_rule_t of various types. If an error * occurs, then the returned rule will be NULL. */ ice_rule_t* ice_rule_create_bool(const char *rule_id, ice_bool_t value); ice_rule_t* ice_rule_create_int(const char *rule_id, int value); ice_rule_t* ice_rule_create_long(const char *rule_id, long long value); ice_rule_t* ice_rule_create_float(const char *rule_id, float value); ice_rule_t* ice_rule_create_double(const char *rule_id, double value); ice_rule_t* ice_rule_create_string(const char *rule_id, const char *value); ice_rule_t* ice_rule_create_time(const char *rule_id, time_t value); /** * Frees the dynamic memory in use by an ice_rule_t object. * * @param rule Rule to free. */ void ice_rule_free(ice_rule_t *rule); /** * Creates an ICE policy iterator that can be used to traverse an ICE * policy rule by rule. * * @param iterator Location where iterator should be stored. * * @return Status of iterator creation. */ ice_status_t ice_policy_iterator_create(ice_policy_iterator_t **); /** * Initializes an ICE policy iterator that can be used to traverse an ICE * policy rule by rule. The iterator will be associated with policy and * point to the first rule in the policy. This routine should be used * following ice_policy_iterator_create and can also be used to point * an iterator back to the beginning of a policy or to associate the * iterator with a different policy. * * @param policy Policy to associate with iterator. * @param iterator Iterator to initialize. * * @return Status of iterator initialization. */ ice_status_t ice_policy_iterator_init(ice_policy_t *policy, ice_policy_iterator_t *); /** * Increments an ICE policy iterator to point to the next rule in the * policy. Return code of ICE_STATUS_ENOENT indicates the iterator * has reached the end of the policy. * * @param iterator Iterator to increment. * * @return Status of iterator incrementation. */ ice_status_t ice_policy_iterator_next(ice_policy_iterator_t *); /** * Frees memory associate with an ICE policy iterator. * * @param iterator Iterator to free. * */ void ice_policy_iterator_free(ice_policy_iterator_t *); #ifdef __cplusplus } #endif #endif