H5Opublic.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:             H5Opublic.h
00019  *                      Aug  5 1997
00020  *                      Robb Matzke <matzke@llnl.gov>
00021  *
00022  * Purpose:             Public declarations for the H5O (object header)
00023  *                      package.
00024  *
00025  *-------------------------------------------------------------------------
00026  */
00027 #ifndef _H5Opublic_H
00028 #define _H5Opublic_H
00029 
00030 /* Public headers needed by this file */
00031 #include "H5public.h"           /* Generic Functions                    */
00032 #include "H5Ipublic.h"          /* IDs                                  */
00033 #include "H5Lpublic.h"          /* Links                                */
00034 
00035 /*****************/
00036 /* Public Macros */
00037 /*****************/
00038 
00039 /* Flags for object copy (H5Ocopy) */
00040 #define H5O_COPY_SHALLOW_HIERARCHY_FLAG (0x0001u)   /* Copy only immediate members */
00041 #define H5O_COPY_EXPAND_SOFT_LINK_FLAG  (0x0002u)   /* Expand soft links into new objects */
00042 #define H5O_COPY_EXPAND_EXT_LINK_FLAG   (0x0004u)   /* Expand external links into new objects */
00043 #define H5O_COPY_EXPAND_REFERENCE_FLAG  (0x0008u)   /* Copy objects that are pointed by references */
00044 #define H5O_COPY_WITHOUT_ATTR_FLAG      (0x0010u)   /* Copy object without copying attributes */
00045 #define H5O_COPY_PRESERVE_NULL_FLAG     (0x0020u)   /* Copy NULL messages (empty space) */
00046 #define H5O_COPY_ALL                    (0x003Fu)   /* All object copying flags (for internal checking) */
00047 
00048 /* Flags for shared message indexes.
00049  * Pass these flags in using the mesg_type_flags parameter in
00050  * H5P_set_shared_mesg_index.
00051  * (Developers: These flags correspond to object header message type IDs,
00052  * but we need to assign each kind of message to a different bit so that
00053  * one index can hold multiple types.)
00054  */
00055 #define H5O_SHMESG_NONE_FLAG    0x0000          /* No shared messages */
00056 #define H5O_SHMESG_SDSPACE_FLAG ((unsigned)1 << 0x0001) /* Simple Dataspace Message.  */
00057 #define H5O_SHMESG_DTYPE_FLAG   ((unsigned)1 << 0x0003) /* Datatype Message.  */
00058 #define H5O_SHMESG_FILL_FLAG    ((unsigned)1 << 0x0005) /* Fill Value Message. */
00059 #define H5O_SHMESG_PLINE_FLAG   ((unsigned)1 << 0x000b) /* Filter pipeline message.  */
00060 #define H5O_SHMESG_ATTR_FLAG    ((unsigned)1 << 0x000c) /* Attribute Message.  */
00061 #define H5O_SHMESG_ALL_FLAG     (H5O_SHMESG_SDSPACE_FLAG | H5O_SHMESG_DTYPE_FLAG | H5O_SHMESG_FILL_FLAG | H5O_SHMESG_PLINE_FLAG | H5O_SHMESG_ATTR_FLAG)
00062 
00063 /* Object header status flag definitions */
00064 #define H5O_HDR_CHUNK0_SIZE             0x03    /* 2-bit field indicating # of bytes to store the size of chunk 0's data */
00065 #define H5O_HDR_ATTR_CRT_ORDER_TRACKED  0x04    /* Attribute creation order is tracked */
00066 #define H5O_HDR_ATTR_CRT_ORDER_INDEXED  0x08    /* Attribute creation order has index */
00067 #define H5O_HDR_ATTR_STORE_PHASE_CHANGE 0x10    /* Non-default attribute storage phase change values stored */
00068 #define H5O_HDR_STORE_TIMES             0x20    /* Store access, modification, change & birth times for object */
00069 #define H5O_HDR_ALL_FLAGS       (H5O_HDR_CHUNK0_SIZE | H5O_HDR_ATTR_CRT_ORDER_TRACKED | H5O_HDR_ATTR_CRT_ORDER_INDEXED | H5O_HDR_ATTR_STORE_PHASE_CHANGE | H5O_HDR_STORE_TIMES)
00070 
00071 /* Maximum shared message values.  Number of indexes is 8 to allow room to add
00072  * new types of messages.
00073  */
00074 #define H5O_SHMESG_MAX_NINDEXES 8
00075 #define H5O_SHMESG_MAX_LIST_SIZE 5000
00076 
00077 /*******************/
00078 /* Public Typedefs */
00079 /*******************/
00080 
00081 /* Types of objects in file */
00082 typedef enum H5O_type_t {
00083     H5O_TYPE_UNKNOWN = -1,      /* Unknown object type          */
00084     H5O_TYPE_GROUP,             /* Object is a group            */
00085     H5O_TYPE_DATASET,           /* Object is a dataset          */
00086     H5O_TYPE_NAMED_DATATYPE,    /* Object is a named data type  */
00087     H5O_TYPE_NTYPES             /* Number of different object types (must be last!) */
00088 } H5O_type_t;
00089 
00090 /* Information struct for object header metadata (for H5Oget_info/H5Oget_info_by_name/H5Oget_info_by_idx) */
00091 typedef struct H5O_hdr_info_t {
00092     unsigned version;           /* Version number of header format in file */
00093     unsigned nmesgs;            /* Number of object header messages */
00094     unsigned nchunks;           /* Number of object header chunks */
00095     unsigned flags;             /* Object header status flags */
00096     struct {
00097         hsize_t total;          /* Total space for storing object header in file */
00098         hsize_t meta;           /* Space within header for object header metadata information */
00099         hsize_t mesg;           /* Space within header for actual message information */
00100         hsize_t free;           /* Free space within object header */
00101     } space;
00102     struct {
00103         uint64_t present;       /* Flags to indicate presence of message type in header */
00104         uint64_t shared;        /* Flags to indicate message type is shared in header */
00105     } mesg;
00106 } H5O_hdr_info_t;
00107 
00108 /* Information struct for object (for H5Oget_info/H5Oget_info_by_name/H5Oget_info_by_idx) */
00109 typedef struct H5O_info_t {
00110     unsigned long       fileno;         /* File number that object is located in */
00111     haddr_t             addr;           /* Object address in file       */
00112     H5O_type_t          type;           /* Basic object type (group, dataset, etc.) */
00113     unsigned            rc;             /* Reference count of object    */
00114     time_t              atime;          /* Access time                  */
00115     time_t              mtime;          /* Modification time            */
00116     time_t              ctime;          /* Change time                  */
00117     time_t              btime;          /* Birth time                   */
00118     hsize_t             num_attrs;      /* # of attributes attached to object */
00119     H5O_hdr_info_t      hdr;            /* Object header information */
00120     /* Extra metadata storage for obj & attributes */
00121     struct {
00122         H5_ih_info_t   obj;             /* v1/v2 B-tree & local/fractal heap for groups, B-tree for chunked datasets */
00123         H5_ih_info_t   attr;            /* v2 B-tree & heap for attributes */
00124     } meta_size;
00125 } H5O_info_t;
00126 
00127 /* Typedef for message creation indexes */
00128 typedef uint32_t H5O_msg_crt_idx_t;
00129 
00130 /* Prototype for H5Ovisit/H5Ovisit_by_name() operator */
00131 typedef herr_t (*H5O_iterate_t)(hid_t obj, const char *name, const H5O_info_t *info,
00132     void *op_data);
00133 
00134 
00135 /********************/
00136 /* Public Variables */
00137 /********************/
00138 
00139 
00140 #ifdef __cplusplus
00141 extern "C" {
00142 #endif
00143 
00144 /*********************/
00145 /* Public Prototypes */
00146 /*********************/
00147 H5_DLL hid_t H5Oopen(hid_t loc_id, const char *name, hid_t lapl_id);
00148 H5_DLL hid_t H5Oopen_by_addr(hid_t loc_id, haddr_t addr);
00149 H5_DLL hid_t H5Oopen_by_idx(hid_t loc_id, const char *group_name,
00150     H5_index_t idx_type, H5_iter_order_t order, hsize_t n, hid_t lapl_id);
00151 H5_DLL htri_t H5Oexists_by_name(hid_t loc_id, const char *name, hid_t lapl_id);
00152 H5_DLL herr_t H5Oget_info(hid_t loc_id, H5O_info_t *oinfo);
00153 H5_DLL herr_t H5Oget_info_by_name(hid_t loc_id, const char *name, H5O_info_t *oinfo,
00154     hid_t lapl_id);
00155 H5_DLL herr_t H5Oget_info_by_idx(hid_t loc_id, const char *group_name,
00156     H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5O_info_t *oinfo,
00157     hid_t lapl_id);
00158 H5_DLL herr_t H5Olink(hid_t obj_id, hid_t new_loc_id, const char *new_name,
00159     hid_t lcpl_id, hid_t lapl_id);
00160 H5_DLL herr_t H5Oincr_refcount(hid_t object_id);
00161 H5_DLL herr_t H5Odecr_refcount(hid_t object_id);
00162 H5_DLL herr_t H5Ocopy(hid_t src_loc_id, const char *src_name, hid_t dst_loc_id,
00163     const char *dst_name, hid_t ocpypl_id, hid_t lcpl_id);
00164 H5_DLL herr_t H5Oset_comment(hid_t obj_id, const char *comment);
00165 H5_DLL herr_t H5Oset_comment_by_name(hid_t loc_id, const char *name,
00166     const char *comment, hid_t lapl_id);
00167 H5_DLL ssize_t H5Oget_comment(hid_t obj_id, char *comment, size_t bufsize);
00168 H5_DLL ssize_t H5Oget_comment_by_name(hid_t loc_id, const char *name,
00169     char *comment, size_t bufsize, hid_t lapl_id);
00170 H5_DLL herr_t H5Ovisit(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order,
00171     H5O_iterate_t op, void *op_data);
00172 H5_DLL herr_t H5Ovisit_by_name(hid_t loc_id, const char *obj_name,
00173     H5_index_t idx_type, H5_iter_order_t order, H5O_iterate_t op,
00174     void *op_data, hid_t lapl_id);
00175 H5_DLL herr_t H5Oclose(hid_t object_id);
00176 
00177 /* Symbols defined for compatibility with previous versions of the HDF5 API.
00178  *
00179  * Use of these symbols is deprecated.
00180  */
00181 #ifndef H5_NO_DEPRECATED_SYMBOLS
00182 
00183 /* Macros */
00184 
00185 /* Typedefs */
00186 
00187 /* A struct that's part of the H5G_stat_t routine (deprecated) */
00188 typedef struct H5O_stat_t {
00189     hsize_t size;               /* Total size of object header in file */
00190     hsize_t free;               /* Free space within object header */
00191     unsigned nmesgs;            /* Number of object header messages */
00192     unsigned nchunks;           /* Number of object header chunks */
00193 } H5O_stat_t;
00194 
00195 /* Function prototypes */
00196 
00197 #endif /* H5_NO_DEPRECATED_SYMBOLS */
00198 
00199 #ifdef __cplusplus
00200 }
00201 #endif
00202 #endif /* _H5Opublic_H */
00203