This chapter provides a reference to the public functions for using Sun JavaTM System Access Manager Access Management SDK policy objects. Function summaries include a short description, syntax, parameters and returns.
The following functions are contained in the header file am_policy.h .
Takes two url resources compares theme, and returns an appropriate result.
#include "am_policy.h" AM_EXPORT am_resource_match_t am_policy_compare_urls(const am_resource_traits_t *rsrc_traits, const char *policy_resource_name, const char *resource_name, boolean_t use_patterns);
If the usePatterns is AM_TRUE, this function will consider occurrences of ’*’ in the policy resource name as wildcards. If usePatterns is AM_FALSE, ’*’ occurrences are taken as a literal characters.
This function returns am_resource_match_t with one of the following values:
If both the resource names exactly matched.
If the resourceName is a sub-resource to the resource name defined in the policy.
If the resourcName is a ancestor of the policy resource name.
If the there is no kind of match between the policy resource and the requested resource name.
This result will be returned only if the policy is matches resource name. Distinction is not made whether it was a EXACT_MATCH or a pattern match.
In cases of SUB/SUPER_RESOURCE_MATCH, if the usePatterns is * AM_TRUE, the patterns are sub/super matching patterns.
Frees an initialized policy evaluator.
#include "am_policy.h" AM_EXPORT am_status_t am_policy_destroy(am_policy_t policy);
This function takes the following parameters:
Opaque handle to the policy service to destroy.
This function returns am_status_t with one of the following values:
If the call was successful.
If any error occurs, the type of error indicated by the status value.
This function destroys a policy service instance. Memory Concerns: Caller must call make sure the same service instance not be destroyed more than once.
Evaluates a policy for a given resource and returns the policy result.
#include "am_policy.h" AM_EXPORT am_status_t am_policy_evaluate(am_policy_t policy_handle, const char *sso_token, const char *resource_name, const char *action_name, const am_map_t env_parameter_map, am_map_t policy_response_map_ptr, am_policy_result_t *policy_result);
This function takes the following parameters:
Opaque handle to the policy service created by policy_service_init .
User’s SSO token to be used for evaluation.
Name of resource to evaluate.
User’s access action, such as GET or POST.
Any environment variables to be used for evaluation.
Map to store user attributes from the policy evaluation call.
Evaluation results.
This function returns am_status_t with one of the following values:
If the call was successful.
If any error occurs, the type of error indicated by the status value.
This function destroys a policy service instance. Memory Concerns: After using the results the caller must call am_policy_result_destroy on the policy_result to cleanup the memory allocated by the evaluation operation. am_map_destroy must also be called on response and env_parameter_map after their respective usage scope.
Populates the pointer resourceRoot with the resource root.
#include "am_policy.h" AM_EXPORT boolean_t am_policy_get_url_resource_root (const char *resource_name, char *resource_root, size_t length);
This function takes a URL resource name.
This function returns boolean_t with one of the following values:
Successful root extraction.
Otherwise
This function is takes a URL and extracts a root of the URL. For example, http://www.sun.com/index.html will return http://www.sun.com/ and http://www.sun.com:8080/index.html will return http://www.sun.com:8080/. Memory Concerns: In an implementation for a different resource other than URLs, the service writer implementing this function must make accurate judgement about the minimum size of resourceRoot.
Initializes the policy evaluation engine.
#include "am_policy.h" AM_EXPORT am_status_t am_policy_init(am_properties_t policy_config_properties);
This function takes the following parameters:
The properties to initialize the policy service with.
This function returns am_status_t with one of the following values:
If the call was successful.
If any error occurs, the type of error indicated by the status value.
This function initializes a policy service instance. Memory Concerns: Caller must call am_policy_destroy structure or free the memory.
Checks if notification is enabled in the SDK.
#include "am_policy.h" AM_EXPORT boolean_t am_policy_is_notification_enabled(am_policy_t policy_handle);
This function takes the following parameters:
The opaque policy service handle created from am_policy_service_init() .
This function returns boolean_t with one of the following values:
If notification is disabled.
If notification is enabled.
Refreshes policy cache when a policy notification is received by the client.
#include "am_policy.h" AM_EXPORT am_status_t am_policy_notify(am_policy_t policy_handle, const char *notification_data, size_t notification_data_len);
This function takes the following parameters:
Opaque handle to the policy service
The notification message as an XML String.
Length of the notification data.
This function returns am_status_t with one of the following values:
If the call was successful.
If any error occurs, the type of error indicated by the status value.
Canonicalize the given resource name.
#include "am_policy.h" AM_EXPORT void am_policy_resource_canonicalize(const char *resource, char **c_resource);
This function takes the following parameters:
Name of resource to be canonicalized.
Pointer to location where the canonicalized string will be placed.
The value returned should be freed using free().
Returns whether the given resource name has patterns such as ’*’.
#include "am_policy.h" AM_EXPORT boolean_t am_policy_resource_has_patterns(const char *resource_name);
This function takes the following parameter:
Name of the resource.
This function returns boolean_t with one of the following values:
If the resource has patterns.
Otherwise.
Destroys am_policy_result internal structures.
#include "am_policy.h" AM_EXPORT void am_policy_result_destroy(am_policy_result_t *result);
This function takes the following parameters:
The policy result to be destroyed.
None
Initializes one specific instance of service for policy evaluation.
#include "am_policy.h" AM_EXPORT am_status_t am_policy_service_init(const char *service_name, const char *instance_name, am_resource_traits_t rsrc_traits, am_properties_t service_config_properties, am_policy_t *policy_handle_ptr);
This function takes the following parameters:
A name for the policy service.
A name for the policy service instance.
Resource traits - see description of am_resource_traits_t in the structure section for more information.
The properties to initialize the policy service with.
Handle to the policy service created.
This function returns am_status_t with one of the following values:
If the call was successful.
If any error occurs, the type of error indicated by the status value.