EIC code displayed by LXR |
|
|
|
|||
File indexing completed on 2025-04-18 09:16:05
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 /* 0014 * This file contains public declarations for the H5R module. 0015 */ 0016 #ifndef H5Rpublic_H 0017 #define H5Rpublic_H 0018 0019 #include "H5public.h" /* Generic Functions */ 0020 #include "H5Gpublic.h" /* Groups */ 0021 #include "H5Ipublic.h" /* Identifiers */ 0022 #include "H5Opublic.h" /* Object Headers */ 0023 0024 /*****************/ 0025 /* Public Macros */ 0026 /*****************/ 0027 0028 /* Deprecated reference buffer sizes that are kept for backward compatibility */ 0029 #define H5R_OBJ_REF_BUF_SIZE sizeof(haddr_t) 0030 #define H5R_DSET_REG_REF_BUF_SIZE (sizeof(haddr_t) + 4) 0031 0032 /** 0033 * Default reference buffer size. 0034 * 0035 * \internal Note! Be careful with the sizes of the references because they 0036 * should really depend on the run-time values in the file. 0037 */ 0038 #define H5R_REF_BUF_SIZE (64) 0039 0040 /*******************/ 0041 /* Public Typedefs */ 0042 /*******************/ 0043 0044 //! <!-- [H5R_type_t_snip] --> 0045 /** 0046 * Reference types allowed. 0047 * 0048 * \internal DO NOT CHANGE THE ORDER or VALUES as reference type values are 0049 * encoded into the datatype message header. 0050 */ 0051 typedef enum { 0052 H5R_BADTYPE = (-1), /**< Invalid reference type */ 0053 H5R_OBJECT1 = 0, /**< Backward compatibility (object) */ 0054 H5R_DATASET_REGION1 = 1, /**< Backward compatibility (region) */ 0055 H5R_OBJECT2 = 2, /**< Object reference */ 0056 H5R_DATASET_REGION2 = 3, /**< Region reference */ 0057 H5R_ATTR = 4, /**< Attribute Reference */ 0058 H5R_MAXTYPE = 5 /**< Highest type (invalid) */ 0059 } H5R_type_t; 0060 //! <!-- [H5R_type_t_snip] --> 0061 0062 /* Deprecated types are kept for backward compatibility with previous versions */ 0063 0064 //! <!-- [hobj_ref_t_snip] --> 0065 /** 0066 * \deprecated Deprecated object reference type that is used with deprecated 0067 * reference APIs. 0068 * 0069 * \note This type can only be used with the "native" HDF5 VOL connector. 0070 */ 0071 typedef haddr_t hobj_ref_t; 0072 //! <!-- [hobj_ref_t_snip] --> 0073 0074 //! <!-- [hdset_reg_ref_t_snip] --> 0075 /** 0076 * Buffer to store heap ID and index 0077 * 0078 * This needs to be large enough to store largest #haddr_t in a worst case 0079 * machine (8 bytes currently) plus an int. 0080 * 0081 * \deprecated Dataset region reference type that is used with deprecated 0082 * reference APIs. 0083 * 0084 * \note This type can only be used with the "native" HDF5 VOL connector. 0085 */ 0086 typedef struct { 0087 uint8_t __data[H5R_DSET_REG_REF_BUF_SIZE]; 0088 } hdset_reg_ref_t; 0089 //! <!-- [hdset_reg_ref_t_snip] --> 0090 0091 //! <!-- [H5R_ref_t_snip] --> 0092 /** 0093 * Opaque reference type. The same reference type is used for object, 0094 * dataset region and attribute references. This is the type that 0095 * should always be used with the current reference API. 0096 */ 0097 typedef struct { 0098 union { 0099 uint8_t __data[H5R_REF_BUF_SIZE]; /**< opaque data */ 0100 int64_t align; /**< ensures alignment */ 0101 } u; 0102 } H5R_ref_t; 0103 //! <!-- [H5R_ref_t_snip] --> 0104 0105 /********************/ 0106 /* Public Variables */ 0107 /********************/ 0108 0109 /*********************/ 0110 /* Public Prototypes */ 0111 /*********************/ 0112 0113 #ifdef __cplusplus 0114 extern "C" { 0115 #endif 0116 0117 /* Constructors */ 0118 /** 0119 * -------------------------------------------------------------------------- 0120 * \ingroup H5R 0121 * 0122 * \brief Creates an object reference 0123 * 0124 * \fgdta_loc_id 0125 * \param[in] name Name of object 0126 * \oapl_id 0127 * \param[out] ref_ptr Pointer to reference 0128 * 0129 * \return \herr_t 0130 * 0131 * \details H5Rcreate_object() creates a reference pointing to the 0132 * object named \p name located at \p loc_id. The parameters \p 0133 * loc_id and \p name are used to locate the object. 0134 * 0135 * The parameter \p oapl_id is an object access property list 0136 * identifier for the referenced object. The access property list 0137 * must be of the same type as the object being referenced, that is 0138 * a group, dataset or committed datatype property list. 0139 * 0140 * \ref H5R_ref_t is defined in H5Rpublic.h as: 0141 * \snippet this H5R_ref_t_snip 0142 * 0143 * The function returns a \p ref_ptr pointer, which must be released 0144 * using H5Rdestroy() to avoid resource leaks and possible HDF5 0145 * library shutdown issues. 0146 * 0147 * \since 1.12.0 0148 * 0149 */ 0150 H5_DLL herr_t H5Rcreate_object(hid_t loc_id, const char *name, hid_t oapl_id, H5R_ref_t *ref_ptr); 0151 0152 /** 0153 * -------------------------------------------------------------------------- 0154 * \ingroup H5R 0155 * 0156 * \brief Creates a region reference 0157 * 0158 * \fgdta_loc_id 0159 * \param[in] name Name of object 0160 * \space_id 0161 * \oapl_id 0162 * \param[out] ref_ptr Pointer to reference 0163 * 0164 * \return \herr_t 0165 * 0166 * \details H5Rcreate_region() creates the reference, \p ref_ptr, 0167 * pointing to the region represented by \p space_id within the 0168 * object named name located at \p loc_id. 0169 * 0170 * The parameters \p loc_id and \p name are used to locate the 0171 * object. The parameter \p space_id identifies the dataset region 0172 * that a dataset region reference points to. 0173 * 0174 * The parameter \p oapl_id is an object access property list 0175 * identifier for the referenced object. The access property list 0176 * must be of the same type as the object being referenced, that is 0177 * a dataset property list in this case. 0178 * 0179 * \ref H5R_ref_t is defined in H5Rpublic.h as: 0180 * \snippet this H5R_ref_t_snip 0181 * 0182 * The function returns a \p ref_ptr pointer, which must be released 0183 * using H5Rdestroy() to avoid resource leaks and possible HDF5 0184 * library shutdown issues. 0185 * 0186 * \since 1.12.0 0187 * 0188 */ 0189 H5_DLL herr_t H5Rcreate_region(hid_t loc_id, const char *name, hid_t space_id, hid_t oapl_id, 0190 H5R_ref_t *ref_ptr); 0191 0192 /** 0193 * -------------------------------------------------------------------------- 0194 * \ingroup H5R 0195 * 0196 * \brief Creates an attribute reference 0197 * 0198 * \fgdta_loc_id 0199 * \param[in] name Name of object 0200 * \param[in] attr_name Name of attribute 0201 * \oapl_id 0202 * \param[out] ref_ptr Pointer to reference 0203 * 0204 * \return \herr_t 0205 * 0206 * \details H5Rcreate_attr() creates the reference, \p ref_ptr, pointing 0207 * to the attribute named \p attr_name and attached to the object 0208 * named \p name located at \p loc_id. 0209 * 0210 * The parameters \p loc_id and \p name locate the object. The 0211 * parameter \p attr_name specifies the attribute within the object. 0212 * 0213 * The parameter \p oapl_id is an object access property list 0214 * identifier for the object that the referenced attribute is 0215 * attached to. The access property list must be of the same type 0216 * as that object, that is a group, dataset or committed datatype 0217 * property list. 0218 * 0219 * \ref H5R_ref_t is defined in H5Rpublic.h as: 0220 * \snippet this H5R_ref_t_snip 0221 * 0222 * The function returns a \p ref_ptr pointer, which must be released 0223 * using H5Rdestroy() to avoid resource leaks and possible HDF5 0224 * library shutdown issues. 0225 * 0226 * \since 1.12.0 0227 * 0228 */ 0229 H5_DLL herr_t H5Rcreate_attr(hid_t loc_id, const char *name, const char *attr_name, hid_t oapl_id, 0230 H5R_ref_t *ref_ptr); 0231 0232 /** 0233 * -------------------------------------------------------------------------- 0234 * \ingroup H5R 0235 * 0236 * \brief Closes a reference 0237 * 0238 * \param[in] ref_ptr Pointer to reference 0239 * 0240 * \return \herr_t 0241 * 0242 * \details Given a reference, \p ref_ptr, to an object, region or attribute 0243 * attached to an object, H5Rdestroy() releases allocated resources 0244 * from a previous create call. 0245 * 0246 * \ref H5R_ref_t is defined in H5Rpublic.h as: 0247 * \snippet this H5R_ref_t_snip 0248 * 0249 * \since 1.12.0 0250 * 0251 */ 0252 H5_DLL herr_t H5Rdestroy(H5R_ref_t *ref_ptr); 0253 0254 /* Info */ 0255 0256 /** 0257 * -------------------------------------------------------------------------- 0258 * \ingroup H5R 0259 * 0260 * \brief Retrieves the type of a reference 0261 * 0262 * \param[in] ref_ptr Pointer to reference 0263 * 0264 * \return Returns a valid reference type if successful; otherwise returns #H5R_BADTYPE . 0265 * 0266 * \details Given a reference, \p ref_ptr, H5Rget_type() returns the 0267 * type of the reference. 0268 * 0269 * Valid returned reference types are: 0270 * \snippet this H5R_type_t_snip 0271 * 0272 * Note that #H5R_OBJECT1 and #H5R_DATASET_REGION1 can never be 0273 * associated with an \ref H5R_ref_t reference and can, therefore, never be 0274 * returned through that function. 0275 * 0276 * \ref H5R_ref_t is defined in H5Rpublic.h as: 0277 * \snippet this H5R_ref_t_snip 0278 * 0279 * \since 1.12.0 0280 * 0281 */ 0282 H5_DLL H5R_type_t H5Rget_type(const H5R_ref_t *ref_ptr); 0283 0284 /** 0285 * -------------------------------------------------------------------------- 0286 * \ingroup H5R 0287 * 0288 * \brief Determines whether two references are equal 0289 * 0290 * \param[in] ref1_ptr Pointer to reference to compare 0291 * \param[in] ref2_ptr Pointer to reference to compare 0292 * 0293 * \return Returns a positive value if the references are equal. Returns 0294 * 0 if the references are not equal. Returns a negative value when the 0295 * function fails. 0296 * 0297 * \details H5Requal() determines whether two references point to the 0298 * same object, region or attribute. 0299 * 0300 * \ref H5R_ref_t is defined in H5Rpublic.h as: 0301 * \snippet this H5R_ref_t_snip 0302 * 0303 * \since 1.12.0 0304 * 0305 */ 0306 H5_DLL htri_t H5Requal(const H5R_ref_t *ref1_ptr, const H5R_ref_t *ref2_ptr); 0307 0308 /** 0309 * -------------------------------------------------------------------------- 0310 * \ingroup H5R 0311 * 0312 * \brief Copies an existing reference 0313 * 0314 * \param[in] src_ref_ptr Pointer to reference to copy 0315 * \param[out] dst_ref_ptr Pointer to output reference 0316 * 0317 * \return \herr_t 0318 * 0319 * \details H5Rcopy() creates a copy of an existing reference. 0320 * \p src_ref_ptr points to the reference to copy, and \p dst_ref_ptr is the 0321 * pointer to the destination reference. 0322 * 0323 * The function returns a \p dst_ref_ptr pointer, which must be released 0324 * using H5Rdestroy() to avoid resource leaks and possible HDF5 0325 * library shutdown issues. 0326 * 0327 * \since 1.12.0 0328 * 0329 */ 0330 H5_DLL herr_t H5Rcopy(const H5R_ref_t *src_ref_ptr, H5R_ref_t *dst_ref_ptr); 0331 0332 /* Dereference */ 0333 0334 /** 0335 * -------------------------------------------------------------------------- 0336 * \ingroup H5R 0337 * 0338 * \brief Opens the HDF5 object referenced 0339 * 0340 * \param[in] ref_ptr Pointer to reference to open 0341 * \rapl_id 0342 * \oapl_id 0343 * 0344 * \return \hid_t{object} 0345 * 0346 * \details Given a reference, \p ref_ptr, to an object, a region in 0347 * an object, or an attribute attached to an object, H5Ropen_object() 0348 * opens that object and returns an identifier. 0349 * 0350 * The parameter \p oapl_id is an object access property list 0351 * identifier for the referenced object. The access property list 0352 * must be of the same type as the object being referenced, that is 0353 * a group or dataset property list. 0354 * 0355 * \ref H5R_ref_t is defined in H5Rpublic.h as: 0356 * \snippet this H5R_ref_t_snip 0357 * 0358 * The object opened with this function should be closed when it 0359 * is no longer needed so that resource leaks will not develop. Use 0360 * the appropriate close function, such as H5Oclose() or H5Dclose() 0361 * for datasets. 0362 * 0363 * \since 1.12.0 0364 * 0365 */ 0366 H5_DLL hid_t H5Ropen_object(H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id); 0367 0368 /** 0369 * -------------------------------------------------------------------------- 0370 * \ingroup ASYNC 0371 * \async_variant_of{H5Ropen_object} 0372 * 0373 * \since 1.14.0 0374 * 0375 */ 0376 #ifndef H5_DOXYGEN 0377 H5_DLL hid_t H5Ropen_object_async(const char *app_file, const char *app_func, unsigned app_line, 0378 H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id, hid_t es_id); 0379 #else 0380 H5_DLL hid_t H5Ropen_object_async(unsigned app_line, H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id, 0381 hid_t es_id); 0382 #endif 0383 0384 /** 0385 * -------------------------------------------------------------------------- 0386 * \ingroup H5R 0387 * 0388 * \brief Sets up a dataspace and selection as specified by a region reference. 0389 * 0390 * \param[in] ref_ptr Pointer to reference to open 0391 * \rapl_id 0392 * \oapl_id 0393 * 0394 * \return \hid_t{dataspace} 0395 * 0396 * \details H5Ropen_region() creates a copy of the dataspace of the 0397 * dataset pointed to by a region reference, \p ref_ptr, and defines 0398 * a selection matching the selection pointed to by \p ref_ptr within 0399 * the dataspace copy. 0400 * 0401 * The parameter \p rapl id is a reference access property list 0402 * identifier for the reference. The access property list can 0403 * be used to access external files that the reference points to 0404 * (through a file access property list). 0405 * 0406 * The parameter \p oapl id is an object access property list 0407 * identifier for the referenced object. The access property list 0408 * must be of the same type as the object being referenced, that is 0409 * a dataset property list in that case. 0410 * 0411 * Use H5Sclose() to release the dataspace identifier returned by 0412 * this function when the identifier is no longer needed. 0413 * 0414 * \since 1.12.0 0415 * 0416 */ 0417 H5_DLL hid_t H5Ropen_region(H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id); 0418 0419 /** 0420 * -------------------------------------------------------------------------- 0421 * \ingroup ASYNC 0422 * \async_variant_of{H5Ropen_region} 0423 * 0424 * \since 1.14.0 0425 * 0426 */ 0427 #ifndef H5_DOXYGEN 0428 H5_DLL hid_t H5Ropen_region_async(const char *app_file, const char *app_func, unsigned app_line, 0429 H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id, hid_t es_id); 0430 #else 0431 H5_DLL hid_t H5Ropen_region_async(H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id, hid_t es_id); 0432 #endif 0433 0434 /** 0435 * -------------------------------------------------------------------------- 0436 * \ingroup H5R 0437 * 0438 * \brief Opens the HDF5 attribute referenced 0439 * 0440 * \param[in] ref_ptr Pointer to reference to open 0441 * \rapl_id 0442 * \aapl_id 0443 * 0444 * \return \hid_t{attribute} 0445 * 0446 * \details Given a reference, \p ref_ptr, to an attribute attached to 0447 * an object, H5Ropen_attr() opens the attribute attached to that 0448 * object and returns an identifier. 0449 * 0450 * The parameter \p rapl id is a reference access property list 0451 * identifier for the reference. The access property list can 0452 * be used to access external files that the reference points to 0453 * (through a file access property list). 0454 * 0455 * The parameter \p aapl_id is an attribute access property list 0456 * identifier for the referenced attribute. 0457 * 0458 * The attribute opened with this function should be closed with 0459 * H5Aclose() when it is no longer needed. 0460 * 0461 * \since 1.12.0 0462 * 0463 */ 0464 H5_DLL hid_t H5Ropen_attr(H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t aapl_id); 0465 0466 /** 0467 * -------------------------------------------------------------------------- 0468 * \ingroup ASYNC 0469 * \async_variant_of{H5Ropen_attr} 0470 * 0471 * \since 1.14.0 0472 */ 0473 #ifndef H5_DOXYGEN 0474 H5_DLL hid_t H5Ropen_attr_async(const char *app_file, const char *app_func, unsigned app_line, 0475 H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t aapl_id, hid_t es_id); 0476 #else 0477 H5_DLL hid_t H5Ropen_attr_async(H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t aapl_id, hid_t es_id); 0478 #endif 0479 0480 /* Get type */ 0481 0482 /** 0483 * -------------------------------------------------------------------------- 0484 * \ingroup H5R 0485 * 0486 * \brief Retrieves the type of object that an object reference points to 0487 * 0488 * \param[in] ref_ptr Pointer to reference to query 0489 * \rapl_id 0490 * \param[out] obj_type Type of referenced object 0491 * 0492 * \return \herr_t 0493 * 0494 * \details Given a reference, \p ref_ptr, H5Rget_obj_type3() retrieves 0495 * the type of the referenced object in \p obj_type. 0496 * 0497 * The parameter \p rapl id is a reference access property list 0498 * identifier for the reference. The access property list can 0499 * be used to access external files that the reference points to 0500 * (through a file access property list). 0501 * 0502 * Upon success, the function returns in \p obj_type the type of 0503 * the object that the reference points to. Valid values for this 0504 * referenced object type are as followed (defined in H5Opublic.h): 0505 * \snippet H5Opublic.h H5O_type_t_snip 0506 * 0507 * \since 1.12.0 0508 * 0509 */ 0510 H5_DLL herr_t H5Rget_obj_type3(H5R_ref_t *ref_ptr, hid_t rapl_id, H5O_type_t *obj_type); 0511 0512 /* Get name */ 0513 0514 /** 0515 * -------------------------------------------------------------------------- 0516 * \ingroup H5R 0517 * 0518 * \brief Retrieves the file name for a referenced object 0519 * 0520 * \param[in] ref_ptr Pointer to reference to query 0521 * \param[in,out] name Buffer to place the file name of the reference 0522 * \param[in] size Size of the \p name buffer. When the size is passed in, 0523 * the \c NULL terminator needs to be included. 0524 * 0525 * \return Returns the length of the name if successful, otherwise, a negative value. 0526 * 0527 * \details H5Rget_file_name() retrieves the file name for the object, 0528 * region or attribute reference pointed to by \p ref_ptr. 0529 * 0530 * \details_namelen{file,H5Rget_file_name} 0531 * 0532 * \since 1.12.0 0533 * 0534 */ 0535 H5_DLL ssize_t H5Rget_file_name(const H5R_ref_t *ref_ptr, char *name, size_t size); 0536 0537 /** 0538 * -------------------------------------------------------------------------- 0539 * \ingroup H5R 0540 * 0541 * \brief Retrieves the object name for a referenced object 0542 * 0543 * \param[in] ref_ptr Pointer to reference to query 0544 * \rapl_id 0545 * \param[in,out] name Buffer to place the object name of the reference 0546 * \param[in] size Size of the \p name buffer. When the size is passed in, 0547 * the \c NULL terminator needs to be included. 0548 * 0549 * \return Returns the length of the name if successful, returning 0550 * 0 (zero) if no name is associated with the identifier. Otherwise 0551 * returns a negative value. 0552 * 0553 * \details H5Rget_obj_name() retrieves the object name for the object, 0554 * region or attribute reference pointed to by \p ref_ptr. 0555 * 0556 * The parameter \p rapl_id is a reference access property list 0557 * identifier for the reference. The access property list can 0558 * be used to access external files that the reference points to 0559 * (through a file access property list). 0560 * 0561 * \details_namelen{object,H5Rget_obj_name} 0562 * 0563 * If \p ref_ptr is an object reference, \p name will be returned with 0564 * a name for the referenced object. If \p ref_ptr is a dataset region 0565 * reference, \p name will contain a name for the object containing 0566 * the referenced region. If \p ref_ptr is an attribute reference, \p 0567 * name will contain a name for the object the attribute is attached 0568 * to. Note that an object in an HDF5 file may have multiple paths 0569 * if there are multiple links pointing to it. This function may 0570 * return any one of these paths. 0571 * 0572 * \since 1.12.0 0573 * 0574 */ 0575 H5_DLL ssize_t H5Rget_obj_name(H5R_ref_t *ref_ptr, hid_t rapl_id, char *name, size_t size); 0576 0577 /** 0578 * -------------------------------------------------------------------------- 0579 * \ingroup H5R 0580 * 0581 * \brief Retrieves the attribute name for a referenced object 0582 * 0583 * \param[in] ref_ptr Pointer to reference to query 0584 * \param[in,out] name Buffer to place the attribute name of the reference 0585 * \param[in] size Size of the \p name buffer 0586 * 0587 * \return Returns the length of the name if successful, otherwise, a negative value. 0588 * 0589 * \details H5Rget_attr_name() retrieves the attribute name for the 0590 * attribute reference pointed to by \p ref_ptr. 0591 * 0592 * \details_namelen{attribute,H5Rget_attr_name} 0593 * 0594 * \since 1.12.0 0595 * 0596 */ 0597 H5_DLL ssize_t H5Rget_attr_name(const H5R_ref_t *ref_ptr, char *name, size_t size); 0598 0599 /// \cond DEV 0600 /* API Wrappers for async routines */ 0601 /* (Must be defined _after_ the function prototype) */ 0602 /* (And must only defined when included in application code, not the library) */ 0603 #ifndef H5R_MODULE 0604 #define H5Ropen_object_async(...) H5Ropen_object_async(__FILE__, __func__, __LINE__, __VA_ARGS__) 0605 #define H5Ropen_region_async(...) H5Ropen_region_async(__FILE__, __func__, __LINE__, __VA_ARGS__) 0606 #define H5Ropen_attr_async(...) H5Ropen_attr_async(__FILE__, __func__, __LINE__, __VA_ARGS__) 0607 0608 /* Define "wrapper" versions of function calls, to allow compile-time values to 0609 * be passed in by language wrapper or library layer on top of HDF5. */ 0610 #define H5Ropen_object_async_wrap H5_NO_EXPAND(H5Ropen_object_async) 0611 #define H5Ropen_region_async_wrap H5_NO_EXPAND(H5Ropen_region_async) 0612 #define H5Ropen_attr_async_wrap H5_NO_EXPAND(H5Ropen_attr_async) 0613 #endif /* H5R_MODULE */ 0614 /// \endcond 0615 0616 /* Symbols defined for compatibility with previous versions of the HDF5 API. 0617 * 0618 * Use of these symbols is or will be deprecated. 0619 */ 0620 0621 /* Macros */ 0622 0623 /* Versions for compatibility */ 0624 #define H5R_OBJECT H5R_OBJECT1 0625 #define H5R_DATASET_REGION H5R_DATASET_REGION1 0626 0627 /* Function prototypes */ 0628 #ifndef H5_NO_DEPRECATED_SYMBOLS 0629 0630 /** 0631 * -------------------------------------------------------------------------- 0632 * \ingroup H5R 0633 * 0634 * \brief Retrieves the type of object that an object reference points to 0635 * 0636 * \param[in] id The dataset containing the reference object or the group 0637 * containing that dataset 0638 * \param[in] ref_type Type of reference to query 0639 * \param[in] ref Reference to query 0640 * 0641 * \return Returns a valid object type if successful; otherwise returns a 0642 * negative value (#H5G_UNKNOWN). 0643 * 0644 * \deprecated This function has been renamed from H5Rget_obj_type() and is 0645 * deprecated in favor of the macro H5Rget_obj_type() or the 0646 * function H5Rget_obj_type2(). 0647 * 0648 * \details Given an object reference, \p ref, H5Rget_obj_type1() returns the 0649 * type of the referenced object. 0650 * 0651 * A \Emph{reference type} is the type of reference, either an object 0652 * reference or a dataset region reference. An \Emph{object reference} 0653 * points to an HDF5 object, while a \Emph{dataset region reference} 0654 * points to a defined region within a dataset. 0655 * 0656 * The \Emph{referenced object} is the object the reference points 0657 * to. The \Emph{referenced object type}, or the type of the referenced 0658 * object, is the type of the object that the reference points to. 0659 * 0660 * The location identifier, \p id, is the identifier for either the 0661 * dataset containing the object reference or the group containing that 0662 * dataset. 0663 * 0664 * Valid reference types, to pass in as \p ref_type, include the 0665 * following: 0666 * \snippet this H5R_type_t_snip 0667 * 0668 * If the application does not already know the object reference type, 0669 * that can be determined with three preliminary calls: 0670 * 0671 * \li Call H5Dget_type() on the dataset containing the reference to 0672 * get a datatype identifier for the dataset's datatype. 0673 * \li Using that datatype identifier, H5Tget_class() returns a datatype 0674 * class.\n If the datatype class is #H5T_REFERENCE, H5Tequal() can 0675 * then be used to determine whether the reference's datatype is 0676 * #H5T_STD_REF_OBJ or #H5T_STD_REF_DSETREG: 0677 * - If the datatype is #H5T_STD_REF_OBJ, the reference object type 0678 * is #H5R_OBJECT. 0679 * - If the datatype is #H5T_STD_REF_DSETREG, the reference object 0680 * type is #H5R_DATASET_REGION. 0681 * 0682 * When the function completes successfully, it returns one of the 0683 * following valid object type values (defined in H5Gpublic.h): 0684 * \snippet H5Gpublic.h H5G_obj_t_snip 0685 * 0686 * \version 1.8.0 Function H5Rget_obj_type() renamed to H5Rget_obj_type1() and 0687 * deprecated in this release. 0688 * 0689 * \since 1.2.0 0690 * 0691 */ 0692 H5_DLL H5G_obj_t H5Rget_obj_type1(hid_t id, H5R_type_t ref_type, const void *ref); 0693 0694 /** 0695 * -------------------------------------------------------------------------- 0696 * \ingroup H5R 0697 * 0698 * \brief Opens the HDF5 object referenced 0699 * 0700 * \obj_id 0701 * \param[in] ref_type The reference type of \p ref 0702 * \param[in] ref Reference to open 0703 * 0704 * \return Returns identifier of referenced object if successful; otherwise 0705 * returns a negative value. 0706 * 0707 * \deprecated This function has been renamed from H5Rdereference() and is 0708 * deprecated in favor of the macro H5Rdereference() or the function 0709 * H5Rdereference2(). 0710 * 0711 * \details Given a reference, \p ref, to an object or a region in an object, 0712 * H5Rdereference1() opens that object and returns an identifier. 0713 * 0714 * The parameter \p obj_id must be a valid identifier for an object in 0715 * the HDF5 file containing the referenced object, including the file 0716 * identifier. 0717 * 0718 * The parameter \p ref_type specifies the reference type of the 0719 * reference \p ref. \p ref_type may contain either of the following 0720 * values: 0721 * - #H5R_OBJECT 0722 * - #H5R_DATASET_REGION 0723 * 0724 * The object opened with this function should be closed when it is no 0725 * longer needed so that resource leaks will not develop. Use the 0726 * appropriate close function, such as H5Oclose() or H5Dclose() for 0727 * datasets. 0728 * 0729 * \version 1.10.0 Function H5Rdereference() renamed to H5Rdereference1() and 0730 * deprecated in this release. 0731 * \since 1.0.0 0732 * 0733 */ 0734 H5_DLL hid_t H5Rdereference1(hid_t obj_id, H5R_type_t ref_type, const void *ref); 0735 0736 #endif /* H5_NO_DEPRECATED_SYMBOLS */ 0737 0738 /** 0739 * -------------------------------------------------------------------------- 0740 * \ingroup H5R 0741 * 0742 * \brief Creates a reference 0743 * 0744 * \param[out] ref Reference created by the function call 0745 * \param[in] loc_id Location identifier used to locate the object being pointed to 0746 * \param[in] name Name of object at location \p loc_id 0747 * \param[in] ref_type Type of reference 0748 * \param[in] space_id Dataspace identifier with selection. Used only for 0749 * dataset region references; pass as -1 if reference is 0750 * an object reference, i.e., of type #H5R_OBJECT 0751 * 0752 * \return \herr_t 0753 * 0754 * \deprecated As of HDF5-1.12, this function has been deprecated in favor of 0755 * H5Rcreate_object(), H5Rcreate_region() and H5Rcreate_attr(). 0756 * 0757 * \details H5Rcreate() creates the reference, \p ref, of the type specified in 0758 * \p ref_type, pointing to the object \p name located at \p loc_id. 0759 * 0760 * The HDF5 library maps the void type specified above for \p ref to 0761 * the type specified in \p ref_type, which will be one of the following: 0762 * \snippet this H5R_type_t_snip 0763 * 0764 * The parameters \p loc_id and \p name are used to locate the object. 0765 * 0766 * The parameter \p space_id identifies the dataset region that a 0767 * dataset region reference points to. This parameter is used only with 0768 * dataset region references and should be set to -1 if the reference 0769 * is an object reference, #H5R_OBJECT. 0770 * 0771 * \since 1.0.0 0772 */ 0773 H5_DLL herr_t H5Rcreate(void *ref, hid_t loc_id, const char *name, H5R_type_t ref_type, hid_t space_id); 0774 0775 /** 0776 * -------------------------------------------------------------------------- 0777 * \ingroup H5R 0778 * 0779 * \brief Retrieves the type of object that an object reference points to 0780 * 0781 * \param[in] id The dataset containing the reference object or the group 0782 * containing that dataset 0783 * \param[in] ref_type Type of reference to query 0784 * \param[in] ref Reference to query 0785 * \param[out] obj_type Type of referenced object 0786 * 0787 * \return \herr_t 0788 * 0789 * \details Given an object reference, \p ref, H5Rget_obj_type2() returns the 0790 * type of the referenced object in \p obj_type. 0791 * 0792 * A \Emph{reference type} is the type of reference, either an object 0793 * reference or a dataset region reference. An \Emph{object reference} 0794 * points to an HDF5 object while a \Emph{dataset region reference} 0795 * points to a defined region within a dataset. 0796 * 0797 * The \Emph{referenced object} is the object the reference points 0798 * to. The \Emph{referenced object type}, or the type of the referenced 0799 * object, is the type of the object that the reference points to. 0800 * 0801 * The location identifier, \p id, is the identifier for either the 0802 * dataset containing the object reference or the group containing that 0803 * dataset. 0804 * 0805 * Valid reference types, to pass in as \p ref_type, include the 0806 * following: 0807 * \snippet this H5R_type_t_snip 0808 * 0809 * If the application does not already know the object reference type, 0810 * that can be determined with three preliminary calls: 0811 * 0812 * \li Call H5Dget_type() on the dataset containing the reference to 0813 * get a datatype identifier for the dataset's datatype. 0814 * \li Using that datatype identifier, H5Tget_class() returns a datatype 0815 * class.\n If the datatype class is #H5T_REFERENCE, H5Tequal() can 0816 * then be used to determine whether the reference's datatype is 0817 * #H5T_STD_REF_OBJ or #H5T_STD_REF_DSETREG: 0818 * - If the datatype is #H5T_STD_REF_OBJ, the reference object type 0819 * is #H5R_OBJECT. 0820 * - If the datatype is #H5T_STD_REF_DSETREG, the reference object 0821 * type is #H5R_DATASET_REGION. 0822 * 0823 * When the function completes successfully, it returns one of the 0824 * following valid object type values (defined in H5Opublic.h): 0825 * \snippet H5Opublic.h H5O_type_t_snip 0826 * 0827 * \since 1.8.0 0828 * 0829 */ 0830 H5_DLL herr_t H5Rget_obj_type2(hid_t id, H5R_type_t ref_type, const void *ref, H5O_type_t *obj_type); 0831 0832 /** 0833 * -------------------------------------------------------------------------- 0834 * \ingroup H5R 0835 * 0836 * \brief Opens the HDF5 object referenced 0837 * 0838 * \obj_id 0839 * \oapl_id 0840 * \param[in] ref_type The reference type of \p ref 0841 * \param[in] ref Reference to open 0842 * 0843 * \return Returns identifier of referenced object if successful; otherwise 0844 * returns a negative value. 0845 * 0846 * \deprecated As of HDF5-1.12, this function and H5Rdereference1() have been 0847 * deprecated in favor of H5Ropen_attr(), H5Ropen_object() 0848 * and H5Ropen_region(). 0849 * 0850 * \details Given a reference, \p ref, to an object or a region in an object, 0851 * H5Rdereference2() opens that object and returns an identifier. 0852 * 0853 * The parameter \p obj_id must be a valid identifier for the HDF5 file 0854 * containing the referenced object or for any object in that HDF5 0855 * file. 0856 * 0857 * The parameter \p oapl_id is an object access property list 0858 * identifier for the referenced object. The access property list must 0859 * be of the same type as the object being referenced, that is a group, 0860 * dataset, or datatype property list. 0861 * 0862 * The parameter \p ref_type specifies the reference type of the 0863 * reference \p ref. \p ref_type may contain either of the following 0864 * values: 0865 * - #H5R_OBJECT 0866 * - #H5R_DATASET_REGION 0867 * 0868 * The object opened with this function should be closed when it is no 0869 * longer needed so that resource leaks will not develop. Use the 0870 * appropriate close function, such as H5Oclose() or H5Dclose() for 0871 * datasets. 0872 * 0873 * \since 1.10.0 0874 * 0875 */ 0876 H5_DLL hid_t H5Rdereference2(hid_t obj_id, hid_t oapl_id, H5R_type_t ref_type, const void *ref); 0877 0878 /** 0879 * -------------------------------------------------------------------------- 0880 * \ingroup H5R 0881 * 0882 * \brief Sets up a dataspace and selection as specified by a region reference 0883 * 0884 * \param[in] dataset File identifier or identifier for any object in the file 0885 * containing the referenced region 0886 * \param[in] ref_type Reference type of \p ref, which must be #H5R_DATASET_REGION 0887 * \param[in] ref Region reference to open 0888 * 0889 * \return Returns a valid dataspace identifier if successful; otherwise returns 0890 * a negative value. 0891 * 0892 * \details H5Rget_region() creates a copy of the dataspace of the dataset 0893 * pointed to by a region reference, \p ref, and defines a selection 0894 * matching the selection pointed to by ref within the dataspace copy. 0895 * 0896 * \p dataset is used to identify the file containing the referenced 0897 * region; it can be a file identifier or an identifier for any object 0898 * in the file. 0899 * 0900 * The parameter \p ref_type specifies the reference type of \p ref and 0901 * must contain the value #H5R_DATASET_REGION. 0902 * 0903 * Use H5Sclose() to release the dataspace identifier returned by this 0904 * function when the identifier is no longer needed. 0905 * 0906 * \since 1.0.0 0907 * 0908 */ 0909 H5_DLL hid_t H5Rget_region(hid_t dataset, H5R_type_t ref_type, const void *ref); 0910 0911 /** 0912 * -------------------------------------------------------------------------- 0913 * \ingroup H5R 0914 * 0915 * \brief Retrieves a name for a referenced object 0916 * 0917 * \param[in] loc_id Identifier for the file containing the reference or for 0918 * any object in that file 0919 * \param[in] ref_type Type of reference 0920 * \param[in] ref An object or dataset region reference 0921 * \param[out] name A buffer to place the name of the referenced object or 0922 * dataset region. If \c NULL, then this call will return the 0923 * size in bytes of the name. 0924 * \param[in] size The size of the \p name buffer. When the size is passed in, 0925 * the \c NULL terminator needs to be included. 0926 * 0927 * \return Returns the length of the name if successful, returning 0 (zero) if 0928 * no name is associated with the identifier. Otherwise returns a 0929 * negative value. 0930 * 0931 * \deprecated As of HDF5-1.12, this function has been deprecated in favor of 0932 * H5Rget_file_name(), H5Rget_obj_name() and H5Rget_attr_name(). 0933 * 0934 * \details H5Rget_name() retrieves a name for the object identified by \p ref.\n 0935 * \p loc_id is used to identify the file containing the reference. It 0936 * can be the file identifier for the file containing the reference or 0937 * an identifier for any object in that file. 0938 * 0939 * \ref H5R_type_t is the reference type of \p ref. Valid values 0940 * include the following: 0941 * \snippet this H5R_type_t_snip 0942 * 0943 * \p ref is the reference for which the target object's name is 0944 * sought. 0945 * 0946 * If \p ref is an object reference, \p name will be returned with a 0947 * name for the referenced object. If \p ref is a dataset region 0948 * reference, \p name will contain a name for the object containing the 0949 * referenced region. 0950 * 0951 * \details_namelen{,H5Rget_name} 0952 * 0953 * \note An object in an HDF5 file may have multiple paths if multiple 0954 * links point to it. This function may return any one of these paths. 0955 * 0956 * \since 1.8.0 0957 */ 0958 H5_DLL ssize_t H5Rget_name(hid_t loc_id, H5R_type_t ref_type, const void *ref, char *name, size_t size); 0959 0960 #ifdef __cplusplus 0961 } 0962 #endif 0963 0964 #endif /* H5Rpublic_H */
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|