H5Epublic.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  * This file contains public declarations for the H5E module.
00018  */
00019 #ifndef _H5Epublic_H
00020 #define _H5Epublic_H
00021 
00022 #include <stdio.h>              /*FILE arg of H5Eprint()                     */
00023 
00024 /* Public headers needed by this file */
00025 #include "H5public.h"
00026 #include "H5Ipublic.h"
00027 
00028 /* Value for the default error stack */
00029 #define H5E_DEFAULT             0
00030 
00031 /* Different kinds of error information */
00032 typedef enum H5E_type_t {
00033     H5E_MAJOR,
00034     H5E_MINOR
00035 } H5E_type_t;
00036 
00037 /* Information about an error; element of error stack */
00038 typedef struct H5E_error2_t {
00039     hid_t       cls_id;         /*class ID                           */
00040     hid_t       maj_num;        /*major error ID                     */
00041     hid_t       min_num;        /*minor error number                 */
00042     unsigned    line;           /*line in file where error occurs    */
00043     const char  *func_name;     /*function in which error occurred   */
00044     const char  *file_name;     /*file in which error occurred       */
00045     const char  *desc;          /*optional supplied description      */
00046 } H5E_error2_t;
00047 
00048 /* When this header is included from a private header, don't make calls to H5open() */
00049 #undef H5OPEN
00050 #ifndef _H5private_H
00051 #define H5OPEN          H5open(),
00052 #else   /* _H5private_H */
00053 #define H5OPEN
00054 #endif  /* _H5private_H */
00055 
00056 /* HDF5 error class */
00057 #define H5E_ERR_CLS             (H5OPEN H5E_ERR_CLS_g)
00058 H5_DLLVAR hid_t H5E_ERR_CLS_g;
00059 
00060 /* Include the automatically generated public header information */
00061 /* (This includes the list of major and minor error codes for the library) */
00062 #include "H5Epubgen.h"
00063 
00064 /*
00065  * One often needs to temporarily disable automatic error reporting when
00066  * trying something that's likely or expected to fail.  The code to try can
00067  * be nested between calls to H5Eget_auto() and H5Eset_auto(), but it's
00068  * easier just to use this macro like:
00069  *      H5E_BEGIN_TRY {
00070  *          ...stuff here that's likely to fail...
00071  *      } H5E_END_TRY;
00072  *
00073  * Warning: don't break, return, or longjmp() from the body of the loop or
00074  *          the error reporting won't be properly restored!
00075  *
00076  * These two macros still use the old API functions for backward compatibility
00077  * purpose.
00078  */
00079 #ifndef H5_NO_DEPRECATED_SYMBOLS
00080 #define H5E_BEGIN_TRY {                                                       \
00081     unsigned H5E_saved_is_v2;                                                 \
00082     union {                                                                   \
00083         H5E_auto1_t efunc1;                                                   \
00084         H5E_auto2_t efunc2;                                                   \
00085     } H5E_saved;                                                              \
00086     void *H5E_saved_edata;                                                    \
00087                                                                               \
00088     (void)H5Eauto_is_v2(H5E_DEFAULT, &H5E_saved_is_v2);                       \
00089     if(H5E_saved_is_v2) {                                                     \
00090         (void)H5Eget_auto2(H5E_DEFAULT, &H5E_saved.efunc2, &H5E_saved_edata); \
00091         (void)H5Eset_auto2(H5E_DEFAULT, NULL, NULL);                          \
00092     } else {                                                                  \
00093         (void)H5Eget_auto1(&H5E_saved.efunc1, &H5E_saved_edata);                      \
00094         (void)H5Eset_auto1(NULL, NULL);                                       \
00095     }
00096 
00097 #define H5E_END_TRY                                                           \
00098     if(H5E_saved_is_v2)                                                       \
00099         (void)H5Eset_auto2(H5E_DEFAULT, H5E_saved.efunc2, H5E_saved_edata);   \
00100     else                                                                      \
00101         (void)H5Eset_auto1(H5E_saved.efunc1, H5E_saved_edata);                \
00102 }
00103 #else /* H5_NO_DEPRECATED_SYMBOLS */
00104 #define H5E_BEGIN_TRY {                                                       \
00105     H5E_auto_t saved_efunc;                                                   \
00106     void *H5E_saved_edata;                                                    \
00107                                                                               \
00108     (void)H5Eget_auto(H5E_DEFAULT, &saved_efunc, &H5E_saved_edata);           \
00109     (void)H5Eset_auto(H5E_DEFAULT, NULL, NULL);
00110 
00111 #define H5E_END_TRY                                                           \
00112     (void)H5Eset_auto(H5E_DEFAULT, saved_efunc, H5E_saved_edata);             \
00113 }
00114 #endif /* H5_NO_DEPRECATED_SYMBOLS */
00115 
00116 /*
00117  * Public API Convenience Macros for Error reporting - Documented
00118  */
00119 /* Use the Standard C __FILE__ & __LINE__ macros instead of typing them in */
00120 #define H5Epush_sim(func, cls, maj, min, str) H5Epush2(H5E_DEFAULT, __FILE__, func, __LINE__, cls, maj, min, str)
00121 
00122 /*
00123  * Public API Convenience Macros for Error reporting - Undocumented
00124  */
00125 /* Use the Standard C __FILE__ & __LINE__ macros instead of typing them in */
00126 /*  And return after pushing error onto stack */
00127 #define H5Epush_ret(func, cls, maj, min, str, ret) {                          \
00128     H5Epush2(H5E_DEFAULT, __FILE__, func, __LINE__, cls, maj, min, str);      \
00129     return(ret);                                                              \
00130 }
00131 
00132 /* Use the Standard C __FILE__ & __LINE__ macros instead of typing them in
00133  * And goto a label after pushing error onto stack.
00134  */
00135 #define H5Epush_goto(func, cls, maj, min, str, label) {                       \
00136     H5Epush2(H5E_DEFAULT, __FILE__, func, __LINE__, cls, maj, min, str);      \
00137     goto label;                                                               \
00138 }
00139 
00140 /* Error stack traversal direction */
00141 typedef enum H5E_direction_t {
00142     H5E_WALK_UPWARD     = 0,            /*begin deep, end at API function    */
00143     H5E_WALK_DOWNWARD   = 1             /*begin at API function, end deep    */
00144 } H5E_direction_t;
00145 
00146 
00147 #ifdef __cplusplus
00148 extern "C" {
00149 #endif
00150 
00151 /* Error stack traversal callback function pointers */
00152 typedef herr_t (*H5E_walk2_t)(unsigned n, const H5E_error2_t *err_desc,
00153     void *client_data);
00154 typedef herr_t (*H5E_auto2_t)(hid_t estack, void *client_data);
00155 
00156 /* Public API functions */
00157 H5_DLL hid_t  H5Eregister_class(const char *cls_name, const char *lib_name,
00158     const char *version);
00159 H5_DLL herr_t H5Eunregister_class(hid_t class_id);
00160 H5_DLL herr_t H5Eclose_msg(hid_t err_id);
00161 H5_DLL hid_t  H5Ecreate_msg(hid_t cls, H5E_type_t msg_type, const char *msg);
00162 H5_DLL hid_t  H5Ecreate_stack(void);
00163 H5_DLL hid_t  H5Eget_current_stack(void);
00164 H5_DLL herr_t H5Eclose_stack(hid_t stack_id);
00165 H5_DLL ssize_t H5Eget_class_name(hid_t class_id, char *name, size_t size);
00166 H5_DLL herr_t H5Eset_current_stack(hid_t err_stack_id);
00167 H5_DLL herr_t H5Epush2(hid_t err_stack, const char *file, const char *func, unsigned line,
00168     hid_t cls_id, hid_t maj_id, hid_t min_id, const char *msg, ...);
00169 H5_DLL herr_t H5Epop(hid_t err_stack, size_t count);
00170 H5_DLL herr_t H5Eprint2(hid_t err_stack, FILE *stream);
00171 H5_DLL herr_t H5Ewalk2(hid_t err_stack, H5E_direction_t direction, H5E_walk2_t func,
00172     void *client_data);
00173 H5_DLL herr_t H5Eget_auto2(hid_t estack_id, H5E_auto2_t *func, void **client_data);
00174 H5_DLL herr_t H5Eset_auto2(hid_t estack_id, H5E_auto2_t func, void *client_data);
00175 H5_DLL herr_t H5Eclear2(hid_t err_stack);
00176 H5_DLL herr_t H5Eauto_is_v2(hid_t err_stack, unsigned *is_stack);
00177 H5_DLL ssize_t H5Eget_msg(hid_t msg_id, H5E_type_t *type, char *msg,
00178     size_t size);
00179 H5_DLL ssize_t H5Eget_num(hid_t error_stack_id);
00180 
00181 
00182 /* Symbols defined for compatibility with previous versions of the HDF5 API.
00183  *
00184  * Use of these symbols is deprecated.
00185  */
00186 #ifndef H5_NO_DEPRECATED_SYMBOLS
00187 
00188 /* Typedefs */
00189 
00190 /* Alias major & minor error types to hid_t's, for compatibility with new
00191  *      error API in v1.8
00192  */
00193 typedef hid_t   H5E_major_t;
00194 typedef hid_t   H5E_minor_t;
00195 
00196 /* Information about an error element of error stack. */
00197 typedef struct H5E_error1_t {
00198     H5E_major_t maj_num;                /*major error number                 */
00199     H5E_minor_t min_num;                /*minor error number                 */
00200     const char  *func_name;             /*function in which error occurred   */
00201     const char  *file_name;             /*file in which error occurred       */
00202     unsigned    line;                   /*line in file where error occurs    */
00203     const char  *desc;                  /*optional supplied description      */
00204 } H5E_error1_t;
00205 
00206 /* Error stack traversal callback function pointers */
00207 typedef herr_t (*H5E_walk1_t)(int n, H5E_error1_t *err_desc, void *client_data);
00208 typedef herr_t (*H5E_auto1_t)(void *client_data);
00209 
00210 /* Function prototypes */
00211 H5_DLL herr_t H5Eclear1(void);
00212 H5_DLL herr_t H5Eget_auto1(H5E_auto1_t *func, void **client_data);
00213 H5_DLL herr_t H5Epush1(const char *file, const char *func, unsigned line,
00214     H5E_major_t maj, H5E_minor_t min, const char *str);
00215 H5_DLL herr_t H5Eprint1(FILE *stream);
00216 H5_DLL herr_t H5Eset_auto1(H5E_auto1_t func, void *client_data);
00217 H5_DLL herr_t H5Ewalk1(H5E_direction_t direction, H5E_walk1_t func,
00218     void *client_data);
00219 H5_DLL char *H5Eget_major(H5E_major_t maj);
00220 H5_DLL char *H5Eget_minor(H5E_minor_t min);
00221 #endif /* H5_NO_DEPRECATED_SYMBOLS */
00222 
00223 #ifdef __cplusplus
00224 }
00225 #endif
00226 
00227 #endif /* end _H5Epublic_H */
00228