/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* 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
*/
//! <!-- [H5T_cdata_t_snip] -->
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;
//! <!-- [H5T_cdata_t_snip] -->
/**
* 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...
*/
//! <!-- [H5T_conv_t_snip] -->
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);
//! <!-- [H5T_conv_t_snip] -->
/********************/
/* 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 */