/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * * terms governing use, modification, and redistribution, is contained in * * the COPYING file, which can be found at the root of the source code * * distribution tree, or in https://www.hdfgroup.org/licenses. * * If you do not have access to either file, you may request a copy from * * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* * This file contains public declarations for the H5T (datatype) developer * support routines. */ #ifndef H5Tdevelop_H #define H5Tdevelop_H /* Include package's public header */ #include "H5Tpublic.h" /*****************/ /* Public Macros */ /*****************/ /*******************/ /* Public Typedefs */ /*******************/ /** * Commands sent to conversion functions */ typedef enum H5T_cmd_t { H5T_CONV_INIT = 0, /**< query and/or initialize private data */ H5T_CONV_CONV = 1, /**< convert data from source to dest datatype */ H5T_CONV_FREE = 2 /**< function is being removed from path */ } H5T_cmd_t; /** * How is the `bkg' buffer used by the conversion function? */ typedef enum H5T_bkg_t { H5T_BKG_NO = 0, /**< background buffer is not needed, send NULL */ H5T_BKG_TEMP = 1, /**< bkg buffer used as temp storage only */ H5T_BKG_YES = 2 /**< init bkg buf with data before conversion */ } H5T_bkg_t; /** * Type conversion client data */ //! typedef struct H5T_cdata_t { H5T_cmd_t command; /**< what should the conversion function do? */ H5T_bkg_t need_bkg; /**< is the background buffer needed? */ hbool_t recalc; /**< recalculate private data */ void *priv; /**< private data */ } H5T_cdata_t; //! /** * Conversion function persistence */ typedef enum H5T_pers_t { H5T_PERS_DONTCARE = -1, /**< wild card */ H5T_PERS_HARD = 0, /**< hard conversion function */ H5T_PERS_SOFT = 1 /**< soft conversion function */ } H5T_pers_t; /** * All datatype conversion functions are... */ //! 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, size_t bkg_stride, void *buf, void *bkg, hid_t dset_xfer_plist); //! /********************/ /* Public Variables */ /********************/ /*********************/ /* Public Prototypes */ /*********************/ #ifdef __cplusplus extern "C" { #endif /** * \ingroup CONV * * \brief Registers a datatype conversion function * * \param[in] pers Conversion function type * \param[in] name Name displayed in diagnostic output * \type_id{src_id} of source datatype * \type_id{dst_id} of destination datatype * \param[in] func Function to convert between source and destination datatypes * * \return \herr_t * * \details H5Tregister() registers a hard or soft conversion function for a * datatype conversion path. The parameter \p pers indicates whether a * conversion function is hard (#H5T_PERS_HARD) or soft * (#H5T_PERS_SOFT). User-defined functions employing compiler casting * are designated as \Emph{hard}; other user-defined conversion * functions registered with the HDF5 library (with H5Tregister() ) * are designated as \Emph{soft}. The HDF5 library also has its own * hard and soft conversion functions. * * A conversion path can have only one hard function. When type is * #H5T_PERS_HARD, \p func replaces any previous hard function. * * When type is #H5T_PERS_SOFT, H5Tregister() adds the function to the * end of the master soft list and replaces the soft function in all * applicable existing conversion paths. Soft functions are used when * determining which conversion function is appropriate for this path. * * The \p name is used only for debugging and should be a short * identifier for the function. * * The path is specified by the source and destination datatypes \p * src_id and \p dst_id. For soft conversion functions, only the class * of these types is important. * * The type of the conversion function pointer is declared as: * \snippet this H5T_conv_t_snip * * The \ref H5T_cdata_t \c struct is declared as: * \snippet this H5T_cdata_t_snip * * \since 1.6.3 The following change occurred in the \ref H5T_conv_t function: * the \c nelmts parameter type changed to size_t. * */ H5_DLL herr_t H5Tregister(H5T_pers_t pers, const char *name, hid_t src_id, hid_t dst_id, H5T_conv_t func); /** * \ingroup CONV * * \brief Removes a conversion function * * \param[in] pers Conversion function type * \param[in] name Name displayed in diagnostic output * \type_id{src_id} of source datatype * \type_id{dst_id} of destination datatype * \param[in] func Function to convert between source and destination datatypes * * \return \herr_t * * \details H5Tunregister() removes a conversion function matching criteria * such as soft or hard conversion, source and destination types, and * the conversion function. * * If a user is trying to remove a conversion function he registered, * all parameters can be used. If he is trying to remove a library’s * default conversion function, there is no guarantee the \p name and * \p func parameters will match the user’s chosen values. Passing in * some values may cause this function to fail. A good practice is to * pass in NULL as their values. * * All parameters are optional. The missing parameters will be used to * generalize the search criteria. * * The conversion function pointer type declaration is described in * H5Tregister(). * * \version 1.6.3 The following change occurred in the \ref H5T_conv_t function: * the \c nelmts parameter type changed to size_t. * */ H5_DLL herr_t H5Tunregister(H5T_pers_t pers, const char *name, hid_t src_id, hid_t dst_id, H5T_conv_t func); /** * \ingroup CONV * * \brief Finds a conversion function * * \type_id{src_id} of source datatype * \type_id{dst_id} of destination datatype * \param[out] pcdata Pointer to type conversion data * * \return Returns a pointer to a suitable conversion function if successful. * Otherwise returns NULL. * * \details H5Tfind() finds a conversion function that can handle a conversion * from type \p src_id to type \p dst_id. The \p pcdata argument is a * pointer to a pointer to type conversion data which was created and * initialized by the soft type conversion function of this path when * the conversion function was installed on the path. * */ H5_DLL H5T_conv_t H5Tfind(hid_t src_id, hid_t dst_id, H5T_cdata_t **pcdata); /** * \ingroup CONV * * \brief Check whether the library’s default conversion is hard conversion * * \type_id{src_id} of source datatype * \type_id{dst_id} of destination datatype * * \return \htri_t * * \details H5Tcompiler_conv() determines whether the library’s conversion * function from type \p src_id to type \p dst_id is a compiler (hard) * conversion or not. A compiler conversion uses compiler’s casting; a * library (soft) conversion uses the library’s own conversion * function. * * \since 1.8.0 * */ H5_DLL htri_t H5Tcompiler_conv(hid_t src_id, hid_t dst_id); #ifdef __cplusplus } #endif /* Symbols defined for compatibility with previous versions of the HDF5 API. * * Use of these symbols is deprecated. */ #ifndef H5_NO_DEPRECATED_SYMBOLS #endif /* H5_NO_DEPRECATED_SYMBOLS */ #endif /* H5Tdevelop_H */