20.1.20 ead_get_group_names() (acquires a list of group names in the highest hierarchy)

(1) Description

This function acquires a list of the group names of the groups in the highest hierarchy that are stored on a specified EADS server.

The group names are listed in ascending order based on their ASCII code values.

To Page Top

(2) Format

#include <eads.h>
ead_group_names ead_get_group_names
(
  const EAD_CACHE     *cp,             /* In */
  const ead_node      *target_node,    /* In */
  int                 *error_code      /* Out */
);

To Page Top

(3) Arguments

cp

Specifies the handle (pointer) to the cache in which the list of group names is to be acquired.

Specify the handle (pointer) obtained from ead_start_cache() when access to the cache was started.

target_node

Specifies a pointer to the EADS server (ead_node structure) from which the list of group names is to be acquired.

You can only specify the pointer of the ead_node structure obtained by using the EADS client library. If you specify any other pointer, correct operation is not guaranteed.

For the format and details of the ead_node structure, see 20.1.50 ead_node structure (object used in a user function with an EADS server specified).

An error results if the address information (IP address and port number) managed by the specified ead_node structure does not match the address information of any EADS servers maintained by the EADS client.

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).

To Page Top

(4) Return value

This function returns a list of the group names of the groups in the highest hierarchy (ead_group_names structure) that are stored on the specified EADS server.

NULL is set in the group_names member of the ead_group_names structure in the following cases:

• The specified EADS server does not contain any keys that belong to the group.

• Acquisition of a list of group names failed due to an error.

For details about the ead_group_names structure and its format, see 20.1.42 ead_group_names structure (multiple group names).

To Page Top

(5) Notes

• If the group_names member of the ead_group_names 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 groups on the specified EADS server increases, the time and the amount of resources required for acquisition processing might increase.

To Page Top