/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 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 /**\defgroup H5PT Packet Table * * Creating and manipulating HDF5 datasets to support append- * and read-only operations on table data (H5PT) * * 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