H5Apkg.h

00001 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
00002  * Copyright by The HDF Group.                                               *
00003  * Copyright by the Board of Trustees of the University of Illinois.         *
00004  * All rights reserved.                                                      *
00005  *                                                                           *
00006  * This file is part of HDF5.  The full HDF5 copyright notice, including     *
00007  * terms governing use, modification, and redistribution, is contained in    *
00008  * the files COPYING and Copyright.html.  COPYING can be found at the root   *
00009  * of the source code distribution tree; Copyright.html can be found at the  *
00010  * root level of an installed copy of the electronic HDF5 document set and   *
00011  * is linked from the top-level documents page.  It can also be found at     *
00012  * http://hdfgroup.org/HDF5/doc/Copyright.html.  If you do not have          *
00013  * access to either file, you may request a copy from help@hdfgroup.org.     *
00014  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
00015 
00016 /*
00017  * Programmer:  Quincey Koziol
00018  *              Monday, Apr 20
00019  *
00020  * Purpose:     This file contains declarations which are visible only within
00021  *              the H5A package.  Source files outside the H5A package should
00022  *              include H5Aprivate.h instead.
00023  */
00024 #ifndef H5A_PACKAGE
00025 #error "Do not include this file outside the H5A package!"
00026 #endif
00027 
00028 #ifndef _H5Apkg_H
00029 #define _H5Apkg_H
00030 
00031 /*
00032  * Define this to enable debugging.
00033  */
00034 #ifdef NDEBUG
00035 #  undef H5A_DEBUG
00036 #endif
00037 
00038 /* Get package's private header */
00039 #include "H5Aprivate.h"
00040 
00041 /* Other private headers needed by this file */
00042 #include "H5B2private.h"        /* v2 B-trees                           */
00043 #include "H5FLprivate.h"        /* Free Lists                           */
00044 #include "H5HFprivate.h"        /* Fractal heaps                        */
00045 #include "H5Oprivate.h"         /* Object headers                       */
00046 #include "H5Sprivate.h"         /* Dataspace                            */
00047 #include "H5Tprivate.h"         /* Datatype functions                   */
00048 
00049 
00050 /**************************/
00051 /* Package Private Macros */
00052 /**************************/
00053 
00054 /* This is the initial version, which does not have support for shared datatypes */
00055 #define H5O_ATTR_VERSION_1      1
00056 
00057 /* This version allows support for shared datatypes & dataspaces by adding a
00058  *      'flag' byte indicating when those components are shared.  This version
00059  *      also dropped the alignment on all the components.
00060  */
00061 #define H5O_ATTR_VERSION_2      2
00062 
00063 /* Add support for different character encodings of attribute names */
00064 #define H5O_ATTR_VERSION_3      3
00065 
00066 /* The latest version of the format.  Look through the 'encode', 'decode'
00067  *      and 'size' message callbacks for places to change when updating this.
00068  */
00069 #define H5O_ATTR_VERSION_LATEST H5O_ATTR_VERSION_3
00070 
00071 
00072 /****************************/
00073 /* Package Private Typedefs */
00074 /****************************/
00075 /* Define the shared attribute structure */
00076 typedef struct H5A_shared_t {
00077     uint8_t     version;    /* Version to encode attribute with */
00078 
00079     char        *name;      /* Attribute's name */
00080     H5T_cset_t  encoding;   /* Character encoding of attribute name */
00081 
00082     H5T_t       *dt;        /* Attribute's datatype */
00083     size_t      dt_size;    /* Size of datatype on disk */
00084 
00085     H5S_t       *ds;        /* Attribute's dataspace */
00086     size_t      ds_size;    /* Size of dataspace on disk */
00087 
00088     void        *data;      /* Attribute data (on a temporary basis) */
00089     size_t      data_size;  /* Size of data on disk */
00090     H5O_msg_crt_idx_t crt_idx;  /* Attribute's creation index in the object header */
00091     unsigned    nrefs;          /* Ref count for times this object is refered   */
00092 } H5A_shared_t;
00093 
00094 /* Define the main attribute structure */
00095 struct H5A_t {
00096     H5O_shared_t sh_loc;     /* Shared message info (must be first) */
00097     H5O_loc_t    oloc;       /* Object location for object attribute is on */
00098     hbool_t      obj_opened; /* Object header entry opened? */
00099     H5G_name_t   path;       /* Group hierarchy path */
00100     H5A_shared_t *shared;    /* Shared attribute information */
00101 };
00102 
00103 /* Typedefs for "dense" attribute storage */
00104 /* (fractal heap & v2 B-tree info) */
00105 
00106 /* Typedef for native 'name' field index records in the v2 B-tree */
00107 /* (Keep 'id' field first so generic record handling in callbacks works) */
00108 typedef struct H5A_dense_bt2_name_rec_t {
00109     H5O_fheap_id_t id;                  /* Heap ID for attribute */
00110     uint8_t flags;                      /* Object header message flags for attribute */
00111     H5O_msg_crt_idx_t corder;           /* 'creation order' field value */
00112     uint32_t hash;                      /* Hash of 'name' field value */
00113 } H5A_dense_bt2_name_rec_t;
00114 
00115 /* Typedef for native 'creation order' field index records in the v2 B-tree */
00116 /* (Keep 'id' field first so generic record handling in callbacks works) */
00117 typedef struct H5A_dense_bt2_corder_rec_t {
00118     H5O_fheap_id_t id;                  /* Heap ID for attribute */
00119     uint8_t flags;                      /* Object header message flags for attribute */
00120     H5O_msg_crt_idx_t corder;           /* 'creation order' field value */
00121 } H5A_dense_bt2_corder_rec_t;
00122 
00123 /* Define the 'found' callback function pointer for matching an attribute record in a v2 B-tree */
00124 typedef herr_t (*H5A_bt2_found_t)(const H5A_t *attr, hbool_t *took_ownership, void *op_data);
00125 
00126 /*
00127  * Common data exchange structure for dense attribute storage.  This structure
00128  * is passed through the v2 B-tree layer to the methods for the objects
00129  * to which the v2 B-tree points.
00130  */
00131 typedef struct H5A_bt2_ud_common_t {
00132     /* downward */
00133     H5F_t       *f;                     /* Pointer to file that fractal heap is in */
00134     hid_t       dxpl_id;                /* DXPL for operation                */
00135     H5HF_t      *fheap;                 /* Fractal heap handle               */
00136     H5HF_t      *shared_fheap;          /* Fractal heap handle for shared messages */
00137     const char  *name;                  /* Name of attribute to compare      */
00138     uint32_t    name_hash;              /* Hash of name of attribute to compare */
00139     uint8_t     flags;                  /* Flags for attribute storage location */
00140     H5O_msg_crt_idx_t corder;           /* Creation order value of attribute to compare */
00141     H5A_bt2_found_t found_op;           /* Callback when correct attribute is found */
00142     void        *found_op_data;         /* Callback data when correct attribute is found */
00143 } H5A_bt2_ud_common_t;
00144 
00145 /*
00146  * Data exchange structure for dense attribute storage.  This structure is
00147  * passed through the v2 B-tree layer when inserting attributes.
00148  */
00149 typedef struct H5A_bt2_ud_ins_t {
00150     /* downward */
00151     H5A_bt2_ud_common_t common;         /* Common info for B-tree user data (must be first) */
00152     H5O_fheap_id_t id;                  /* Heap ID of attribute to insert    */
00153 } H5A_bt2_ud_ins_t;
00154 
00155 /* Data structure to hold table of attributes for an object */
00156 typedef struct {
00157     size_t      nattrs;         /* # of attributes in table */
00158     H5A_t       **attrs;        /* Pointer to array of attribute pointers */
00159 } H5A_attr_table_t;
00160 
00161 /* Attribute iteration operator for internal library callbacks */
00162 typedef herr_t (*H5A_lib_iterate_t)(const H5A_t *attr, void *op_data);
00163 
00164 /* Describe kind of callback to make for each attribute */
00165 typedef enum H5A_attr_iter_op_type_t {
00166 #ifndef H5_NO_DEPRECATED_SYMBOLS
00167     H5A_ATTR_OP_APP,                /* Application callback */
00168 #endif /* H5_NO_DEPRECATED_SYMBOLS */
00169     H5A_ATTR_OP_APP2,               /* Revised application callback */
00170     H5A_ATTR_OP_LIB                 /* Library internal callback */
00171 } H5A_attr_iter_op_type_t;
00172 
00173 typedef struct H5A_attr_iter_op_t {
00174     H5A_attr_iter_op_type_t op_type;
00175     union {
00176 #ifndef H5_NO_DEPRECATED_SYMBOLS
00177         H5A_operator1_t app_op;         /* Application callback for each attribute */
00178 #endif /* H5_NO_DEPRECATED_SYMBOLS */
00179         H5A_operator2_t app_op2;        /* Revised application callback for each attribute */
00180         H5A_lib_iterate_t lib_op;       /* Library internal callback for each attribute */
00181     } u;
00182 } H5A_attr_iter_op_t;
00183 
00184 
00185 /*****************************/
00186 /* Package Private Variables */
00187 /*****************************/
00188 
00189 /* Declare extern the free list for H5A_t's */
00190 H5FL_EXTERN(H5A_t);
00191 
00192 /* Declare the external free lists for H5A_shared_t's */
00193 H5FL_EXTERN(H5A_shared_t);
00194 
00195 /* Declare extern a free list to manage blocks of type conversion data */
00196 H5FL_BLK_EXTERN(attr_buf);
00197 
00198 /* The v2 B-tree class for indexing 'name' field on attributes */
00199 H5_DLLVAR const H5B2_class_t H5A_BT2_NAME[1];
00200 
00201 /* The v2 B-tree class for indexing 'creation order' field on attributes */
00202 H5_DLLVAR const H5B2_class_t H5A_BT2_CORDER[1];
00203 
00204 
00205 /******************************/
00206 /* Package Private Prototypes */
00207 /******************************/
00208 
00209 /* Function prototypes for H5A package scope */
00210 H5_DLL herr_t H5A_init(void);
00211 H5_DLL hid_t H5A_create(const H5G_loc_t *loc, const char *name,
00212     const H5T_t *type, const H5S_t *space, hid_t acpl_id, hid_t dxpl_id);
00213 H5_DLL H5A_t * H5A_open_by_name(const H5G_loc_t *loc, const char *obj_name,
00214     const char *attr_name, hid_t lapl_id, hid_t dxpl_id);
00215 H5_DLL H5A_t *H5A_open_by_idx(const H5G_loc_t *loc, const char *obj_name,
00216     H5_index_t idx_type, H5_iter_order_t order, hsize_t n, hid_t lapl_id, hid_t dxpl_id);
00217 H5_DLL ssize_t H5A_get_name(H5A_t *attr, size_t buf_size, char *buf);
00218 H5_DLL H5A_t *H5A_copy(H5A_t *new_attr, const H5A_t *old_attr);
00219 H5_DLL herr_t H5A_get_info(const H5A_t *attr, H5A_info_t *ainfo);
00220 H5_DLL herr_t H5A_free(H5A_t *attr);
00221 H5_DLL herr_t H5A_close(H5A_t *attr);
00222 H5_DLL htri_t H5A_get_ainfo(H5F_t *f, hid_t dxpl_id, H5O_t *oh, H5O_ainfo_t *ainfo);
00223 H5_DLL herr_t H5A_set_version(const H5F_t *f, H5A_t *attr);
00224 
00225 /* Attribute "dense" storage routines */
00226 H5_DLL herr_t H5A_dense_create(H5F_t *f, hid_t dxpl_id, H5O_ainfo_t *ainfo);
00227 H5_DLL H5A_t *H5A_dense_open(H5F_t *f, hid_t dxpl_id, const H5O_ainfo_t *ainfo,
00228     const char *name);
00229 H5_DLL herr_t H5A_dense_insert(H5F_t *f, hid_t dxpl_id, const H5O_ainfo_t *ainfo,
00230     H5A_t *attr);
00231 H5_DLL herr_t H5A_dense_write(H5F_t *f, hid_t dxpl_id, const H5O_ainfo_t *ainfo,
00232     H5A_t *attr);
00233 H5_DLL herr_t H5A_dense_rename(H5F_t *f, hid_t dxpl_id, const H5O_ainfo_t *ainfo,
00234     const char *old_name, const char *new_name);
00235 H5_DLL herr_t H5A_dense_iterate(H5F_t *f, hid_t dxpl_id, hid_t loc_id,
00236     const H5O_ainfo_t *ainfo, H5_index_t idx_type, H5_iter_order_t order,
00237     hsize_t skip, hsize_t *last_attr, const H5A_attr_iter_op_t *attr_op,
00238     void *op_data);
00239 H5_DLL herr_t H5A_dense_remove(H5F_t *f, hid_t dxpl_id, const H5O_ainfo_t *ainfo,
00240     const char *name);
00241 H5_DLL herr_t H5A_dense_remove_by_idx(H5F_t *f, hid_t dxpl_id, const H5O_ainfo_t *ainfo,
00242     H5_index_t idx_type, H5_iter_order_t order, hsize_t n);
00243 H5_DLL htri_t H5A_dense_exists(H5F_t *f, hid_t dxpl_id, const H5O_ainfo_t *ainfo,
00244     const char *name);
00245 H5_DLL herr_t H5A_dense_delete(H5F_t *f, hid_t dxpl_id, H5O_ainfo_t *ainfo);
00246 
00247 
00248 /* Attribute table operations */
00249 H5_DLL herr_t H5A_compact_build_table(H5F_t *f, hid_t dxpl_id, H5O_t *oh,
00250     H5_index_t idx_type, H5_iter_order_t order, H5A_attr_table_t *atable);
00251 H5_DLL herr_t H5A_dense_build_table(H5F_t *f, hid_t dxpl_id,
00252     const H5O_ainfo_t *ainfo, H5_index_t idx_type, H5_iter_order_t order,
00253     H5A_attr_table_t *atable);
00254 H5_DLL herr_t H5A_attr_iterate_table(const H5A_attr_table_t *atable,
00255     hsize_t skip, hsize_t *last_attr, hid_t loc_id,
00256     const H5A_attr_iter_op_t *attr_op, void *op_data);
00257 H5_DLL herr_t H5A_attr_release_table(H5A_attr_table_t *atable);
00258 
00259 /* Attribute operations */
00260 H5_DLL herr_t H5O_attr_create(const H5O_loc_t *loc, hid_t dxpl_id, H5A_t *attr);
00261 H5_DLL H5A_t *H5O_attr_open_by_name(const H5O_loc_t *loc, const char *name,
00262     hid_t dxpl_id);
00263 H5_DLL H5A_t *H5O_attr_open_by_idx(const H5O_loc_t *loc, H5_index_t idx_type,
00264     H5_iter_order_t order, hsize_t n, hid_t dxpl_id);
00265 H5_DLL herr_t H5O_attr_update_shared(H5F_t *f, hid_t dxpl_id, H5O_t *oh,
00266         H5A_t *attr, H5O_shared_t *sh_mesg);
00267 H5_DLL herr_t H5O_attr_write(const H5O_loc_t *loc, hid_t dxpl_id,
00268     H5A_t *attr);
00269 H5_DLL herr_t H5O_attr_rename(const H5O_loc_t *loc, hid_t dxpl_id,
00270     const char *old_name, const char *new_name);
00271 H5_DLL herr_t H5O_attr_iterate(hid_t loc_id, hid_t dxpl_id, H5_index_t idx_type,
00272     H5_iter_order_t order, hsize_t skip, hsize_t *last_attr,
00273     const H5A_attr_iter_op_t *op, void *op_data);
00274 H5_DLL herr_t H5O_attr_remove(const H5O_loc_t *loc, const char *name,
00275     hid_t dxpl_id);
00276 H5_DLL herr_t H5O_attr_remove_by_idx(const H5O_loc_t *loc, H5_index_t idx_type,
00277     H5_iter_order_t order, hsize_t n, hid_t dxpl_id);
00278 H5_DLL htri_t H5O_attr_exists(const H5O_loc_t *loc, const char *name, hid_t dxpl_id);
00279 #ifndef H5_NO_DEPRECATED_SYMBOLS
00280 H5_DLL int H5O_attr_count(const H5O_loc_t *loc, hid_t dxpl_id);
00281 #endif /* H5_NO_DEPRECATED_SYMBOLS */
00282 H5_DLL H5A_t *H5A_attr_copy_file(const H5A_t *attr_src, H5F_t *file_dst, hbool_t *recompute_size,
00283     H5O_copy_t *cpy_info, hid_t dxpl_id);
00284 H5_DLL herr_t H5A_attr_post_copy_file(const H5O_loc_t *src_oloc, const H5A_t *mesg_src,
00285     H5O_loc_t *dst_oloc, const H5A_t *mesg_dst, hid_t dxpl_id, H5O_copy_t *cpy_info);
00286 H5_DLL herr_t H5A_dense_copy_file_all(H5F_t *file_src, H5O_ainfo_t *ainfo_src, H5F_t *file_dst,
00287     const H5O_ainfo_t *ainfo_dst, hbool_t *recompute_size, H5O_copy_t *cpy_info, hid_t dxpl_id);
00288 H5_DLL herr_t H5A_dense_post_copy_file_all(const H5O_loc_t *src_oloc, const H5O_ainfo_t * ainfo_src,
00289     H5O_loc_t *dst_oloc, H5O_ainfo_t *ainfo_dst, hid_t dxpl_id, H5O_copy_t *cpy_info);
00290 
00291 
00292 /* Testing functions */
00293 #ifdef H5A_TESTING
00294 H5_DLL htri_t H5A_is_shared_test(hid_t aid);
00295 H5_DLL herr_t H5A_get_shared_rc_test(hid_t attr_id, hsize_t *ref_count);
00296 #endif /* H5A_TESTING */
00297 
00298 #endif /* _H5Apkg_H */
00299