You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
315 lines
13 KiB
C
315 lines
13 KiB
C
3 weeks ago
|
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
|
||
|
|
* 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 H5L (link) developer
|
||
|
|
* support routines.
|
||
|
|
*/
|
||
|
|
|
||
|
|
#ifndef H5Ldevelop_H
|
||
|
|
#define H5Ldevelop_H
|
||
|
|
|
||
|
|
/* Include package's public header */
|
||
|
|
#include "H5Lpublic.h"
|
||
|
|
|
||
|
|
/*****************/
|
||
|
|
/* Public Macros */
|
||
|
|
/*****************/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \brief Current version of the H5L_class_t struct
|
||
|
|
*/
|
||
|
|
#define H5L_LINK_CLASS_T_VERS 1
|
||
|
|
|
||
|
|
/*******************/
|
||
|
|
/* Public Typedefs */
|
||
|
|
/*******************/
|
||
|
|
|
||
|
|
/* The H5L_class_t struct can be used to override the behavior of a
|
||
|
|
* "user-defined" link class. Users should populate the struct with callback
|
||
|
|
* functions defined below.
|
||
|
|
*/
|
||
|
|
/* Callback prototypes for user-defined links */
|
||
|
|
/**
|
||
|
|
* \brief Link creation callback
|
||
|
|
*/
|
||
|
|
typedef herr_t (*H5L_create_func_t)(const char *link_name, hid_t loc_group, const void *lnkdata,
|
||
|
|
size_t lnkdata_size, hid_t lcpl_id);
|
||
|
|
/**
|
||
|
|
* \brief Callback for link move
|
||
|
|
*/
|
||
|
|
typedef herr_t (*H5L_move_func_t)(const char *new_name, hid_t new_loc, const void *lnkdata,
|
||
|
|
size_t lnkdata_size);
|
||
|
|
/**
|
||
|
|
* \brief Callback for link copy
|
||
|
|
*/
|
||
|
|
typedef herr_t (*H5L_copy_func_t)(const char *new_name, hid_t new_loc, const void *lnkdata,
|
||
|
|
size_t lnkdata_size);
|
||
|
|
/**
|
||
|
|
* \brief Callback during link traversal
|
||
|
|
*/
|
||
|
|
typedef hid_t (*H5L_traverse_func_t)(const char *link_name, hid_t cur_group, const void *lnkdata,
|
||
|
|
size_t lnkdata_size, hid_t lapl_id, hid_t dxpl_id);
|
||
|
|
/**
|
||
|
|
* \brief Callback for link deletion
|
||
|
|
*/
|
||
|
|
typedef herr_t (*H5L_delete_func_t)(const char *link_name, hid_t file, const void *lnkdata,
|
||
|
|
size_t lnkdata_size);
|
||
|
|
/**
|
||
|
|
* \brief Callback for querying the link.
|
||
|
|
*
|
||
|
|
* Returns the size of the buffer needed.
|
||
|
|
*/
|
||
|
|
typedef ssize_t (*H5L_query_func_t)(const char *link_name, const void *lnkdata, size_t lnkdata_size,
|
||
|
|
void *buf /*out*/, size_t buf_size);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \brief Link prototype
|
||
|
|
*
|
||
|
|
* The H5L_class_t struct can be used to override the behavior of a
|
||
|
|
* "user-defined" link class. Users should populate the struct with callback
|
||
|
|
* functions defined elsewhere.
|
||
|
|
*/
|
||
|
|
//! <!-- [H5L_class_t_snip] -->
|
||
|
|
typedef struct {
|
||
|
|
int version; /**< Version number of this struct */
|
||
|
|
H5L_type_t id; /**< Link type ID */
|
||
|
|
const char *comment; /**< Comment for debugging */
|
||
|
|
H5L_create_func_t create_func; /**< Callback during link creation */
|
||
|
|
H5L_move_func_t move_func; /**< Callback after moving link */
|
||
|
|
H5L_copy_func_t copy_func; /**< Callback after copying link */
|
||
|
|
H5L_traverse_func_t trav_func; /**< Callback during link traversal */
|
||
|
|
H5L_delete_func_t del_func; /**< Callback for link deletion */
|
||
|
|
H5L_query_func_t query_func; /**< Callback for queries */
|
||
|
|
} H5L_class_t;
|
||
|
|
//! <!-- [H5L_class_t_snip] -->
|
||
|
|
|
||
|
|
/********************/
|
||
|
|
/* Public Variables */
|
||
|
|
/********************/
|
||
|
|
|
||
|
|
/*********************/
|
||
|
|
/* Public Prototypes */
|
||
|
|
/*********************/
|
||
|
|
|
||
|
|
#ifdef __cplusplus
|
||
|
|
extern "C" {
|
||
|
|
#endif
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \ingroup H5LA
|
||
|
|
*
|
||
|
|
* \brief Registers a user-defined link class or changes behavior of an
|
||
|
|
* existing class
|
||
|
|
*
|
||
|
|
* \param[in] cls Pointer to a buffer containing the struct describing the
|
||
|
|
* user-defined link class
|
||
|
|
*
|
||
|
|
* \return \herr_t
|
||
|
|
*
|
||
|
|
* \details H5Lregister() registers a class of user-defined links, or changes
|
||
|
|
* the behavior of an existing class.
|
||
|
|
*
|
||
|
|
* \p cls is a pointer to a buffer containing a copy of the
|
||
|
|
* H5L_class_t struct. This struct is defined in H5Lpublic.h as
|
||
|
|
* follows:
|
||
|
|
* \snippet this H5L_class_t_snip
|
||
|
|
*
|
||
|
|
* The class definition passed with \p cls must include at least the
|
||
|
|
* following:
|
||
|
|
* \li An H5L_class_t version (which should be #H5L_LINK_CLASS_T_VERS)
|
||
|
|
* \li A link class identifier, \c class_id
|
||
|
|
* \li A traversal function, \c trav_func
|
||
|
|
*
|
||
|
|
* Remaining \c struct members are optional and may be passed as NULL.
|
||
|
|
*
|
||
|
|
* The link class passed in \c class_id must be in the user-definable
|
||
|
|
* range between #H5L_TYPE_UD_MIN and #H5L_TYPE_UD_MAX
|
||
|
|
* (see the table below) and will override
|
||
|
|
* any existing link class with that identifier.
|
||
|
|
*
|
||
|
|
* As distributed, valid values of \c class_id used in HDF5 include
|
||
|
|
* the following (defined in H5Lpublic.h):
|
||
|
|
* \link_types
|
||
|
|
*
|
||
|
|
* The hard and soft link class identifiers cannot be modified or
|
||
|
|
* reassigned, but the external link class is implemented as an
|
||
|
|
* example in the user-definable link class identifier range.
|
||
|
|
* H5Lregister() is used to register additional link classes. It could
|
||
|
|
* also be used to modify the behavior of the external link class,
|
||
|
|
* though that is not recommended.
|
||
|
|
*
|
||
|
|
* The following table summarizes existing link types and values and
|
||
|
|
* the reserved and user-definable link class identifier value ranges.
|
||
|
|
* <table>
|
||
|
|
* <tr>
|
||
|
|
* <th>Link class identifier or Value range</th>
|
||
|
|
* <th>Description</th>
|
||
|
|
* <th>Link class or label</th>
|
||
|
|
* </tr>
|
||
|
|
* <tr>
|
||
|
|
* <td>0 to 63</td>
|
||
|
|
* <td>Reserved range</td>
|
||
|
|
* <td></td>
|
||
|
|
* </tr>
|
||
|
|
* <tr>
|
||
|
|
* <td>64 to 255</td>
|
||
|
|
* <td>User-definable range</td>
|
||
|
|
* <td></td>
|
||
|
|
* </tr>
|
||
|
|
* <tr>
|
||
|
|
* <td>64</td>
|
||
|
|
* <td>Minimum user-defined value</td>
|
||
|
|
* <td>#H5L_TYPE_UD_MIN</td>
|
||
|
|
* </tr>
|
||
|
|
* <tr>
|
||
|
|
* <td>64</td>
|
||
|
|
* <td>External link</td>
|
||
|
|
* <td>#H5L_TYPE_EXTERNAL</td>
|
||
|
|
* </tr>
|
||
|
|
* <tr>
|
||
|
|
* <td>255</td>
|
||
|
|
* <td>Maximum user-defined value</td>
|
||
|
|
* <td>#H5L_TYPE_UD_MAX</td>
|
||
|
|
* </tr>
|
||
|
|
* <tr>
|
||
|
|
* <td>255</td>
|
||
|
|
* <td>Maximum value</td>
|
||
|
|
* <td>#H5L_TYPE_MAX</td>
|
||
|
|
* </tr>
|
||
|
|
* <tr>
|
||
|
|
* <td>-1</td>
|
||
|
|
* <td>Error</td>
|
||
|
|
* <td>#H5L_TYPE_ERROR</td>
|
||
|
|
* </tr>
|
||
|
|
* </table>
|
||
|
|
*
|
||
|
|
* Note that HDF5 internally registers user-defined link classes only
|
||
|
|
* by the numeric value of the link class identifier. An application,
|
||
|
|
* on the other hand, will generally use a name for a user-defined
|
||
|
|
* class, if for no other purpose than as a variable name. Assume,
|
||
|
|
* for example, that a complex link type is registered with the link
|
||
|
|
* class identifier 73 and that the code includes the following
|
||
|
|
* assignment:
|
||
|
|
* \code
|
||
|
|
* H5L_TYPE_COMPLEX_A = 73
|
||
|
|
* \endcode
|
||
|
|
* The application can refer to the link class with a term,
|
||
|
|
* \c H5L_TYPE_COMPLEX_A, that conveys meaning to a human reviewing
|
||
|
|
* the code, while HDF5 recognizes it by the more cryptic numeric
|
||
|
|
* identifier, 73.
|
||
|
|
*
|
||
|
|
* \attention Important details and considerations include the following:
|
||
|
|
* \li If you plan to distribute files or software with a
|
||
|
|
* user-defined link class, please contact the Help Desk at
|
||
|
|
* The HDF Group to help prevent collisions between \c class_id
|
||
|
|
* values. See below.
|
||
|
|
* \li As distributed with HDF5, the external link class is
|
||
|
|
* implemented as an example of a user-defined link class with
|
||
|
|
* #H5L_TYPE_EXTERNAL equal to #H5L_TYPE_UD_MIN. \c class_id in
|
||
|
|
* the H5L_class_t \c struct must not equal #H5L_TYPE_UD_MIN
|
||
|
|
* unless you intend to overwrite or modify the behavior of
|
||
|
|
* external links.
|
||
|
|
* \li H5Lregister() can be used only with link class identifiers
|
||
|
|
* in the user-definable range (see table above).
|
||
|
|
* \li The hard and soft links defined by the HDF5 library,
|
||
|
|
* #H5L_TYPE_HARD and #H5L_TYPE_SOFT, reside in the reserved
|
||
|
|
* range below #H5L_TYPE_UD_MIN and cannot be redefined or
|
||
|
|
* modified.
|
||
|
|
* \li H5Lis_registered() can be used to determine whether a desired
|
||
|
|
* link class identifier is available. \Emph{Note that this
|
||
|
|
* function will tell you only whether the link class identifier
|
||
|
|
* has been registered with the installed copy of HDF5; it
|
||
|
|
* cannot tell you whether the link class has been registered
|
||
|
|
* with The HDF Group.}
|
||
|
|
* \li #H5L_TYPE_MAX is the maximum allowed value for a link type
|
||
|
|
* identifier.
|
||
|
|
* \li #H5L_TYPE_UD_MIN equals #H5L_TYPE_EXTERNAL.
|
||
|
|
* \li #H5L_TYPE_UD_MAX equals #H5L_TYPE_MAX.
|
||
|
|
* \li #H5L_TYPE_ERROR indicates that an error has occurred.
|
||
|
|
*
|
||
|
|
* \note \Bold{Registration with The HDF Group:}\n
|
||
|
|
* There are sometimes reasons to take a broader approach to registering
|
||
|
|
* a user-defined link class than just invoking H5Lregister(). For
|
||
|
|
* example:
|
||
|
|
* \li A user-defined link class is intended for use across an
|
||
|
|
* organization, among collaborators, or across a community of users.
|
||
|
|
* \li An application or library overlying HDF5 invokes a user-defined
|
||
|
|
* link class that must be shipped with the software.
|
||
|
|
* \li Files are distributed that make use of a user-defined link class.
|
||
|
|
* \li Or simply, a specific user-defined link class is thought to be
|
||
|
|
* widely useful.
|
||
|
|
*
|
||
|
|
* In such cases, you are encouraged to register that link class with
|
||
|
|
* The HDF Group's Helpdesk. The HDF Group maintains a registry of known
|
||
|
|
* user-defined link classes and tracks the selected link class
|
||
|
|
* identifiers. This registry is intended to reduce the risk of
|
||
|
|
* collisions between \c class_id values and to help coordinate the use
|
||
|
|
* of specialized link classes.
|
||
|
|
*
|
||
|
|
* \since 1.8.0
|
||
|
|
*
|
||
|
|
*/
|
||
|
|
H5_DLL herr_t H5Lregister(const H5L_class_t *cls);
|
||
|
|
/**
|
||
|
|
* \ingroup H5LA
|
||
|
|
*
|
||
|
|
* \brief Unregisters a class of user-defined links
|
||
|
|
*
|
||
|
|
* \param[in] id User-defined link class identifier
|
||
|
|
*
|
||
|
|
* \return \herr_t
|
||
|
|
*
|
||
|
|
* \details H5Lunregister() unregisters a class of user-defined links,
|
||
|
|
* preventing them from being traversed, queried, moved, etc.
|
||
|
|
*
|
||
|
|
* \note A link class can be re-registered using H5Lregister().
|
||
|
|
*
|
||
|
|
* \since 1.8.0
|
||
|
|
*
|
||
|
|
*/
|
||
|
|
H5_DLL herr_t H5Lunregister(H5L_type_t 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
|
||
|
|
|
||
|
|
/* Previous versions of the H5L_class_t struct */
|
||
|
|
#define H5L_LINK_CLASS_T_VERS_0 0
|
||
|
|
|
||
|
|
/** Callback during link traversal */
|
||
|
|
typedef hid_t (*H5L_traverse_0_func_t)(const char *link_name, hid_t cur_group, const void *lnkdata,
|
||
|
|
size_t lnkdata_size, hid_t lapl_id);
|
||
|
|
|
||
|
|
/** User-defined link types */
|
||
|
|
typedef struct {
|
||
|
|
int version; /**< Version number of this struct */
|
||
|
|
H5L_type_t id; /**< Link type ID */
|
||
|
|
const char *comment; /**< Comment for debugging */
|
||
|
|
H5L_create_func_t create_func; /**< Callback during link creation */
|
||
|
|
H5L_move_func_t move_func; /**< Callback after moving link */
|
||
|
|
H5L_copy_func_t copy_func; /**< Callback after copying link */
|
||
|
|
H5L_traverse_0_func_t trav_func; /**< Callback during link traversal */
|
||
|
|
H5L_delete_func_t del_func; /**< Callback for link deletion */
|
||
|
|
H5L_query_func_t query_func; /**< Callback for queries */
|
||
|
|
} H5L_class_0_t;
|
||
|
|
|
||
|
|
#endif /* H5_NO_DEPRECATED_SYMBOLS */
|
||
|
|
|
||
|
|
#endif /* H5Ldevelop_H */
|