Chapter 6 Mapping Data Types and Functions

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:

• The Mapping API for C

• Mapping Data Types

• Mapping Functions

The Mapping API for C

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.

Mapping Data Types

The mapping types defined in <am_map.h> are:

• am_map_t

• am_map_entry_iter_t

• am_map_value_iter_t

am_map_t

Pointer to a map object consisting of key/value entry mappings.

Syntax

#include "am_map.h"
typedef struct am_map *am_map_t;

Members

am_map is an opaque structure with no accessible members.

Memory Concerns

Free the allocated structure by calling am_map_destroy(). See am_map_destroy().

am_map_entry_iter_t

Pointer to an iterator for the entries in a map object.

Syntax

#include "am_map.h"
typedef struct am_map_entry_iter *am_map_entry_iter_t;

Members

am_map_entry_iter is an opaque structure with no accessible members.

am_map_value_iter_t

Pointer to an iterator for the values in a map object associated with a specified key.

Syntax

#include "am_map.h"
typedef struct am_map_value_iter *am_map_value_iter_t;

Members

am_map_value_iter is an opaque structure with no accessible members.

Mapping Functions

The mapping functions defined in <am_map.h> are:

• am_map_clear()

• am_map_copy()

• am_map_create()

• am_map_destroy()

• am_map_entry_iter_destroy()

• am_map_entry_iter_get_first_value()

• am_map_entry_iter_get_key()

• am_map_entry_iter_get_values()

• am_map_entry_iter_is_entry_valid()

• am_map_entry_iter_next()

• am_map_erase()

• am_map_find()

• am_map_find_first_value()

• am_map_for_each()

• am_map_get_entries()

• am_map_insert()

• am_map_size()

• am_map_value_iter_destroy()

• am_map_value_iter_get()

• am_map_value_iter_is_value_valid()

• am_map_value_iter_next()

am_map_clear()

Erases all of the entries in the specified map object.

Syntax

#include "am_map.h"
AM_EXPORT am_status_t
am_map_clear(am_map_t map);

Parameters

This function takes the following parameter:

map

The map object.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS

If the entries were successfully erased.

AM_INVALID_ARGUMENT

If the map argument is NULL.

am_map_copy()

Makes a copy of the specified map object.

Details

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.

Syntax

#include "am_map.h"
AM_EXPORT am_status_t
am_map_copy(am_map_t source_map, 
            am_map_t *map_ptr);

Parameters

This function takes the following parameters:

source_map

The specified map object. It may be NULL.

map_ptr

Pointer to the location of the new map object copy.

---

Caution –

Be sure not to pass map_ptr as a valid am_map structure as the reference will be lost.

---

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS

If the map object was successfully copied.

AM_NO_MEMORY

If unable to allocate memory for the new map object.

AM_INVALID_ARGUMENT

If the source_map or map_ptr argument is NULL.

Memory Concerns

The caller must destroy map_ptr after usage by calling am_map_destroy().

am_map_create()

Creates a new, empty map object.

Details

am_map_create() creates an instance of a am_map_t and returns a pointer back to the caller.

Syntax

#include "am_map.h"
AM_EXPORT am_status_t
am_map_create(am_map_t *map_ptr);

Parameters

This function takes the following parameter:

map_ptr

Pointer specifying the location of the new map object.

---

Caution –

Be sure not to pass map_ptr as a valid am_map structure as the reference will be lost.

---

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS

If the map object was successfully created.

AM_NO_MEMORY

If unable to allocate memory for the new map object.

AM_INVALID_ARGUMENT

If the map_ptr argument is NULL.

am_map_destroy()

Destroys the specified map object.

Syntax

#include "am_map.h"
AM_EXPORT void
am_map_destroy(am_map_t map);

Parameters

This function takes the following parameter:

map

The specified map object. It may be NULL.

---

Caution –

Be sure not to pass map as a valid am_map structure as the reference will be lost.

---

Returns

This function does not return a value.

Memory Concerns

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.

am_map_entry_iter_destroy()

Destroys the specified entry iterator.

Syntax

#include "am_map.h"
AM_EXPORT void
am_map_entry_iter_destroy(am_map_entry_iter_t entry_iter);

Parameters

This function takes the following parameter:

entry_iter

The specified entry iterator. It may be NULL.

Returns

This function does not return a value.

am_map_entry_iter_get_first_value()

Returns the first value assigned to the entry currently being referenced by the specified entry iterator.

Syntax

#include "am_map.h"
AM_EXPORT const char *
am_map_entry_iter_get_first_value(am_map_entry_iter_t entry_iter);

Parameters

This function takes the following parameter:

entry_iter

The specified entry iterator. It may be NULL.

Returns

This function returns one of the following:

char *

Returns the first associated value of the specified key. The order of insertion into the map does not guarantee the value returned.

NULL

If the specified iterator is NULL, does not reference a valid entry, or the entry does not have any associated values.

Memory Concerns

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.

am_map_entry_iter_get_key()

Returns the key assigned to the entry currently being referenced by the specified entry iterator.

Syntax

#include "am_map.h"
AM_EXPORT const char *
am_map_entry_iter_get_key(am_map_entry_iter_t entry_iter);

Parameters

This function takes the following parameters:

entry_iter

The specified entry iterator.

Returns

This function returns one of the following values:

char *

Returns the key.

---

Note –

Caller must not modify or free the return value.

---

NULL

If the specified key iterator is NULL or does not reference a valid entry.

am_map_entry_iter_get_values()

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.

Syntax

#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);

Parameters

This function takes the following parameters:

entry_iter

The specified entry iterator.

value_iter_ptr

Pointer specifying the location of the value iterator.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS

If no error was detected.

AM_NO_MEMORY

If unable to allocate memory for the key iterator.

AM_INVALID_ARGUMENT

If the value_iter_ptr argument is NULL.

---

Note –

If value_iter_ptr is not NULL and an error is returned, the location that it references will be set to NULL.

---

AM_NOT_FOUND

If the entry_iter argument is NULL or does not reference a valid entry.

Memory Concerns

After using am_map_value_iter_t, the caller must call am_map_value_iter_destroy().

am_map_entry_iter_is_entry_valid()

Determines if the entry currently being referenced by the specified entry iterator is valid.

Syntax

#include "am_map.h"
AM_EXPORT boolean_t
am_map_entry_iter_is_entry_valid(am_map_entry_iter_t entry_iter);

Parameters

This function takes the following parameter:

entry_iter

The specified entry iterator.

Returns

This function returns one of the following values of the boolean_t enumeration (defined in the standard <types.h> header file):

---

Note –

The code used is dependent on the server operating system.

---

!0

If the entry is valid.

0

If the specified iterator is NULL or does not reference a valid entry.

am_map_entry_iter_next()

Advances the specified entry iterator to the next entry in the map specified when the iterator was first created.

Syntax

#include "am_map.h"
AM_EXPORT boolean_t
am_map_entry_iter_next(am_map_entry_iter_t entry_iter);

Parameters

This function takes the following parameter:

entry_iter

The specified event iterator.

Returns

This function returns one of the following values of the boolean_t enumeration (defined in the standard <types.h> header file):

---

Note –

The code used is dependent on the server operating system.

---

!0

If the entry is valid.

0

If the specified iterator is NULL or does not reference a valid entry after being updated.

am_map_erase()

Erases the entry, associated with the specified key, from the specified map object.

Syntax

#include "am_map.h"
AM_EXPORT am_status_t
am_map_erase(am_map_t map,
             const char *key);

Parameters

This function takes the following parameters:

map

The specified map object.

key

Pointer to the key of the entry to be erased.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS

If the entry was successfully erased.

AM_INVALID_ARGUMENT

If either the map or key argument is NULL.

AM_NOT_FOUND

If the specified key is not in the map.

am_map_find()

Returns a value iterator that can sequence through all values associated with the specified key in the specified map object.

Syntax

#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);

Parameters

This function takes the following parameters:

map

The specified map object.

key

Pointer to a key.

value_iter_ptr

Pointer specifying the location of the returned value iterator.

---

Note –

If value_iter_ptr is not NULL, the location that it references will be set to NULL if an error is returned.

---

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS

If no error was detected.

AM_NO_MEMORY

If unable to allocate memory for the key iterator.

AM_INVALID_ARGUMENT

If the value_iter_ptr argument is NULL.

AM_NOT_FOUND

If the specified key is not found in the map.

Memory Concerns

After using value_iter_ptr, the caller must call am_map_value_iter_destroy().

am_map_find_first_value()

Returns the first value associated with the specified key in the specified map object.

Details

am_map_find_first_value() takes a key and returns the first value associated with that key.

Syntax

#include "am_map.h"
AM_EXPORT const char *
am_map_find_first_value(am_map_t map, 
                        const char *key);

Parameters

This function takes the following parameters:

map

The specified map object.

key

Pointer to a key.

Returns

This function returns one of the following values:

char *

Returns the first value associated with the specified key.

---

Note –

Caller must not modify or free the return value.

---

NULL

If the specified key could not be found in the map or had no associated values.

am_map_for_each()

Returns a map iterator on a function pointer for the specified map object.

Details

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.

Syntax

#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);

Parameters

This function takes the following parameters:

am_map_t

The specified map object.

key

Pointer to a key in an entry.

args

Pointer to application-defined parameters.

Returns

This function returns one of the following values:

Other codes

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.

AM_INVALID_ARGUMENT

If the parameters are invalid.

am_map_get_entries()

Returns an entry iterator object that can be used to enumerate all entries in the specified map.

Details

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.

Syntax

#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);

Parameters

This function takes the following parameters:

map

The specified map object.

entry_iter_ptr

Pointer specifying the location of the entry iterator.

---

Note –

If entry_iter_ptr is not NULL, the location it refers to will be set to NULL if an error is returned.

---

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS

If no error is detected.

AM_NO_MEMORY

If unable to allocate memory for the entry iterator object.

AM_INVALID_ARGUMENT

If entry_iter_ptr is NULL.

AM_NOT_FOUND

If the specified map object contains no keys.

Memory Concerns

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.

am_map_insert()

Inserts a new key/value pair into the specified map.

Details

The map does not retain any references to the provided key or value parameters. It makes copies of any strings it needs to store.

Syntax

#include "am_map.h"
AM_EXPORT am_status_t
am_map_insert(am_map_t map, 
              const char *key, 
              const char *value,
              int replace);

Parameters

This function takes the following parameters:

map

The specified map object.

key

Pointer to the key for the entry.

---

Note –

If an entry with the same key already exists, the existing value is replaced by the new value.

---

value

Pointer to the [new] value to be associated with the key.

replace

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.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS

If the entry was successfully inserted into the map object.

AM_NO_MEMORY

If unable to allocate memory for the value and, if necessary, the key.

AM_INVALID_ARGUMENT

If either the map, key, or value argument is NULL.

am_map_size()

Returns the number of entries in the specified map object.

Syntax

#include "am_map.h"
AM_EXPORT size_t
am_map_size(const am_map_t map);

Parameters

This function takes the following parameter:

map

The specified map object.

Returns

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.

am_map_value_iter_destroy()

Destroys the specified value iterator.

Details

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.

Syntax

#include "am_map.h"
AM_EXPORT void
am_map_value_iter_destroy(am_map_value_iter_t iter);

Parameters

This function takes the following parameter:

iter

The specified value iterator.

Returns

This function does not return a value.

am_map_value_iter_get()

Returns the value currently referenced by the specified value iterator.

Syntax

#include "am_map.h"
AM_EXPORT const char *
am_map_value_iter_get(am_map_value_iter_t iter);

Parameters

This function takes the following parameter:

iter

The specified value iterator.

Returns

This function returns one of the following values:

char *

The value.

NULL

If the specified iterator is NULL or does not reference a valid value.

am_map_value_iter_is_value_valid()

Determines if the specified value iterator references a valid value.

Syntax

#include "am_map.h"
AM_EXPORT boolean_t
am_map_value_iter_is_value_valid(am_map_value_iter_t iter);

Parameters

This function takes the following parameter:

iter

The specified value iterator.

Returns

This function returns one of the following values of the boolean_t enumeration (defined in the standard <types.h> header file):

---

Note –

The code used is dependent on the server operating system.

---

!0

If the value is valid.

0

If the specified iterator is NULL or does not reference a valid value.

am_map_value_iter_next()

Advances the specified value iterator to the next value associated with the key that was specified when the iterator was created.

Syntax

#include "am_map.h"
AM_EXPORT boolean_t
am_map_value_iter_next(am_map_value_iter_t iter);

Parameters

This function takes the following parameter:

iter

The specified value iterator.

Returns

This function returns one of the following values of the boolean_t enumeration (defined in the standard <types.h> header file):

---

Note –

The code used is dependent on the server operating system.

---

!0

If successful.

0

If the specified iterator is NULL or does not reference a valid value after being updated.