source/include/H5PLpublic.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 H5PL module.
0015  */
0016
0017 #ifndef H5PLpublic_H
0018 #define H5PLpublic_H
0019
0020 #include "H5public.h" /* Generic Functions                        */
0021
0022 /*******************/
0023 /* Public Typedefs */
0024 /*******************/
0025
0026 /** Special string to indicate no plugin loading \since 1.10.2 */
0027 #define H5PL_NO_PLUGIN "::"
0028
0029 //! <!-- [H5PL_type_t_snip] -->
0030 /**
0031  * Plugin type (bit-position) used by the plugin library
0032  */
0033 typedef enum H5PL_type_t {
0034     H5PL_TYPE_ERROR  = -1, /**< Error                */
0035     H5PL_TYPE_FILTER = 0,  /**< Filter               */
0036     H5PL_TYPE_VOL    = 1,  /**< VOL connector        */
0037     H5PL_TYPE_VFD    = 2,  /**< VFD                  */
0038     H5PL_TYPE_NONE   = 3   /**< Sentinel: This must be last!   */
0039 } H5PL_type_t;
0040 //! <!-- [H5PL_type_t_snip] -->
0041
0042 /* Common dynamic plugin type flags used by the set/get_loading_state functions */
0043 /** Flag for filter plugin \since 1.8.15 */
0044 #define H5PL_FILTER_PLUGIN 0x0001
0045 /** Flag for VOL plugin \since 1.12.0 */
0046 #define H5PL_VOL_PLUGIN 0x0002
0047 /** Flag for VFD plugin \since 1.14.0 */
0048 #define H5PL_VFD_PLUGIN 0x0004
0049 /** Flag for all plugin types \since 1.8.15 */
0050 #define H5PL_ALL_PLUGIN 0xFFFF
0051
0052 #ifdef __cplusplus
0053 extern "C" {
0054 #endif
0055
0056 /* plugin state */
0057 /**
0058  * \ingroup H5PL
0059  * \brief Controls the loadability of dynamic plugin types
0060  *
0061  * \param[in] plugin_control_mask The list of dynamic plugin types to enable or disable.\n
0062  *                                A plugin bit set to 0 (zero) prevents use of that dynamic plugin.\n
0063  *                                A plugin bit set to 1 (one) enables use of that dynamic plugin.\n
0064  *                                Setting \p plugin_control_mask to a negative value enables all dynamic
0065  *                                plugin types.\n
0066  *                                Setting \p plugin_control_mask to 0 (zero) disables all dynamic plugin\n
0067  *                                types.
0068  * \return \herr_t
0069  *
0070  * \details H5PLset_loading_state() uses one argument to enable or disable individual plugin types.
0071  *
0072  * \details The \p plugin_control_mask parameter is an encoded integer in which each bit controls a specific
0073  *          plugin type. Bit positions allocated to date are specified in \ref H5PL_type_t as follows:
0074  *          \snippet this H5PL_type_t_snip
0075  *
0076  *          A plugin bit set to 0 (zero) prevents the use of the dynamic plugin type corresponding to that bit
0077  *          position. A plugin bit set to 1 (one) allows the use of that dynamic plugin type.
0078  *
0079  *          All dynamic plugin types can be enabled by setting \p plugin_control_mask to a negative value. A
0080  *          value of 0 (zero) will disable all dynamic plugin types.
0081  *
0082  *          The loading of external dynamic plugins can be controlled during runtime with an environment
0083  *          variable, \c HDF5_PLUGIN_PRELOAD. H5PLset_loading_state() inspects the \c HDF5_PLUGIN_PRELOAD
0084  *          environment variable every time it is called. If the environment variable is set to the special
0085  *          \c :: string, all dynamic plugins are disabled.
0086  *
0087  * \warning The environment variable \c HDF5_PLUGIN_PRELOAD controls the loading of dynamic plugin types at
0088  *          runtime. If it is set to disable all plugin types, then it will disable them for \Emph{all}
0089  *          running programs that access the same variable instance.
0090  *
0091  * \since 1.8.15
0092  *
0093  */
0094 H5_DLL herr_t H5PLset_loading_state(unsigned int plugin_control_mask);
0095 /**
0096  * \ingroup H5PL
0097  * \brief Queries the loadability of dynamic plugin types
0098  *
0099  * \param[out] plugin_control_mask List of dynamic plugin types that are enabled or disabled.\n
0100  *                                 A plugin bit set to 0 (zero) indicates that the dynamic plugin type is
0101  *                                 disabled.\n
0102  *                                 A plugin bit set to 1 (one) indicates that the dynamic plugin type is
0103  *                                 enabled.\n
0104  *                                 If the value of \p plugin_control_mask is negative, all dynamic plugin
0105  *                                 types are enabled.\n
0106  *                                 If the value of \p plugin_control_mask is 0 (zero), all dynamic plugins
0107  *                                 are disabled.
0108  * \return \herr_t
0109  *
0110  * \details H5PLget_loading_state() retrieves the bitmask that controls whether a certain type of plugin
0111  *          (e.g.: filters, VOL drivers) will be loaded by the HDF5 library.
0112  *
0113  *          Bit positions allocated to date are specified in \ref H5PL_type_t as follows:
0114  *          \snippet this H5PL_type_t_snip
0115  *
0116  * \since 1.8.15
0117  *
0118  */
0119 H5_DLL herr_t H5PLget_loading_state(unsigned int *plugin_control_mask /*out*/);
0120 /**
0121  * \ingroup H5PL
0122  * \brief Inserts a plugin path at the end of the plugin search path list
0123  *
0124  * \param[in] search_path A plugin path
0125  * \return \herr_t
0126  *
0127  * \details H5PLappend() inserts a plugin path at the end of the plugin search path list.
0128  *
0129  * \since 1.10.1
0130  *
0131  */
0132 H5_DLL herr_t H5PLappend(const char *search_path);
0133 /**
0134  * \ingroup H5PL
0135  * \brief Inserts a plugin path at the beginning of the plugin search path list
0136  *
0137  * \param[in] search_path A plugin path
0138  * \return \herr_t
0139  *
0140  * \details H5PLprepend() inserts a plugin path at the end of the plugin search path list.
0141  *
0142  * \since 1.10.1
0143  *
0144  */
0145 H5_DLL herr_t H5PLprepend(const char *search_path);
0146 /**
0147  * \ingroup H5PL
0148  * \brief Replaces the path at the specified index in the plugin search path list
0149  *
0150  * \param[in] search_path A plugin path
0151  * \param[in] index Index
0152  * \return \herr_t
0153  *
0154  * \details H5PLreplace() replaces a plugin path at the specified index in the plugin search path list.
0155  *
0156  * \since 1.10.1
0157  *
0158  */
0159 H5_DLL herr_t H5PLreplace(const char *search_path, unsigned int index);
0160 /**
0161  * \ingroup H5PL
0162  * \brief Inserts a path at the specified index in the plugin search path list
0163  *
0164  * \param[in] search_path A plugin path
0165  * \param[in] index Index
0166  * \return \herr_t
0167  *
0168  * \details H5PLinsert() inserts a plugin path at the specified index in the plugin search path list,
0169  *          moving other paths after \p index.
0170  *
0171  * \since 1.10.1
0172  *
0173  */
0174 H5_DLL herr_t H5PLinsert(const char *search_path, unsigned int index);
0175 /**
0176  * \ingroup H5PL
0177  * \brief Removes a plugin path at a specified index from the plugin search path list
0178  *
0179  * \param[in] index Index
0180  * \return \herr_t
0181  *
0182  * \details H5PLremove() removes a plugin path at the specified \p index and compacts the plugin search path
0183  *          list.
0184  *
0185  * \since 1.10.1
0186  *
0187  */
0188 H5_DLL herr_t H5PLremove(unsigned int index);
0189 /**
0190  * \ingroup H5PL
0191  * \brief Queries the plugin search path list at the specified index
0192  *
0193  * \param[in] index Index
0194  * \param[out] path_buf Pathname
0195  * \param[in] buf_size Size of \p path_buf
0196  * \return Returns the length of the path, a non-negative value, if successful; otherwise returns a negative
0197  *         value.
0198  *
0199  * \details H5PLget() queries the plugin path at a specified index. If \p path_buf is non-NULL then it writes
0200  *          up to \p buf_size bytes into that buffer and always returns the length of the path name.
0201  *
0202  *          If \p path_buf is NULL, this function will simply return the number of characters required to
0203  *          store the path name, ignoring \p path_buf and \p buf_size.
0204  *
0205  *          If an error occurs then the buffer pointed to by \p path_buf (NULL or non-NULL) is unchanged and
0206  *          the function returns a negative value. If a zero is returned for the name's length, then there is
0207  *          no path name associated with the index. and the \p path_buf buffer will be unchanged.
0208  *
0209  * \since 1.10.1
0210  *
0211  */
0212 H5_DLL ssize_t H5PLget(unsigned int index, char *path_buf /*out*/, size_t buf_size);
0213 /**
0214  * \ingroup H5PL
0215  * \brief Retrieves the number of stored plugin paths
0216  *
0217  * \param[out] num_paths Current length of the plugin search path list
0218  * \return \herr_t
0219  *
0220  * \details H5PLsize() retrieves the number of paths stored in the plugin search path list.
0221  *
0222  * \since 1.10.1
0223  *
0224  */
0225 H5_DLL herr_t H5PLsize(unsigned int *num_paths /*out*/);
0226
0227 #ifdef __cplusplus
0228 }
0229 #endif
0230
0231 #endif /* H5PLpublic_H */