Chapter 7 Property Data Types and Functions

Sun OpenSSO Enterprise contains public data types and functions you can use to associate properties between an external application and OpenSSO Enterprise itself. Reference summaries include a short description, syntax, parameters and returns. Prototypes for the types and functions are contained in the <am_properties.h> header file. This chapter contains the following sections:

• Property Data Types

• Property Functions

The Property API for C

The property API for C are used to manipulate configuration data read from a standard Java^TM properties file. A properties file is a text file that contains a list of key/value pairs. More information on properties files can be found at http://java.sun.com/j2se/1.4.2/docs/api/java/util/Properties.html#load(java.io.InputStream).

Property Data Types

The property data types defined in <am_properties.h> are:

• am_properties_t

• am_properties_iter_t

am_properties_t

Pointer to a properties object.

Details

am_properties_t provides a key to single value mapping. It provides the additional functionality of loading a configuration file and getting values of specific data types.

Syntax

#include "am_properties.h"
typedef struct am_properties *am_properties_t;

Members

am_properties is an opaque structure with no accessible members.

am_properties_iter_t

Pointer to the iterator for a properties object.

Syntax

#include "am_properties.h"
typedef struct am_properties_iter *am_properties_iter_t;

Members

am_properties_iter is an opaque structure with no accessible members.

Property Functions

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

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

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

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

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_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.