H5Isearch(
H5I_type_t type,
H5I_search_func_t func,
void *key
)
H5Isearch searches through a given ID type
to find an object that satisfies the criteria
defined by func.
If such an object is found,
the pointer to the memory containing this object is returned.
Otherwise, NULL is returned.
To do this, func is called on every member of
type.
The first member to satisfy func is returned.
The type parameter is the identifier for
the ID type which is to be searched.
This identifier must have been created by a call to
H5Iregister_type.
The parameter func is a function pointer to a function
which takes three parameters.
The first parameter is a void * and
will be a pointer to the object to be tested.
This is the same object that was placed in storage
using H5Iregister.
The second parameter is a hid_t and
is the ID of the object to be tested.
The last parameter is a void *.
This is the key parameter
and can be used however the user finds helpful,
or it can be ignored if it is not needed.
func returns 0 if the object it is testing
does not pass its criteria. A non-zero value should be
returned if the object does pass its criteria.
H5I_search__func_t is defined in H5Ipublic.h and
is shown below.
typedef int (*H5I_search_func_t)(void *obj, hid_t id, void *key);
The key parameter will be passed to the
search function as a parameter.
It can be used to further define the search at run-time.
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.
H5I_type_t type |
IN: The identifier of the type to be searched |
H5I_search_func_t func |
IN: The function defining the search criteria |
void *key |
IN: A key for the search function |
NULL on failure.