diff options
Diffstat (limited to 'src/H5Rpublic.h')
| -rw-r--r-- | src/H5Rpublic.h | 115 |
1 files changed, 83 insertions, 32 deletions
diff --git a/src/H5Rpublic.h b/src/H5Rpublic.h index 598bafd..13d82d7 100644 --- a/src/H5Rpublic.h +++ b/src/H5Rpublic.h @@ -26,47 +26,71 @@ /* Public Macros */ /*****************/ -/* Note! Be careful with the sizes of the references because they should really - * depend on the run-time values in the file. Unfortunately, the arrays need - * to be defined at compile-time, so we have to go with the worst case sizes - * for them. -QAK - */ +/* Deprecated reference buffer sizes that are kept for backward compatibility */ #define H5R_OBJ_REF_BUF_SIZE sizeof(haddr_t) +#define H5R_DSET_REG_REF_BUF_SIZE (sizeof(haddr_t) + 4) -/* 4 is used instead of sizeof(int) to permit portability between the Crays - * and other machines (the heap ID is always encoded as an int32 anyway). +/* Default reference buffer size. + * Note! Be careful with the sizes of the references because they should really + * depend on the run-time values in the file. */ -#define H5R_DSET_REG_REF_BUF_SIZE (sizeof(haddr_t) + 4) +#define H5R_REF_BUF_SIZE (64) /*******************/ /* Public Typedefs */ /*******************/ -/* Reference types */ -typedef enum H5R_type_t { - H5R_BADTYPE = (-1), /* Invalid Reference Type */ - H5R_OBJECT, /* Object reference */ - H5R_DATASET_REGION, /* Dataset Region Reference */ - H5R_MAXTYPE /* Highest type (Invalid as true type) */ +/* + * Reference types allowed. + * DO NOT CHANGE THE ORDER or VALUES as reference type values are encoded into + * the datatype message header. + */ +typedef enum { + H5R_BADTYPE = (-1), /* Invalid reference type */ + H5R_OBJECT1 = 0, /* Backward compatibility (object) */ + H5R_DATASET_REGION1 = 1, /* Backward compatibility (region) */ + H5R_OBJECT2 = 2, /* Object reference */ + H5R_DATASET_REGION2 = 3, /* Region reference */ + H5R_ATTR = 4, /* Attribute Reference */ + H5R_MAXTYPE = 5 /* Highest type (invalid) */ } H5R_type_t; -/* Object reference structure for user's code - * This needs to be large enough to store largest haddr_t on a worst case - * machine (8 bytes currently). +/* Deprecated types are kept for backward compatibility with previous versions */ + +/** + * Deprecated object reference type that is used with deprecated reference APIs. + * Note! This type can only be used with the "native" HDF5 VOL connector. */ typedef haddr_t hobj_ref_t; -/* Dataset Region reference structure for user's code +/** + * Dataset region reference type that is used with deprecated reference APIs. * (Buffer to store heap ID and index) * This needs to be large enough to store largest haddr_t in a worst case - * machine (8 bytes currently) plus an int + * machine (8 bytes currently) plus an int. + * Note! This type can only be used with the "native" HDF5 VOL connector. */ -typedef unsigned char hdset_reg_ref_t[H5R_DSET_REG_REF_BUF_SIZE]; +typedef struct { + uint8_t __data[H5R_DSET_REG_REF_BUF_SIZE]; +} hdset_reg_ref_t; + +/** + * Opaque reference type. The same reference type is used for object, + * dataset region and attribute references. This is the type that + * should always be used with the current reference API. + */ +typedef struct { + union { + uint8_t __data[H5R_REF_BUF_SIZE]; /* opaque data */ + int64_t align; /* ensures alignment */ + } u; +} H5R_ref_t; /********************/ /* Public Variables */ /********************/ + /*********************/ /* Public Prototypes */ /*********************/ @@ -75,30 +99,57 @@ typedef unsigned char hdset_reg_ref_t[H5R_DSET_REG_REF_BUF_SIZE]; extern "C" { #endif -H5_DLL herr_t H5Rcreate(void *ref, hid_t loc_id, const char *name, - H5R_type_t ref_type, hid_t space_id); -H5_DLL hid_t H5Rdereference2(hid_t obj_id, hid_t oapl_id, H5R_type_t ref_type, const void *ref); -H5_DLL hid_t H5Rget_region(hid_t dataset, H5R_type_t ref_type, const void *ref); -H5_DLL herr_t H5Rget_obj_type2(hid_t id, H5R_type_t ref_type, const void *_ref, - H5O_type_t *obj_type); -H5_DLL ssize_t H5Rget_name(hid_t loc_id, H5R_type_t ref_type, const void *ref, - char *name /*out*/, size_t size); +/* Constructors */ +H5_DLL herr_t H5Rcreate_object(hid_t loc_id, const char *name, hid_t oapl_id, H5R_ref_t *ref_ptr); +H5_DLL herr_t H5Rcreate_region(hid_t loc_id, const char *name, hid_t space_id, hid_t oapl_id, H5R_ref_t *ref_ptr); +H5_DLL herr_t H5Rcreate_attr(hid_t loc_id, const char *name, const char *attr_name, hid_t oapl_id, H5R_ref_t *ref_ptr); +H5_DLL herr_t H5Rdestroy(H5R_ref_t *ref_ptr); + +/* Info */ +H5_DLL H5R_type_t H5Rget_type(const H5R_ref_t *ref_ptr); +H5_DLL htri_t H5Requal(const H5R_ref_t *ref1_ptr, const H5R_ref_t *ref2_ptr); +H5_DLL herr_t H5Rcopy(const H5R_ref_t *src_ref_ptr, H5R_ref_t *dst_ref_ptr); + +/* Dereference */ +H5_DLL hid_t H5Ropen_object(H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id); +H5_DLL hid_t H5Ropen_region(H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id); +H5_DLL hid_t H5Ropen_attr(H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t aapl_id); + +/* Get type */ +H5_DLL herr_t H5Rget_obj_type3(H5R_ref_t *ref_ptr, hid_t rapl_id, H5O_type_t *obj_type); + +/* Get name */ +H5_DLL ssize_t H5Rget_file_name(const H5R_ref_t *ref_ptr, char *buf, size_t size); +H5_DLL ssize_t H5Rget_obj_name(H5R_ref_t *ref_ptr, hid_t rapl_id, char *buf, size_t size); +H5_DLL ssize_t H5Rget_attr_name(const H5R_ref_t *ref_ptr, char *buf, size_t size); /* Symbols defined for compatibility with previous versions of the HDF5 API. * - * Use of these symbols is deprecated. + * Use of these symbols is or will be deprecated. */ -#ifndef H5_NO_DEPRECATED_SYMBOLS + +/* Macros */ + +/* Versions for compatibility */ +#define H5R_OBJECT H5R_OBJECT1 +#define H5R_DATASET_REGION H5R_DATASET_REGION1 /* Function prototypes */ -H5_DLL H5G_obj_t H5Rget_obj_type1(hid_t id, H5R_type_t ref_type, const void *_ref); +#ifndef H5_NO_DEPRECATED_SYMBOLS + +H5_DLL H5G_obj_t H5Rget_obj_type1(hid_t id, H5R_type_t ref_type, const void *ref); H5_DLL hid_t H5Rdereference1(hid_t obj_id, H5R_type_t ref_type, const void *ref); #endif /* H5_NO_DEPRECATED_SYMBOLS */ +H5_DLL herr_t H5Rcreate(void *ref, hid_t loc_id, const char *name, H5R_type_t ref_type, hid_t space_id); +H5_DLL herr_t H5Rget_obj_type2(hid_t id, H5R_type_t ref_type, const void *ref, H5O_type_t *obj_type); +H5_DLL hid_t H5Rdereference2(hid_t obj_id, hid_t oapl_id, H5R_type_t ref_type, const void *ref); +H5_DLL hid_t H5Rget_region(hid_t dataset, H5R_type_t ref_type, const void *ref); +H5_DLL ssize_t H5Rget_name(hid_t loc_id, H5R_type_t ref_type, const void *ref, char *name, size_t size); + #ifdef __cplusplus } #endif #endif /* _H5Rpublic_H */ - |