H5Gprivate.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  *
00018  * Created:             H5Gprivate.h
00019  *                      Jul 11 1997
00020  *                      Robb Matzke <matzke@llnl.gov>
00021  *
00022  * Purpose:             Library-visible declarations.
00023  *
00024  *-------------------------------------------------------------------------
00025  */
00026 
00027 #ifndef _H5Gprivate_H
00028 #define _H5Gprivate_H
00029 
00030 /* Include package's public header */
00031 #include "H5Gpublic.h"
00032 
00033 /* Private headers needed by this file */
00034 #include "H5private.h"          /* Generic Functions                    */
00035 #include "H5Bprivate.h"         /* B-trees                              */
00036 #include "H5Fprivate.h"         /* File access                          */
00037 #include "H5RSprivate.h"        /* Reference-counted strings            */
00038 
00039 /*
00040  * Define this to enable debugging.
00041  */
00042 #ifdef NDEBUG
00043 #  undef H5G_DEBUG
00044 #endif
00045 
00046 /*
00047  * The disk size for a symbol table entry...
00048  */
00049 #define H5G_SIZEOF_SCRATCH      16
00050 #define H5G_SIZEOF_ENTRY(F)                                                   \
00051    (H5F_SIZEOF_SIZE(F) +        /*offset of name into heap              */    \
00052     H5F_SIZEOF_ADDR(F) +        /*address of object header              */    \
00053     4 +                         /*entry type                            */    \
00054     4 +                         /*reserved                              */    \
00055     H5G_SIZEOF_SCRATCH)         /*scratch pad space                     */
00056 
00057 /* ========= Group Creation properties ============ */
00058 
00059 /* Defaults for link info values */
00060 #define H5G_CRT_LINFO_TRACK_CORDER              FALSE
00061 #define H5G_CRT_LINFO_INDEX_CORDER              FALSE
00062 #define H5G_CRT_LINFO_NLINKS                    0
00063 #define H5G_CRT_LINFO_MAX_CORDER                0
00064 #define H5G_CRT_LINFO_LINK_FHEAP_ADDR           HADDR_UNDEF
00065 #define H5G_CRT_LINFO_NAME_BT2_ADDR             HADDR_UNDEF
00066 #define H5G_CRT_LINFO_CORDER_BT2_ADDR           HADDR_UNDEF
00067 
00068 /* Definitions for link info settings */
00069 #define H5G_CRT_LINK_INFO_NAME                  "link info"
00070 #define H5G_CRT_LINK_INFO_SIZE                  sizeof(H5O_linfo_t)
00071 #define H5G_CRT_LINK_INFO_DEF                   {H5G_CRT_LINFO_TRACK_CORDER, \
00072                                                     H5G_CRT_LINFO_INDEX_CORDER, \
00073                                                     H5G_CRT_LINFO_MAX_CORDER, \
00074                                                     H5G_CRT_LINFO_CORDER_BT2_ADDR, \
00075                                                     H5G_CRT_LINFO_NLINKS, \
00076                                                     H5G_CRT_LINFO_LINK_FHEAP_ADDR, \
00077                                                     H5G_CRT_LINFO_NAME_BT2_ADDR \
00078                                                 }
00079 
00080 /* Defaults for group info values */
00081 #define H5G_CRT_GINFO_LHEAP_SIZE_HINT           0
00082 #define H5G_CRT_GINFO_STORE_LINK_PHASE_CHANGE   FALSE
00083 #define H5G_CRT_GINFO_MAX_COMPACT               8
00084 #define H5G_CRT_GINFO_MIN_DENSE                 6
00085 #define H5G_CRT_GINFO_STORE_EST_ENTRY_INFO      FALSE
00086 #define H5G_CRT_GINFO_EST_NUM_ENTRIES           4
00087 #define H5G_CRT_GINFO_EST_NAME_LEN              8
00088 
00089 /* Definitions for group info settings */
00090 #define H5G_CRT_GROUP_INFO_NAME                 "group info"
00091 #define H5G_CRT_GROUP_INFO_SIZE                 sizeof(H5O_ginfo_t)
00092 #define H5G_CRT_GROUP_INFO_DEF                  {H5G_CRT_GINFO_LHEAP_SIZE_HINT, \
00093                                                     H5G_CRT_GINFO_STORE_LINK_PHASE_CHANGE, \
00094                                                     H5G_CRT_GINFO_MAX_COMPACT, \
00095                                                     H5G_CRT_GINFO_MIN_DENSE, \
00096                                                     H5G_CRT_GINFO_STORE_EST_ENTRY_INFO, \
00097                                                     H5G_CRT_GINFO_EST_NUM_ENTRIES, \
00098                                                     H5G_CRT_GINFO_EST_NAME_LEN \
00099                                                 }
00100 
00101 /* If the module using this macro is allowed access to the private variables, access them directly */
00102 #ifdef H5G_PACKAGE
00103 #define H5G_MOUNTED(G)              ((G)->shared->mounted)
00104 #else /* H5G_PACKAGE */
00105 #define H5G_MOUNTED(G)              (H5G_mounted(G))
00106 #endif /* H5G_PACKAGE */
00107 
00108 /* Type of operation being performed for call to H5G_name_replace() */
00109 typedef enum {
00110     H5G_NAME_MOVE = 0,          /* H5*move call    */
00111     H5G_NAME_DELETE,            /* H5Ldelete call  */
00112     H5G_NAME_MOUNT,             /* H5Fmount call   */
00113     H5G_NAME_UNMOUNT            /* H5Funmount call */
00114 } H5G_names_op_t;
00115 
00116 /* Status returned from traversal callbacks; whether the object location
00117  * or group location need to be closed */
00118 #define H5G_OWN_NONE 0
00119 #define H5G_OWN_OBJ_LOC 1
00120 #define H5G_OWN_GRP_LOC 2
00121 #define H5G_OWN_BOTH 3
00122 typedef int H5G_own_loc_t;
00123 
00124 /* Structure to store information about the name an object was opened with */
00125 typedef struct {
00126     H5RS_str_t  *full_path_r;           /* Path to object, as seen from root of current file mounting hierarchy */
00127     H5RS_str_t  *user_path_r;           /* Path to object, as opened by user */
00128     unsigned    obj_hidden;             /* Whether the object is visible in group hier. */
00129 } H5G_name_t;
00130 
00131 /* Forward declarations (for prototypes & struct definitions) */
00132 struct H5O_loc_t;
00133 struct H5O_link_t;
00134 
00135 /*
00136  * The "location" of an object in a group hierarchy.  This points to an object
00137  * location and a group hierarchy path for the object.
00138  */
00139 typedef struct {
00140     struct H5O_loc_t *oloc;             /* Object header location            */
00141     H5G_name_t *path;                   /* Group hierarchy path              */
00142 } H5G_loc_t;
00143 
00144 /* Callback information for copying groups */
00145 typedef struct H5G_copy_file_ud_t {
00146     H5O_copy_file_ud_common_t common;   /* Shared information (must be first) */
00147 } H5G_copy_file_ud_t;
00148 
00149 typedef struct H5G_t H5G_t;
00150 typedef struct H5G_shared_t H5G_shared_t;
00151 typedef struct H5G_entry_t H5G_entry_t;
00152 
00153 /*
00154  * Library prototypes...  These are the ones that other packages routinely
00155  * call.
00156  */
00157 H5_DLL herr_t H5G_mkroot(H5F_t *f, hid_t dxpl_id, hbool_t create_root);
00158 H5_DLL struct H5O_loc_t *H5G_oloc(H5G_t *grp);
00159 H5_DLL H5G_t *H5G_rootof(H5F_t *f);
00160 H5_DLL H5G_name_t * H5G_nameof(H5G_t *grp);
00161 H5_DLL H5F_t *H5G_fileof(H5G_t *grp);
00162 H5_DLL herr_t H5G_free(H5G_t *grp);
00163 H5_DLL H5G_t *H5G_open(const H5G_loc_t *loc, hid_t dxpl_id);
00164 H5_DLL herr_t H5G_close(H5G_t *grp);
00165 H5_DLL herr_t H5G_free_grp_name(H5G_t *grp);
00166 H5_DLL herr_t H5G_get_shared_count(H5G_t *grp);
00167 H5_DLL herr_t H5G_mount(H5G_t *grp);
00168 H5_DLL hbool_t H5G_mounted(H5G_t *grp);
00169 H5_DLL herr_t H5G_unmount(H5G_t *grp);
00170 #ifndef H5_NO_DEPRECATED_SYMBOLS
00171 H5_DLL H5G_obj_t H5G_map_obj_type(H5O_type_t obj_type);
00172 #endif /* H5_NO_DEPRECATED_SYMBOLS */
00173 H5_DLL herr_t H5G_visit(hid_t loc_id, const char *group_name,
00174     H5_index_t idx_type, H5_iter_order_t order, H5L_iterate_t op, void *op_data,
00175     hid_t lapl_id, hid_t dxpl_id);
00176 
00177 /*
00178  * These functions operate on symbol table nodes.
00179  */
00180 H5_DLL herr_t H5G_node_close(const H5F_t *f);
00181 H5_DLL herr_t H5G_node_debug(H5F_t *f, hid_t dxpl_id, haddr_t addr, FILE *stream,
00182                               int indent, int fwidth, haddr_t heap);
00183 
00184 /*
00185  * These functions operate on group object locations.
00186  */
00187 H5_DLL herr_t H5G_ent_encode(const H5F_t *f, uint8_t **pp, const H5G_entry_t *ent);
00188 H5_DLL herr_t H5G_ent_decode(const H5F_t *f, const uint8_t **pp, H5G_entry_t *ent);
00189 
00190 /*
00191  * These functions operate on group hierarchy names.
00192  */
00193 H5_DLL herr_t H5G_name_replace(const struct H5O_link_t *lnk, H5G_names_op_t op,
00194     H5F_t *src_file, H5RS_str_t *src_full_path_r, H5F_t *dst_file,
00195     H5RS_str_t *dst_full_path_r, hid_t dxpl_id);
00196 H5_DLL herr_t H5G_name_reset(H5G_name_t *name);
00197 H5_DLL herr_t H5G_name_copy(H5G_name_t *dst, const H5G_name_t *src, H5_copy_depth_t depth);
00198 H5_DLL herr_t H5G_name_free(H5G_name_t *name);
00199 H5_DLL ssize_t H5G_get_name(hid_t id, char *name/*out*/, size_t size,
00200     hid_t lapl_id, hid_t dxpl_id);
00201 H5_DLL ssize_t H5G_get_name_by_addr(hid_t fid, hid_t lapl_id, hid_t dxpl_id,
00202     const struct H5O_loc_t *loc, char* name, size_t size);
00203 
00204 /*
00205  * These functions operate on group "locations"
00206  */
00207 H5_DLL herr_t H5G_loc(hid_t loc_id, H5G_loc_t *loc);
00208 H5_DLL herr_t H5G_loc_find(const H5G_loc_t *loc, const char *name,
00209     H5G_loc_t *obj_loc/*out*/, hid_t lapl_id, hid_t dxpl_id);
00210 H5_DLL herr_t H5G_loc_find_by_idx(H5G_loc_t *loc, const char *group_name,
00211     H5_index_t idx_type, H5_iter_order_t order, hsize_t n,
00212     H5G_loc_t *obj_loc/*out*/, hid_t lapl_id, hid_t dxpl_id);
00213 H5_DLL htri_t H5G_loc_exists(const H5G_loc_t *loc, const char *name,
00214     hid_t lapl_id, hid_t dxpl_id);
00215 H5_DLL herr_t H5G_loc_info(H5G_loc_t *loc, const char *name,
00216     hbool_t want_ih_info, H5O_info_t *oinfo/*out*/, hid_t lapl_id,
00217     hid_t dxpl_id);
00218 H5_DLL herr_t H5G_loc_set_comment(H5G_loc_t *loc, const char *name,
00219     const char *comment, hid_t lapl_id, hid_t dxpl_id);
00220 H5_DLL ssize_t H5G_loc_get_comment(H5G_loc_t *loc, const char *name,
00221     char *comment/*out*/, size_t bufsize, hid_t lapl_id, hid_t dxpl_id);
00222 H5_DLL herr_t H5G_loc_reset(H5G_loc_t *loc);
00223 H5_DLL herr_t H5G_loc_free(H5G_loc_t *loc);
00224 
00225 #endif /* _H5Gprivate_H */
00226