H5Gpublic.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:             H5Gpublic.h
00019  *                      Jul 11 1997
00020  *                      Robb Matzke <matzke@llnl.gov>
00021  *
00022  * Purpose:             Public declarations for the H5G package
00023  *
00024  *-------------------------------------------------------------------------
00025  */
00026 #ifndef _H5Gpublic_H
00027 #define _H5Gpublic_H
00028 
00029 /* System headers needed by this file */
00030 #include <sys/types.h>
00031 
00032 /* Public headers needed by this file */
00033 #include "H5public.h"           /* Generic Functions                    */
00034 #include "H5Lpublic.h"          /* Links                                */
00035 #include "H5Opublic.h"          /* Object headers                       */
00036 #include "H5Tpublic.h"          /* Datatypes                            */
00037 
00038 /*****************/
00039 /* Public Macros */
00040 /*****************/
00041 
00042 #ifdef __cplusplus
00043 extern "C" {
00044 #endif
00045 
00046 /*******************/
00047 /* Public Typedefs */
00048 /*******************/
00049 
00050 /* Types of link storage for groups */
00051 typedef enum H5G_storage_type_t {
00052     H5G_STORAGE_TYPE_UNKNOWN = -1,      /* Unknown link storage type    */
00053     H5G_STORAGE_TYPE_SYMBOL_TABLE,      /* Links in group are stored with a "symbol table" */
00054                                         /* (this is sometimes called "old-style" groups) */
00055     H5G_STORAGE_TYPE_COMPACT,           /* Links are stored in object header */
00056     H5G_STORAGE_TYPE_DENSE              /* Links are stored in fractal heap & indexed with v2 B-tree */
00057 } H5G_storage_type_t;
00058 
00059 /* Information struct for group (for H5Gget_info/H5Gget_info_by_name/H5Gget_info_by_idx) */
00060 typedef struct H5G_info_t {
00061     H5G_storage_type_t  storage_type;   /* Type of storage for links in group */
00062     hsize_t     nlinks;                 /* Number of links in group */
00063     int64_t     max_corder;             /* Current max. creation order value for group */
00064     hbool_t     mounted;                /* Whether group has a file mounted on it */
00065 } H5G_info_t;
00066 
00067 /********************/
00068 /* Public Variables */
00069 /********************/
00070 
00071 
00072 /*********************/
00073 /* Public Prototypes */
00074 /*********************/
00075 H5_DLL hid_t H5Gcreate2(hid_t loc_id, const char *name, hid_t lcpl_id,
00076     hid_t gcpl_id, hid_t gapl_id);
00077 H5_DLL hid_t H5Gcreate_anon(hid_t loc_id, hid_t gcpl_id, hid_t gapl_id);
00078 H5_DLL hid_t H5Gopen2(hid_t loc_id, const char *name, hid_t gapl_id);
00079 H5_DLL hid_t H5Gget_create_plist(hid_t group_id);
00080 H5_DLL herr_t H5Gget_info(hid_t loc_id, H5G_info_t *ginfo);
00081 H5_DLL herr_t H5Gget_info_by_name(hid_t loc_id, const char *name, H5G_info_t *ginfo,
00082     hid_t lapl_id);
00083 H5_DLL herr_t H5Gget_info_by_idx(hid_t loc_id, const char *group_name,
00084     H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5G_info_t *ginfo,
00085     hid_t lapl_id);
00086 H5_DLL herr_t H5Gclose(hid_t group_id);
00087 
00088 /* Symbols defined for compatibility with previous versions of the HDF5 API.
00089  *
00090  * Use of these symbols is deprecated.
00091  */
00092 #ifndef H5_NO_DEPRECATED_SYMBOLS
00093 
00094 /* Macros */
00095 
00096 /* Link definitions */
00097 #define H5G_SAME_LOC H5L_SAME_LOC
00098 #define H5G_LINK_ERROR H5L_TYPE_ERROR
00099 #define H5G_LINK_HARD H5L_TYPE_HARD
00100 #define H5G_LINK_SOFT H5L_TYPE_SOFT
00101 #define H5G_link_t H5L_type_t
00102 
00103 /* Macros for types of objects in a group (see H5G_obj_t definition) */
00104 #define H5G_NTYPES      256             /* Max possible number of types */
00105 #define H5G_NLIBTYPES   8               /* Number of internal types     */
00106 #define H5G_NUSERTYPES  (H5G_NTYPES - H5G_NLIBTYPES)
00107 #define H5G_USERTYPE(X) (8 + (X))       /* User defined types           */
00108 
00109 
00110 /* Typedefs */
00111 
00112 /*
00113  * An object has a certain type. The first few numbers are reserved for use
00114  * internally by HDF5. Users may add their own types with higher values.  The
00115  * values are never stored in the file -- they only exist while an
00116  * application is running.  An object may satisfy the `isa' function for more
00117  * than one type.
00118  */
00119 typedef enum H5G_obj_t {
00120     H5G_UNKNOWN = -1,           /* Unknown object type          */
00121     H5G_GROUP,                  /* Object is a group            */
00122     H5G_DATASET,                /* Object is a dataset          */
00123     H5G_TYPE,                   /* Object is a named data type  */
00124     H5G_LINK,                   /* Object is a symbolic link    */
00125     H5G_UDLINK,                 /* Object is a user-defined link */
00126     H5G_RESERVED_5,             /* Reserved for future use      */
00127     H5G_RESERVED_6,             /* Reserved for future use      */
00128     H5G_RESERVED_7              /* Reserved for future use      */
00129 } H5G_obj_t;
00130 
00131 /* Prototype for H5Giterate() operator */
00132 typedef herr_t (*H5G_iterate_t)(hid_t group, const char *name, void *op_data);
00133 
00134 /* Information about an object */
00135 typedef struct H5G_stat_t {
00136     unsigned long       fileno[2];      /*file number                   */
00137     unsigned long       objno[2];       /*object number                 */
00138     unsigned            nlink;          /*number of hard links to object*/
00139     H5G_obj_t           type;           /*basic object type             */
00140     time_t              mtime;          /*modification time             */
00141     size_t              linklen;        /*symbolic link value length    */
00142     H5O_stat_t          ohdr;           /* Object header information    */
00143 } H5G_stat_t;
00144 
00145 
00146 /* Function prototypes */
00147 H5_DLL hid_t H5Gcreate1(hid_t loc_id, const char *name, size_t size_hint);
00148 H5_DLL hid_t H5Gopen1(hid_t loc_id, const char *name);
00149 H5_DLL herr_t H5Glink(hid_t cur_loc_id, H5G_link_t type, const char *cur_name,
00150     const char *new_name);
00151 H5_DLL herr_t H5Glink2(hid_t cur_loc_id, const char *cur_name, H5G_link_t type,
00152     hid_t new_loc_id, const char *new_name);
00153 H5_DLL herr_t H5Gmove(hid_t src_loc_id, const char *src_name,
00154     const char *dst_name);
00155 H5_DLL herr_t H5Gmove2(hid_t src_loc_id, const char *src_name, hid_t dst_loc_id,
00156     const char *dst_name);
00157 H5_DLL herr_t H5Gunlink(hid_t loc_id, const char *name);
00158 H5_DLL herr_t H5Gget_linkval(hid_t loc_id, const char *name, size_t size,
00159     char *buf/*out*/);
00160 H5_DLL herr_t H5Gset_comment(hid_t loc_id, const char *name, const char *comment);
00161 H5_DLL int H5Gget_comment(hid_t loc_id, const char *name, size_t bufsize,
00162     char *buf);
00163 H5_DLL herr_t H5Giterate(hid_t loc_id, const char *name, int *idx,
00164         H5G_iterate_t op, void *op_data);
00165 H5_DLL herr_t H5Gget_num_objs(hid_t loc_id, hsize_t *num_objs);
00166 H5_DLL herr_t H5Gget_objinfo(hid_t loc_id, const char *name,
00167     hbool_t follow_link, H5G_stat_t *statbuf/*out*/);
00168 H5_DLL ssize_t H5Gget_objname_by_idx(hid_t loc_id, hsize_t idx, char* name,
00169     size_t size);
00170 H5_DLL H5G_obj_t H5Gget_objtype_by_idx(hid_t loc_id, hsize_t idx);
00171 
00172 #endif /* H5_NO_DEPRECATED_SYMBOLS */
00173 
00174 #ifdef __cplusplus
00175 }
00176 #endif
00177 #endif /* _H5Gpublic_H */
00178