Previous      Contents      Next
Sun Java System Access Manager 2005Q1 Developer's Reference

Chapter 6
Properties Functions

This 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()
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:

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:

Value	Description
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.

---

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:

Value	Description
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.

---

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:

Parameter	Description
properties	The handle for the properties object to be destroyed.

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:

Parameter	Description
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:

Value	Description
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.

---

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:

Value	Description
!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:

Value	Description
!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:

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:

Value	Description
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

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:

Value	Description
!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:

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:

Parameter	Description
properties_iter	The handle for the properties iterator object to be examined.

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:

Parameter	Description
properties_iter	The handle for the properties iterator object to be examined.

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:

Value	Description
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:

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:

Value	Description
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.

Previous      Contents      Next

---

Copyright 2005 Sun Microsystems, Inc. All rights reserved.