Chapter 7 Properties Functions

This chapter provides a reference to the properties map used by clients of the Sun Java^TM System Access Manager Client APIs. Function summaries include a short description, syntax, parameters and returns.

The following functions are contained in the header file am_properties.h :

• am_properties_copy()

• am_properties_create()

• am_properties_destroy()

• am_properties_get()

• am_properties_get_boolean()

• am_properties_get_boolean_with_default()

• am_properties_get_entries()

• am_properties_get_signed()

• am_properties_get_signed_with_default()

• am_properties_get_unsigned()

• am_properties_get_unsigned_with_default()

• am_properties_get_with_default()

• am_properties_is_set()

• am_properties_iter_destroy()

• am_properties_iter_get_key()

• am_properties_iter_get_value()

• am_properties_load()

• am_properties_set()

• am_properties_store()

am_properties_copy()

Makes a copy of a properties object.

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 handle for the properties object to be copied.

properties_ptr

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

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

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

Details

Creates an instance of am_properties_t and assigns it to properties_ptr. The function copies all the elements in the source_ptr to properties_ptr. The source_ptr is not affected during this operation.

Memory Concerns: After the usage of the instance properties_ptr the caller must call am_properties_destroy to clean up the allocated memory. The removal of any item in either structures do not affect the other.

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

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

Returns

This function returns am_status_t with one of the following values:

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.

Details

Creates an instance of am_properties_t and assigns it to properties_ptr.

Memory Concerns: After the usage of the instance the caller must call am_properties_destroy to clean up the allocated memory.

am_properties_destroy()

Destroys the properties object referenced by the provided handle.

Syntax

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

Parameters

This function takes the following parameters:

properties

The handle for the properties object to be destroyed.

Returns

This function returns one of the following values:

AM_SUCCESS

If the operation was successful.

AM_INVALID_ARGUMENT

If properties argument is NULL.

Details

Destroys an instance of am_properties_t.

Memory Concerns: Caller must make sure not to pass the same instance of am_properties_t to be destroyed more than once. After calling this function it is advised that the caller initializes properties to NULL.

am_properties_get()

This function and all functions beginning with am_properties_get retrieve values from the properties map. The following parameters and exceptions are common to all functions in the am_propteries_get collection. Additional return values may be specified some functions.

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

Handle to the properties object to be examined.

key

Name of the property to look up.

value_ptr

A pointer to where to store the value associated with the default value.

default_value

Default value to use if there is no value associated with the specified key.

Returns

This function returns the unparsed string form of the value associated with one of the following keys:

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.

Details

This function checks if the key is present is the properties instance and returns its value.

Memory Concerns: Caller must not modify the value_ptr structure or free the memory.

am_properties_get_boolean()

Retrieves values from the properties map.

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

See am_properties_get().

Returns

• The unparsed string form of the value associated with the specified key. See am_properties_get().

• A value stored in value_ptr with one of the following values.

!0

If the value associated with the specified key is one of: true, on, or yes.

0

If the value associated with the specified key is one of: false, off, or no.

Details

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

See also am_properties_get().

am_properties_get_boolean_with_default()

Retrieves values from the properties map.

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

See am_properties_get().

Returns

• The unparsed string form of the value associated with the specified key. See am_properties_get().

• A value stored in value_ptr with one of the following values.

!0

If the value associated with the specified key is one of: true, on, or yes.

0

If the value associated with the specified key is one of: false, off, or no.

Details

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

See also am_properties_get().

am_properties_get_entries()

Returns an iterator object that can be used to enumerate all of the entries in the specified properties object. See also am_properties_get() .

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

properties_iter_ptr

Pointer to where the handle for the new properties 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 properties iterator object.

AM_INVALID_ARGUMENT

If the properties_iter_ptr argument is NULL.

AM_NOT_FOUND

If the specified properties object contains no entries.

Details

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

See also am_properties_get().

am_properties_get_signed()

Retrieves values from the properties map.

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

See am_properties_get().

Returns

This function returns the value stored in value_ptr which is the signed integer value associated with the specified key.

Details

If the associated value cannot be parsed as an integer or cannot be represented in the range LONG_MIN to LONG_MAX, then AM_INVALID_VALUE will be returned.

See also am_properties_get().

am_properties_get_signed_with_default()

Retrieve values from the properties map.

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

See am_properties_get().

Returns

This function returns the value stored in value_ptr which is the signed integer value associated with the specified key.

Details

If the associated value cannot be parsed as an integer or cannot be represented in the range LONG_MIN to LONG_MAX, then AM_INVALID_VALUE will be returned.

See also am_properties_get().

am_properties_get_unsigned()

See am_properties_get().

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

See am_properties_get().

Returns

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

Details

See am_properties_get().

am_properties_get_unsigned_with_default()

See am_properties_get().

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

See am_properties_get().

Returns

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

Details

See am_properties_get().

am_properties_get_with_default()

Retrieves values from the properties map.

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 am_properties_t instance from which the keys value needs to be extracted. key The key whose value will be returned.

default_value

The value to be returned in case of any error condition. value_ptr The value pointer to which the value will be assigned to. This is an output parameter. Returns Return values may be ignored.

Details

This function checks if the key is present is the properties instance. If the key is not present, the function returns the default value passed in. Otherwise it returns the value of the key.

Memory Concerns: Caller must not modify the value_ptr structure or free the memory.

am_properties_is_set()

Determines whether the object contains property with the specified name.

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

Handle to the properties object to be examined.

key

Name of the property to look up.

Returns

This function returns boolean_t with one of the following values:

!0

If the property has a value.

0

Otherwise

am_properties_iter_destroy()

Destroys the properties iterator object referenced by the provided handle.

Syntax

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

Parameters

This function takes the following parameters:

properties_iter

The handle for the key iterator object to be destroyed. The handle may be NULL.

Returns

None

am_properties_iter_get_key()

Returns the key of the element currently referenced by the specified iterator.

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

properties_iter

The handle for the properties 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.

am_properties_iter_get_value()

Returns the value of the element currently referenced by the specified iterator.

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 handle for the properties 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.

value

Otherwise.

am_properties_load()

Loads property information from the specified 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

Handle to the properties object to be modified.

file_name

Name of the file from which to load the property information.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If no error is detected.

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.

Details

The file is expected to use the standard Java Properties file syntax.

am_properties_set()

Sets the value associated with the specified key.

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

Handle to the properties object to be modified.

key

The key to modify.

value

The value to associate with the specified key.

Returns

This function returns am_status_t with one of the following values:

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.

Details

The specified value will replace any previously existing value.

am_properties_store()

Stores the property information 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

Handle to the properties object to be stored.

file_name

Name of the file in which to store the property information.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If no error is detected.

AM_NSPR_ERROR

If there is a problem writing the properties to the file.

AM_INVALID_ARGUMENT

If properties or file_name is NULL or file_name points to an empty string.