From eb4159933e17ee19780f33a9ff1ed0530185f191 Mon Sep 17 00:00:00 2001 From: Frank Baker Date: Tue, 22 Jun 2004 11:56:29 -0500 Subject: [svn-r8719] Purpose: To include new functionality. Description: Added twelve new functions: H5Iregister H5Iclear_type H5Iregister_type H5Iget_type_ref H5Idestroy_type H5Iget_file_id H5Iremove_verify H5Inmembers H5Iobject_verify H5Idec_type_ref H5Isearch H5Iinc_type_ref This is a checkin for technical content; an editorial checkin will follow, though not immediately. Platforms tested: Mozilla, IE, Safari --- doc/html/RM_H5I.html | 622 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 616 insertions(+), 6 deletions(-) diff --git a/doc/html/RM_H5I.html b/doc/html/RM_H5I.html index dabd466..be43068 100644 --- a/doc/html/RM_H5I.html +++ b/doc/html/RM_H5I.html @@ -79,15 +79,27 @@ object names.               @@ -100,8 +112,12 @@ object names. @@ -109,8 +125,12 @@ object names. @@ -118,7 +138,11 @@ object names. @@ -150,6 +174,54 @@ as the corresponding C function. + + + +
+
+
Name: H5Iclear_type +
Signature: +
herr_t H5Iclear_type(H5I_type_t type, + hbool_t force) +
Purpose: +
Deletes all IDs of the given type +
Description: +
H5Iclear_type deletes all IDs of the type identified by the argument type. +

+ The type’s free function is first called on all of these IDs to free their memory, + then they are removed from the type. + +

+ If the force flag is set to false, only those IDs whose reference + counts are equal to 1 will be deleted, and all other IDs will be entirely unchanged. + If the force flag is true, all IDs of this type will be deleted. +

Parameters: +
    + + + + + + + + + +
    H5I_type_t type    IN: Identifier of ID type which is to be cleared of IDs
    hbool_t forceIN: Whether or not to force deletion of all IDs
    +
+
Returns: +
Returns non-negative on success, negative on failure. +
Fortran90 Interface: +
This function is not supported in FORTRAN 90. + + +
+
@@ -226,6 +298,131 @@ END SUBROUTINE h5idec_ref_f + +
+
+
Name: H5Idec_type_ref +
Signature: +
int H5Idec_type_ref(H5I_type_t type) +
Purpose: +
Decrements the reference count on an ID type. +
Description: +
H5Idec_type_ref decrements the reference count on an ID type. + The reference count is used by the library to indicate when an ID type can + be destroyed. If the reference count reaches zero, this function will destroy it. + +

The type parameter is the identifier for the ID type whose + reference count is to be decremented. This identifier must have been + created by a call to H5Iregister_type. +

Parameters: +
    + + + + + +
    H5I_type_t type    IN: The identifier of the type whose reference count is to be decremented
    +
+
Returns: +
Returns the current reference count on success, negative on failure. +
Fortran90 Interface: +
This function is not supported in FORTRAN 90. + + +
+ + + +
+
+
Name: H5Idestroy_type +
Signature: +
herr_t H5Idestroy_type(H5I_type_t type) +
Purpose: +
Removes the type type and all IDs within that type. +
Description: +
H5Idestroy_type deletes an entire ID type. All IDs of this + type are destroyed and no new IDs of this type can be registered. + +

+ The type’s free function is called on all of the IDs which are deleted by + this function, freeing their memory. In addition, all memory used by this + type’s hash table is freed. + +

+ Since the H5I_type_t values of destroyed ID types are reused + when new types are registered, it is a good idea to set the variable + holding the value of the destroyed type to H5I_UNINIT. +

Parameters: +
    + + + + + +
    H5I_type_t type    IN: Identifier of ID type which is to be destroyed
    +
+
Returns: +
Returns non-negative on success, negative on failure. +
Fortran90 Interface: +
This function is not supported in FORTRAN 90. + + +
+ + + +
+
+
Name: H5Iget_file_id +
Signature: +
hid_t H5Iget_file_id(hid_t obj_id) +
Purpose: +
Retrieves the ID of the file associated with the object referenced by obj_id. +
Description: +
H5Iget_file_id returns the ID of the file associated with the + object referenced by obj_id. The retrieved file ID must be closed + using H5Fclose. + +

+ Currently, obj_id can be the ID of one of the following objects: + a file, a named datatype, a group, a dataset, or an attribute. +

Parameters: +
    + + + + + +
    hid_t obj_id    IN: Identifier of the object whose associated file ID will be returned.
    +
+
Returns: +
Returns the file ID on success, negative on failure. +
Fortran90 Interface: +
This function is currently not supported in FORTRAN 90. + + +
+ +
@@ -428,6 +625,47 @@ END SUBROUTINE h5iget_type_f
+ +
+
+
Name: H5Iget_type_ref +
Signature: +
int H5Iget_type_ref(H5I_type_t type) +
Purpose: +
Retrieves the reference count on an ID type. +
Description: +
H5Iget_type_ref retrieves the reference count on an ID type. + The reference count is used by the library to indicate when an + ID type can be destroyed. + +

+ The type parameter is the identifier for the ID type whose + reference count is to be retrieved. This identifier must have been created + by a call to H5Iregister_type. +

Parameters: +
    + + + + + +
    H5I_type_t type    IN: The identifier of the type whose reference count is to be retrieved
    +
+
Returns: +
Returns the current reference count on success, negative on failure. +
Fortran90 Interface: +
This function is not supported in FORTRAN 90. + + +
+ +
@@ -501,6 +739,376 @@ END SUBROUTINE h5iinc_ref_f -->
+ + +
+
+
Name: H5Iinc_type_ref +
Signature: +
int H5Iinc_type_ref(H5I_type_t type) +
Purpose: +
Increments the reference count on an ID type. +
Description: +
H5Iinc_type_ref increments the reference count on an ID type. + The reference count is used by the library to indicate when an ID type can be destroyed. + +

+ The type parameter is the identifier for the ID type whose + reference count is to be incremented. This identifier must have been created + by a call to H5Iregister_type. +

Parameters: +
    + + + + + +
    H5I_type_t type    IN: The identifier of the type whose reference count is to be incremented
    +
+
Returns: +
Returns the current reference count on success, negative on failure. +
Fortran90 Interface: +
This function is not supported in FORTRAN 90. + + +
+ + + +
+
+
Name: H5Inmembers +
Signature: +
int H5Inmembers(H5I_type_t type) +
Purpose: +
Returns the number of IDs in a given type. +
Description: +
H5Inmembers returns the number of IDs of a given ID type. + If no IDs of this type have been registered, H5Inmembers returns 0. + If the type does not exist or has been destroyed, H5Inmembers + also returns 0. +
Parameters: +
    + + + + + +
    H5I_type_t type    IN: Identifier of ID type whose member count will be retrieved
    +
+
Returns: +
Returns number of members on success, zero if type is not a valid ID type. +
Fortran90 Interface: +
This function is not supported in FORTRAN 90. + + +
+ + + +
+
+
Name: H5Iobject_verify +
Signature: +
void * H5Iobject_verify(hid_t id, + H5I_type_t id_type) +
Purpose: +
Returns the object referenced by id. +
Description: +
H5Iobject_verify returns a pointer to the memory referenced by + id after verifying that id is of type id_type. + This function is analogous to dereferencing a pointer in C with type checking. + +

+ H5Iregister(H5I_type_t type, + void *object) takes an H5I_type_t and a + void pointer to an object, returning an hid_t of that type. + This hid_t can then be passed to H5Iobject_verify + along with its type to retrieve the object. + +

+ H5Iobject_verify does not change the ID it is called on in any + way (as opposed to H5Iremove_verify, which removes the ID from its + type’s hash table). +

Parameters: +
    + + + + + + + + + +
    hid_t idIN: ID to be dereferenced
    H5I_type_t type    IN: ID type to which id should belong
    +
+
Returns: +
Pointer to the object referenced by id on success, NULL on failure. +
Fortran90 Interface: +
This function is not supported in FORTRAN 90. + + +
+ + + +
+
+
Name: H5Iregister +
Signature: +
hid_t H5Iregister(H5I_type_t type, + void *object) +
Purpose: +
Creates and returns a new ID. +
Description: +
H5Iregister allocates space for a new ID and returns an identifier for it. + +

+ The type parameter is the identifier for the ID type to which + this new ID will belong. This identifier must have been created by a call + to H5Iregister_type. + +

+ The object parameter is a pointer to the memory which the new + ID will be a reference to. This pointer will be stored by the library and + returned to you via a call to H5Iobject_verify. +

Parameters: +
    + + + + + + + + + +
    H5I_type_t type    IN: The identifier of the type to which the new ID will belong
    void *objectIN: Pointer to memory for the library to store
    +
+
Returns: +
Returns the new ID on success, negative on failure. +
Fortran90 Interface: +
This function is not supported in FORTRAN 90. + + +
+ + + +
+
+
Name: H5Iregister_type +
Signature: +
H5I_type_t H5Iregister_type(size_t + hash_size, unsigned reserved, + H5I_free_t free_func) +
Purpose: +
Creates and returns a new ID type. +
Description: +
H5Iregister_type allocates space for a new ID type and + returns an identifier for it. + +

+ The hash_size parameter indicates the minimum size of the hash + table used to store IDs in the new type. + +

+ The reserved parameter indicates the number of IDs in this new + type to be reserved. Reserved IDs are valid IDs which are not associated with + any storage within the library. + +

+ The free_func parameter is a function pointer to a function + which returns an herr_t and accepts a void *. The purpose + of this function is to deallocate memory for a single ID. It will be called + by H5Iclear_type and H5Idestroy_type on each ID. + This function is NOT called by H5Iremove_verify. + The void * will be the same pointer which was passed in to + the H5Iregister function. The free_func + function should return 0 on success and -1 on failure. +

Parameters: +
    + + + + + + + + + + + + + +
    size_t hash_sizeIN: Size of the hash table (in entries) used to store IDs for the new type
    unsigned reservedIN: Number of reserved IDs for the new type
    H5I_free_t free_func    IN: Function used to deallocate space for a single ID
    +
+
Returns: +
Returns the type identifier on success, negative on failure. +
Fortran90 Interface: +
This function is not supported in FORTRAN 90. + + +
+ + + +
+
+
Name: H5Iremove_verify +
Signature: +
void *H5Iremove_verify(hid_t id, + H5I_type_t id_type) +
Purpose: +
Removes an ID from internal storage. +
Description: +
H5Iremove_verify first ensures that id belongs to + id_type. If so, it removes id from internal storage + and returns the pointer to the memory it referred to. This pointer is the + same pointer that was placed in storage by H5Iregister. + If id does not belong to id_type, + then NULL is returned. + +

+ The id parameter is the ID which is to be removed from + internal storage. Note: this function does NOT deallocate the memory that + id refers to. The pointer returned by H5Iregister + must be deallocated by the user to avoid memory leaks. + +

+ The type parameter is the identifier for the ID type + which id is supposed to belong to. This identifier must + have been created by a call to H5Iregister_type. +

Parameters: +
    + + + + + + + + + +
    hid_t idIN: The ID to be removed from internal storage
    H5I_type_t type    IN: The identifier of the type whose reference count is to be retrieved
    +
+
Returns: +
Returns a pointer to the memory referred to by id + on success, NULL on failure. +
Fortran90 Interface: +
This function is not supported in FORTRAN 90. + + +
+ + + +
+
+
Name: H5Isearch +
Signature: +
void *H5Isearch(H5I_type_t type, + H5I_search_func_t func, void *key) +
Purpose: +
Finds the memory referred to by an ID within the given ID type such that + some criterion is satisfied. +
Description: +
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. +

Parameters: +
    + + + + + + + + + + + + + +
    H5I_type_t typeIN: The identifier of the type to be searched
    H5I_search_func_t func    IN: The function defining the search criteria
    void *keyIN: A key for the search function
    +
+
Returns: +
Returns a pointer to the object which satisfies the search function + on success, NULL on failure. +
Fortran90 Interface: +
This function is not supported in FORTRAN 90. + + +
+
@@ -540,9 +1148,11 @@ And in this document, the Describes HDF5 Release 1.7, the unreleased development branch; working toward HDF5 Release 1.8.0 + + -- cgit v0.12