/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * 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.                                                        *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

/*
 * Onion Virtual File Driver (VFD)
 *
 * Purpose:    The public header file for the Onion VFD.
 */
#ifndef H5FDonion_H
#define H5FDonion_H

#define H5FD_ONION       (H5FDperform_init(H5FD_onion_init))
#define H5FD_ONION_VALUE H5_VFD_ONION

/**
 *  Current version of the onion VFD fapl info struct.
 */
#define H5FD_ONION_FAPL_INFO_VERSION_CURR 1

#define H5FD_ONION_FAPL_INFO_CREATE_FLAG_ENABLE_PAGE_ALIGNMENT                                               \
    (0x0001u) /**<                                                                                           \
               * Onion history metadata will align to page_size.                                             \
               * Partial pages of unused space will occur in the file,                                       \
               * but may improve read performance from the backing store                                     \
               * on some systems.                                                                            \
               * If disabled (0), padding will not be inserted to align                                      \
               * to page boundaries.                                                                         \
               */

/**
 * Max length of a comment.
 * The buffer is defined to be this size + 1 to handle the NUL.
 */
#define H5FD_ONION_FAPL_INFO_COMMENT_MAX_LEN 255

/**
 * Indicates that you want the latest revision.
 */
#define H5FD_ONION_FAPL_INFO_REVISION_ID_LATEST UINT64_MAX

/**
 * Indicates how the new onion data will be stored.
 */
typedef enum H5FD_onion_target_file_constant_t {
    H5FD_ONION_STORE_TARGET_ONION, /**<
                                    * Onion history is stored in a single, separate "onion
                                    * file". Shares filename and path as hdf5 file (if any),
                                    * with only a different filename extension.
                                    */
} H5FD_onion_target_file_constant_t;

/**
 * Stores fapl information for creating onion VFD files.
 */
typedef struct H5FD_onion_fapl_info_t {
    uint8_t version;                                /**<
                                                     * Future-proofing identifier. Informs struct membership.
                                                     * Must equal H5FD_ONION_FAPL_VERSION_CURR to be considered valid.
                                                     */
    hid_t backing_fapl_id;                          /**<
                                                     * Backing or 'child' FAPL ID to handle I/O with the
                                                     * underlying backing store. It must use the same backing driver as the
                                                     * original file.
                                                     */
    uint32_t page_size;                             /**<
                                                     * page_size:   Size of the amended data pages. If opening an existing file,
                                                     *              must equal the existing page size or zero. If creating a new
                                                     *              file or an initial revision of an existing file, must be a
                                                     *              power of 2.
                                                     *
                                                     */
    H5FD_onion_target_file_constant_t store_target; /**<
                                                     * Identifies where the history data is stored.
                                                     */
    uint64_t revision_num;                          /**<
                                                     * Which revision to open. Valid values are 0 (the original file) or the
                                                     *              revision number of an existing revision.
                                                     *              H5FD_ONION_FAPL_INFO_REVISION_ID_LATEST refers to the most
                                                     *              recently-created revision in the history.
                                                     */
    uint8_t force_write_open;                       /**<
                                                     *              Flag to ignore the write-lock flag in the onion data
                                                     *              and attempt to open the file write-only anyway.
                                                     *              This may be relevant if, for example, the library crashed
                                                     *              while the file was open in write mode and the write-lock
                                                     *              flag was not cleared.
                                                     *              Must equal H5FD_ONION_FAPL_FLAG_FORCE_OPEN to enable.
                                                     *
                                                     */
    uint8_t creation_flags;                         /**<
                                                     * Flag used only when instantiating an onion file.
                                                     * If the relevant bit is set to a nonzero value, its feature
                                                     * will be enabled.
                                                     */
    char comment[H5FD_ONION_FAPL_INFO_COMMENT_MAX_LEN +
                 1]; /**<
                      * User-supplied NULL-terminated comment for a revision to be
                      * written.
                      * Cannot be longer than H5FD_ONION_FAPL_COMMENT_MAX_LEN.
                      * Ignored if part of a FAPL used to open in read mode.
                      */
} H5FD_onion_fapl_info_t;

#ifdef __cplusplus
extern "C" {
#endif

H5_DLL hid_t H5FD_onion_init(void);

/**
 * --------------------------------------------------------------------------
 * \ingroup FAPL
 *
 * \brief get the onion info from the file access property list
 *
 * \fapl_id
 * \param[out] fa_out The pointer to the structure H5FD_onion_fapl_info_t
 *
 * \return \herr_t
 *
 * \details H5Pget_fapl_onion() retrieves the structure H5FD_onion_fapl_info_t
 *          from the file access property list that is set for the onion VFD
 *          driver.
 *
 * \since 1.14.0
 */
H5_DLL herr_t H5Pget_fapl_onion(hid_t fapl_id, H5FD_onion_fapl_info_t *fa_out);

/**
 * --------------------------------------------------------------------------
 * \ingroup FAPL
 *
 * \brief set the onion info for the file access property list
 *
 * \fapl_id
 * \param[in] fa The pointer to the structure H5FD_onion_fapl_info_t
 *
 * \return \herr_t
 *
 * \details H5Pset_fapl_onion() sets the structure H5FD_onion_fapl_info_t
 *          for the file access property list that is set for the onion VFD
 *          driver.
 *
 * \since 1.14.0
 */
H5_DLL herr_t H5Pset_fapl_onion(hid_t fapl_id, const H5FD_onion_fapl_info_t *fa);

/**
 * --------------------------------------------------------------------------
 * \ingroup H5FD
 *
 * \brief get the number of revisions
 *
 * \param[in] filename The name of the onion file
 * \param[in] fapl_id The ID of the file access property list
 * \param[out] revision_count The number of revisions
 *
 * \return \herr_t
 *
 * \details H5FDonion_get_revision_count() returns the number of revisions
 *          for an onion file. It takes the file name and file access property
 *          list that is set for the onion VFD driver.
 *
 *
 * \since 1.14.0
 */
H5_DLL herr_t H5FDonion_get_revision_count(const char *filename, hid_t fapl_id, uint64_t *revision_count);

#ifdef __cplusplus
}
#endif

#endif /* H5FDonion_H */
