source/include/H5Tdevelop.h

0001 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
0002  * Copyright by The HDF Group.                                               *
0003  * All rights reserved.                                                      *
0004  *                                                                           *
0005  * This file is part of HDF5.  The full HDF5 copyright notice, including     *
0006  * terms governing use, modification, and redistribution, is contained in    *
0007  * the COPYING file, which can be found at the root of the source code       *
0008  * distribution tree, or in https://www.hdfgroup.org/licenses.               *
0009  * If you do not have access to either file, you may request a copy from     *
0010  * help@hdfgroup.org.                                                        *
0011  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
0012
0013 /*
0014  * This file contains public declarations for the H5T (datatype) developer
0015  *      support routines.
0016  */
0017
0018 #ifndef H5Tdevelop_H
0019 #define H5Tdevelop_H
0020
0021 /* Include package's public header */
0022 #include "H5Tpublic.h"
0023
0024 /*****************/
0025 /* Public Macros */
0026 /*****************/
0027
0028 /*******************/
0029 /* Public Typedefs */
0030 /*******************/
0031
0032 /**
0033  * Commands sent to conversion functions
0034  */
0035 typedef enum H5T_cmd_t {
0036     H5T_CONV_INIT = 0, /**< query and/or initialize private data         */
0037     H5T_CONV_CONV = 1, /**< convert data from source to dest datatype */
0038     H5T_CONV_FREE = 2  /**< function is being removed from path      */
0039 } H5T_cmd_t;
0040
0041 /**
0042  * How is the `bkg' buffer used by the conversion function?
0043  */
0044 typedef enum H5T_bkg_t {
0045     H5T_BKG_NO   = 0, /**< background buffer is not needed, send NULL */
0046     H5T_BKG_TEMP = 1, /**< bkg buffer used as temp storage only       */
0047     H5T_BKG_YES  = 2  /**< init bkg buf with data before conversion   */
0048 } H5T_bkg_t;
0049
0050 /**
0051  * Type conversion client data
0052  */
0053 //! <!-- [H5T_cdata_t_snip] -->
0054 typedef struct H5T_cdata_t {
0055     H5T_cmd_t command;  /**< what should the conversion function do?    */
0056     H5T_bkg_t need_bkg; /**< is the background buffer needed?        */
0057     hbool_t   recalc;   /**< recalculate private data            */
0058     void     *priv;     /**< private data                    */
0059 } H5T_cdata_t;
0060 //! <!-- [H5T_cdata_t_snip] -->
0061
0062 /**
0063  * Conversion function persistence
0064  */
0065 typedef enum H5T_pers_t {
0066     H5T_PERS_DONTCARE = -1, /**< wild card                   */
0067     H5T_PERS_HARD     = 0,  /**< hard conversion function            */
0068     H5T_PERS_SOFT     = 1   /**< soft conversion function            */
0069 } H5T_pers_t;
0070
0071 /**
0072  * All datatype conversion functions are...
0073  */
0074 //! <!-- [H5T_conv_t_snip] -->
0075 typedef herr_t (*H5T_conv_t)(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride,
0076                              size_t bkg_stride, void *buf, void *bkg, hid_t dset_xfer_plist);
0077 //! <!-- [H5T_conv_t_snip] -->
0078
0079 /********************/
0080 /* Public Variables */
0081 /********************/
0082
0083 /*********************/
0084 /* Public Prototypes */
0085 /*********************/
0086
0087 #ifdef __cplusplus
0088 extern "C" {
0089 #endif
0090
0091 /**
0092  * \ingroup CONV
0093  *
0094  * \brief Registers a datatype conversion function
0095  *
0096  * \param[in] pers Conversion function type
0097  * \param[in] name Name displayed in diagnostic output
0098  * \type_id{src_id} of source datatype
0099  * \type_id{dst_id} of destination datatype
0100  * \param[in] func Function to convert between source and destination datatypes
0101  *
0102  * \return \herr_t
0103  *
0104  * \details H5Tregister() registers a hard or soft conversion function for a
0105  *          datatype conversion path. The parameter \p pers indicates whether a
0106  *          conversion function is hard (#H5T_PERS_HARD) or soft
0107  *          (#H5T_PERS_SOFT). User-defined functions employing compiler casting
0108  *          are designated as \Emph{hard}; other user-defined conversion
0109  *          functions registered with the HDF5 library (with H5Tregister() )
0110  *          are designated as \Emph{soft}. The HDF5 library also has its own
0111  *          hard and soft conversion functions.
0112  *
0113  *          A conversion path can have only one hard function. When type is
0114  *          #H5T_PERS_HARD, \p func replaces any previous hard function.
0115  *
0116  *          When type is #H5T_PERS_SOFT, H5Tregister() adds the function to the
0117  *          end of the master soft list and replaces the soft function in all
0118  *          applicable existing conversion paths. Soft functions are used when
0119  *          determining which conversion function is appropriate for this path.
0120  *
0121  *          The \p name is used only for debugging and should be a short
0122  *          identifier for the function.
0123  *
0124  *          The path is specified by the source and destination datatypes \p
0125  *          src_id and \p dst_id. For soft conversion functions, only the class
0126  *          of these types is important.
0127  *
0128  *          The type of the conversion function pointer is declared as:
0129  *          \snippet this H5T_conv_t_snip
0130  *
0131  *          The \ref H5T_cdata_t \c struct is declared as:
0132  *          \snippet this H5T_cdata_t_snip
0133  *
0134  * \since 1.6.3 The following change occurred in the \ref H5T_conv_t function:
0135  *              the \c nelmts parameter type changed to size_t.
0136  *
0137  */
0138 H5_DLL herr_t H5Tregister(H5T_pers_t pers, const char *name, hid_t src_id, hid_t dst_id, H5T_conv_t func);
0139 /**
0140  * \ingroup CONV
0141  *
0142  * \brief Removes a conversion function
0143  *
0144  * \param[in] pers Conversion function type
0145  * \param[in] name Name displayed in diagnostic output
0146  * \type_id{src_id} of source datatype
0147  * \type_id{dst_id} of destination datatype
0148  * \param[in] func Function to convert between source and destination datatypes
0149  *
0150  * \return \herr_t
0151  *
0152  * \details H5Tunregister() removes a conversion function matching criteria
0153  *          such as soft or hard conversion, source and destination types, and
0154  *          the conversion function.
0155  *
0156  *          If a user is trying to remove a conversion function he registered,
0157  *          all parameters can be used. If he is trying to remove a library's
0158  *          default conversion function, there is no guarantee the \p name and
0159  *          \p func parameters will match the user's chosen values. Passing in
0160  *          some values may cause this function to fail. A good practice is to
0161  *          pass in NULL as their values.
0162  *
0163  *          All parameters are optional. The missing parameters will be used to
0164  *          generalize the search criteria.
0165  *
0166  *          The conversion function pointer type declaration is described in
0167  *          H5Tregister().
0168  *
0169  * \version 1.6.3 The following change occurred in the \ref H5T_conv_t function:
0170  *                the \c nelmts parameter type changed to size_t.
0171  *
0172  */
0173 H5_DLL herr_t H5Tunregister(H5T_pers_t pers, const char *name, hid_t src_id, hid_t dst_id, H5T_conv_t func);
0174 /**
0175  * \ingroup CONV
0176  *
0177  * \brief Finds a conversion function
0178  *
0179  * \type_id{src_id} of source datatype
0180  * \type_id{dst_id} of destination datatype
0181  * \param[out] pcdata Pointer to type conversion data
0182  *
0183  * \return Returns a pointer to a suitable conversion function if successful.
0184  *         Otherwise returns NULL.
0185  *
0186  * \details H5Tfind() finds a conversion function that can handle a conversion
0187  *          from type \p src_id to type \p dst_id. The \p pcdata argument is a
0188  *          pointer to a pointer to type conversion data which was created and
0189  *          initialized by the soft type conversion function of this path when
0190  *          the conversion function was installed on the path.
0191  *
0192  */
0193 H5_DLL H5T_conv_t H5Tfind(hid_t src_id, hid_t dst_id, H5T_cdata_t **pcdata);
0194 /**
0195  * \ingroup CONV
0196  *
0197  * \brief Check whether the library's default conversion is hard conversion
0198  *
0199  * \type_id{src_id} of source datatype
0200  * \type_id{dst_id} of destination datatype
0201  *
0202  * \return \htri_t
0203  *
0204  * \details H5Tcompiler_conv() determines whether the library's conversion
0205  *          function from type \p src_id to type \p dst_id is a compiler (hard)
0206  *          conversion or not. A compiler conversion uses compiler's casting; a
0207  *          library (soft) conversion uses the library's own conversion
0208  *          function.
0209  *
0210  * \since 1.8.0
0211  *
0212  */
0213 H5_DLL htri_t H5Tcompiler_conv(hid_t src_id, hid_t dst_id);
0214
0215 #ifdef __cplusplus
0216 }
0217 #endif
0218
0219 /* Symbols defined for compatibility with previous versions of the HDF5 API.
0220  *
0221  * Use of these symbols is deprecated.
0222  */
0223 #ifndef H5_NO_DEPRECATED_SYMBOLS
0224
0225 #endif /* H5_NO_DEPRECATED_SYMBOLS */
0226
0227 #endif /* H5Tdevelop_H */