1 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 2 * Copyright by The HDF Group. * 3 * Copyright by the Board of Trustees of the University of Illinois. * 4 * All rights reserved. * 5 * * 6 * This file is part of HDF5. The full HDF5 copyright notice, including * 7 * terms governing use, modification, and redistribution, is contained in * 8 * the files COPYING and Copyright.html. COPYING can be found at the root * 9 * of the source code distribution tree; Copyright.html can be found at the * 10 * root level of an installed copy of the electronic HDF5 document set and * 11 * is linked from the top-level documents page. It can also be found at * 12 * http://hdfgroup.org/HDF5/doc/Copyright.html. If you do not have * 13 * access to either file, you may request a copy from help@hdfgroup.org. * 14 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 15 16 /*------------------------------------------------------------------------- 17 * 18 * Created: H5Lpublic.h 19 * Dec 1 2005 20 * James Laird 21 * 22 * Purpose: Public declarations for the H5L package (links) 23 * 24 *------------------------------------------------------------------------- 25 */ 26 #ifndef _H5Lpublic_H 27 #define _H5Lpublic_H 28 29 /* Public headers needed by this file */ 30 #include "H5public.h" /* Generic Functions */ 31 #include "H5Ipublic.h" /* IDs */ 32 #include "H5Tpublic.h" /* Datatypes */ 33 34 /*****************/ 35 /* Public Macros */ 36 /*****************/ 37 38 /* Maximum length of a link's name */ 39 /* (encoded in a 32-bit unsigned integer) */ 40 #define H5L_MAX_LINK_NAME_LEN ((uint32_t)(-1)) /* (4GB - 1) */ 41 42 /* Macro to indicate operation occurs on same location */ 43 #define H5L_SAME_LOC 0 44 45 /* Current version of the H5L_class_t struct */ 46 #define H5L_LINK_CLASS_T_VERS 0 47 48 #ifdef __cplusplus 49 extern "C" { 50 #endif 51 52 /*******************/ 53 /* Public Typedefs */ 54 /*******************/ 55 56 /* Link class types. 57 * Values less than 64 are reserved for the HDF5 library's internal use. 58 * Values 64 to 255 are for "user-defined" link class types; these types are 59 * defined by HDF5 but their behavior can be overridden by users. 60 * Users who want to create new classes of links should contact the HDF5 61 * development team at hdfhelp@ncsa.uiuc.edu . 62 * These values can never change because they appear in HDF5 files. 63 */ 64 typedef enum { 65 H5L_TYPE_ERROR = (-1), /* Invalid link type id */ 66 H5L_TYPE_HARD = 0, /* Hard link id */ 67 H5L_TYPE_SOFT = 1, /* Soft link id */ 68 H5L_TYPE_EXTERNAL = 64, /* External link id */ 69 H5L_TYPE_MAX = 255 /* Maximum link type id */ 70 } H5L_type_t; 71 #define H5L_TYPE_BUILTIN_MAX H5L_TYPE_SOFT /* Maximum value link value for "built-in" link types */ 72 #define H5L_TYPE_UD_MIN H5L_TYPE_EXTERNAL /* Link ids at or above this value are "user-defined" link types. */ 73 74 /* Information struct for link (for H5Lget_info/H5Lget_info_by_idx) */ 75 typedef struct { 76 H5L_type_t type; /* Type of link */ 77 hbool_t corder_valid; /* Indicate if creation order is valid */ 78 int64_t corder; /* Creation order */ 79 H5T_cset_t cset; /* Character set of link name */ 80 union { 81 haddr_t address; /* Address hard link points to */ 82 size_t val_size; /* Size of a soft link or UD link value */ 83 } u; 84 } H5L_info_t; 85 86 /* The H5L_class_t struct can be used to override the behavior of a 87 * "user-defined" link class. Users should populate the struct with callback 88 * functions defined below. 89 */ 90 /* Callback prototypes for user-defined links */ 91 /* Link creation callback */ 92 typedef herr_t (*H5L_create_func_t)(const char *link_name, hid_t loc_group, 93 const void *lnkdata, size_t lnkdata_size, hid_t lcpl_id); 94 95 /* Callback for when the link is moved */ 96 typedef herr_t (*H5L_move_func_t)(const char *new_name, hid_t new_loc, 97 const void *lnkdata, size_t lnkdata_size); 98 99 /* Callback for when the link is copied */ 100 typedef herr_t (*H5L_copy_func_t)(const char *new_name, hid_t new_loc, 101 const void *lnkdata, size_t lnkdata_size); 102 103 /* Callback during link traversal */ 104 typedef herr_t (*H5L_traverse_func_t)(const char *link_name, hid_t cur_group, 105 const void *lnkdata, size_t lnkdata_size, hid_t lapl_id); 106 107 /* Callback for when the link is deleted */ 108 typedef herr_t (*H5L_delete_func_t)(const char *link_name, hid_t file, 109 const void *lnkdata, size_t lnkdata_size); 110 111 /* Callback for querying the link */ 112 /* Returns the size of the buffer needed */ 113 typedef ssize_t (*H5L_query_func_t)(const char *link_name, const void *lnkdata, 114 size_t lnkdata_size, void *buf /*out*/, size_t buf_size); 115 116 /* User-defined link types */ 117 typedef struct { 118 int version; /* Version number of this struct */ 119 H5L_type_t id; /* Link type ID */ 120 const char *comment; /* Comment for debugging */ 121 H5L_create_func_t create_func; /* Callback during link creation */ 122 H5L_move_func_t move_func; /* Callback after moving link */ 123 H5L_copy_func_t copy_func; /* Callback after copying link */ 124 H5L_traverse_func_t trav_func; /* Callback during link traversal */ 125 H5L_delete_func_t del_func; /* Callback for link deletion */ 126 H5L_query_func_t query_func; /* Callback for queries */ 127 } H5L_class_t; 128 129 /* Prototype for H5Literate/H5Literate_by_name() operator */ 130 typedef herr_t (*H5L_iterate_t)(hid_t group, const char *name, const H5L_info_t *info, 131 void *op_data); 132 133 /* Callback for external link traversal */ 134 typedef herr_t (*H5L_elink_traverse_t)(const char *parent_file_name, 135 const char *parent_group_name, const char *child_file_name, 136 const char *child_object_name, unsigned *acc_flags, hid_t fapl_id, 137 void *op_data); 138 139 140 /********************/ 141 /* Public Variables */ 142 /********************/ 143 144 145 /*********************/ 146 /* Public Prototypes */ 147 /*********************/ 148 H5_DLL herr_t H5Lmove(hid_t src_loc, const char *src_name, hid_t dst_loc, 149 const char *dst_name, hid_t lcpl_id, hid_t lapl_id); 150 H5_DLL herr_t H5Lcopy(hid_t src_loc, const char *src_name, hid_t dst_loc, 151 const char *dst_name, hid_t lcpl_id, hid_t lapl_id); 152 H5_DLL herr_t H5Lcreate_hard(hid_t cur_loc, const char *cur_name, 153 hid_t dst_loc, const char *dst_name, hid_t lcpl_id, hid_t lapl_id); 154 H5_DLL herr_t H5Lcreate_soft(const char *link_target, hid_t link_loc_id, 155 const char *link_name, hid_t lcpl_id, hid_t lapl_id); 156 H5_DLL herr_t H5Ldelete(hid_t loc_id, const char *name, hid_t lapl_id); 157 H5_DLL herr_t H5Ldelete_by_idx(hid_t loc_id, const char *group_name, 158 H5_index_t idx_type, H5_iter_order_t order, hsize_t n, hid_t lapl_id); 159 H5_DLL herr_t H5Lget_val(hid_t loc_id, const char *name, void *buf/*out*/, 160 size_t size, hid_t lapl_id); 161 H5_DLL herr_t H5Lget_val_by_idx(hid_t loc_id, const char *group_name, 162 H5_index_t idx_type, H5_iter_order_t order, hsize_t n, 163 void *buf/*out*/, size_t size, hid_t lapl_id); 164 H5_DLL htri_t H5Lexists(hid_t loc_id, const char *name, hid_t lapl_id); 165 H5_DLL herr_t H5Lget_info(hid_t loc_id, const char *name, 166 H5L_info_t *linfo /*out*/, hid_t lapl_id); 167 H5_DLL herr_t H5Lget_info_by_idx(hid_t loc_id, const char *group_name, 168 H5_index_t idx_type, H5_iter_order_t order, hsize_t n, 169 H5L_info_t *linfo /*out*/, hid_t lapl_id); 170 H5_DLL ssize_t H5Lget_name_by_idx(hid_t loc_id, const char *group_name, 171 H5_index_t idx_type, H5_iter_order_t order, hsize_t n, 172 char *name /*out*/, size_t size, hid_t lapl_id); 173 H5_DLL herr_t H5Literate(hid_t grp_id, H5_index_t idx_type, 174 H5_iter_order_t order, hsize_t *idx, H5L_iterate_t op, void *op_data); 175 H5_DLL herr_t H5Literate_by_name(hid_t loc_id, const char *group_name, 176 H5_index_t idx_type, H5_iter_order_t order, hsize_t *idx, 177 H5L_iterate_t op, void *op_data, hid_t lapl_id); 178 H5_DLL herr_t H5Lvisit(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, 179 H5L_iterate_t op, void *op_data); 180 H5_DLL herr_t H5Lvisit_by_name(hid_t loc_id, const char *group_name, 181 H5_index_t idx_type, H5_iter_order_t order, H5L_iterate_t op, 182 void *op_data, hid_t lapl_id); 183 184 /* UD link functions */ 185 H5_DLL herr_t H5Lcreate_ud(hid_t link_loc_id, const char *link_name, 186 H5L_type_t link_type, const void *udata, size_t udata_size, hid_t lcpl_id, 187 hid_t lapl_id); 188 H5_DLL herr_t H5Lregister(const H5L_class_t *cls); 189 H5_DLL herr_t H5Lunregister(H5L_type_t id); 190 H5_DLL htri_t H5Lis_registered(H5L_type_t id); 191 192 /* External link functions */ 193 H5_DLL herr_t H5Lunpack_elink_val(const void *ext_linkval/*in*/, size_t link_size, 194 unsigned *flags, const char **filename/*out*/, const char **obj_path /*out*/); 195 H5_DLL herr_t H5Lcreate_external(const char *file_name, const char *obj_name, 196 hid_t link_loc_id, const char *link_name, hid_t lcpl_id, hid_t lapl_id); 197 198 #ifdef __cplusplus 199 } 200 #endif 201 #endif /* _H5Lpublic_H */ 202 203