H5Isearch
(
H5I_type_t type
,
H5I_search_func_t func
,
void *key
)
H5Isearch
searches through a give 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 *.
It will be a pointer the object to be tested.
This is the same object that was placed in storage
using H5Iregister
.
The second parameter is a hid_t.
It 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 simply 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.
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.