|
| |
| Sun Java System Identity Server 2004Q2 Developer's Reference | |
Chapter 4
Map FunctionsThis chapter provides a reference to functions you can use for creating, destroying, and manipulating the map objects used by the Sun Java™ System Identity Server 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()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 parameters:
Returns
This function returns am_status_t with one of the following values:
Value
Description
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:
Parameter
Description
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_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:
Returns
This function returns am_status_t with one of the following values:
Value
Description
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:
Returns
None
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 parameters:
Parameter
Description
entry_iter
The handle for the key iterator object to be destroyed. The handle may be NULL.
Returns
None
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 parameters:
Returns
This function returns const char * with one of the following values:
Value
Description
NULL
If the specified iterator is NULL or does not reference a valid entry or the entry does not have any associated values.
value
Otherwise.
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:
Returns
This function returns const char * with one of the following values:
Value
Description
NULL
If the specified iterator is NULL or does not reference a valid entry.
key
Otherwise
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:
Parameter
Description
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_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 parameters:
Returns
This function returns boolean_t with one of the following values:
Value
Description
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:
Returns
This function returns boolean_t with one of the following values:
Value
Description
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:
Parameter
Description
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_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:
Returns
This function returns am_status_t with one of the following values:
Details
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.
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:
Parameter
Description
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:
Value
Description
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.
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:
Parameter
Description
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:
Details
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:
Returns
This function returns am_status_t with one of the following values:
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:
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 parameters:
Parameter
Description
entry_iter
The handle for the key iterator object to be destroyed. The handle may be NULL.
Returns
None
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:
Returns
This function returns const char * with one of the following values:
Value
Description
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:
Returns
This function returnsAM_EXPORT boolean_t with one of the following values:
Value
Description
0
If the specified iterator is NULL or does not reference a valid value after being updated.
!0
Otherwise