Chapter 5 Map Functions

This chapter provides a reference to functions you can use for creating, destroying, and manipulating the map objects used by the Sun Java^TM System Access Management SDK. Function summaries include a short description, syntax, parameters and returns.

The following functions are contained in the header file am_map.h.

• 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_first_value()

• am_map_get_entries()

• am_map_insert()

• am_map_size()

• am_map_entry_iter_destroy()

• am_map_value_iter_get()

• am_map_value_iter_is_value_valid()

am_map_clear()

Erases all of the entries in the specified map.

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 handle for the map object to be modified.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If no error was detected.

AM_INVALID_ARGUMENT

If the map argument is NULL.

am_map_copy()

Makes a copy of a 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 handle for the map object to be destroyed. The handle may be NULL.

map_ptr

A pointer to where to store the handle of the new created map object.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If a 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.

Details

This function creates an instance of am_map_t structure, copies all the elements in source_map into the newly created structure and assigns it to map_ptr. It does not alter the contents of source_map.

Memory Concerns: The caller must make sure not to pass a map_ptr which as a valid am_map_t structure, otherwise the reference will be lost. The caller must destroy map_ptr after usage by calling am_map_destroy.

am_map_create()

Creates a new, empty map object.

Syntax

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

Parameters

This function takes the following parameters:

map_ptr

Pointer to where the handle for the new map object should be stored.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If a map was successfully created.

AM_NO_MEMORY

If unable to allocate memory for the map object.

AM_INVALID_ARGUMENT

If the map_ptr parameter is NULL.

am_map_destroy()

Destroys the map object referenced by the provided handle.

Syntax

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

Parameters

This function takes the following parameters:

map

The handle for the map object to be destroyed. The handle may be NULL.

Returns

This function returns one of the following values:

AM_SUCCESS

If the destroy operation was successfully performed.

AM_NO_MEMORY

If there was an internal memory operation error.

AM_INVALID_ARGUMENT

If the address of map_ptr or source_map is invalid.

Details

This function destroys an instance of am_map_t structure which is pointed by map_ptr.

Memory Concerns: Care must be taken that map_ptr was not freed before by calling am_map_destroy or by erroneously calling the system void free (void *) function.

am_map_entry_iter_destroy()

Destroys the entry iterator object referenced by the provided handle.

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 handle for the key iterator object to be destroyed. The handle may be NULL.

am_map_entry_iter_get_first_value()

Returns the first value of the element currently referenced by the specified 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 handle for the entry iterator object to be examined.

Returns

This function returns const char * with one of the following values:

Value

If the operation is successful, returns the first associated value of this iterator. The order of insertion into the map does not guarantee the value returned.

NULL

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

Details

This function destroys the am_map_entry_iterator_t passed to it.

Memory Concerns: Caller must be sure that this function is not called multiple times on the same am_map_entry_iter_t.

am_map_entry_iter_get_key()

Returns the key of the element currently referenced by the specified 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 handle for the entry iterator object to be examined.

Returns

This function returns const char * with one of the following values:

NULL

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

key

Otherwise

Details

This function returns the key of this key-value pair entry iterator.

Memory Concerns: Caller must not modify or free the return value.

am_map_entry_iter_get_values()

Returns an iterator object that can be used to enumerate all of the values associated with the entry referenced by the iterator you specify.

Syntax

#include "am_map.h"
AM_EXPORT am_status_t
am_map_entry_iter_get_values(am_map_entry_iter_t entry_iter,

Parameters

This function takes the following parameters:

entry_iter

The handle for the entry iterator object to be examined.

value_iter_ptr

Pointer to where the handle for the new value iterator object should be stored.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If no error was detected.

AM_NO_MEMORY

If unable to allocate memory for the value iterator object.

AM_INVALID_ARGUMENT

If the value_iter_ptr argument is NULL.

AM_NOT_FOUND

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

Details

This function returns an am_map_value_iter_t that enumerates over the values associated with am_map_entry_iter_t.

Memory Concerns After the use of value_iter_t the caller must call am_map_value_iter_destroy.

am_map_entry_iter_is_entry_valid()

Determines if the specified iterator references a valid entry.

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 handle for the entry iterator object to be examined.

Returns

This function returns boolean_t with one of the following values:

0

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

!0

Otherwise.

am_map_entry_iter_next()

Advances the specified iterator to the next entry in the map specified when the iterator was 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 parameters:

entry_iter

The handle for the entry iterator object to be modified.

Returns

This function returns boolean_t with one of the following values:

0

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

!0

Otherwise.

am_map_erase()

Erases the specified key from the specified map.

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 handle for the map object to be modified.

key

The key for the entry to erase.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If the entry was successfully erased from the map.

AM_INVALID_ARGUMENT

If either the map or key argument is NULL.

AM_NOT_FOUND

If the specified key is not currently in the map.

am_map_find()

Returns an iterator object that can be used to enumerate all of the values associated with the specified key.

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 handle for the map object to be examined.

key

The key for the entry to look up.

value_iter_ptr

Pointer to where the handle for the new value iterator object should be stored.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If no error was detected.

AM_NO_MEMORY

If unable to allocate memory for the value iterator object.

AM_INVALID_ARGUMENT

If the value_iter_ptr argument is NULL.

AM_NOT_FOUND

If the specified key could not be found in the map.

Details

This function takes a key and returns an iterator that iterates over the values associated with the key.

If the value_iter_ptr argument is non-NULL, then the location that it refers to will be set to NULL if an error is returned.

Memory Concerns: At the end of usage of value_iter_ptr, the caller must call am_map_value_iter_destroy with the iterators pointer.

am_map_find_first_value()

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

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 handle for the map object to be examined.

key

The key for the entry to look up.

Returns

This function returns const char * with one of the following values:

NULL

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

value

Otherwise, the first value associated with the key.

Details

This function takes a key and returns the first value associated with the key.

Memory Concerns: Caller must not modify or free the return value.

am_map_get_entries()

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

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 handle for the map object to be examined.

entry_iter_ptr

Pointer to where the handle for the new entry iterator object should be stored.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If no error was detected.

AM_NO_MEMORY

If unable to allocate memory for the entry iterator object.

AM_INVALID_ARGUMENT

If the entry_iter_ptr argument is NULL.

AM_NOT_FOUND

If the specified map contains no keys.

Details

This function extracts an iterator pointer that can be used to iterate over the key value pairs stored in this table.

Memory Concerns: The iterator pointer passed in must not have non-destroyed iterators assigned to them. The caller, in future must call am_map_entry_iter_destroy to destroy the iterator instance.

If the entry_iter_ptr argument is non-NULL, then the location that it refers to will be set to NULL if an error is returned.

am_map_insert()

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

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 handle for the map object to be modified.

key

The key for the entry.

value

The (new) value to be associated with the key.

replace

If non-zero, then the specified value replaces all of the existing values. Otherwise the specified value is added to the list of values associated with the specified key.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If the entry was successfully inserted into the map.

AM_INVALID_ARGUMENT

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

AM_NO_MEMORY

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

Details

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

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

am_map_size()

Returns the number of elements in the map.

Syntax

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

Parameters

This function takes the following parameters:

map_ptr

The pointer to the map for which size is requested.

Returns

This function returns size_t with the size whose type is size_t.

am_map_entry_iter_destroy()

Destroys the entry iterator object referenced by the provided handle.

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 handle for the key iterator object to be destroyed. The handle may be NULL.

Details

This function destroys the am_map_entry_iterator_t passed to it.

Memory Concerns: Caller must be sure that this function is not called multiple times on the same am_map_entry_iter_t.

am_map_value_iter_get()

Returns the value currently referenced by the specified 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 parameters:

value_iter

The handle for the value iterator object to be examined.

Returns

This function returns const char * with one of the following values:

NULL

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

value

Otherwise

am_map_value_iter_is_value_valid()

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

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 parameters:

value_iter

The handle for the value iterator object to be modified.

Returns

This function returns AM_EXPORT boolean_t with one of the following values:

0

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

!0

Otherwise