20.1.28 ead_get_group_next_key() (acquires the next key with group specification)
- Organization of this subsection
(1) Description
This function acquires the key that immediately follows a specified key in ascending order based on its ASCII code value from among all the keys that belong to a specified group. The keys that belong to the groups under the specified group's hierarchy are also subject to this acquisition processing.
If the specified key does not exist on the connection-target EADS server, the function similarly acquires the key that immediately follows the specified key.
(2) Format
#include <eads.h> char* ead_get_group_next_key ( const EAD_CACHE *cp, /* In */ const char *group_name, /* In */ const char *key, /* In */ int *error_code /* Out */ );
(3) Arguments
- cp
-
Specifies the handle (pointer) to the cache in which the key 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.
- key
-
Specifies the reference key.
For details about the data types that can be specified, see 15.2.2(1) Data types that can be specified as keys.
- 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 the key that immediately follows the specified key in ascending order based on its ASCII code value from among all the keys that belong to the specified group.
The function returns NULL in the following cases:
-
No key follows the specified key.
-
Acquisition of the key failed due to an error.
(5) Notes
-
If acquisition of the key is successful (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.
-
This function determines the connection-target EADS server based on the specified group.
-
The EADS server that stores the keys belonging to the specified group might change due to isolation, restoration, or addition (scale-out) processing on EADS servers other than the connection-target EADS server. Therefore, if you have obtained the first key by executing ead_get_group_first_key(), connection might be established with a different EADS server.
-
Because groups are not locked on EADS servers, keys that belong to groups might be inserted or deleted by another process after ead_get_group_first_key() or ead_get_group_next_key() has executed.