path: root/src/H5Apublic.h

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * Copyright by The HDF Group.                                               *
 * Copyright by the Board of Trustees of the University of Illinois.         *
 * All rights reserved.                                                      *
 *                                                                           *
 * This file is part of HDF5.  The full HDF5 copyright notice, including     *
 * terms governing use, modification, and redistribution, is contained in    *
 * the COPYING file, which can be found at the root of the source code       *
 * distribution tree, or in https://support.hdfgroup.org/ftp/HDF5/releases.  *
 * If you do not have access to either file, you may request a copy from     *
 * help@hdfgroup.org.                                                        *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

/*
 * This file contains public declarations for the H5A module.
 */
#ifndef _H5Apublic_H
#define _H5Apublic_H

/* Public headers needed by this file */
#include "H5Ipublic.h" /* IDs			  		*/
#include "H5Opublic.h" /* Object Headers			*/
#include "H5Tpublic.h" /* Datatypes				*/

/* Information struct for attribute (for H5Aget_info/H5Aget_info_by_idx) */
typedef struct {
    hbool_t           corder_valid; /* Indicate if creation order is valid */
    H5O_msg_crt_idx_t corder;       /* Creation order                 */
    H5T_cset_t        cset;         /* Character set of attribute name */
    hsize_t           data_size;    /* Size of raw data		  */
} H5A_info_t;

/* Typedef for H5Aiterate2() callbacks */
typedef herr_t (*H5A_operator2_t)(hid_t location_id /*in*/, const char *attr_name /*in*/,
                                  const H5A_info_t *ainfo /*in*/, void *op_data /*in,out*/);

/********************/
/* Public Variables */
/********************/

/*********************/
/* Public Prototypes */
/*********************/
#ifdef __cplusplus
extern "C" {
#endif

/* --------------------------------------------------------------------------*/
/**
 * \ingroup H5A
 *
 * \brief Creates an attribute attached to a specified object
 *
 * \fgdt_loc_id
 * \param[in] attr_name  Name of attribute
 * \param[in] type_id    Attribute datatype identifier
 * \space_id
 * \acpl_id
 * \aapl_id
 *
 * \return \hid_tv{attribute}
 *
 * \details H5Acreate2() creates an attribute, \p attr_name, which is attached
 *          to the object specified by the identifier \p loc_id.
 *
 *          The attribute name, \p attr_name, must be unique for the object.
 *
 *          The attribute is created with the specified datatype and dataspace,
 *          \p type_id and \p space_id, which are created with the H5T and
 *          H5S interfaces, respectively.
 *
 *          If \p type_id is either a fixed-length or variable-length string,
 *          it is important to set the string length when defining the
 *          datatype. String datatypes are derived from #H5T_C_S1 (or
 *          #H5T_FORTRAN_S1 for Fortran), which defaults to 1 character in
 *          size. See H5Tset_size() and Creating variable-length string
 *          datatypes.
 *
 *          The access property list is currently unused, but will be used in
 *          the future. This property list should currently be #H5P_DEFAULT.
 *
 *          The attribute identifier returned by this function must be released
 *          with H5Aclose() resource leaks will develop.
 *
 * \note The \p acpl and \p aapl parameters are currently not used; specify
 *       #H5P_DEFAULT.
 * \note If \p loc_id is a file identifier, the attribute will be attached
 *       that file’s root group.
 *
 * \since 1.8.0
 *
 * \see H5Aclose()
 *
 */
H5_DLL hid_t   H5Acreate2(hid_t loc_id, const char *attr_name, hid_t type_id, hid_t space_id, hid_t acpl_id,
                          hid_t aapl_id);
/*--------------------------------------------------------------------------*/
/**
 * \ingroup H5A
 *
 * \brief  Creates an attribute attached to a specified object
 *
 * \fgdt_loc_id
 * \param[in] obj_name  Name, relative to \p loc_id, of object that
 *                      attribute is to be attached to
 * \param[in] attr_name Attribute name
 * \param[in] type_id   Attribute datatype identifier
 * \space_id
 * \acpl_id
 * \aapl_id
 * \lapl_id
 *
 * \return \hid_tv{attribute}
 *
 * \details H5Acreate_by_name() creates an attribute, \p attr_name, which is
 *          attached to the object specified by \p loc_id and \p obj_name.
 *
 *          \p loc_id is a location identifier; \p obj_name is the object
 *          name relative to \p loc_id. If \p loc_id fully specifies the
 *          object to which the attribute is to be attached, \p obj_name
 *          should be '.' (a dot).
 *
 *          The attribute name, \p attr_name, must be unique for the object.
 *
 *          The attribute is created with the specified datatype and
 *          dataspace, \p type_id and \p space_id, which are created with
 *          the H5T and H5S interfaces respectively.
 *
 *          The attribute creation and access property lists are currently
 *          unused, but will be used in the future for optional attribute
 *          creation and access properties. These property lists should
 *          currently be #H5P_DEFAULT.
 *
 *          The link access property list, \p lapl_id, may provide
 *          information regarding the properties of links required to access
 *          the object, \p obj_name.
 *
 *          The attribute identifier returned by this function must be
 *          released with H5close() or resource leaks will develop.
 *
 * \since 1.8.0
 *
 */
H5_DLL hid_t   H5Acreate_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, hid_t type_id,
                                 hid_t space_id, hid_t acpl_id, hid_t aapl_id, hid_t lapl_id);
/*--------------------------------------------------------------------------*/
/**
 * \ingroup H5A
 *
 * \brief Opens an attribute for an object specified by object identifier and
 *        attribute name
 *
 * \fgdt_loc_id{obj_id}
 * \param[in]  attr_name    Name of attribute to open
 * \aapl_id
 *
 * \return \hid_tv{attribute}
 *
 * \details H5Aopen() opens an existing attribute, \p attr_name, that is
 *          attached to object specified by an object identifier, \p obj_id.
 *
 *          The attribute access property list, \p aapl_id, is currently unused
 *          and should be #H5P_DEFAULT.
 *
 *          This function, H5Aopen_by_idx() or H5Aopen_by_name() must be called
 *          before the attribute can be accessed for any further purpose,
 *          including reading, writing, or any modification.
 *
 *          The attribute identifier returned by this function must be released
 *          with H5Aclose() or resource leaks will develop.
 *
 * \since 1.8.0
 *
 * \see H5Aclose(), H5Acreate()
 */
H5_DLL hid_t   H5Aopen(hid_t obj_id, const char *attr_name, hid_t aapl_id);
/*--------------------------------------------------------------------------*/
/**
 * \ingroup H5A
 *
 * \brief Opens the nth attribute attached to an object
 *
 * \loc_id
 * \param[in] obj_name  Name of object to which attribute is attached,
 *                      relative to location
 * \param[in] idx_type  Type of index
 * \param[in] order     Index traversal order
 * \param[in] n         Attribute’s position in index
 * \aapl_id
 * \lapl_id
 *
 * \return \hid_tv{attribute}
 *
 * \details H5Aopen_by_idx() opens an existing attribute that is attached
 *          to an object specified by location and name, \p loc_id and
 *          \p obj_name, respectively. If \p loc_id fully specifies the
 *          object to which the attribute is attached, \p obj_name, should
 *          be  '.'  (a dot).
 *
 *          The attribute is identified by an index type, an index traversal
 *          order, and a position in the index, \p idx_type, \p order and
 *          \p n, respectively. These parameters and their valid values are
 *          discussed in the description of H5Aiterate2().
 *
 *          The attribute access property list, \p aapl_id, is currently
 *          unused and should currently be #H5P_DEFAULT.
 *
 *          The link access property list, \p lapl_id, may provide
 *          information regarding the properties of links required to access
 *          the object, \p obj_name.
 *
 *          This function, H5Aopen(), or H5Aopen_by_name() must be called
 *          before an attribute can be accessed for any further purpose,
 *          including reading, writing, or any modification.
 *
 *          The attribute identifier returned by this function must be
 *          released with H5Aclose() or resource leaks will develop.
 *
 * \since 1.8.0
 *
 */
H5_DLL hid_t   H5Aopen_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order,
                              hsize_t n, hid_t aapl_id, hid_t lapl_id);
/*--------------------------------------------------------------------------*/
/**
 * \ingroup H5A
 *
 * \brief Opens an attribute for an object by object name and attribute name
 *
 * \fgdt_loc_id
 * \param[in] obj_name   Name of object to which attribute is attached,
 *                       relative to \p loc_id
 * \param[in] attr_name  Name of attribute to open
 * \aapl_id
 * \lapl_id
 *
 * \return \hid_tv{attribute}
 *
 * \details H5Aopen_by_name() opens an existing attribute, \p attr_name,
 *          that is attached to an object specified by location and name,
 *          \p loc_id and \p obj_name, respectively.
 *
 *          \p loc_id specifies a location from which the target object can
 *          be located and \p obj_name is an object name relative to
 *          \p loc_id. If \p loc_id fully specifies the object to which the
 *          attribute is attached, \p obj_name should be '.' (a dot).
 *
 *          The attribute access property list, \p aapl_id, is currently
 *          unused and should currently be #H5P_DEFAULT.
 *
 *          The link access property list, \p lapl_id, may provide
 *          information regarding the properties of links required to access
 *          the object, \p obj_name.
 *
 *          This function, H5Aopen(), or H5Aopen_by_idx() must be called
 *          before an attribute can be accessed for any further purpose,
 *          including reading, writing, or any modification.
 *
 *          The attribute identifier returned by this function must be
 *          released with H5Aclose() or resource leaks will develop.
 *
 * \since 1.8.0
 *
 */
H5_DLL hid_t   H5Aopen_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, hid_t aapl_id,
                               hid_t lapl_id);
/*-------------------------------------------------------------------------- */
/**
 * \ingroup H5A
 *
 * \brief Reads the value of an attribute
 *
 * \attr_id
 * \mem_type_id{type_id}
 * \param[out] buf        Buffer for data to be read
 *
 * \return \herr_t
 *
 * \details H5Aread() reads an attribute, specified with \p attr_id. The
 *          attribute's in-memory datatype is specified with \p type_id. The
 *          entire attribute is read into \p buf from the file.
 *
 *          Datatype conversion takes place at the time of a read or write and
 *          is automatic.
 *
 * \version 1.8.8  Fortran updated to Fortran2003.
 * \version 1.4.2  The \p dims parameter was added to the Fortran API in this
 *                 release.
 * \since   1.0.0
 *
 * \see H5Awrite()
 *
*/
H5_DLL herr_t  H5Aread(hid_t attr_id, hid_t type_id, void *buf);
/*--------------------------------------------------------------------------*/
/**
 * \ingroup H5A
 *
 * \brief Writes data to an attribute
 *
 * \attr_id
 * \mem_type_id{type_id}
 * \param[out]  buf       Data to be written
 *
 * \return \herr_t
 *
 * \details H5Awrite() writes an attribute, specified with \p attr_id. The
 *          attribute's in-memory datatype is specified with \p type_id.
 *          The entire attribute is written from \p buf to the file.
 *
 *          If \p type_id is either a fixed-length or variable-length string,
 *          it is important to set the string length when defining the datatype.
 *          String datatypes are derived from #H5T_C_S1 (or #H5T_FORTRAN_S1 for
 *          Fortran codes), which defaults to 1 character in size.
 *          See H5Tset_size() and Creating variable-length string datatypes.
 *
 *          Datatype conversion takes place at the time of a read or write and
 *          is automatic.
 *
 * \version 1.8.8   Fortran updated to Fortran2003.
 * \version 1.4.2   Fortran \p dims parameter added in this release
 * \since 1.0.0
 * \see H5Aread()
 *
 */
H5_DLL herr_t  H5Awrite(hid_t attr_id, hid_t type_id, const void *buf);
H5_DLL hid_t   H5Aget_space(hid_t attr_id);
H5_DLL hid_t   H5Aget_type(hid_t attr_id);
H5_DLL hid_t   H5Aget_create_plist(hid_t attr_id);
H5_DLL ssize_t H5Aget_name(hid_t attr_id, size_t buf_size, char *buf);
H5_DLL ssize_t H5Aget_name_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_type,
                                  H5_iter_order_t order, hsize_t n, char *name /*out*/, size_t size,
                                  hid_t lapl_id);
H5_DLL hsize_t H5Aget_storage_size(hid_t attr_id);
H5_DLL herr_t  H5Aget_info(hid_t attr_id, H5A_info_t *ainfo /*out*/);
H5_DLL herr_t  H5Aget_info_by_name(hid_t loc_id, const char *obj_name, const char *attr_name,
                                   H5A_info_t *ainfo /*out*/, hid_t lapl_id);
H5_DLL herr_t  H5Aget_info_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_type,
                                  H5_iter_order_t order, hsize_t n, H5A_info_t *ainfo /*out*/, hid_t lapl_id);
H5_DLL herr_t  H5Arename(hid_t loc_id, const char *old_name, const char *new_name);
H5_DLL herr_t  H5Arename_by_name(hid_t loc_id, const char *obj_name, const char *old_attr_name,
                                 const char *new_attr_name, hid_t lapl_id);
H5_DLL herr_t  H5Aiterate2(hid_t loc_id, H5_index_t idx_type, H5_iter_order_t order, hsize_t *idx,
                           H5A_operator2_t op, void *op_data);
H5_DLL herr_t  H5Aiterate_by_name(hid_t loc_id, const char *obj_name, H5_index_t idx_type,
                                  H5_iter_order_t order, hsize_t *idx, H5A_operator2_t op, void *op_data,
                                  hid_t lapd_id);
H5_DLL herr_t  H5Adelete(hid_t loc_id, const char *name);
H5_DLL herr_t  H5Adelete_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, hid_t lapl_id);
H5_DLL herr_t H5Adelete_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order,
                               hsize_t n, hid_t lapl_id);
H5_DLL htri_t H5Aexists(hid_t obj_id, const char *attr_name);
H5_DLL htri_t H5Aexists_by_name(hid_t obj_id, const char *obj_name, const char *attr_name, hid_t lapl_id);
/*-------------------------------------------------------------------------*/
/**
 * \ingroup H5A
 *
 * \brief Closes the specified attribute
 *
 * \attr_id
 *
 * \return \herr_t
 *
 * \details H5Aclose() terminates access to the attribute specified by
 *          \p attr_id by releasing the identifier.
 *
 * \attention Further use of a released attribute identifier is illegal; a
 *            function using such an identifier will generate an error.
 *
 * \since 1.0.0
 *
 * \see H5Acreate(), H5Aopen()
 */
H5_DLL herr_t H5Aclose(hid_t attr_id);

/* Symbols defined for compatibility with previous versions of the HDF5 API.
 *
 * Use of these symbols is deprecated.
 */
#ifndef H5_NO_DEPRECATED_SYMBOLS

/* Macros */

/* Typedefs */

/* Typedef for H5Aiterate1() callbacks */
typedef herr_t (*H5A_operator1_t)(hid_t location_id /*in*/, const char *attr_name /*in*/,
                                  void *operator_data /*in,out*/);

/* Function prototypes */
/* --------------------------------------------------------------------------*/
/**
 * \ingroup H5A
 *
 * \brief Creates an attribute attached to a specified object
 *
 * \fgdt_loc_id
 * \param[in] name     Name of attribute to locate and open
 * \param[in] type_id  Identifier of attribute datatype
 * \space_id
 * \acpl_id
 *
 * \return \hid_tv{attribute}
 *
 * \note The \p acpl parameters is currently not used; specify #H5P_DEFAULT.
 *
 * \deprecated Deprecated in favor of H5Acreate2()
 *
 * \details H5Acreate1() creates an attribute, \p name, which is attached
 *          to the object specified by the identifier \p loc_id.
 *
 *          The attribute name, \p name, must be unique for the object.
 *
 *          The attribute is created with the specified datatype and dataspace,
 *          \p type_id and \p space_id, which are created with the H5T and
 *          H5S interfaces, respectively.
 *
 *          If \p type_id is either a fixed-length or variable-length string,
 *          it is important to set the string length when defining the
 *          datatype. String datatypes are derived from #H5T_C_S1 (or
 *          #H5T_FORTRAN_S1 for Fortran), which defaults to 1 character in
 *          size. See H5Tset_size() and Creating variable-length string
 *          datatypes.
 *
 *          The attribute identifier returned by this function must be released
 *          with H5Aclose() resource leaks will develop.
 *
 * \since 1.8.0
 *
 * \version 1.8.0 The function H5Acreate() was renamed to H5Acreate1() and
 *          deprecated in this release.
 *
 * \see H5Aclose()
 *
 */
H5_DLL hid_t  H5Acreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t acpl_id);
H5_DLL hid_t  H5Aopen_name(hid_t loc_id, const char *name);
H5_DLL hid_t  H5Aopen_idx(hid_t loc_id, unsigned idx);
H5_DLL int    H5Aget_num_attrs(hid_t loc_id);
H5_DLL herr_t H5Aiterate1(hid_t loc_id, unsigned *attr_num, H5A_operator1_t op, void *op_data);

#endif /* H5_NO_DEPRECATED_SYMBOLS */

#ifdef __cplusplus
}
#endif

#endif /* _H5Apublic_H */