HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
H5Lpublic.h
Go to the documentation of this file.
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);
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 
H5T_cset_t cset
Definition: H5Lpublic.h:79
H5_DLL herr_t H5Lcopy(hid_t src_loc, const char *src_name, hid_t dst_loc, const char *dst_name, hid_t lcpl_id, hid_t lapl_id)
GT_API const UT_StringHolder filename
unsigned int hbool_t
Definition: H5public.h:125
H5L_type_t id
Definition: H5Lpublic.h:119
H5_DLL herr_t H5Lget_info(hid_t loc_id, const char *name, H5L_info_t *linfo, hid_t lapl_id)
H5_index_t
Definition: H5public.h:289
#define H5_DLL
Definition: H5api_adpt.h:406
int herr_t
Definition: H5public.h:107
H5_DLL htri_t H5Lis_registered(H5L_type_t id)
GLbitfield flags
Definition: glcorearb.h:1595
H5_DLL herr_t H5Lvisit(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, H5L_iterate_t op, void *op_data)
haddr_t address
Definition: H5Lpublic.h:81
unsigned long long hsize_t
Definition: H5public.h:151
H5_DLL herr_t H5Lunregister(H5L_type_t id)
H5_DLL ssize_t H5Lget_name_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, char *name, size_t size, hid_t lapl_id)
GLsizeiptr size
Definition: glcorearb.h:663
H5_DLL herr_t H5Lcreate_external(const char *file_name, const char *obj_name, hid_t link_loc_id, const char *link_name, hid_t lcpl_id, hid_t lapl_id)
H5_DLL htri_t H5Lexists(hid_t loc_id, const char *name, hid_t lapl_id)
herr_t(* H5L_copy_func_t)(const char *new_name, hid_t new_loc, const void *lnkdata, size_t lnkdata_size)
Definition: H5Lpublic.h:100
int64_t corder
Definition: H5Lpublic.h:78
GLdouble n
Definition: glcorearb.h:2007
size_t val_size
Definition: H5Lpublic.h:82
uint64_t haddr_t
Definition: H5public.h:163
H5L_copy_func_t copy_func
Definition: H5Lpublic.h:123
H5_DLL herr_t H5Lget_val(hid_t loc_id, const char *name, void *buf, size_t size, hid_t lapl_id)
H5_DLL herr_t H5Lcreate_ud(hid_t link_loc_id, const char *link_name, H5L_type_t link_type, const void *udata, size_t udata_size, hid_t lcpl_id, hid_t lapl_id)
H5_DLL herr_t H5Lmove(hid_t src_loc, const char *src_name, hid_t dst_loc, const char *dst_name, hid_t lcpl_id, hid_t lapl_id)
H5T_cset_t
Definition: H5Tpublic.h:80
H5_DLL herr_t H5Lget_val_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, void *buf, size_t size, hid_t lapl_id)
H5_iter_order_t
Definition: H5public.h:268
H5_DLL herr_t H5Literate(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, hsize_t *idx, H5L_iterate_t op, void *op_data)
H5_DLL herr_t H5Lregister(const H5L_class_t *cls)
H5_DLL herr_t H5Ldelete(hid_t loc_id, const char *name, hid_t lapl_id)
int hid_t
Definition: H5Ipublic.h:56
GLuint const GLchar * name
Definition: glcorearb.h:785
herr_t(* H5L_move_func_t)(const char *new_name, hid_t new_loc, const void *lnkdata, size_t lnkdata_size)
Definition: H5Lpublic.h:96
herr_t(* H5L_delete_func_t)(const char *link_name, hid_t file, const void *lnkdata, size_t lnkdata_size)
Definition: H5Lpublic.h:108
H5_DLL herr_t H5Lunpack_elink_val(const void *ext_linkval, size_t link_size, unsigned *flags, const char **filename, const char **obj_path)
H5_DLL herr_t H5Lcreate_hard(hid_t cur_loc, const char *cur_name, hid_t dst_loc, const char *dst_name, hid_t lcpl_id, hid_t lapl_id)
herr_t(* H5L_elink_traverse_t)(const char *parent_file_name, const char *parent_group_name, const char *child_file_name, const char *child_object_name, unsigned *acc_flags, hid_t fapl_id, void *op_data)
Definition: H5Lpublic.h:134
GLenum GLuint GLenum GLsizei const GLchar * buf
Definition: glcorearb.h:2539
H5_DLL herr_t H5Lvisit_by_name(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, H5L_iterate_t op, void *op_data, hid_t lapl_id)
herr_t(* H5L_iterate_t)(hid_t group, const char *name, const H5L_info_t *info, void *op_data)
Definition: H5Lpublic.h:130
H5L_traverse_func_t trav_func
Definition: H5Lpublic.h:124
const char * comment
Definition: H5Lpublic.h:120
H5L_type_t
Definition: H5Lpublic.h:64
hbool_t corder_valid
Definition: H5Lpublic.h:77
ssize_t(* H5L_query_func_t)(const char *link_name, const void *lnkdata, size_t lnkdata_size, void *buf, size_t buf_size)
Definition: H5Lpublic.h:113
H5L_create_func_t create_func
Definition: H5Lpublic.h:121
H5L_move_func_t move_func
Definition: H5Lpublic.h:122
H5_DLL herr_t H5Lcreate_soft(const char *link_target, hid_t link_loc_id, const char *link_name, hid_t lcpl_id, hid_t lapl_id)
H5_DLL herr_t H5Ldelete_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, hid_t lapl_id)
H5L_query_func_t query_func
Definition: H5Lpublic.h:126
herr_t(* H5L_create_func_t)(const char *link_name, hid_t loc_group, const void *lnkdata, size_t lnkdata_size, hid_t lcpl_id)
Definition: H5Lpublic.h:92
int htri_t
Definition: H5public.h:126
H5L_type_t type
Definition: H5Lpublic.h:76
H5_DLL herr_t H5Literate_by_name(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t *idx, H5L_iterate_t op, void *op_data, hid_t lapl_id)
herr_t(* H5L_traverse_func_t)(const char *link_name, hid_t cur_group, const void *lnkdata, size_t lnkdata_size, hid_t lapl_id)
Definition: H5Lpublic.h:104
H5L_delete_func_t del_func
Definition: H5Lpublic.h:125
H5_DLL herr_t H5Lget_info_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5L_info_t *linfo, hid_t lapl_id)