Sun Java System Access Manager 2005Q1 Developer's Reference |
Chapter 6
Properties FunctionsThis chapter provides a reference to the properties map used by clients of the Sun Java System Access Manager 6 2005Q1 Remote Client SDK. 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()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:
Parameter
Description
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_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:
Parameter
Description
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_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:
Returns
None
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:
Returns
This function returns the unparsed string form of the value associated with one of the following keys:
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().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().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:
Parameter
Description
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:
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
See am_properties_get().
Returns
See am_properties_get().
Details
See am_properties_get().
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:
Parameter
Description
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:
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:
Parameter
Description
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:
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_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:
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.
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:
Parameter
Description
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:
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:
Parameter
Description
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:
Value
Description
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:
Parameter
Description
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: