Sun Java System Access Manager 7.1 C API Reference

Property Functions

The property functions defined in <am_properties.h> are:

`am_properties_copy()`

Duplicates a specified properties object.

Details

am_properties_copy() copies all the elements in the specified properties object, creates a duplicate instance, and assigns a pointer to it. The original object is not affected during the operation. The removal of any item in either structures does not affect the other.

Syntax

#include "am_properties.h"
AM_EXPORT am_status_t
am_properties_copy(am_properties_t source_properties,
                   am_properties_t *properties_ptr);

Parameters

This function takes the following parameters:

source_properties: The specified properties object.
properties_ptr: Pointer to the location of the copy of the specified properties 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 specified properties object was successfully copied.
AM_NO_MEMORY: If unable to allocate memory for the new properties object.
AM_INVALID_ARGUMENT: If the source_properties or properties_ptr argument is NULL.

Memory Concerns

After using the properties_ptr, call am_properties_destroy() to clean up the allocated memory.

`am_properties_create()`

Creates an empty properties object.

Syntax

#include "am_properties.h"
AM_EXPORT am_status_t
am_properties_create(am_properties_t *properties_ptr);

Parameters

This function takes the following parameters:

properties_ptr: Pointer to the location of the new properties 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 a properties object was successfully created.
AM_NO_MEMORY: If unable to allocate memory for the properties object.
AM_INVALID_ARGUMENT: If the properties_ptr argument is NULL.

Memory Concerns

After using the properties_ptr, call am_properties_destroy() to clean up the allocated memory.

`am_properties_destroy()`

Destroys the specified properties object.

Details

Be sure not to pass the same instance of am_properties_t to am_properties_destroy() more than once. After calling this function, it is advised to initialize properties to NULL.

Syntax

#include "am_properties.h"
AM_EXPORT void
am_properties_destroy(am_properties_t properties);

Parameters

This function takes the following parameter:

properties: Pointer to the specified properties object.

Returns

This function returns no values.

`am_properties_get()`

Retrieves the value associated with the specified key from the specified properties object.

Details

am_properties_get() checks for the presence of the specified key and returns its value, if present.

Syntax

#include "am_properties.h"
AM_EXPORT am_status_t
am_properties_get(am_properties_t properties,
                  const char *key,
                  const char **value_ptr);

Parameters

This function takes the following parameters:

properties: Pointer to the specified properties object.
key: Pointer to the specified key in the specified properties object.
value_ptr: Pointer to a pointer to the location where the value associated with the specified key will be stored.

Returns

One of the following values as well as value_ptr containing an unparsed string with the address of the location of the value.

AM_SUCCESS: If no error is detected.
AM_INVALID_ARGUMENT: If the properties, key, or value_ptr argument is NULL.
AM_NOT_FOUND: If the specified key has no associated value and a default value is not provided.
AM_INVALID_VALUE: If the value associated with the specified key cannot be parsed as required by the particular accessor function.
AM_NO_MEMORY: If insufficient memory is available to look up the key.

Memory Concerns

Do not modify value_ptr or free the memory.

`am_properties_get_boolean()`

Retrieves boolean type values associated with the specified key from the specified properties object.

Syntax

#include "am_properties.h"
AM_EXPORT am_status_t
am_properties_get_boolean(am_properties_t properties, 
                          const char *key,
                          int *value_ptr);

Parameters

This function takes the following parameters:

properties: The specified properties object.
key: Pointer to the specified key in the specified properties object.
value_ptr: Pointer to the location where the boolean associated with the specified key will be stored.

Returns

One of the following values stored in value_ptr:

!0: If the value associated with the specified key is true, on, or yes.
0: If the value associated with the specified key is false, off, or no.

If the associated value does not match any of these recognized boolean values, AM_INVALID_VALUE will be returned.

`am_properties_get_boolean_with_default()`

Retrieves boolean type values from the specified properties object.

Details

am_properties_get_boolean_with_default() will return a defined default value if no other value is present, contrary to the behavior of am_properties_get_boolean().

Syntax

#include "am_properties.h"
am_properties_get_boolean_with_default(am_properties_t properties,
                                       const char *key, 
                                       int default_value,
                                       int *value_ptr);

Parameters

This function takes the following parameters:

properties: The specified properties object.
key: Pointer to the specified key in the specified properties object.
default_value: Value to return if none is defined for the specified key.
value_ptr: Pointer to the location where the boolean associated with the specified key will be stored.

Returns

One of the following values stored in value_ptr:

!0: If the value associated with the specified key is true, on, or yes.
0: If the value associated with the specified key is false, off, or no.

If the associated value does not match any of the recognized boolean values, AM_INVALID_VALUE will be returned.

`am_properties_get_entries()`

Returns an iterator object that can be used to sequence through the entries in the specified properties object.

Syntax

#include "am_properties.h"
AM_EXPORT am_status_t
am_properties_get_entries(am_properties_t properties,
                          am_properties_iter_t *properties_iter_ptr);

Parameters

This function takes the following parameters:

properties: The specified properties object.
properties_iter_ptr: Pointer to the location of the new properties iterator 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 no error was detected.
AM_NO_MEMORY: If unable to allocate memory for the iterator object.
AM_INVALID_ARGUMENT: If properties_iter_ptr is NULL. If properties_iter_ptr is not NULL and an error is returned, the location that it refers to will be set to NULL.
AM_NOT_FOUND: If the specified properties object contains no entries.

`am_properties_get_positive_number()`

Retrieves a positive integer value associated with a specified key from the specified properties object.

Syntax

#include "am_properties.h"
AM_EXPORT am_status_t
am_properties_get_unsigned(am_properties_t properties, 
                           const char *key,
                           unsigned long default_value
                           unsigned long *value_ptr);

Parameters

This function takes the following parameters:

properties: Pointer to a properties object.
key: Pointer to the key in the properties object.
default_value: Value to return if none is defined for the specified key.
value_ptr: Pointer to the location where the returned integer will be stored.

Returns

This function returns the unsigned integer value associated with the specified key.

`am_properties_get_signed()`

Retrieves a signed integer value associated with the specified key from the specified properties object.

Syntax

#include "am_properties.h"
AM_EXPORT am_status_t
am_properties_get_signed(am_properties_t properties,
                         const char *key, 
                         long *value_ptr);

Parameters

This function takes the following parameters:

properties: The specified properties object.
key: Pointer to the specified key in the specified properties object.
value_ptr: Pointer to the location where the signed integer associated with the specified key will be stored.

Returns

This function returns a signed integer value associated with the specified key. If the associated value cannot be parsed as an integer or cannot be represented in the range LONG_MIN to LONG_MAX, AM_INVALID_VALUE will be returned.

`am_properties_get_signed_with_default()`

Retrieves a signed integer value associated with a specified key from the specified properties object.

Details

am_properties_get_signed_with_default() will return a defined default value if no other value is present, contrary to the behavior of am_properties_get_signed().

Syntax

#include "am_properties.h"
AM_EXPORT am_status_t
am_properties_get_signed_with_default(am_properties_t properties,
                                      const char *key, 
                                      long default_value,
                                      long *value_ptr);

Parameters

This function takes the following parameters:

properties: The specified properties object.
key: Pointer to the specified key in the specified properties object.
default_value: Value to return if none is defined for the specified key.
value_ptr: Pointer to the location where the signed integer associated with the specified key will be stored.

Returns

`am_properties_get_unsigned()`

Retrieves an unsigned integer value associated with a specified key from the specified properties object.

Syntax

#include "am_properties.h"
AM_EXPORT am_status_t
am_properties_get_unsigned(am_properties_t properties, 
                           const char *key,
                           unsigned long *value_ptr);

Parameters

This function takes the following parameters:

properties: Pointer to a properties object.
key: Pointer to the key in the properties object.
value_ptr: Pointer to the location where the integer associated with the specified key will be stored.

Returns

This function returns the unsigned integer value associated with the specified key.

`am_properties_get_unsigned_with_default()`

Retrieves an unsigned integer value associated with a specified key from the specified properties object.

Details

am_properties_get_unsigned_with_default() will return a defined default value if no other value is present, contrary to the behavior of am_properties_get_unsigned().

Syntax

#include "am_properties.h"
AM_EXPORT am_status_t
am_properties_get_unsigned_with_default(am_properties_t properties,
                                        const char *key,
                                        unsigned long default_value,
                                        unsigned long *value_ptr);

Parameters

This function takes the following parameters:

properties: The specified properties object.
key: Pointer to the specified key in the specified properties object.
default_value: Value to return if none is defined for the specified key.
value_ptr: Pointer to the location where the integer associated with the specified key will be stored.

Returns

This function returns the unsigned integer value associated with the specified key.

`am_properties_get_with_default()`

Retrieves the value (or the specified default) associated with the specified key from the specified properties object.

Details

am_properties_get_with_default() checks for the presence of the specified key and returns its value, if present. Contrary to am_properties_get(), if no value is present, it returns the specified default value.

Syntax

#include "am_properties.h"
AM_EXPORT am_status_t
am_properties_get_with_default(am_properties_t properties,
                               const char *key, 
                               const char *default_value,
                               const char **value_ptr);

Parameters

This function takes the following parameters:

properties: The specified properties object.
key: Pointer to the specified key in the specified properties object.
default_value: Pointer to the value to be returned in case of no associated value.
value_ptr: Pointer to a pointer to the location where the returned value will be stored.

Returns

One of the following values as well as value_ptr containing an unparsed string with the address of the location of the value.

AM_SUCCESS: If no error is detected.
AM_INVALID_ARGUMENT: If the properties, key, or value_ptr argument is NULL.
AM_NOT_FOUND: If the specified key has no associated value and a default value is not provided.
AM_INVALID_VALUE: If the value associated with the specified key is cannot be parsed as required by the particular accessor function.
AM_NO_MEMORY: If insufficient memory is available to look up the key.

Memory Concerns

Do not modify value_ptr or free the memory.

`am_properties_is_set()`

Determines whether the specified key of the specified properties object contains a value.

Details

am_properties_is_set() does not return the value.

Syntax

#include "am_properties.h"
AM_EXPORT boolean_t
am_properties_is_set(am_properties_t properties,
                     const char *key);

Parameters

This function takes the following parameters:

properties: The specified properties object.
key: Pointer to the name of a key.

Returns

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

!0: If the property has a value.
0: Otherwise

`am_properties_iter_destroy()`

Destroys the specified iterator object.

Syntax

#include "am_properties.h"
AM_EXPORT void
am_properties_iter_destroy(am_properties_iter_t properties_iter);

Parameters

This function takes the following parameter:

properties_iter: The specified iterator object. It may be NULL.

Returns

This function returns no value.

`am_properties_iter_get_key()`

Returns the key of the entry currently referenced by the specified iterator object.

Syntax

#include "am_properties.h"
AM_EXPORT const char * 
am_properties_iter_get_key (am_properties_iter_t properties_iter);

Parameters

This function takes the following parameter:

properties_iter: The specified iterator object.

Returns

This function returns one of the following values:

NULL: If the specified iterator is NULL or does not reference a valid entry.
char *: The key.

`am_properties_iter_get_value()`

Returns the value of the key currently referenced by the specified iterator object.

Syntax

#include "am_properties.h"
AM_EXPORT const char * 
am_properties_iter_get_value (am_properties_iter_t properties_iter);

Parameters

This function takes the following parameters:

properties_iter: The specified iterator object.

Returns

This function returns one of the following values:

NULL: If the specified iterator is NULL or does not reference a valid entry.
char *: Value associated with the key.

`am_properties_load()`

Loads information from the specified properties file into the specified properties object.

Details

The file is assumed to follow the syntax of a standard Java properties file.

Syntax

#include "am_properties.h"
AM_EXPORT am_status_t
am_properties_load(am_properties_t properties, 
                   const char *file_name);

Parameters

This function takes the following parameters:

properties: The specified properties object.
file_name: Pointer to a properties file.

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 has occurred.
AM_NOT_FOUND: If the specified file does not exist.
AM_NSPR_ERROR: If there is a problem accessing the file.
AM_INVALID_ARGUMENT: If properties or file_name is NULL or file_name points to an empty string.
AM_NO_MEMORY: If unable to allocate memory to store the property information.

`am_properties_set()`

Sets a value for the specified key in the specified properties object.

Details

The specified value will replace any existing value.

Syntax

#include "am_properties.h"
AM_EXPORT am_status_t
am_properties_set(am_properties_t properties, 
                  const char *key,
                  const char *value);

Parameters

This function takes the following parameters:

properties: The specified properties object.
key: Pointer to the key being modified.
value: Pointer to the value to associate 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 no error is detected.
AM_INVALID_ARGUMENT: If the properties, key, or value argument is NULL.
AM_NO_MEMORY: If unable to allocate memory to store the new key/value.

`am_properties_store()`

Retrieves key/value information from the specified properties object and stores it in the specified file.

Syntax

#include "am_properties.h"
AM_EXPORT am_status_t
am_properties_store(am_properties_t properties, 
                    const char *file_name);

Parameters

This function takes the following parameters:

properties: The specified properties object.
file_name: Pointer to the file in which the property information will be stored.

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_NSPR_ERROR: If there is a problem writing to the file.
AM_INVALID_ARGUMENT: If properties or file_name is NULL or file_name points to an empty string.