diff options
| -rw-r--r-- | doxygen/aliases | 15 | ||||
| -rw-r--r-- | src/H5Dpublic.h | 147 | ||||
| -rw-r--r-- | src/H5Gpublic.h | 132 | ||||
| -rw-r--r-- | src/H5Rmodule.h | 7 | ||||
| -rw-r--r-- | src/H5Rpublic.h | 471 |
5 files changed, 764 insertions, 8 deletions
diff --git a/doxygen/aliases b/doxygen/aliases index c10c3e8..2255c9b 100644 --- a/doxygen/aliases +++ b/doxygen/aliases @@ -133,12 +133,18 @@ ALIASES += lapl_id{1}="\param[in] \1 Link access property list identifier" ALIASES += lcpl_id="\param[in] lcpl_id Link creation property list identifier" ALIASES += lcpl_id{1}="\param[in] \1 Link creation property list identifier" +ALIASES += oapl_id="\param[in] oapl_id Object access property list identifier" +ALIASES += oapl_id{1}="\param[in] \1 Object access property list identifier" + ALIASES += plist_id="\param[in] plist_id Property list identifier" ALIASES += plist_id{1}="\param[in] \1 Property list identifier" ALIASES += plistcls_id="\param[in] plistcls_id Property list class identifier" ALIASES += plistcls_id{1}="\param[in] \1 Property list class identifier" +ALIASES += rapl_id="\param[in] rapl_id Reference access property list identifier" +ALIASES += rapl_id{1}="\param[in] \1 Reference access property list identifier" + ALIASES += tapl_id="\param[in] tapl_id Datatype access property list identifier" ALIASES += tapl_id{1}="\param[in] \1 Datatype access property list identifier" @@ -161,6 +167,15 @@ ALIASES += fgdta_obj_id{1}="\obj_id{\1}. The identifier may be that of a file, g ALIASES += fgdta_loc_obj_id{1}="\loc_obj_id{\1}. The identifier may be that of a file, group, dataset, named datatype, or attribute." ################################################################################ +# Asynchronous Arguments +################################################################################ + +ALIASES += app_file="\param[in] app_file For internal use only, not a visible user parameter" +ALIASES += app_func="\param[in] app_func For internal use only, not a visible user parameter" +ALIASES += app_line="\param[in] app_line For internal use only, not a visible user parameter" +ALIASES += es_id="\param[in] es_id The event set ID to add this asynchronous operation to. H5ES_NONE may be used for synchronous execution." + +################################################################################ # Others ################################################################################ diff --git a/src/H5Dpublic.h b/src/H5Dpublic.h index 00948f9..8d0ef30 100644 --- a/src/H5Dpublic.h +++ b/src/H5Dpublic.h @@ -140,7 +140,7 @@ extern "C" { * \brief Creates a new dataset and links it into the file * * \fgdta_loc_id - * \param[in] name Name of the dataset to open + * \param[in] name Name of the dataset to create * \type_id * \space_id * \lcpl_id @@ -149,7 +149,6 @@ extern "C" { * * \return \hid_t{dataset} * - * * \details H5Dcreate2() creates a new dataset named \p name at * the location specified by \p loc_id, and associates constant * and initial persistent properties with that dataset, including @@ -201,6 +200,30 @@ extern "C" { */ H5_DLL hid_t H5Dcreate2(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t lcpl_id, hid_t dcpl_id, hid_t dapl_id); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Asynchronous version of H5Dcreate2() + * + * \app_file + * \app_func + * \app_line + * \fgdta_loc_id + * \param[in] name Name of the dataset to create + * \type_id + * \space_id + * \lcpl_id + * \dcpl_id + * \dapl_id + * \es_id + * + * \return \hid_t{dataset} + * + * \see H5Dcreate2() + * + */ H5_DLL hid_t H5Dcreate_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t lcpl_id, hid_t dcpl_id, hid_t dapl_id, hid_t es_id); @@ -299,6 +322,26 @@ H5_DLL hid_t H5Dcreate_anon(hid_t loc_id, hid_t type_id, hid_t space_id, hid_t * */ H5_DLL hid_t H5Dopen2(hid_t loc_id, const char *name, hid_t dapl_id); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Asynchronous version of H5Dopen2() + * + * \app_file + * \app_func + * \app_line + * \fgdta_loc_id + * \param[in] name Name of the dataset to open + * \dapl_id + * \es_id + * + * \return \hid_t{dataset} + * + * \see H5Dopen2() + * + */ H5_DLL hid_t H5Dopen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *name, hid_t dapl_id, hid_t es_id); @@ -324,6 +367,24 @@ H5_DLL hid_t H5Dopen_async(const char *app_file, const char *app_func, unsigned * */ H5_DLL hid_t H5Dget_space(hid_t dset_id); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Asynchronous version of H5Dget_space() + * + * \app_file + * \app_func + * \app_line + * \dset_id + * \es_id + * + * \return \hid_t{dataspace} + * + * \see H5Dget_space() + * + */ H5_DLL hid_t H5Dget_space_async(const char *app_file, const char *app_func, unsigned app_line, hid_t dset_id, hid_t es_id); @@ -732,6 +793,28 @@ H5_DLL haddr_t H5Dget_offset(hid_t dset_id); H5_DLL herr_t H5Dread(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, hid_t dxpl_id, void *buf /*out*/); +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Asynchronous version of H5Dread() + * + * \app_file + * \app_func + * \app_line + * \dset_id Identifier of the dataset to read from + * \param[in] mem_type_id Identifier of the memory datatype + * \param[in] mem_space_id Identifier of the memory dataspace + * \param[in] file_space_id Identifier of the dataset's dataspace in the file + * \param[in] dxpl_id Identifier of a transfer property list + * \param[out] buf Buffer to receive data read from file + * \es_id + * + * \return \herr_t + * + * \see H5Dread() + * + */ H5_DLL herr_t H5Dread_async(const char *app_file, const char *app_func, unsigned app_line, hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, hid_t dxpl_id, void *buf /*out*/, hid_t es_id); @@ -847,6 +930,28 @@ H5_DLL herr_t H5Dread_async(const char *app_file, const char *app_func, unsigne H5_DLL herr_t H5Dwrite(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, hid_t dxpl_id, const void *buf); +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Asynchronous version of H5Dwrite() + * + * \app_file + * \app_func + * \app_line + * \param[in] dset_id Identifier of the dataset to read from + * \param[in] mem_type_id Identifier of the memory datatype + * \param[in] mem_space_id Identifier of the memory dataspace + * \param[in] file_space_id Identifier of the dataset's dataspace in the file + * \dxpl_id + * \param[out] buf Buffer with data to be written to the file + * \es_id + * + * \return \herr_t + * + * \see H5Dwrite() + * + */ H5_DLL herr_t H5Dwrite_async(const char *app_file, const char *app_func, unsigned app_line, hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, hid_t dxpl_id, const void *buf, hid_t es_id); @@ -1184,6 +1289,26 @@ H5_DLL herr_t H5Dfill(const void *fill, hid_t fill_type_id, void *buf, hid_t bu * */ H5_DLL herr_t H5Dset_extent(hid_t dset_id, const hsize_t size[]); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Asynchronous version of H5Dset_extent() + * + * \app_file + * \app_func + * \app_line + * \dset_id + * \param[in] size[] Array containing the new magnitude of each dimension + * of the dataset + * \es_id + * + * \return \herr_t + * + * \see H5Dset_extent() + * + */ H5_DLL herr_t H5Dset_extent_async(const char *app_file, const char *app_func, unsigned app_line, hid_t dset_id, const hsize_t size[], hid_t es_id); @@ -1408,6 +1533,24 @@ H5_DLL herr_t H5Dgather(hid_t src_space_id, const void *src_buf, hid_t type_id, * */ H5_DLL herr_t H5Dclose(hid_t dset_id); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Asynchronous version of H5Dclose() + * + * \app_file + * \app_func + * \app_line + * \dset_id + * \es_id + * + * \return \herr_t + * + * \see H5Dclose() + * + */ H5_DLL herr_t H5Dclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t dset_id, hid_t es_id); diff --git a/src/H5Gpublic.h b/src/H5Gpublic.h index e46bef6..26617d3 100644 --- a/src/H5Gpublic.h +++ b/src/H5Gpublic.h @@ -118,6 +118,28 @@ extern "C" { * */ H5_DLL hid_t H5Gcreate2(hid_t loc_id, const char *name, hid_t lcpl_id, hid_t gcpl_id, hid_t gapl_id); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Asynchronous version of H5Gcreate2() + * + * \app_file + * \app_func + * \app_line + * \fgdta_loc_id + * \param[in] name Name of the group to create + * \lcpl_id + * \gcpl_id + * \gapl_id + * \es_id + * + * \return \hid_t{group} + * + * \see H5Gcreate2() + * + */ H5_DLL hid_t H5Gcreate_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *name, hid_t lcpl_id, hid_t gcpl_id, hid_t gapl_id, hid_t es_id); @@ -199,6 +221,26 @@ H5_DLL hid_t H5Gcreate_anon(hid_t loc_id, hid_t gcpl_id, hid_t gapl_id); * */ H5_DLL hid_t H5Gopen2(hid_t loc_id, const char *name, hid_t gapl_id); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Asynchronous version of H5Gopen2() + * + * \app_file + * \app_func + * \app_line + * \fgdta_loc_id + * \param[in] name Name of the group to open + * \gapl_id + * \es_id + * + * \return \hid_t{group} + * + * \see H5Gopen2() + * + */ H5_DLL hid_t H5Gopen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *name, hid_t gapl_id, hid_t es_id); @@ -253,8 +295,26 @@ H5_DLL hid_t H5Gget_create_plist(hid_t group_id); */ H5_DLL herr_t H5Gget_info(hid_t loc_id, H5G_info_t *ginfo); +/** + * -------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Asynchronous version of H5Gget_info() + * + * \app_file + * \app_func + * \app_line + * \fgdta_loc_id + * \param[out] ginfo Struct in which group information is returned + * \es_id + * + * \return \hid_t{group} + * + * \see H5Gget_info() + * + */ H5_DLL herr_t H5Gget_info_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, - H5G_info_t *group_info /*out*/, hid_t es_id); + H5G_info_t *ginfo /*out*/, hid_t es_id); /** *------------------------------------------------------------------------- @@ -289,8 +349,29 @@ H5_DLL herr_t H5Gget_info_async(const char *app_file, const char *app_func, unsi * */ H5_DLL herr_t H5Gget_info_by_name(hid_t loc_id, const char *name, H5G_info_t *ginfo, hid_t lapl_id); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Asynchronous version of H5Gget_info_by_name() + * + * \app_file + * \app_func + * \app_line + * \fgdta_loc_id + * \param[in] name Name of the group to query + * \param[out] ginfo Struct in which group information is returned + * \lapl_id + * \es_id + * + * \return \herr_t + * + * \see H5Gget_info_by_name() + * + */ H5_DLL herr_t H5Gget_info_by_name_async(const char *app_file, const char *app_func, unsigned app_line, - hid_t loc_id, const char *name, H5G_info_t *group_info /*out*/, + hid_t loc_id, const char *name, H5G_info_t *ginfo /*out*/, hid_t lapl_id, hid_t es_id); /** @@ -340,9 +421,36 @@ H5_DLL herr_t H5Gget_info_by_name_async(const char *app_file, const char *app_fu */ H5_DLL herr_t H5Gget_info_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5G_info_t *ginfo, hid_t lapl_id); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Asynchronous version of H5Gcreate2() + * + * \app_file + * \app_func + * \app_line + * \fgdta_loc_id + * \param[in] group_name Name of the group to query + * \param[in] idx_type Transient index identifying object + * \param[in] order Transient index identifying object + * \param[in] n Position in the index of the group to query + * \param[out] ginfo Struct in which group information is returned + * \lapl_id + * \es_id + * + * \return Returns + * \li The size of the object name if successful, or + * \li 0 if no name is associated with the group identifier, or + * \li negative value, if failure occurred + * + * \see H5Gcreate2() + * + */ H5_DLL herr_t H5Gget_info_by_idx_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *group_name, H5_index_t idx_type, - H5_iter_order_t order, hsize_t n, H5G_info_t *group_info /*out*/, + H5_iter_order_t order, hsize_t n, H5G_info_t *ginfo /*out*/, hid_t lapl_id, hid_t es_id); /** @@ -422,6 +530,24 @@ H5_DLL herr_t H5Grefresh(hid_t group_id); * */ H5_DLL herr_t H5Gclose(hid_t group_id); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Asynchronous version of H5Gcreate2() + * + * \app_file + * \app_func + * \app_line + * \group_id + * \es_id + * + * \return \herr_t + * + * \see H5Gcreate2() + * + */ H5_DLL herr_t H5Gclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t group_id, hid_t es_id); diff --git a/src/H5Rmodule.h b/src/H5Rmodule.h index e4f5313..0a910a1 100644 --- a/src/H5Rmodule.h +++ b/src/H5Rmodule.h @@ -25,4 +25,11 @@ #define H5_MY_PKG_ERR H5E_REFERENCE #define H5_MY_PKG_INIT YES +/** + * \defgroup H5R H5R + * \brief Reference Interface + * \details The HDF5 Reference Interface, H5R, provides a mechanism for managing + * HDF5 referenced objects. + */ + #endif /* _H5Rmodule_H */ diff --git a/src/H5Rpublic.h b/src/H5Rpublic.h index b2803de..96db2a7 100644 --- a/src/H5Rpublic.h +++ b/src/H5Rpublic.h @@ -99,36 +99,501 @@ extern "C" { #endif /* Constructors */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5R + * + * \brief Creates an object reference + * + * \fgdta_loc_id + * \param[in] name Name of object + * \oapl_id + * \param[out] ref_ptr Pointer to reference + * + * \return \herr_t + * + * \details H5Rcreate_object() creates a reference pointing to the + * object named \p name located at \p loc_id. The parameters \p + * loc_id and \p name are used to locate the object. + * + * The parameter \p oapl_id is an object access property list + * identifier for the referenced object. The access property list + * must be of the same type as the object being referenced, that is + * a group, dataset or committed datatype property list. + * + * H5R_ref_t is defined in H5Rpublic.h as: typedef unsigned char + * H5R_ref_t[#H5R_REF_BUF_SIZE]; + * + * H5Rdestroy() should be used to release the resource from the + * reference. + * + */ H5_DLL herr_t H5Rcreate_object(hid_t loc_id, const char *name, hid_t oapl_id, H5R_ref_t *ref_ptr); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5R + * + * \brief Creates a region reference + * + * \fgdta_loc_id + * \param[in] name Name of object + * \space_id + * \oapl_id + * \param[out] ref_ptr Pointer to reference + * + * \return \herr_t + * + * \details H5Rcreate_region() creates the reference, \p ref_ptr, + * pointing to the region represented by \p space_id within the + * object named name located at \p loc_id. + * + * The parameters \p loc_id and \p name are used to locate the + * object. The parameter \p space_id identifies the dataset region + * that a dataset region reference points to. + * + * The parameter \p oapl_id is an object access property list + * identifier for the referenced object. The access property list + * must be of the same type as the object being referenced, that is + * a dataset property list in this case. + * + * H5R_ref_t is defined in H5Rpublic.h as: typedef unsigned char + * H5R_ref_t[#H5R_REF_BUF_SIZE]; + * + * H5Rdestroy() should be used to release the resource from the + * reference. + * + * \see function_name() + * + */ H5_DLL herr_t H5Rcreate_region(hid_t loc_id, const char *name, hid_t space_id, hid_t oapl_id, H5R_ref_t *ref_ptr); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5R + * + * \brief Creates an attribute reference + * + * \fgdta_loc_id + * \param[in] name Name of object + * \param[in] attr_name Name of attribute + * \oapl_id + * \param[out] ref_ptr Pointer to reference + * + * \return \herr_t + * + * \details H5Rcreate_attr() creates the reference, \p ref_ptr, pointing + * to the attribute named \p attr_name and attached to the object + * named \p name located at \p loc_id. + * + * The parameters \p loc_id and \p name locate the object. The + * parameter \p attr_name specifies the attribute within the object. + * + * The parameter \p oapl_id is an object access property list + * identifier for the object that the referenced attribute is + * attached to. The access property list must be of the same type + * as that object, that is a group, dataset or committed datatype + * property list. + * + * H5R_ref_t is defined in H5Rpublic.h as: typedef unsigned char + * H5R_ref_t[#H5R_REF_BUF_SIZE]; + * + * H5Rdestroy() should be used to release the resource from the + * reference. + * + */ H5_DLL herr_t H5Rcreate_attr(hid_t loc_id, const char *name, const char *attr_name, hid_t oapl_id, H5R_ref_t *ref_ptr); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5R + * + * \brief Closes a reference + * + * \param[in] ref_ptr Pointer to reference + * + * \return \herr_t + * + * \details Given a reference, ref_ptr, to an object, region or attribute + * attached to an object, H5R_DESTROY releases allocated resources + * from a previous create call. + * + * H5R_ref_t is defined in H5Rpublic.h as: typedef unsigned char + * H5R_ref_t[#H5R_REF_BUF_SIZE]; + * + */ H5_DLL herr_t H5Rdestroy(H5R_ref_t *ref_ptr); /* Info */ + +/** + * -------------------------------------------------------------------------- + * \ingroup H5R + * + * \brief Retrieves the type of a reference + * + * \param[in] ref_ptr Pointer to reference + * + * \return Returns a valid reference type if successful; otherwise returns #H5R_UNKNOWN. + * + * \details Given a reference, \p ref_ptr, H5Rget_type() returns the + * type of the reference. + * + * Valid returned reference types are: + * + * #H5R_OBJECT2 Object reference version 2 + * #H5R_DATASET_REGION2 Region reference version 2 + * #H5R_ATTRIBUTE Attribute reference + * + * Note that #H5R_OBJECT1 and #H5R_DATASET REGION1 can never be + * associated to an H5R_ref_t reference and can therefore never be + * returned through that function. + * + * H5R_ref_t is defined in H5Rpublic.h as: typedef unsigned char + * H5R_ref_t[#H5R_REF_BUF_SIZE]; + * + */ H5_DLL H5R_type_t H5Rget_type(const H5R_ref_t *ref_ptr); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5R + * + * \brief Determines whether two references are equal + * + * \param[in] ref1_ptr Pointer to reference to compare + * \param[in] ref2_ptr Pointer to reference to compare + * + * \return Returns a positive value if the references are equal. Returns + * 0 if the references are not equal. Returns a negative value when the + * function fails. + * + * \details H5Requal() determines whether two references point to the + * same object, region or attribute. + * + * H5R_ref_t is defined in H5Rpublic.h as: typedef unsigned char + * H5R_ref_t[#H5R_REF_BUF_SIZE]; + * + */ H5_DLL htri_t H5Requal(const H5R_ref_t *ref1_ptr, const H5R_ref_t *ref2_ptr); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5R + * + * \brief Copies an existing reference + * + * \param[in] src_ref_ptr Pointer to reference to copy + * \param[out] dst_ref_ptr Pointer to output reference + * + * \return \herr_t + * + * \details H5Rcopy() creates a copy of an existing reference. + * \p src_ref_ptr points to the reference to copy and \p dst_ref_ptr is the + * pointer to the destination reference. + * + */ H5_DLL herr_t H5Rcopy(const H5R_ref_t *src_ref_ptr, H5R_ref_t *dst_ref_ptr); /* Dereference */ + +/** + * -------------------------------------------------------------------------- + * \ingroup H5R + * + * \brief Opens the HDF5 object referenced + * + * \param[in] ref_ptr Pointer to reference to open + * \rapl_id + * \oapl_id + * + * \return \hid_t{object} + * + * \details Given a reference, \p ref_ptr, to an object, a region in + * an object, or an attribute attached to an object, H5Ropen_object() + * opens that object and returns an identifier. + * + * The parameter \p oapl_id is an object access property list + * identifier for the referenced object. The access property list + * must be of the same type as the object being referenced, that is + * a group or dataset property list. + * + * H5R_ref_t is defined in H5Rpublic.h as: typedef unsigned char + * H5R_ref_t[#H5R_REF_BUF_SIZE]; + * + * The object opened with this function should be closed when it + * is no longer needed so that resource leaks will not develop. Use + * the appropriate close function such as H5Oclose() or H5Dclose() + * for datasets. + * + */ H5_DLL hid_t H5Ropen_object(H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5R + * + * \brief Asynchronous version of H5Ropen_object() + * + * \app_file + * \app_func + * \app_line + * \param[out] ref_ptr Pointer to reference to open + * \rapl_id + * \oapl_id + * \es_id + * + * \return \hid_t{object} + * + * \see H5Ropen_object() + * + */ H5_DLL hid_t H5Ropen_object_async(const char *app_file, const char *app_func, unsigned app_line, H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id, hid_t es_id); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5R + * + * \brief Sets up a dataspace and selection as specified by a region reference. + * + * \param[in] ref_ptr Pointer to reference to open + * \rapl_id + * \oapl_id + * + * \return \hid_t{dataspace} + * + * \details H5Ropen_region() creates a copy of the dataspace of the + * dataset pointed to by a region reference, \p ref_ptr, and defines + * a selection matching the selection pointed to by \p ref_ptr within + * the dataspace copy. + * + * The parameter \p rapl id is a reference access property list + * identifier for the reference. The access property list can + * be used to access external files that the reference points to + * (through a file access property list). + * + * The parameter \p oapl id is an object access property list + * identifier for the referenced object. The access property list + * must be of the same type as the object being referenced, that is + * a dataset property list in that case. + * + * Use H5Sclose() to release the dataspace identifier returned by + * this function when the identifier is no longer needed. + * + */ H5_DLL hid_t H5Ropen_region(H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5R + * + * \brief Asynchronous version of H5Ropen_region() + * + * \app_file + * \app_func + * \app_line + * \param[in] ref_ptr Pointer to reference to open + * \rapl_id + * \oapl_id + * \es_id + * + * \return \hid_t{dataspace} + * + * \see H5Ropen_region() + * + */ H5_DLL hid_t H5Ropen_region_async(const char *app_file, const char *app_func, unsigned app_line, H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id, hid_t es_id); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5R + * + * \brief Opens the HDF5 attribute referenced + * + * \param[in] ref_ptr Pointer to reference to open + * \rapl_id + * \aapl_id + * + * \return \hid_t{attribute} + * + * \details Given a reference, \p ref_ptr, to an attribute attached to + * an object, H5Ropen_attr() opens the attribute attached to that + * object and returns an identifier. + * + * The parameter \p rapl id is a reference access property list + * identifier for the reference. The access property list can + * be used to access external files that the reference points to + * (through a file access property list). + * + * The parameter \p aapl_id is an attribute access property list + * identifier for the referenced attribute. + * + * The attribute opened with this function should be closed with + * H5Aclose() when it is no longer needed. + * + */ H5_DLL hid_t H5Ropen_attr(H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t aapl_id); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5R + * + * \brief Asynchronous version of H5Ropen_attr() + * + * \app_file + * \app_func + * \app_line + * \param[in] ref_ptr Pointer to reference to open + * \rapl_id + * \aapl_id + * \es_id + * + * \return \hid_t{attribute} + * + * \see H5Ropen_attr() + * + */ H5_DLL hid_t H5Ropen_attr_async(const char *app_file, const char *app_func, unsigned app_line, H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t aapl_id, hid_t es_id); /* Get type */ + +/** + * -------------------------------------------------------------------------- + * \ingroup H5R + * + * \brief Retrieves the type of object that an object reference points to + * + * \param[in] ref_ptr Pointer to reference to query + * \rapl_id + * \param[out] obj_type Type of referenced object + * + * \return \herr_t + * + * \details Given a reference, \p ref_ptr, H5Rget_obj_type3() retrieves + * the type of the referenced object in \p obj_type. + * + * The parameter \p rapl id is a reference access property list + * identifier for the reference. The access property list can + * be used to access external files that the reference points to + * (through a file access property list). + * + * Upon success, the function returns in \p obj_type the type of + * the object that the reference points to. Valid values for this + * referenced object type are as followed (defined in H5Opublic.h): + * + * H5O_TYPE_GROUP Object is a group + * H5O_TYPE_DATASET Object is a dataset + * H5O_TYPE_NAMED_DATATYPE Object is a named datatype + * + */ H5_DLL herr_t H5Rget_obj_type3(H5R_ref_t *ref_ptr, hid_t rapl_id, H5O_type_t *obj_type); /* Get name */ -H5_DLL ssize_t H5Rget_file_name(const H5R_ref_t *ref_ptr, char *buf, size_t size); -H5_DLL ssize_t H5Rget_obj_name(H5R_ref_t *ref_ptr, hid_t rapl_id, char *buf, size_t size); -H5_DLL ssize_t H5Rget_attr_name(const H5R_ref_t *ref_ptr, char *buf, size_t size); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5R + * + * \brief Retrieves the file name for a referenced object + * + * \param[in] ref_ptr Pointer to reference to query + * \param[in,out] name Buffer to place the file name of the reference + * \param[in] size Size of the \p name buffer + * + * \return Returns the length of the name if successful, otherwise, a negative value. + * + * \details H5Rget_file_name() retrieves the file name for the object, + * region or attribute reference pointed to by \p ref_ptr. + * + * Up to \p size characters of the name are returned in \p name; + * additional characters, if any, are not returned to the user + * application. If the length of the name, which determines + * the required value of size, is unknown, a preliminary + * H5Rget_file_name() call can be made. The return value of this + * call will be the size of the file name. That value can then be + * passed in for size in the second call to H5Rget_file_name(), + * which will retrieve the actual name. + * + */ +H5_DLL ssize_t H5Rget_file_name(const H5R_ref_t *ref_ptr, char *name, size_t size); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5R + * + * \brief Retrieves the object name for a referenced object + * + * \param[in] ref_ptr Pointer to reference to query + * \rapl_id + * \param[in,out] name Buffer to place the file name of the reference + * \param[in] size Size of the \p name buffer + * + * \return Returns the length of the name if successful, returning + * 0 (zero) if no name is associated with the identifier. Otherwise + * returns a negative value. + * + * \details H5Rget_obj_name() retrieves the object name for the object, + * region or attribute reference pointed to by \p ref_ptr. + * + * The parameter \p rapl id is a reference access property list + * identifier for the reference. The access property list can + * be used to access external files that the reference points to + * (through a file access property list). + * + * Up to size characters of the name are returned in name; additional + * characters, if any, are not returned to the user application. If + * the length of the name, which determines the required value of + * \p size, is unknown, a preliminary call to H5Rget_obj_name() call + * can be made. The return value of this call will be the size of the + * object name. That value can then be passed in for \p size in the + * second call to H5Rget_obj_name(), which will retrieve the actual + * name. If there is no name associated with the object identifier + * or if the name is #NULL, H5Rget_obj_name() returns the size of + * the name buffer (the size does not include the #NULL terminator). + * + * If \p ref_ptr is an object reference, \p name will be returned with + * a name for the referenced object. If \p ref_ptr is a dataset region + * reference, \p name will contain a name for the object containing + * the referenced region. If \p ref_ptr is an attribute reference, \p + * name will contain a name for the object the attribute is attached + * to. Note that an object in an HDF5 file may have multiple paths + * if there are multiple links pointing to it. This function may + * return any one of these paths. + * + */ +H5_DLL ssize_t H5Rget_obj_name(H5R_ref_t *ref_ptr, hid_t rapl_id, char *name, size_t size); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5R + * + * \brief Retrieves the attribute name for a referenced object + * + * \param[in] ref_ptr Pointer to reference to query + * \param[in,out] name Buffer to place the attribute name of the reference + * \param[in] size Size of the \p name buffer + * + * \return Returns the length of the name if successful, otherwise, a negative value. + * + * \details H5Rget_attr_name() retrieves the attribute name for the + * attribute reference pointed to by \p ref_ptr. + * + * Up to size characters of the name are returned in \p name; + * additional characters, if any, are not returned to the user + * application. If the length of the name, which determines + * the required value of \p size, is unknown, a preliminary + * H5Rget_attr_name() call can be made. The return value of this + * call will be the size of the attribute name. That value can then + * be passed in for size in the second call to H5Rget_attr_name(), + * which will retrieve the actual name. + * + */ +H5_DLL ssize_t H5Rget_attr_name(const H5R_ref_t *ref_ptr, char *name, size_t size); /* API Wrappers for async routines */ /* (Must be defined _after_ the function prototype) */ |