Sun™ Java System Access Manager contains public data types and functions you can use for creating, destroying, and manipulating map objects. Reference summaries include a short description, syntax, parameters and returns. The code is contained in the <am_map.h> header file (located in the /AccessManager-base/SUNWam/include directory). The sample source am_policy_test.c (located in the /AccessManager-base/SUNWam/samples/csdk directory) demonstrates the basic usage of some of the basic mapping functions. This chapter contains the following sections:
A map is an object that associates a key to a value. One key/value pair is an entry in the map. Maps are used by the policy API for C to return policy decision results from the Policy Service. They are also used to pass any environment variables to the Policy Service for evaluation.
The mapping types defined in <am_map.h> are:
Pointer to a map object consisting of key/value entry mappings.
#include "am_map.h" typedef struct am_map *am_map_t;
am_map is an opaque structure with no accessible members.
Free the allocated structure by calling am_map_destroy(). See am_map_destroy().
Pointer to an iterator for the entries in a map object.
#include "am_map.h" typedef struct am_map_entry_iter *am_map_entry_iter_t;
am_map_entry_iter is an opaque structure with no accessible members.
Pointer to an iterator for the values in a map object associated with a specified key.
#include "am_map.h" typedef struct am_map_value_iter *am_map_value_iter_t;
am_map_value_iter is an opaque structure with no accessible members.
The mapping functions defined in <am_map.h> are:
Erases all of the entries in the specified map object.
#include "am_map.h" AM_EXPORT am_status_t am_map_clear(am_map_t map);
This function takes the following parameter:
The map object.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the entries were successfully erased.
If the map argument is NULL.
Makes a copy of the specified map object.
am_map_copy() creates a new instance of a am_map_t, copies all the elements from the specified source_map into it, and assigns to the new instance a pointer. It does not alter the contents of the original map object.
#include "am_map.h" AM_EXPORT am_status_t am_map_copy(am_map_t source_map, am_map_t *map_ptr);
This function takes the following parameters:
The specified map object. It may be NULL.
Pointer to the location of the new map object copy.
Be sure not to pass map_ptr as a valid am_map structure as the reference will be lost.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the map object was successfully copied.
If unable to allocate memory for the new map object.
If the source_map or map_ptr argument is NULL.
The caller must destroy map_ptr after usage by calling am_map_destroy().
Creates a new, empty map object.
am_map_create() creates an instance of a am_map_t and returns a pointer back to the caller.
#include "am_map.h" AM_EXPORT am_status_t am_map_create(am_map_t *map_ptr);
This function takes the following parameter:
Pointer specifying the location of the new map object.
Be sure not to pass map_ptr as a valid am_map structure as the reference will be lost.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the map object was successfully created.
If unable to allocate memory for the new map object.
If the map_ptr argument is NULL.
Destroys the specified map object.
#include "am_map.h" AM_EXPORT void am_map_destroy(am_map_t map);
This function takes the following parameter:
The specified map object. It may be NULL.
Be sure not to pass map as a valid am_map structure as the reference will be lost.
This function does not return a value.
The pointer to the specified map object can not be freed before calling am_map_destroy(). This includes erroneously calling the system free(void *) function.
Destroys the specified entry iterator.
#include "am_map.h" AM_EXPORT void am_map_entry_iter_destroy(am_map_entry_iter_t entry_iter);
This function takes the following parameter:
The specified entry iterator. It may be NULL.
This function does not return a value.
Returns the first value assigned to the entry currently being referenced by the specified entry iterator.
#include "am_map.h" AM_EXPORT const char * am_map_entry_iter_get_first_value(am_map_entry_iter_t entry_iter);
This function takes the following parameter:
The specified entry iterator. It may be NULL.
This function returns one of the following:
Returns the first associated value of the specified key. The order of insertion into the map does not guarantee the value returned.
If the specified iterator is NULL, does not reference a valid entry, or the entry does not have any associated values.
am_map_entry_iter_get_first_value() destroys the am_map_entry_iter_t passed to it. Because of this, don't call this function more than once on the same am_map_entry_iter_t.
Returns the key assigned to the entry currently being referenced by the specified entry iterator.
#include "am_map.h" AM_EXPORT const char * am_map_entry_iter_get_key(am_map_entry_iter_t entry_iter);
This function takes the following parameters:
The specified entry iterator.
This function returns one of the following values:
Returns the key.
Caller must not modify or free the return value.
If the specified key iterator is NULL or does not reference a valid entry.
Returns a value iterator that can be used to sequence through the values assigned to the entry currently being referenced by the specified entry iterator.
#include "am_map.h" AM_EXPORT am_status_t am_map_entry_iter_get_values(am_map_entry_iter_t entry_iter, am_map_value_iter_t *value_iter_ptr);
This function takes the following parameters:
The specified entry iterator.
Pointer specifying the location of the value iterator.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If no error was detected.
If unable to allocate memory for the key iterator.
If the value_iter_ptr argument is NULL.
If value_iter_ptr is not NULL and an error is returned, the location that it references will be set to NULL.
If the entry_iter argument is NULL or does not reference a valid entry.
After using am_map_value_iter_t, the caller must call am_map_value_iter_destroy().
Determines if the entry currently being referenced by the specified entry iterator is valid.
#include "am_map.h" AM_EXPORT boolean_t am_map_entry_iter_is_entry_valid(am_map_entry_iter_t entry_iter);
This function takes the following parameter:
The specified entry iterator.
This function returns one of the following values of the boolean_t enumeration (defined in the standard <types.h> header file):
The code used is dependent on the server operating system.
If the entry is valid.
If the specified iterator is NULL or does not reference a valid entry.
Advances the specified entry iterator to the next entry in the map specified when the iterator was first created.
#include "am_map.h" AM_EXPORT boolean_t am_map_entry_iter_next(am_map_entry_iter_t entry_iter);
This function takes the following parameter:
The specified event iterator.
This function returns one of the following values of the boolean_t enumeration (defined in the standard <types.h> header file):
The code used is dependent on the server operating system.
If the entry is valid.
If the specified iterator is NULL or does not reference a valid entry after being updated.
Erases the entry, associated with the specified key, from the specified map object.
#include "am_map.h" AM_EXPORT am_status_t am_map_erase(am_map_t map, const char *key);
This function takes the following parameters:
The specified map object.
Pointer to the key of the entry to be erased.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the entry was successfully erased.
If either the map or key argument is NULL.
If the specified key is not in the map.
Returns a value iterator that can sequence through all values associated with the specified key in the specified map object.
#include "am_map.h" AM_EXPORT am_status_t am_map_find(am_map_t map, const char *key, am_map_value_iter_t *value_iter_ptr);
This function takes the following parameters:
The specified map object.
Pointer to a key.
Pointer specifying the location of the returned value iterator.
If value_iter_ptr is not NULL, the location that it references will be set to NULL if an error is returned.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If no error was detected.
If unable to allocate memory for the key iterator.
If the value_iter_ptr argument is NULL.
If the specified key is not found in the map.
After using value_iter_ptr, the caller must call am_map_value_iter_destroy().
Returns the first value associated with the specified key in the specified map object.
am_map_find_first_value() takes a key and returns the first value associated with that key.
#include "am_map.h" AM_EXPORT const char * am_map_find_first_value(am_map_t map, const char *key);
This function takes the following parameters:
The specified map object.
Pointer to a key.
This function returns one of the following values:
Returns the first value associated with the specified key.
Caller must not modify or free the return value.
If the specified key could not be found in the map or had no associated values.
Returns a map iterator on a function pointer for the specified map object.
am_map_for_each() will iterate over the list of key/value pairs and call each one. For every key in the map, a function can be invoked via the function pointer.
#include "am_map.h" AM_EXPORT am_status_t am_map_for_each(am_map_t, am_status_t (*func)(const char *key, const char *value, void **args), void **args);
This function takes the following parameters:
The specified map object.
Pointer to a key in an entry.
Pointer to application-defined parameters.
This function returns one of the following values:
If the function returns any code other than AM_SUCCESS, the iteration will terminate and the same status code will be returned to the user.
If the parameters are invalid.
Returns an entry iterator object that can be used to enumerate all entries in the specified map.
am_map_get_entries() returns a pointer to an entry iterator that can be used on the key/value pairs stored in the specified map object.
#include "am_map.h" AM_EXPORT am_status_t am_map_get_entries(am_map_t map, am_map_entry_iter_t *entry_iter_ptr);
This function takes the following parameters:
The specified map object.
Pointer specifying the location of the entry iterator.
If entry_iter_ptr is not NULL, the location it refers to will be set to NULL if an error is returned.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If no error is detected.
If unable to allocate memory for the entry iterator object.
If entry_iter_ptr is NULL.
If the specified map object contains no keys.
The pointer to the iterator must have only one iterator assigned. am_map_entry_iter_destroy() must be called when finished to destroy the iterator instance.
Inserts a new key/value pair into the specified map.
The map does not retain any references to the provided key or value parameters. It makes copies of any strings it needs to store.
#include "am_map.h" AM_EXPORT am_status_t am_map_insert(am_map_t map, const char *key, const char *value, int replace);
This function takes the following parameters:
The specified map object.
Pointer to the key for the entry.
If an entry with the same key already exists, the existing value is replaced by the new value.
Pointer to the [new] value to be associated with the key.
If not zero, the specified value replaces all existing values. Otherwise, the specified value is added to the list of values already associated with the specified key.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the entry was successfully inserted into the map object.
If unable to allocate memory for the value and, if necessary, the key.
If either the map, key, or value argument is NULL.
Returns the number of entries in the specified map object.
#include "am_map.h" AM_EXPORT size_t am_map_size(const am_map_t map);
This function takes the following parameter:
The specified map object.
This function returns a value based on size_t defined in the standard <stddef.h> header file. The value reflects the number of entries in the specified map object.
Destroys the specified value iterator.
am_map_value_iter_destroy() destroys the am_map_value_iter_t passed to it. The caller must be sure that this function is not called multiple times on the same am_map_value_iter_t.
#include "am_map.h" AM_EXPORT void am_map_value_iter_destroy(am_map_value_iter_t iter);
This function takes the following parameter:
The specified value iterator.
This function does not return a value.
Returns the value currently referenced by the specified value iterator.
#include "am_map.h" AM_EXPORT const char * am_map_value_iter_get(am_map_value_iter_t iter);
This function takes the following parameter:
The specified value iterator.
This function returns one of the following values:
The value.
If the specified iterator is NULL or does not reference a valid value.
Determines if the specified value iterator references a valid value.
#include "am_map.h" AM_EXPORT boolean_t am_map_value_iter_is_value_valid(am_map_value_iter_t iter);
This function takes the following parameter:
The specified value iterator.
This function returns one of the following values of the boolean_t enumeration (defined in the standard <types.h> header file):
The code used is dependent on the server operating system.
If the value is valid.
If the specified iterator is NULL or does not reference a valid value.
Advances the specified value iterator to the next value associated with the key that was specified when the iterator was created.
#include "am_map.h" AM_EXPORT boolean_t am_map_value_iter_next(am_map_value_iter_t iter);
This function takes the following parameter:
The specified value iterator.
This function returns one of the following values of the boolean_t enumeration (defined in the standard <types.h> header file):
The code used is dependent on the server operating system.
If successful.
If the specified iterator is NULL or does not reference a valid value after being updated.