THIS PACKAGE IS WORK IN PROGRESS. THE INTERFACE MAY CHANGE IN THE
NEXT RELEASE, POSSIBLY WITHOUT NOTICE.
Functions
| aa_create | Create a general purpose associative array of key-value pairs.
|
| aa_get_info | Get information attached to associative array.
|
| aa_put_pair | Add a key-value pair to an associative array.
|
| aa_get_pair | Find a key-value pair in an associative array.
|
| aa_destroy_pair | Remove a key-value pair from an associative array.
|
| aa_get_all_pairs | Get all the key-value pairs on an associative array.
|
| aa_get_pair_info | Get key and value information for a key-value pair.
|
Prototype Functions
Tables
Functions
KAssociativeArray
aa_create (void *info,
int (*key_compare_func) (void *key1, void *key2),
void *(*key_copy_func) (void *key,
uaddr length, flag *ok),
void (*key_destroy_func) (void *key),
void *(*value_copy_func) (void *value,
uaddr length, flag *ok),
void (*value_destroy_func) (void *value))
Create a general purpose associative array of key-value pairs.
Parameters:
Returns: An associative array on success, else NULL.
Multithreading Level: Unsafe
void *
aa_get_info (KAssociativeArray aa)
This routine will get the arbitrary information pointer stored
with an associative array.
Parameters:
- aa :
The associative array.
Returns: The arbitrary information pointer.
Multithreading Level: Unsafe
KAssociativeArrayPair
aa_put_pair (KAssociativeArray aa,
void *key, uaddr key_length,
void *value, uaddr value_length,
unsigned int replacement_policy, flag front)
Add a key-value pair to an associative array.
Parameters:
- aa :
The associative array.
- key :
The key.
- key_length :
The length of the key, in bytes. If this is 0 and the
key_copy_func is NULL, the key pointer is copied directly. If this is
greater than zero and the key_copy_func is NULL, the specified number
of bytes are copied.
- value :
The value.
- value_length :
The length of the value, in bytes. If this is 0 and the
value_copy_func is NULL, the value pointer is copied directly. If this
is greater than zero and the value_copy_func is NULL, the specified
number of bytes are copied.
- replacement_policy :
The policy to use when adding the pair. See
AA_REPLACEMENT_POLICIES for a list of legal values.
- front :
If TRUE and the key is new, place the pair at the front of the
array. If FALSE and the key is new, place the pair at the end of the
array.
Returns: A KAssociativeArrayPair object on success, else NULL.
Multithreading Level: Unsafe
KAssociativeArrayPair
aa_get_pair (KAssociativeArray aa, void *key,
void **value)
Find a key-value pair in an associative array.
Parameters:
- aa :
The associative array.
- key :
The key.
- value :
The value found will be written here on success.
Returns: A KAssociativeArrayPair object if the key was found, else NULL.
Multithreading Level: Unsafe
void
aa_destroy_pair (KAssociativeArrayPair pair)
This routine will remove a key-value pair from an associative
array and will destroy all storage allocated for the pair.
Parameters:
- pair :
The key-value pair.
Returns: Nothing.
Multithreading Level: Unsafe
KAssociativeArrayPair *
aa_get_all_pairs (KAssociativeArray aa,
unsigned int *num_pairs)
Get all the key-value pairs on an associative array.
Parameters:
- aa :
The associative array.
- num_pairs :
The number of pairs found is written here. If no pairs are
found NULL is written here.
Returns: An array of key-value pairs on success, else NULL. If
num_pairs is non-zero, an error occurred.
Multithreading Level: Unsafe
void
aa_get_pair_info (KAssociativeArrayPair pair,
void **key, uaddr *key_length,
void **value, uaddr *value_length)
This routine will get the key and value information for a
key-value pair in an associative array.
Parameters:
- pair :
The key-value pair.
- key :
The key will be written here.
- key_length :
The length of the key will be written here.
- value :
The value will be written here.
- value_length :
The length of the value will be written here.
Returns: Nothing.
Multithreading Level: Unsafe
Prototype Functions
int
AA_PROTO_key_compare_func (void *key1, void *key2)
This routine will compare two keys.
Parameters:
- key1 :
The first key.
- key2 :
The second key.
Returns: 0 if the keys match, a negative number if key1 is less
than key2, a positive number if key1 is greater than key2.
Multithreading Level: Unsafe
void *
AA_PROTO_key_copy_func (void *key, uaddr length, flag *ok)
This routine will copy a key.
Parameters:
- key :
The key to copy.
- length :
The length of the key in bytes.
- ok :
The value TRUE will be written here on success, else FALSE is
written here.
Returns: A copy of the key on success.
Multithreading Level: Unsafe
void
AA_PROTO_key_destroy_func (void *key)
This routine will destroy keys.
Parameters:
- key :
The key to destroy.
Returns: Nothing.
Multithreading Level: Unsafe
void *
AA_PROTO_value_copy_func (void *value, uaddr length, flag *ok)
This routine will copy a value.
Parameters:
- value :
The value to copy.
- length :
The length of the value in bytes.
- ok :
The value TRUE will be written here on success, else FALSE is
written here.
Returns: A copy of the value on success.
Multithreading Level: Unsafe
void
AA_PROTO_value_destroy_func (void *value)
This routine will destroy values.
Parameters:
- value :
The value to destroy.
Returns: Nothing.
Multithreading Level: Unsafe
Tables
AA_REPLACEMENT_POLICIES
| Policy Name | Meaning
|
| KAA_REPLACEMENT_POLICY_NEW | Fail if existing key found
|
| KAA_REPLACEMENT_POLICY_UPDATE | Fail if no existing key found
|
| KAA_REPLACEMENT_POLICY_PUT | Add pair, remove old key if exists
|
Contact: Richard Gooch
Web Development: Ariel Internet Services