EIC code displayed by LXR |
|
|
|
|||
File indexing completed on 2025-06-20 08:49:48
0001 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 0002 * Copyright by The HDF Group. * 0003 * All rights reserved. * 0004 * * 0005 * This file is part of HDF5. The full HDF5 copyright notice, including * 0006 * terms governing use, modification, and redistribution, is contained in * 0007 * the COPYING file, which can be found at the root of the source code * 0008 * distribution tree, or in https://www.hdfgroup.org/licenses. * 0009 * If you do not have access to either file, you may request a copy from * 0010 * help@hdfgroup.org. * 0011 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 0012 0013 #ifndef H5PTpublic_H 0014 #define H5PTpublic_H 0015 0016 #ifdef __cplusplus 0017 extern "C" { 0018 #endif 0019 0020 /** \page H5PT_UG HDF5 High Level Packet Table 0021 * @todo Under Construction 0022 */ 0023 0024 /**\defgroup H5PT HDF5 Packet Table APIs (H5PT) 0025 * 0026 * <em>Creating and manipulating HDF5 datasets to support append- 0027 * and read-only operations on table data (H5PT)</em> 0028 * 0029 * The HDF5 Packet Table API is designed to allow records to be 0030 * appended to and read from a table. Packet Table datasets are 0031 * chunked, allowing them to grow as needed. 0032 * 0033 * The Packet Table API, with the H5PT prefix, is not to be confused with 0034 * the H5TB Table API (H5TB prefix). The H5TB APIs are stateless 0035 * (H5TB Tables do not need to be opened or closed) but H5PT Packet Tables 0036 * require less performance overhead. Also, H5TB Tables support insertions 0037 * and deletions, while H5PT Packet Tables support only append operations. 0038 * H5TB functions should not be called on tables created with the 0039 * H5PT API, or vice versa. 0040 * 0041 * Packet Tables are datasets in an HDF5 file, so while their contents 0042 * should not be changed outside of the H5PT API calls, the datatypes of 0043 * Packet Tables can be queried using \ref H5Dget_type. 0044 * Packet Tables can also be given attributes using the normal HDF5 APIs. 0045 * 0046 * \note \Bold{Programming hints:} 0047 * \note The following line includes the HDF5 Packet Table package, H5PT, 0048 * in C applications: 0049 * \code #include "hdf5_hl.h" \endcode 0050 * Without this include, an application will not have access to 0051 * these functions. 0052 * 0053 * - \ref H5PTappend 0054 * \n Appends packets to the end of a packet table. 0055 * - \ref H5PTclose 0056 * \n Closes an open packet table. 0057 * - \ref H5PTcreate 0058 * \n Creates a packet table to store fixed-length 0059 * or variable-length packets. 0060 * - \ref H5PTcreate_fl 0061 * \n Creates a packet table to store fixed-length packets. 0062 * - \ref H5PTcreate_index 0063 * \n Resets a packet table's index to the first packet. 0064 * - \ref H5PTfree_vlen_buff 0065 * \n Releases memory allocated in the process of 0066 * reading variable-length packets. 0067 * - \ref H5PTget_dataset 0068 * \n Returns the backend dataset of this packet table. 0069 * - \ref H5PTget_index 0070 * \n Gets the current record index for a packet table 0071 * - \ref H5PTget_next 0072 * \n Reads packets from a packet table starting at the 0073 * current index. 0074 * - \ref H5PTget_num_packets 0075 * \n Returns the number of packets in a packet table. 0076 * - \ref H5PTget_type 0077 * \n Returns the backend datatype of this packet table. 0078 * - \ref H5PTis_valid 0079 * \n Determines whether an identifier points to a packet table. 0080 * - \ref H5PTis_varlen 0081 * \n Determines whether a packet table contains variable-length 0082 * or fixed-length packets. 0083 * - \ref H5PTopen 0084 * \n Opens an existing packet table. 0085 * - \ref H5PTread_packets 0086 * \n Reads a number of packets from a packet table. 0087 * - \ref H5PTset_index 0088 * \n Sets a packet table's index. 0089 * 0090 */ 0091 0092 /*------------------------------------------------------------------------- 0093 * Create/Open/Close functions 0094 *------------------------------------------------------------------------- 0095 */ 0096 /* NOTE: H5PTcreate is replacing H5PTcreate_fl for better name due to the 0097 removal of H5PTcreate_vl. H5PTcreate_fl may be retired in 1.8.19. */ 0098 0099 /** 0100 * -------------------------------------------------------------------------- 0101 * \ingroup H5PT 0102 * 0103 * \brief Creates a packet table to store fixed-length or 0104 * variable-length packets. 0105 * 0106 * \fg_loc_id 0107 * \param[in] dset_name The name of the packet table to create 0108 * \param[in] dtype_id The datatype of the packet 0109 * \param[in] chunk_size The size in number of table entries per chunk 0110 * \param[in] plist_id Identifier of the property list. Can be used to 0111 * specify the compression of the packet table. 0112 * 0113 * \return Returns an identifier for the new packet table or 0114 * #H5I_INVALID_HID on error. 0115 * 0116 * \details The H5PTcreate() creates and opens a packet table named 0117 * \p dset_name attached to the object specified by the 0118 * identifier \p loc_id. The created packet table should be closed 0119 * with H5PTclose(), eventually. 0120 * 0121 * The datatype, \p dtype_id, may specify any datatype, including 0122 * variable-length data. If \p dtype_id specifies a compound 0123 * datatype, one or more fields in that compound type may be 0124 * variable-length. 0125 * 0126 * \p chunk_size is the size in number of table entries per chunk. 0127 * Packet table datasets use HDF5 chunked storage 0128 * to allow them to grow. This value allows the user 0129 * to set the size of a chunk. The chunk size affects 0130 * performance. 0131 * 0132 * \since 1.10.0 and 1.8.17 0133 * 0134 */ 0135 H5_HLDLL hid_t H5PTcreate(hid_t loc_id, const char *dset_name, hid_t dtype_id, hsize_t chunk_size, 0136 hid_t plist_id); 0137 0138 /** 0139 * -------------------------------------------------------------------------- 0140 * \ingroup H5PT 0141 * 0142 * \brief Opens an existing packet table. 0143 * 0144 * \fg_loc_id 0145 * \param[in] dset_name The name of the packet table to open 0146 * 0147 * \return Returns an identifier for the packet table or 0148 * #H5I_INVALID_HID on error. 0149 * 0150 * \details H5PTopen() opens an existing packet table in the file or group 0151 * specified by \p loc_id. \p dset_name is the name of the packet 0152 * table and is used to identify it in the file. This function is 0153 * used to open both fixed-length packet tables and variable-length 0154 * packet tables. The packet table should later be closed with 0155 * H5PTclose(). 0156 * 0157 */ 0158 H5_HLDLL hid_t H5PTopen(hid_t loc_id, const char *dset_name); 0159 0160 /** 0161 * -------------------------------------------------------------------------- 0162 * \ingroup H5PT 0163 * 0164 * \brief Closes an open packet table. 0165 * 0166 * \param[in] table_id Identifier of packet table to be closed 0167 * 0168 * \return \herr_t 0169 * 0170 * \details The H5PTclose() ends access to a packet table specified 0171 * by \p table_id. 0172 * 0173 */ 0174 H5_HLDLL herr_t H5PTclose(hid_t table_id); 0175 0176 /** 0177 * -------------------------------------------------------------------------- 0178 * \ingroup H5PT 0179 * 0180 * \brief Creates a packet table to store fixed-length packets 0181 * 0182 * \fg_loc_id 0183 * \param[in] dset_name The name of the dataset to create 0184 * \param[in] dtype_id The datatype of a packet. 0185 * \param[in] chunk_size The size in number of table entries per 0186 * chunk. 0187 * \param[in] compression The compression level; 0188 * a value of 0 through 9. 0189 * 0190 * \return Returns an identifier for the packet table or 0191 * #H5I_INVALID_HID on error. 0192 * 0193 * \deprecated This function was deprecated in favor of the function 0194 * H5PTcreate(). 0195 * 0196 * \details The H5PTcreate_fl() creates and opens a packet table 0197 * named \p dset_name attached to the object specified by 0198 * the identifier \p loc_id. It should be closed 0199 * with H5PTclose(). 0200 * 0201 * The datatype, \p dtype_id, may specify any datatype, 0202 * including variable-length data. If \p dtype_id specifies a 0203 * compound datatype, one or more fields in that compound type 0204 * may be variable-length. 0205 * 0206 * \p chunk_size is the size in number of table entries per chunk. 0207 * Packet table datasets use HDF5 chunked storage 0208 * to allow them to grow. This value allows the user 0209 * to set the size of a chunk. The chunk size affects 0210 * performance. 0211 * 0212 * \p compression is the compression level, a value of 0 through 9. 0213 * Level 0 is faster but offers the least compression; 0214 * level 9 is slower but offers maximum compression. 0215 * A setting of -1 indicates that no compression is desired. 0216 * 0217 */ 0218 /* This function may be removed from the packet table in release 1.8.19. */ 0219 H5_HLDLL hid_t H5PTcreate_fl(hid_t loc_id, const char *dset_name, hid_t dtype_id, hsize_t chunk_size, 0220 int compression); 0221 0222 /*------------------------------------------------------------------------- 0223 * Write functions 0224 *------------------------------------------------------------------------- 0225 */ 0226 /** 0227 * -------------------------------------------------------------------------- 0228 * \ingroup H5PT 0229 * 0230 * \brief Appends packets to the end of a packet table. 0231 * 0232 * \param[in] table_id Identifier of packet table to which 0233 * packets should be appended 0234 * \param[in] nrecords Number of packets to be appended 0235 * \param[in] data Buffer holding data to write 0236 * 0237 * \return \herr_t 0238 * 0239 * \details The H5PTappend() writes \p nrecords packets to the end of a 0240 * packet table specified by \p table_id. \p data is a buffer 0241 * containing the data to be written. For a packet table holding 0242 * fixed-length packets, this data should be in the packet 0243 * table's datatype. For a variable-length packet table, 0244 * the data should be in the form of #hvl_t structs. 0245 * 0246 */ 0247 H5_HLDLL herr_t H5PTappend(hid_t table_id, size_t nrecords, const void *data); 0248 0249 /*------------------------------------------------------------------------- 0250 * Read functions 0251 *------------------------------------------------------------------------- 0252 */ 0253 /** 0254 * -------------------------------------------------------------------------- 0255 * \ingroup H5PT 0256 * 0257 * \brief Reads packets from a packet table starting at the current index. 0258 * 0259 * \param[in] table_id Identifier of packet table to read from 0260 * \param[in] nrecords Number of packets to be read 0261 * \param[out] data Buffer into which to read data 0262 * 0263 * \return \herr_t 0264 * 0265 * \details The H5PTget_next() reads \p nrecords packets starting with 0266 * the "current index" from a packet table specified by \p table_id. 0267 * The packet table's index is set and reset with H5PTset_index() 0268 * and H5PTcreate_index(). \p data is a buffer into which the 0269 * data should be read. 0270 * 0271 * For a packet table holding variable-length records, the data 0272 * returned in the buffer will be in form of a #hvl_t struct 0273 * containing the length of the data and a pointer to it in memory. 0274 * The memory used by this data must be freed using H5PTfree_vlen_buff(). 0275 * 0276 */ 0277 H5_HLDLL herr_t H5PTget_next(hid_t table_id, size_t nrecords, void *data); 0278 0279 /** 0280 * -------------------------------------------------------------------------- 0281 * \ingroup H5PT 0282 * 0283 * \brief Reads a number of packets from a packet table. 0284 * 0285 * \param[in] table_id Identifier of packet table to read from 0286 * \param[in] start Packet to start reading from 0287 * \param[in] nrecords Number of packets to be read 0288 * \param[out] data Buffer into which to read data. 0289 * 0290 * \return \herr_t 0291 * 0292 * \details The H5PTread_packets() reads \p nrecords packets starting at 0293 * packet number \p start from a packet table specified by 0294 * \p table_id. \p data is a buffer into which the data should 0295 * be read. 0296 * 0297 * For a packet table holding variable-length records, the data 0298 * returned in the buffer will be in form of #hvl_t structs, 0299 * each containing the length of the data and a pointer to it in 0300 * memory. The memory used by this data must be freed using 0301 * H5PTfree_vlen_buff(). 0302 * 0303 */ 0304 H5_HLDLL herr_t H5PTread_packets(hid_t table_id, hsize_t start, size_t nrecords, void *data); 0305 0306 /*------------------------------------------------------------------------- 0307 * Inquiry functions 0308 *------------------------------------------------------------------------- 0309 */ 0310 0311 /** 0312 * -------------------------------------------------------------------------- 0313 * \ingroup H5PT 0314 * 0315 * \brief Returns the number of packets in a packet table. 0316 * 0317 * \param[in] table_id Identifier of packet table to query 0318 * \param[out] nrecords Number of packets in packet table 0319 * 0320 * \return \herr_t 0321 * 0322 * \details The H5PTget_num_packets() returns by reference the number 0323 * of packets in a packet table specified by \p table_id. 0324 * 0325 */ 0326 H5_HLDLL herr_t H5PTget_num_packets(hid_t table_id, hsize_t *nrecords); 0327 0328 /** 0329 * -------------------------------------------------------------------------- 0330 * \ingroup H5PT 0331 * 0332 * \brief Determines whether an identifier points to a packet table. 0333 * 0334 * \param[in] table_id Identifier to query 0335 * 0336 * \return Returns a non-negative value if \p table_id is 0337 * a valid packet table, otherwise returns a negative value. 0338 * 0339 * \details The H5PTis_valid() returns a non-negative value if 0340 * \p table_id corresponds to an open packet table, 0341 * and returns a negative value otherwise. 0342 * 0343 */ 0344 H5_HLDLL herr_t H5PTis_valid(hid_t table_id); 0345 0346 /** 0347 * -------------------------------------------------------------------------- 0348 * \ingroup H5PT 0349 * 0350 * \brief Determines whether a packet table contains 0351 * variable-length or fixed-length packets. 0352 * 0353 * \param[in] table_id Packet table to query 0354 * 0355 * \return Returns 1 for a variable-length packet table, 0356 * 0 for fixed-length, or a negative value on error. 0357 * 0358 * \details The H5PTis_varlen() returns 1 (TRUE) if \p table_id is 0359 * a packet table containing variable-length records. 0360 * It returns 0 (FALSE) if \p table_id is a packet table 0361 * containing fixed-length records. If \p table_id is not a 0362 * packet table, a negative value is returned. 0363 * 0364 * \version 1.10.0 and 1.8.17 Function re-introduced. 0365 * Function had been removed in 1.8.3. 0366 * 0367 */ 0368 H5_HLDLL herr_t H5PTis_varlen(hid_t table_id); 0369 0370 /*------------------------------------------------------------------------- 0371 * 0372 * Accessor functions 0373 * 0374 *------------------------------------------------------------------------- 0375 */ 0376 0377 /** 0378 * -------------------------------------------------------------------------- 0379 * \ingroup H5PT 0380 * 0381 * \brief Returns the backend dataset of this packet table. 0382 * 0383 * \param[in] table_id Identifier of the packet table 0384 * 0385 * \return Returns a dataset identifier or H5I_INVALID_HID on error. 0386 * 0387 * \details The H5PTget_dataset() returns the identifier of the dataset 0388 * storing the packet table \p table_id. This dataset identifier 0389 * will be closed by H5PTclose(). 0390 * 0391 * \since 1.10.0 and 1.8.17 0392 * 0393 */ 0394 H5_HLDLL hid_t H5PTget_dataset(hid_t table_id); 0395 0396 /** 0397 * -------------------------------------------------------------------------- 0398 * \ingroup H5PT 0399 * 0400 * \brief Returns the backend datatype of this packet table. 0401 * 0402 * \param[in] table_id Identifier of the packet table 0403 * 0404 * \return Returns a datatype identifier or H5I_INVALID_HID on error. 0405 * 0406 * \details The H5PTget_type() returns the identifier of the datatype 0407 * used by the packet table \p table_id. This datatype 0408 * identifier will be closed by H5PTclose(). 0409 * 0410 * \since 1.10.0 and 1.8.17 0411 * 0412 */ 0413 H5_HLDLL hid_t H5PTget_type(hid_t table_id); 0414 0415 /*------------------------------------------------------------------------- 0416 * 0417 * Packet Table "current index" functions 0418 * 0419 *------------------------------------------------------------------------- 0420 */ 0421 0422 /** 0423 * -------------------------------------------------------------------------- 0424 * \ingroup H5PT 0425 * 0426 * \brief Resets a packet table's index to the first packet. 0427 * 0428 * \param[in] table_id Identifier of packet table whose index 0429 * should be initialized. 0430 * 0431 * \return \herr_t 0432 * 0433 * \details Each packet table keeps an index of the "current" packet 0434 * so that \c get_next can iterate through the packets in order. 0435 * H5PTcreate_index() initializes a packet table's index, and 0436 * should be called before using \c get_next. The index must be 0437 * initialized every time a packet table is created or opened; 0438 * this information is lost when the packet table is closed. 0439 * 0440 */ 0441 H5_HLDLL herr_t H5PTcreate_index(hid_t table_id); 0442 0443 /** 0444 * -------------------------------------------------------------------------- 0445 * \ingroup H5PT 0446 * 0447 * \brief Sets a packet table's index. 0448 * 0449 * \param[in] table_id Identifier of packet table whose index is to be set 0450 * \param[in] pt_index The packet to which the index should point 0451 * 0452 * \return \herr_t 0453 * 0454 * \details Each packet table keeps an index of the "current" packet 0455 * so that \c get_next can iterate through the packets in order. 0456 * H5PTset_index() sets this index to point to a user-specified 0457 * packet (the packets are zero-indexed). 0458 * 0459 */ 0460 H5_HLDLL herr_t H5PTset_index(hid_t table_id, hsize_t pt_index); 0461 0462 /** 0463 * -------------------------------------------------------------------------- 0464 * \ingroup H5PT 0465 * 0466 * \brief Gets the current record index for a packet table. 0467 * 0468 * \param[in] table_id Table identifier 0469 * \param[out] pt_index Current record index 0470 * 0471 * \return \herr_t 0472 * 0473 * \details The H5PTget_index() returns the current record index 0474 * \p pt_index for the table identified by \p table_id. 0475 * 0476 * \since 1.8.0 0477 * 0478 */ 0479 H5_HLDLL herr_t H5PTget_index(hid_t table_id, hsize_t *pt_index); 0480 0481 /*------------------------------------------------------------------------- 0482 * 0483 * Memory Management functions 0484 * 0485 *------------------------------------------------------------------------- 0486 */ 0487 0488 /** 0489 * -------------------------------------------------------------------------- 0490 * \ingroup H5PT 0491 * 0492 * \brief Releases memory allocated in the process of reading 0493 * variable-length packets. 0494 * 0495 * \param[in] table_id Packet table whose memory should be freed. 0496 * \param[in] bufflen Size of \p buff 0497 * \param[in] buff Buffer that was used to read in variable-length 0498 * packets 0499 * 0500 * \return \herr_t 0501 * 0502 * \details When variable-length packets are read, memory is automatically 0503 * allocated to hold them, and must be freed. H5PTfree_vlen_buff() 0504 * frees this memory, and should be called whenever packets are 0505 * read from a variable-length packet table. 0506 * 0507 * \version 1.10.0 and 1.8.17 Function re-introduced. 0508 * Function had been removed in 1.8.3. 0509 * 0510 */ 0511 H5_HLDLL herr_t H5PTfree_vlen_buff(hid_t table_id, size_t bufflen, void *buff); 0512 0513 #ifdef __cplusplus 0514 } 0515 #endif 0516 0517 #endif
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|