path: root/hl/src/H5PTpublic.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://www.hdfgroup.org/licenses.               *
 * If you do not have access to either file, you may request a copy from     *
 * help@hdfgroup.org.                                                        *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

#ifndef H5PTpublic_H
#define H5PTpublic_H

#ifdef __cplusplus
extern "C" {
#endif

/** \page H5PT_UG The HDF5 High Level Packet Table
 * @todo Under Construction
 */

/**\defgroup H5PT HDF5 Packet Table APIs (H5PT)
 *
 * <em>Creating and manipulating HDF5 datasets to support append-
 * and read-only operations on table data (H5PT)</em>
 *
 * The HDF5 Packet Table API is designed to allow records to be
 * appended to and read from a table. Packet Table datasets are
 * chunked, allowing them to grow as needed.
 *
 * The Packet Table API, with the H5PT prefix, is not to be confused with
 * the H5TB Table API (H5TB prefix). The H5TB APIs are stateless
 * (H5TB Tables do not need to be opened or closed) but H5PT Packet Tables
 * require less performance overhead. Also, H5TB Tables support insertions
 * and deletions, while H5PT Packet Tables support only append operations.
 * H5TB functions should not be called on tables created with the
 * H5PT API, or vice versa.
 *
 * Packet Tables are datasets in an HDF5 file, so while their contents
 * should not be changed outside of the H5PT API calls, the datatypes of
 * Packet Tables can be queried using \ref H5Dget_type.
 * Packet Tables can also be given attributes using the normal HDF5 APIs.
 *
 * \note \Bold{Programming hints:}
 * \note The following line includes the HDF5 Packet Table package, H5PT,
 *       in C applications:
 *       \code #include "hdf5_hl.h" \endcode
 *       Without this include, an application will not have access to
 *       these functions.
 *
 * - \ref H5PTappend
 *   \n Appends packets to the end of a packet table.
 * - \ref H5PTclose
 *   \n Closes an open packet table.
 * - \ref H5PTcreate
 *   \n Creates a packet table to store fixed-length
 *      or variable-length packets.
 * - \ref H5PTcreate_fl
 *   \n Creates a packet table to store fixed-length packets.
 * - \ref H5PTcreate_index
 *   \n Resets a packet table's index to the first packet.
 * - \ref H5PTfree_vlen_buff
 *   \n Releases memory allocated in the process of
 *      reading variable-length packets.
 * - \ref H5PTget_dataset
 *   \n Returns the backend dataset of this packet table.
 * - \ref H5PTget_index
 *   \n Gets the current record index for a packet table
 * - \ref H5PTget_next
 *   \n Reads packets from a packet table starting at the
 *      current index.
 * - \ref H5PTget_num_packets
 *   \n Returns the number of packets in a packet table.
 * - \ref H5PTget_type
 *   \n Returns the backend datatype of this packet table.
 * - \ref H5PTis_valid
 *   \n Determines whether an identifier points to a packet table.
 * - \ref H5PTis_varlen
 *   \n Determines whether a packet table contains variable-length
 *      or fixed-length packets.
 * - \ref H5PTopen
 *   \n Opens an existing packet table.
 * - \ref H5PTread_packets
 *   \n Reads a number of packets from a packet table.
 * - \ref H5PTset_index
 *   \n Sets a packet table's index.
 *
 */

/*-------------------------------------------------------------------------
 * Create/Open/Close functions
 *-------------------------------------------------------------------------
 */
/* NOTE: H5PTcreate is replacing H5PTcreate_fl for better name due to the
   removal of H5PTcreate_vl.  H5PTcreate_fl may be retired in 1.8.19. */

/**
 * --------------------------------------------------------------------------
 * \ingroup H5PT
 *
 * \brief   Creates a packet table to store fixed-length or
 *          variable-length packets.
 *
 * \fg_loc_id
 * \param[in] dset_name     The name of the packet table to create
 * \param[in] dtype_id      The datatype of the packet
 * \param[in] chunk_size    The size in number of table entries per chunk
 * \param[in] plist_id      Identifier of the property list. Can be used to
 *                          specify the compression of the packet table.
 *
 * \return Returns an identifier for the new packet table or
 *         #H5I_INVALID_HID on error.
 *
 * \details The H5PTcreate() creates and opens a packet table named
 *          \p dset_name attached to the object specified by the
 *          identifier \p loc_id. The created packet table should be closed
 *          with H5PTclose(), eventually.
 *
 *          The datatype, \p dtype_id, may specify any datatype, including
 *          variable-length data.  If \p dtype_id specifies a compound
 *          datatype, one or more fields in that compound type may be
 *          variable-length.
 *
 *          \p chunk_size is the size in number of table entries per chunk.
 *          Packet table datasets use HDF5 chunked storage
 *          to allow them to grow. This value allows the user
 *          to set the size of a chunk. The chunk size affects
 *          performance.
 *
 * \since   1.10.0 and 1.8.17
 *
 */
H5_HLDLL hid_t H5PTcreate(hid_t loc_id, const char *dset_name, hid_t dtype_id, hsize_t chunk_size,
                          hid_t plist_id);

/**
 * --------------------------------------------------------------------------
 * \ingroup H5PT
 *
 * \brief Opens an existing packet table.
 *
 * \fg_loc_id
 * \param[in] dset_name     The name of the packet table to open
 *
 * \return Returns an identifier for the packet table or
 *         #H5I_INVALID_HID on error.
 *
 * \details H5PTopen() opens an existing packet table in the file or group
 *          specified by \p loc_id. \p dset_name is the name of the packet
 *          table and is used to identify it in the file. This function is
 *          used to open both fixed-length packet tables and variable-length
 *          packet tables. The packet table should later be closed with
 *          H5PTclose().
 *
 */
H5_HLDLL hid_t H5PTopen(hid_t loc_id, const char *dset_name);

/**
 * --------------------------------------------------------------------------
 * \ingroup H5PT
 *
 * \brief Closes an open packet table.
 *
 * \param[in] table_id  Identifier of packet table to be closed
 *
 * \return \herr_t
 *
 * \details The H5PTclose() ends access to a packet table specified
 *          by \p table_id.
 *
 */
H5_HLDLL herr_t H5PTclose(hid_t table_id);

/**
 * --------------------------------------------------------------------------
 * \ingroup H5PT
 *
 * \brief Creates a packet table to store fixed-length packets
 *
 * \fg_loc_id
 * \param[in] dset_name     The name of the dataset to create
 * \param[in] dtype_id      The datatype of a packet.
 * \param[in] chunk_size    The size in number of table entries per
 *                          chunk.
 * \param[in] compression   The compression level;
 *                          a value of 0 through 9.
 *
 * \return Returns an identifier for the packet table or
 *         #H5I_INVALID_HID on error.
 *
 * \deprecated This function was deprecated in favor of the function
 *             H5PTcreate().
 *
 * \details The H5PTcreate_fl() creates and opens a packet table
 *          named \p dset_name attached to the object specified by
 *          the identifier \p loc_id. It should be closed
 *          with H5PTclose().
 *
 *          The datatype, \p dtype_id, may specify any datatype,
 *          including variable-length data. If \p dtype_id specifies a
 *          compound datatype, one or more fields in that compound type
 *          may be variable-length.
 *
 *          \p chunk_size is the size in number of table entries per chunk.
 *          Packet table datasets use HDF5 chunked storage
 *          to allow them to grow. This value allows the user
 *          to set the size of a chunk. The chunk size affects
 *          performance.
 *
 *          \p compression is the compression level, a value of 0 through 9.
 *          Level 0 is faster but offers the least compression;
 *          level 9 is slower but offers maximum compression.
 *          A setting of -1 indicates that no compression is desired.
 *
 */
/* This function may be removed from the packet table in release 1.8.19. */
H5_HLDLL hid_t H5PTcreate_fl(hid_t loc_id, const char *dset_name, hid_t dtype_id, hsize_t chunk_size,
                             int compression);

/*-------------------------------------------------------------------------
 * Write functions
 *-------------------------------------------------------------------------
 */
/**
 * --------------------------------------------------------------------------
 * \ingroup H5PT
 *
 * \brief Appends packets to the end of a packet table.
 *
 * \param[in] table_id  Identifier of packet table to which
 *                      packets should be appended
 * \param[in] nrecords  Number of packets to be appended
 * \param[in] data      Buffer holding data to write
 *
 * \return \herr_t
 *
 * \details The H5PTappend() writes \p nrecords packets to the end of a
 *          packet table specified by \p table_id. \p data is a buffer
 *          containing the data to be written. For a packet table holding
 *          fixed-length packets, this data should be in the packet
 *          table's datatype. For a variable-length packet table,
 *          the data should be in the form of #hvl_t structs.
 *
 */
H5_HLDLL herr_t H5PTappend(hid_t table_id, size_t nrecords, const void *data);

/*-------------------------------------------------------------------------
 * Read functions
 *-------------------------------------------------------------------------
 */
/**
 * --------------------------------------------------------------------------
 * \ingroup H5PT
 *
 * \brief Reads packets from a packet table starting at the current index.
 *
 * \param[in] table_id  Identifier of packet table to read from
 * \param[in] nrecords  Number of packets to be read
 * \param[out] data     Buffer into which to read data
 *
 * \return \herr_t
 *
 * \details The H5PTget_next() reads \p nrecords packets starting with
 *          the "current index" from a packet table specified by \p table_id.
 *          The packet table's index is set and reset with H5PTset_index()
 *          and H5PTcreate_index(). \p data is a buffer into which the
 *          data should be read.
 *
 *          For a packet table holding variable-length records, the data
 *          returned in the buffer will be in form of a #hvl_t struct
 *          containing the length of the data and a pointer to it in memory.
 *          The memory used by this data must be freed using H5PTfree_vlen_buff().
 *
 */
H5_HLDLL herr_t H5PTget_next(hid_t table_id, size_t nrecords, void *data);

/**
 * --------------------------------------------------------------------------
 * \ingroup H5PT
 *
 * \brief Reads a number of packets from a packet table.
 *
 * \param[in] table_id  Identifier of packet table to read from
 * \param[in] start     Packet to start reading from
 * \param[in] nrecords  Number of packets to be read
 * \param[out] data     Buffer into which to read data.
 *
 * \return \herr_t
 *
 * \details The H5PTread_packets() reads \p nrecords packets starting at
 *          packet number \p start from a packet table specified by
 *          \p table_id. \p data is a buffer into which the data should
 *          be read.
 *
 *          For a packet table holding variable-length records, the data
 *          returned in the buffer will be in form of #hvl_t structs,
 *          each containing the length of the data and a pointer to it in
 *          memory. The memory used by this data must be freed using
 *          H5PTfree_vlen_buff().
 *
 */
H5_HLDLL herr_t H5PTread_packets(hid_t table_id, hsize_t start, size_t nrecords, void *data);

/*-------------------------------------------------------------------------
 * Inquiry functions
 *-------------------------------------------------------------------------
 */

/**
 * --------------------------------------------------------------------------
 * \ingroup H5PT
 *
 * \brief Returns the number of packets in a packet table.
 *
 * \param[in] table_id  Identifier of packet table to query
 * \param[out] nrecords Number of packets in packet table
 *
 * \return \herr_t
 *
 * \details The H5PTget_num_packets() returns by reference the number
 *          of packets in a packet table specified by \p table_id.
 *
 */
H5_HLDLL herr_t H5PTget_num_packets(hid_t table_id, hsize_t *nrecords);

/**
 * --------------------------------------------------------------------------
 * \ingroup H5PT
 *
 * \brief Determines whether an identifier points to a packet table.
 *
 * \param[in] table_id  Identifier to query
 *
 * \return Returns a non-negative value if \p table_id is
 *         a valid packet table, otherwise returns a negative value.
 *
 * \details The H5PTis_valid() returns a non-negative value if
 *          \p table_id corresponds to an open packet table,
 *          and returns a negative value otherwise.
 *
 */
H5_HLDLL herr_t H5PTis_valid(hid_t table_id);

/**
 * --------------------------------------------------------------------------
 * \ingroup H5PT
 *
 * \brief Determines whether a packet table contains
 *        variable-length or fixed-length packets.
 *
 * \param[in] table_id  Packet table to query
 *
 * \return Returns 1 for a variable-length packet table,
 *         0 for fixed-length, or a negative value on error.
 *
 * \details The H5PTis_varlen() returns 1 (TRUE) if \p table_id is
 *          a packet table containing variable-length records.
 *          It returns 0 (FALSE) if \p table_id is a packet table
 *          containing fixed-length records. If \p table_id is not a
 *          packet table, a negative value is returned.
 *
 * \version 1.10.0 and 1.8.17 Function re-introduced.
 *                            Function had been removed in 1.8.3.
 *
 */
H5_HLDLL herr_t H5PTis_varlen(hid_t table_id);

/*-------------------------------------------------------------------------
 *
 * Accessor functions
 *
 *-------------------------------------------------------------------------
 */

/**
 * --------------------------------------------------------------------------
 * \ingroup H5PT
 *
 * \brief Returns the backend dataset of this packet table.
 *
 * \param[in] table_id  Identifier of the packet table
 *
 * \return Returns a dataset identifier or H5I_INVALID_HID on error.
 *
 * \details The H5PTget_dataset() returns the identifier of the dataset
 *          storing the packet table \p table_id. This dataset identifier
 *          will be closed by H5PTclose().
 *
 * \since 1.10.0 and 1.8.17
 *
 */
H5_HLDLL hid_t H5PTget_dataset(hid_t table_id);

/**
 * --------------------------------------------------------------------------
 * \ingroup H5PT
 *
 * \brief Returns the backend datatype of this packet table.
 *
 * \param[in] table_id  Identifier of the packet table
 *
 * \return Returns a datatype identifier or H5I_INVALID_HID on error.
 *
 * \details The H5PTget_type() returns the identifier of the datatype
 *          used by the packet table \p table_id. This datatype
 *          identifier will be closed by H5PTclose().
 *
 * \since 1.10.0 and 1.8.17
 *
 */
H5_HLDLL hid_t H5PTget_type(hid_t table_id);

/*-------------------------------------------------------------------------
 *
 * Packet Table "current index" functions
 *
 *-------------------------------------------------------------------------
 */

/**
 * --------------------------------------------------------------------------
 * \ingroup H5PT
 *
 * \brief Resets a packet table's index to the first packet.
 *
 * \param[in] table_id  Identifier of packet table whose index
 *                      should be initialized.
 *
 * \return \herr_t
 *
 * \details Each packet table keeps an index of the "current" packet
 *          so that \c get_next can iterate through the packets in order.
 *          H5PTcreate_index() initializes a packet table's index, and
 *          should be called before using \c get_next. The index must be
 *          initialized every time a packet table is created or opened;
 *          this information is lost when the packet table is closed.
 *
 */
H5_HLDLL herr_t H5PTcreate_index(hid_t table_id);

/**
 * --------------------------------------------------------------------------
 * \ingroup H5PT
 *
 * \brief Sets a packet table's index.
 *
 * \param[in] table_id  Identifier of packet table whose index is to be set
 * \param[in] pt_index  The packet to which the index should point
 *
 * \return \herr_t
 *
 * \details Each packet table keeps an index of the "current" packet
 *          so that \c get_next can iterate through the packets in order.
 *          H5PTset_index() sets this index to point to a user-specified
 *          packet (the packets are zero-indexed).
 *
 */
H5_HLDLL herr_t H5PTset_index(hid_t table_id, hsize_t pt_index);

/**
 * --------------------------------------------------------------------------
 * \ingroup H5PT
 *
 * \brief Gets the current record index for a packet table.
 *
 * \param[in] table_id  Table identifier
 * \param[out] pt_index Current record index
 *
 * \return \herr_t
 *
 * \details The H5PTget_index() returns the current record index
 *          \p pt_index for the table identified by \p table_id.
 *
 * \since 1.8.0
 *
 */
H5_HLDLL herr_t H5PTget_index(hid_t table_id, hsize_t *pt_index);

/*-------------------------------------------------------------------------
 *
 * Memory Management functions
 *
 *-------------------------------------------------------------------------
 */

/**
 * --------------------------------------------------------------------------
 * \ingroup H5PT
 *
 * \brief Releases memory allocated in the process of reading
 *        variable-length packets.
 *
 * \param[in] table_id  Packet table whose memory should be freed.
 * \param[in] bufflen   Size of \p buff
 * \param[in] buff      Buffer that was used to read in variable-length
 *                      packets
 *
 * \return \herr_t
 *
 * \details When variable-length packets are read, memory is automatically
 *          allocated to hold them, and must be freed. H5PTfree_vlen_buff()
 *          frees this memory, and should be called whenever packets are
 *          read from a variable-length packet table.
 *
 * \version 1.10.0 and 1.8.17 Function re-introduced.
 *                            Function had been removed in 1.8.3.
 *
 */
H5_HLDLL herr_t H5PTfree_vlen_buff(hid_t table_id, size_t bufflen, void *buff);

#ifdef __cplusplus
}
#endif

#endif