You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
518 lines
19 KiB
C
518 lines
19 KiB
C
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
|
|
* Copyright by The HDF Group. *
|
|
* 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
|