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:
The property API for C are used to manipulate configuration data read from a standard JavaTM 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).
The property data types defined in <am_properties.h> are:
Pointer to a properties object.
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.
#include "am_properties.h" typedef struct am_properties *am_properties_t;
am_properties is an opaque structure with no accessible members.
Pointer to the iterator for a properties object.
#include "am_properties.h" typedef struct am_properties_iter *am_properties_iter_t;
am_properties_iter is an opaque structure with no accessible members.
The property functions defined in <am_properties.h> are:
Duplicates a specified properties object.
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.
#include "am_properties.h" AM_EXPORT am_status_t am_properties_copy(am_properties_t source_properties, am_properties_t *properties_ptr);
This function takes the following parameters:
The specified properties object.
Pointer to the location of the copy of the specified properties object.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the specified properties object was successfully copied.
If unable to allocate memory for the new properties object.
If the source_properties or properties_ptr argument is NULL.
After using the properties_ptr, call am_properties_destroy() to clean up the allocated memory.
Creates an empty properties object.
#include "am_properties.h" AM_EXPORT am_status_t am_properties_create(am_properties_t *properties_ptr);
This function takes the following parameters:
Pointer to the location of the new properties object.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If a properties object was successfully created.
If unable to allocate memory for the properties object.
If the properties_ptr argument is NULL.
After using the properties_ptr, call am_properties_destroy() to clean up the allocated memory.
Destroys the specified properties object.
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.
#include "am_properties.h" AM_EXPORT void am_properties_destroy(am_properties_t properties);
This function takes the following parameter:
Pointer to the specified properties object.
This function returns no values.
Retrieves the value associated with the specified key from the specified properties object.
am_properties_get() checks for the presence of the specified key and returns its value, if present.
#include "am_properties.h" AM_EXPORT am_status_t am_properties_get(am_properties_t properties, const char *key, const char **value_ptr);
This function takes the following parameters:
Pointer to the specified properties object.
Pointer to the specified key in the specified properties object.
Pointer to a pointer to the location where the value associated with the specified key will be stored.
One of the following values as well as value_ptr containing an unparsed string with the address of the location of the value.
If no error is detected.
If the properties, key, or value_ptr argument is NULL.
If the specified key has no associated value and a default value is not provided.
If the value associated with the specified key cannot be parsed as required by the particular accessor function.
If insufficient memory is available to look up the key.
Do not modify value_ptr or free the memory.
Retrieves boolean type values associated with the specified key from the specified properties object.
#include "am_properties.h" AM_EXPORT am_status_t am_properties_get_boolean(am_properties_t properties, const char *key, int *value_ptr);
This function takes the following parameters:
The specified properties object.
Pointer to the specified key in the specified properties object.
Pointer to the location where the boolean associated with the specified key will be stored.
One of the following values stored in value_ptr:
If the value associated with the specified key is true, on, or yes.
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.
Retrieves boolean type values from the specified properties object.
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().
#include "am_properties.h" am_properties_get_boolean_with_default(am_properties_t properties, const char *key, int default_value, int *value_ptr);
This function takes the following parameters:
The specified properties object.
Pointer to the specified key in the specified properties object.
Value to return if none is defined for the specified key.
Pointer to the location where the boolean associated with the specified key will be stored.
One of the following values stored in value_ptr:
If the value associated with the specified key is true, on, or yes.
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.
Returns an iterator object that can be used to sequence through the entries in the specified properties object.
#include "am_properties.h" AM_EXPORT am_status_t am_properties_get_entries(am_properties_t properties, am_properties_iter_t *properties_iter_ptr);
This function takes the following parameters:
The specified properties object.
Pointer to the location of the new properties iterator object.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If no error was detected.
If unable to allocate memory for the iterator object.
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.
If the specified properties object contains no entries.
Retrieves a positive integer value associated with a specified key from the specified properties object.
#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);
This function takes the following parameters:
Pointer to a properties object.
Pointer to the key in the properties object.
Value to return if none is defined for the specified key.
Pointer to the location where the returned integer will be stored.
This function returns the unsigned integer value associated with the specified key.
Retrieves a signed integer value associated with the specified key from the specified properties object.
#include "am_properties.h" AM_EXPORT am_status_t am_properties_get_signed(am_properties_t properties, const char *key, long *value_ptr);
This function takes the following parameters:
The specified properties object.
Pointer to the specified key in the specified properties object.
Pointer to the location where the signed integer associated with the specified key will be stored.
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.
Retrieves a signed integer value associated with a specified key from the specified properties object.
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().
#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);
This function takes the following parameters:
The specified properties object.
Pointer to the specified key in the specified properties object.
Value to return if none is defined for the specified key.
Pointer to the location where the signed integer associated with the specified key will be stored.
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.
Retrieves an unsigned integer value associated with a specified key from the specified properties object.
#include "am_properties.h" AM_EXPORT am_status_t am_properties_get_unsigned(am_properties_t properties, const char *key, unsigned long *value_ptr);
This function takes the following parameters:
Pointer to a properties object.
Pointer to the key in the properties object.
Pointer to the location where the integer associated with the specified key will be stored.
This function returns the unsigned integer value associated with the specified key.
Retrieves an unsigned integer value associated with a specified key from the specified properties object.
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().
#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);
This function takes the following parameters:
The specified properties object.
Pointer to the specified key in the specified properties object.
Value to return if none is defined for the specified key.
Pointer to the location where the integer associated with the specified key will be stored.
This function returns the unsigned integer value associated with the specified key.
Retrieves the value (or the specified default) associated with the specified key from the specified properties object.
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.
#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);
This function takes the following parameters:
The specified properties object.
Pointer to the specified key in the specified properties object.
Pointer to the value to be returned in case of no associated value.
Pointer to a pointer to the location where the returned value will be stored.
One of the following values as well as value_ptr containing an unparsed string with the address of the location of the value.
If no error is detected.
If the properties, key, or value_ptr argument is NULL.
If the specified key has no associated value and a default value is not provided.
If the value associated with the specified key is cannot be parsed as required by the particular accessor function.
If insufficient memory is available to look up the key.
Do not modify value_ptr or free the memory.
Determines whether the specified key of the specified properties object contains a value.
am_properties_is_set() does not return the value.
#include "am_properties.h" AM_EXPORT boolean_t am_properties_is_set(am_properties_t properties, const char *key);
This function takes the following parameters:
The specified properties object.
Pointer to the name of a key.
This function returns one of the following values of the boolean_t enumeration (defined in the standard <types.h> header file):
If the property has a value.
Otherwise
Destroys the specified iterator object.
#include "am_properties.h" AM_EXPORT void am_properties_iter_destroy(am_properties_iter_t properties_iter);
This function takes the following parameter:
The specified iterator object. It may be NULL.
This function returns no value.
Returns the key of the entry currently referenced by the specified iterator object.
#include "am_properties.h" AM_EXPORT const char * am_properties_iter_get_key (am_properties_iter_t properties_iter);
This function takes the following parameter:
The specified iterator object.
This function returns one of the following values:
If the specified iterator is NULL or does not reference a valid entry.
The key.
Returns the value of the key currently referenced by the specified iterator object.
#include "am_properties.h" AM_EXPORT const char * am_properties_iter_get_value (am_properties_iter_t properties_iter);
This function takes the following parameters:
The specified iterator object.
This function returns one of the following values:
If the specified iterator is NULL or does not reference a valid entry.
Value associated with the key.
Loads information from the specified properties file into the specified properties object.
The file is assumed to follow the syntax of a standard Java properties file.
#include "am_properties.h" AM_EXPORT am_status_t am_properties_load(am_properties_t properties, const char *file_name);
This function takes the following parameters:
The specified properties object.
Pointer to a properties file.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If no error has occurred.
If the specified file does not exist.
If there is a problem accessing the file.
If properties or file_name is NULL or file_name points to an empty string.
If unable to allocate memory to store the property information.
Sets a value for the specified key in the specified properties object.
The specified value will replace any existing value.
#include "am_properties.h" AM_EXPORT am_status_t am_properties_set(am_properties_t properties, const char *key, const char *value);
This function takes the following parameters:
The specified properties object.
Pointer to the key being modified.
Pointer to the value to associate with the specified key.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If no error is detected.
If the properties, key, or value argument is NULL.
If unable to allocate memory to store the new key/value.
Retrieves key/value information from the specified properties object and stores it in the specified file.
#include "am_properties.h" AM_EXPORT am_status_t am_properties_store(am_properties_t properties, const char *file_name);
This function takes the following parameters:
The specified properties object.
Pointer to the file in which the property information will be stored.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If no error is detected.
If there is a problem writing to the file.
If properties or file_name is NULL or file_name points to an empty string.