summaryrefslogtreecommitdiffstats
path: root/src/H5Rpublic.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/H5Rpublic.h')
-rw-r--r--src/H5Rpublic.h471
1 files changed, 468 insertions, 3 deletions
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) */