Last modified: 23 August 2012
Name: H5Piterate
Purpose:
Iterates over properties in a property class or list.
Signature:
int H5Piterate( hid_t id, int * idx, H5P_iterate_t iter_func, void * iter_data )
Description:

H5Piterate iterates over the properties in the property object specified in id, which may be either a property list or a property class, performing a specified operation on each property in turn.

For each property in the object, iter_func and the additional information specified below are passed to the H5P_iterate_t operator function.

The iteration begins with the idx-th property in the object; the next element to be processed by the operator is returned in idx. If idx is NULL, the iterator starts at the first property; since no stopping point is returned in this case, the iterator cannot be restarted if one of the calls to its operator returns non-zero.

The prototype for the H5P_iterate_t operator is as follows: The operation receives the property list or class identifier for the object being iterated over, id, the name of the current property within the object, name, and the pointer to the operator data passed in to H5Piterate, iter_data.

The valid return values from an operator are as follows:

H5Piterate assumes that the properties in the object identified by id remain unchanged through the iteration. If the membership changes during the iteration, the function's behavior is undefined.

Programming Note for C++ Developers Using C Functions:

If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally.

Examples of this kind of routine include callbacks such as H5Pset_elink_cb and H5Pset_type_conv_cb and functions such as H5Tconvert and H5Ewalk2.

Exiting the routine in its normal fashion allows the HDF5 C Library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ “catch” statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.

Parameters:
Returns:
Success: the return value of the last call to iter_func if it was non-zero; zero if all properties have been processed
Failure: a negative value
Fortran90 Interface:
None.