H5L_ITERATE1 iterates through the links in a file or group, group_id, in the order of the specified index, idx_type, using a user-defined callback routine op.H5L_ITERATE1 does not recursively follow links into subgroups of the specified group. Three parameters are used to manage progress of the iteration: idx_type, order, and idx_p. idx_type specifies the index to be used. If the links have not been indexed by the index type, they will first be sorted by that index then the iteration will begin; if the links have been so indexed, the sorting step will be unnecessary, so the iteration may begin more quickly.
The choices for idx_type are: | Name | Meaning |
|---|
| H5_INDEX_NAME | Lexicographic order | | H5_INDEX_CRT_ORDER | Creation order |
order specifies the order in which objects are to be inspected along the index idx_type. The choices for order are:
| Name | Meaning |
|---|
| H5_ITER_INC | Increasing order | | H5_ITER_DEC | Decreasing order | | H5_ITER_NATIVE | Fastest order |
idx_p tracks the iteration and allows an iteration to be resumed if it was stopped before all members were processed. It is passed in by the application with a starting point and returned by the library with the point at which the iteration stopped.
The op callback function, the related H5L_info1_t struct, and the effect of the callback function’s return value on the application are described in H5L_VISIT. op_data is a user-defined pointer to the data required to process links in the course of the iteration. This pointer is passed back to each step of the iteration in the op callback function’s op_data parameter.
op is invoked for each link encounter:
| Tip |
|---|
Signature:| HTML |
|---|
<pre><code class="language-c">herr_t (*H5L_iterate1_t)
(
hid_t group,
const char* name,
const H5L_info1_t* info,
void* op_data
)</code>
</pre> |
Info:| HTML |
|---|
<pre><code class="language-c">typedef struct {
H5L_type_t type; /* Type of link */
hbool_t corder_valid; /* Indicates whether creation */
/* order is valid */
int64_t corder; /* Creation order */
H5T_cset_t cset; /* Character set of link name */
union {
haddr_t address; /* Address hard link points to */
size_t val_size; /* Size of soft link or */
/* user-defined link value */
} u;
} H5L_info1_t;</code></pre> |
Returns:| Return value | Meaning |
|---|
| 0 | Continue iteration | | > 0 | Stop iteration; successful termination | | < 0 | Stop iteration; abnormal termination |
|
op_data is passed to and from each iteration and can be used to supply or aggregate information across iterations.
| Warning |
|---|
The behavior of H5L_ITERATE1 is undefined if the link membership of group_id changes during the iteration. This does not limit the ability to change link destinations while iterating, but caution is advised. |
| 