diff --git a/src/H5FDmirror.h b/src/H5FDmirror.h index 6c98e1a8a6f..304f1e5a3f8 100644 --- a/src/H5FDmirror.h +++ b/src/H5FDmirror.h @@ -25,39 +25,43 @@ /** Identifier for the mirror VFD */ #define H5FD_MIRROR_VALUE H5_VFD_MIRROR -#ifdef __cplusplus -extern "C" { -#endif +/** Magic number to identify the H5FD_mirror_fapl_t struct */ +#define H5FD_MIRROR_FAPL_MAGIC 0xF8DD514C -/* ============================================================================ - * Mirror VFD use and operation. - * ============================================================================ +/** + * The version number of the H5FD_mirror_fapl_t configuration + * structure for the #H5FD_MIRROR driver */ +#define H5FD_MIRROR_CURR_FAPL_T_VERSION 1 -/* --------------------------------------------------------------------------- - * Structure: H5FD_mirror_fapl_t +/** Max size of the remote_ip array in H5FD_mirror_fapl_t */ +#define H5FD_MIRROR_MAX_IP_LEN 32 + +/** + *\struct H5FD_mirror_fapl_t + * \brief Configuration structure for H5Pset_fapl_mirror() / H5Pget_fapl_mirror() * - * Used to pass configuration information to the Mirror VFD. - * Populate components as appropriate and pass structure pointer to - * `H5Pset_fapl_mirror()`. + * \details H5FD_mirror_fapl_t is a public structure that is used to pass + * configuration data to the #H5FD_MIRROR driver via a File Access + * Property List. A pointer to an instance of this structure is + * a parameter to H5Pset_fapl_mirror() and H5Pget_fapl_mirror(). * - * `magic` (uint32_t) + * \var uint32_t H5FD_mirror_fapl_t::magic * Semi-unique number to sanity-check pointers to this structure type. - * MUST equal H5FD_MIRROR_FAPL_MAGIC to be considered valid. + * Must equal H5FD_MIRROR_FAPL_MAGIC to be considered valid. * - * `version` (uint32_t) - * Indicates expected components of the structure. + * \var uint32_t H5FD_mirror_fapl_t::version + * Version number of the H5FD_mirror_fapl_t structure. Any instance passed + * to H5Pset_fapl_mirror() / H5Pget_fapl_mirror() must have a recognized version + * number or an error will be raised. Currently, this field should be set + * to #H5FD_MIRROR_CURR_FAPL_T_VERSION. * - * `handshake_port (int) - * Port number to expect to reach the "Mirror Server" on the remote host. + * \var int H5FD_mirror_fapl_t::handshake_port + * Port number on the remote host. * - * `remote_ip` (char[]) - * IP address string of "Mirror Server" remote host. - * --------------------------------------------------------------------------- + * \var char H5FD_mirror_fapl_t::remote_ip[H5FD_MIRROR_MAX_IP_LEN + 1] + * IP address string of the remote host. */ -#define H5FD_MIRROR_FAPL_MAGIC 0xF8DD514C -#define H5FD_MIRROR_CURR_FAPL_T_VERSION 1 -#define H5FD_MIRROR_MAX_IP_LEN 32 typedef struct H5FD_mirror_fapl_t { uint32_t magic; uint32_t version; @@ -65,6 +69,10 @@ typedef struct H5FD_mirror_fapl_t { char remote_ip[H5FD_MIRROR_MAX_IP_LEN + 1]; } H5FD_mirror_fapl_t; +#ifdef __cplusplus +extern "C" { +#endif + /** @private * * \brief Private initializer for the mirror VFD @@ -74,14 +82,33 @@ H5_DLL hid_t H5FD_mirror_init(void); /** * \ingroup FAPL * - * \todo Add missing documentation + * \brief Queries a File Access Property List for #H5FD_MIRROR file driver properties + * + * \fapl_id + * \param[out] fa_out Pointer to #H5FD_MIRROR driver configuration structure + * \returns \herr_t + * + * \details H5Pget_fapl_mirror() queries the #H5FD_MIRROR driver properties as set + * by H5Pset_fapl_mirror(). + * + * \since 1.10.7 */ H5_DLL herr_t H5Pget_fapl_mirror(hid_t fapl_id, H5FD_mirror_fapl_t *fa_out); /** * \ingroup FAPL * - * \todo Add missing documentation + * \brief Modifies the file access property list to use the #H5FD_MIRROR driver + * + * \fapl_id + * \param[in] fa Pointer to #H5FD_MIRROR driver configuration structure + * + * \returns \herr_t + * + * \details H5Pset_fapl_mirror() modifies the file access property list to use the + * #H5FD_MIRROR driver. + * + * \since 1.10.7 */ H5_DLL herr_t H5Pset_fapl_mirror(hid_t fapl_id, H5FD_mirror_fapl_t *fa);