20.1.21 ead_get_group_keys() (acquires a list of keys with group specification)
- Organization of this subsection
(1) Description
This function acquires a list of keys that belong to a specified group, including keys that belong to groups under the specified group's hierarchy.
The keys are listed in ascending order based on their ASCII code values.
(2) Format
#include <eads.h> ead_keys ead_get_group_keys ( const EAD_CACHE *cp, /* In */ const char *group_name, /* In */ int *error_code /* Out */ );
(3) Arguments
- cp
-
Specifies the handle (pointer) to the cache in which the list of keys is to be acquired.
Specify the handle (pointer) obtained from ead_start_cache() when access to the cache was started.
- group_name
-
Specifies a group name.
For details about the data that can be specified, see 15.2.2(2) Data that can be specified as group names.
- error_code
-
Specifies the pointer from which to retrieve the error code.
For details about error codes, see 20.2 Error codes in the client library (C).
(4) Return value
This function returns a list of the keys (ead_keys structure) that belong to the specified group in ascending order based on their ASCII code values.
NULL is set in the keys member of the ead_keys structure in the following cases:
-
No keys belong to the specified group.
-
Acquisition of a list of keys failed due to an error.
For details about the ead_keys structure and its format, see 20.1.41 ead_keys structure (multiple keys).
(5) Notes
-
If the keys member of the ead_keys structure that is returned as the return value is not NULL, the memory area is not freed automatically. You must free it in the application program. For details, see 19.1.1(10) Freeing a memory area returned as a return value.
-
As the number of keys on the specified EADS server increases, the time and the amount of resources required for the acquisition processing might increase.