H5Lpublic.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:             H5Lpublic.h
00019  *                      Dec 1 2005
00020  *                      James Laird
00021  *
00022  * Purpose:             Public declarations for the H5L package (links)
00023  *
00024  *-------------------------------------------------------------------------
00025  */
00026 #ifndef _H5Lpublic_H
00027 #define _H5Lpublic_H
00028 
00029 /* Public headers needed by this file */
00030 #include "H5public.h"           /* Generic Functions                    */
00031 #include "H5Ipublic.h"          /* IDs                                  */
00032 #include "H5Tpublic.h"          /* Datatypes                            */
00033 
00034 /*****************/
00035 /* Public Macros */
00036 /*****************/
00037 
00038 /* Maximum length of a link's name */
00039 /* (encoded in a 32-bit unsigned integer) */
00040 #define H5L_MAX_LINK_NAME_LEN   ((uint32_t)(-1))  /* (4GB - 1) */
00041 
00042 /* Macro to indicate operation occurs on same location */
00043 #define H5L_SAME_LOC 0
00044 
00045 /* Current version of the H5L_class_t struct */
00046 #define H5L_LINK_CLASS_T_VERS 0
00047 
00048 #ifdef __cplusplus
00049 extern "C" {
00050 #endif
00051 
00052 /*******************/
00053 /* Public Typedefs */
00054 /*******************/
00055 
00056 /* Link class types.
00057  * Values less than 64 are reserved for the HDF5 library's internal use.
00058  * Values 64 to 255 are for "user-defined" link class types; these types are
00059  * defined by HDF5 but their behavior can be overridden by users.
00060  * Users who want to create new classes of links should contact the HDF5
00061  * development team at hdfhelp@ncsa.uiuc.edu .
00062  * These values can never change because they appear in HDF5 files.
00063  */
00064 typedef enum {
00065     H5L_TYPE_ERROR = (-1),      /* Invalid link type id         */
00066     H5L_TYPE_HARD = 0,          /* Hard link id                 */
00067     H5L_TYPE_SOFT = 1,          /* Soft link id                 */
00068     H5L_TYPE_EXTERNAL = 64,     /* External link id             */
00069     H5L_TYPE_MAX = 255          /* Maximum link type id         */
00070 } H5L_type_t;
00071 #define H5L_TYPE_BUILTIN_MAX H5L_TYPE_SOFT      /* Maximum value link value for "built-in" link types */
00072 #define H5L_TYPE_UD_MIN      H5L_TYPE_EXTERNAL  /* Link ids at or above this value are "user-defined" link types. */
00073 
00074 /* Information struct for link (for H5Lget_info/H5Lget_info_by_idx) */
00075 typedef struct {
00076     H5L_type_t          type;           /* Type of link                   */
00077     hbool_t             corder_valid;   /* Indicate if creation order is valid */
00078     int64_t             corder;         /* Creation order                 */
00079     H5T_cset_t          cset;           /* Character set of link name     */
00080     union {
00081         haddr_t         address;        /* Address hard link points to    */
00082         size_t          val_size;       /* Size of a soft link or UD link value */
00083     } u;
00084 } H5L_info_t;
00085 
00086 /* The H5L_class_t struct can be used to override the behavior of a
00087  * "user-defined" link class. Users should populate the struct with callback
00088  * functions defined below.
00089  */
00090 /* Callback prototypes for user-defined links */
00091 /* Link creation callback */
00092 typedef herr_t (*H5L_create_func_t)(const char *link_name, hid_t loc_group,
00093     const void *lnkdata, size_t lnkdata_size, hid_t lcpl_id);
00094 
00095 /* Callback for when the link is moved */
00096 typedef herr_t (*H5L_move_func_t)(const char *new_name, hid_t new_loc,
00097     const void *lnkdata, size_t lnkdata_size);
00098 
00099 /* Callback for when the link is copied */
00100 typedef herr_t (*H5L_copy_func_t)(const char *new_name, hid_t new_loc,
00101     const void *lnkdata, size_t lnkdata_size);
00102 
00103 /* Callback during link traversal */
00104 typedef herr_t (*H5L_traverse_func_t)(const char *link_name, hid_t cur_group,
00105     const void *lnkdata, size_t lnkdata_size, hid_t lapl_id);
00106 
00107 /* Callback for when the link is deleted */
00108 typedef herr_t (*H5L_delete_func_t)(const char *link_name, hid_t file,
00109     const void *lnkdata, size_t lnkdata_size);
00110 
00111 /* Callback for querying the link */
00112 /* Returns the size of the buffer needed */
00113 typedef ssize_t (*H5L_query_func_t)(const char *link_name, const void *lnkdata,
00114     size_t lnkdata_size, void *buf /*out*/, size_t buf_size);
00115 
00116 /* User-defined link types */
00117 typedef struct {
00118     int version;                    /* Version number of this struct        */
00119     H5L_type_t id;                  /* Link type ID                         */
00120     const char *comment;            /* Comment for debugging                */
00121     H5L_create_func_t create_func;  /* Callback during link creation        */
00122     H5L_move_func_t move_func;      /* Callback after moving link           */
00123     H5L_copy_func_t copy_func;      /* Callback after copying link          */
00124     H5L_traverse_func_t trav_func;  /* Callback during link traversal       */
00125     H5L_delete_func_t del_func;     /* Callback for link deletion           */
00126     H5L_query_func_t query_func;    /* Callback for queries                 */
00127 } H5L_class_t;
00128 
00129 /* Prototype for H5Literate/H5Literate_by_name() operator */
00130 typedef herr_t (*H5L_iterate_t)(hid_t group, const char *name, const H5L_info_t *info,
00131     void *op_data);
00132 
00133 /* Callback for external link traversal */
00134 typedef herr_t (*H5L_elink_traverse_t)(const char *parent_file_name,
00135     const char *parent_group_name, const char *child_file_name,
00136     const char *child_object_name, unsigned *acc_flags, hid_t fapl_id,
00137     void *op_data);
00138 
00139 
00140 /********************/
00141 /* Public Variables */
00142 /********************/
00143 
00144 
00145 /*********************/
00146 /* Public Prototypes */
00147 /*********************/
00148 H5_DLL herr_t H5Lmove(hid_t src_loc, const char *src_name, hid_t dst_loc,
00149     const char *dst_name, hid_t lcpl_id, hid_t lapl_id);
00150 H5_DLL herr_t H5Lcopy(hid_t src_loc, const char *src_name, hid_t dst_loc,
00151     const char *dst_name, hid_t lcpl_id, hid_t lapl_id);
00152 H5_DLL herr_t H5Lcreate_hard(hid_t cur_loc, const char *cur_name,
00153     hid_t dst_loc, const char *dst_name, hid_t lcpl_id, hid_t lapl_id);
00154 H5_DLL herr_t H5Lcreate_soft(const char *link_target, hid_t link_loc_id,
00155     const char *link_name, hid_t lcpl_id, hid_t lapl_id);
00156 H5_DLL herr_t H5Ldelete(hid_t loc_id, const char *name, hid_t lapl_id);
00157 H5_DLL herr_t H5Ldelete_by_idx(hid_t loc_id, const char *group_name,
00158     H5_index_t idx_type, H5_iter_order_t order, hsize_t n, hid_t lapl_id);
00159 H5_DLL herr_t H5Lget_val(hid_t loc_id, const char *name, void *buf/*out*/,
00160     size_t size, hid_t lapl_id);
00161 H5_DLL herr_t H5Lget_val_by_idx(hid_t loc_id, const char *group_name,
00162     H5_index_t idx_type, H5_iter_order_t order, hsize_t n,
00163     void *buf/*out*/, size_t size, hid_t lapl_id);
00164 H5_DLL htri_t H5Lexists(hid_t loc_id, const char *name, hid_t lapl_id);
00165 H5_DLL herr_t H5Lget_info(hid_t loc_id, const char *name,
00166     H5L_info_t *linfo /*out*/, hid_t lapl_id);
00167 H5_DLL herr_t H5Lget_info_by_idx(hid_t loc_id, const char *group_name,
00168     H5_index_t idx_type, H5_iter_order_t order, hsize_t n,
00169     H5L_info_t *linfo /*out*/, hid_t lapl_id);
00170 H5_DLL ssize_t H5Lget_name_by_idx(hid_t loc_id, const char *group_name,
00171     H5_index_t idx_type, H5_iter_order_t order, hsize_t n,
00172     char *name /*out*/, size_t size, hid_t lapl_id);
00173 H5_DLL herr_t H5Literate(hid_t grp_id, H5_index_t idx_type,
00174     H5_iter_order_t order, hsize_t *idx, H5L_iterate_t op, void *op_data);
00175 H5_DLL herr_t H5Literate_by_name(hid_t loc_id, const char *group_name,
00176     H5_index_t idx_type, H5_iter_order_t order, hsize_t *idx,
00177     H5L_iterate_t op, void *op_data, hid_t lapl_id);
00178 H5_DLL herr_t H5Lvisit(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order,
00179     H5L_iterate_t op, void *op_data);
00180 H5_DLL herr_t H5Lvisit_by_name(hid_t loc_id, const char *group_name,
00181     H5_index_t idx_type, H5_iter_order_t order, H5L_iterate_t op,
00182     void *op_data, hid_t lapl_id);
00183 
00184 /* UD link functions */
00185 H5_DLL herr_t H5Lcreate_ud(hid_t link_loc_id, const char *link_name,
00186     H5L_type_t link_type, const void *udata, size_t udata_size, hid_t lcpl_id,
00187     hid_t lapl_id);
00188 H5_DLL herr_t H5Lregister(const H5L_class_t *cls);
00189 H5_DLL herr_t H5Lunregister(H5L_type_t id);
00190 H5_DLL htri_t H5Lis_registered(H5L_type_t id);
00191 
00192 /* External link functions */
00193 H5_DLL herr_t H5Lunpack_elink_val(const void *ext_linkval/*in*/, size_t link_size,
00194    unsigned *flags, const char **filename/*out*/, const char **obj_path /*out*/);
00195 H5_DLL herr_t H5Lcreate_external(const char *file_name, const char *obj_name,
00196     hid_t link_loc_id, const char *link_name, hid_t lcpl_id, hid_t lapl_id);
00197 
00198 #ifdef __cplusplus
00199 }
00200 #endif
00201 #endif /* _H5Lpublic_H */
00202