diff options
| -rw-r--r-- | doxygen/dox/VOLConnGuide.dox | 4908 | ||||
| -rw-r--r-- | doxygen/examples/tables/propertyLists.dox | 267 | ||||
| -rw-r--r-- | doxygen/hdf5doxy_layout.xml | 2 | ||||
| -rw-r--r-- | java/src/hdf/hdf5lib/callbacks/package-info.java | 1 | ||||
| -rw-r--r-- | release_docs/RELEASE.txt | 6 | ||||
| -rw-r--r-- | src/H5Apublic.h | 3 | ||||
| -rw-r--r-- | src/H5Dpublic.h | 3 | ||||
| -rw-r--r-- | src/H5FDhdfs.h | 1 | ||||
| -rw-r--r-- | src/H5Gpublic.h | 18 | ||||
| -rw-r--r-- | src/H5Lpublic.h | 12 | ||||
| -rw-r--r-- | src/H5Mpublic.h | 3 | ||||
| -rw-r--r-- | src/H5Pmodule.h | 2 |
12 files changed, 5143 insertions, 83 deletions
diff --git a/doxygen/dox/VOLConnGuide.dox b/doxygen/dox/VOLConnGuide.dox new file mode 100644 index 0000000..fb662a0 --- /dev/null +++ b/doxygen/dox/VOLConnGuide.dox @@ -0,0 +1,4908 @@ +/** \page VOL_Connector HDF5 Virtual Object Layer (VOL) Connector Author Guide + +Navigate back: \ref index "Main" +<hr> + +\section secVOLIntro Introduction +The Virtual Object Layer (VOL) is an abstraction layer in the HDF5 library which intercepts all API +calls that could potentially access objects in an HDF5 container and forwards those calls to object drivers +referred to as <em>VOL connectors</em>. The architecture of this feature is described in the \ref H5VL_UG +and VOL Architecture and Internals Documentation and will not be duplicated here. + +This guide is for people who are interested in developing their own VOL connector for the HDF5 library. +It is assumed that the reader has good knowledge of the VOL architecture obtained by reading the VOL +architectural design document. + +\section secVOLCreate Creating a New Connector + +\subsection subsecVOLOverview Overview +Creating a new VOL connector can be a complicated process. You will need to map your storage system +to the HDF5 data model through the lens of the VOL and this may involve some impedance mismatch that +you will have to work around. The good news is that the HDF5 library has been re-engineered to handle +arbitrary, connector-specific data structures via the VOL callbacks, so no knowledge of the library internals +is necessary to write a VOL connector. + +Writing a VOL connector requires these things: +\li Decide on library vs plugin vs internal. +\li Set up your build/test files (CMake, Autotools, etc.). +\li Fill in some boilerplate information in yourH5VLclasststruct. +\li Decide how you will perform any necessary initialization needed by your storage system. +\li Map Storage to HDF5 File Objects +\li Create implementations for the callbacks you need to support. +\li Test the connector. + +Each of the steps listed above is described in more detail in this section of the document. + +The "model then implement" steps can be performed iteratively. You might begin by only supporting files, +datasets, and groups and only allowing basic operations on them. In some cases, this may be all that is +needed. As your needs grow, you can repeat those steps and increase the connector's HDF5 API coverage +at a pace that makes sense for your users. + +Also, note that this document only covers writing VOL connectors using the C programming language. It +is often possible to write connectors in other programming languages (e.g.; Python) via the language's C +interop facilities, but that topic is out of scope for this document. + +\subsection subsecVOL112dep The HDF5 1.12.x VOL Interface Is DEPRECATED +Important changes were made to the VOL interface for HDF5 1.13.0 and, due to binary compatibility issues, +these cannot be merged to HDF5 1.12.x. For this reason, VOL connector development should be shifted to +target 1.13.0 as no further development of the VOL interface will take place on the 1.12.x branch. Unlike the +other development branches of the library, there is no hdf5_1_13 branch - all HDF5 1.13.0 development is +taking place in the develop branch of the HDF5 repository and 1.13.x branches will split off from that. + +Note also that HDF5 1.13.0 is considered an unstable branch, and the API and file format are subject to +change ("unstable" means "not yet finalized", not "buggy"). The VOL feature is under active development +and, although it is nearing its final form, may change further before the stable HDF5 1.14.0 release targeted +for 2022. + +\subsection subsecVOLRelated VOL-Related HDF5 Header Files +Use of the VOL, including topics such as registration and loading VOL plugins, is described in the \ref H5VL_UG. + +Public header Files you will need to be familiar with include: +<table> +<tr> +<td>H5VLpublic.h +</td> +<td>Public VOL header. +</td> +</tr> +<tr> +<td>H5VLconnector.h +</td> +<td>Main header for connector authors. Contains definitions for the main VOL struct and callbacks, enum values, etc. +</td> +</tr> +<tr> +<td>H5VLconnector_passthru.h +</td> +<td>Helper routines for passthrough connector authors. +</td> +</tr> +<tr> +<td>H5VLnative.h +</td> +<td>Native VOL connector header. May be useful if your connector will attempt to implement native HDF5 API calls that are handled via the optional callbacks. +</td> +</tr> +<tr> +<td>H5PLextern.h +</td> +<td>Needed if your connector will be built as a plugin. +</td> +</tr> +</table> + +Many VOL connectors are listed on The HDF Group's VOL plugin registration page, located at: +<a href="https://portal.hdfgroup.org/display/support/Registered+VOL+Connectors">Registered VOL Connectors</a>. +Not all of these VOL connectors are supported by The HDF Group and the level of completeness varies, but the +connectors found there can serve as examples of working implementations + +\subsection subsecVOLLPI Library vs Plugin vs Internal +When building a VOL connector, you have several options: + +<h4>Library</h4> +The connector can be built as a normal shared or static library. Software that uses your connector will have +to link to it just like any other library. This can be convenient since you don't have to deal with plugin paths +and searching for the connector at runtime, but it also means that software which uses your connector will +have to be built and linked against it. + +<h4>Plugin</h4> +You can also build your connector as a dynamically loaded plugin. The mechanism for this is the same +mechanism used to dynamically load HDF5 filter plugins. This can allow use of your connector via the +VOL environment variable, without modifying the application, but requires your plugin to be discoverable +at runtime. See the \ref H5VL_UG for more information about using HDF5 plugins. + +To build your connector as a plugin, you will have to include <b>H5PLextern.h</b> +(a public header distributed with the library) and implement the #H5PLget_plugin_type +#H5PLget_plugin_info calls, both of which are trivial to code up. It also often requires your connector +to be built with certain compile/link options. The VOL connector template does all of these things. + +The HDF5 library's plugin loading code will call #H5PLget_plugin_type +to determine the type of plugin(e.g.; filter, VOL) and #H5PLget_plugin_info +to get the class struct, which allows the library to query the plugin for its name and value to see if it has found +a requested plugin. When a match is found, the library will use the class struct to register the connector and map its callbacks. + +For the HDF5 library to be able to load an external plugin dynamically, the plugin developer has to define +two public routines with the following name and signature: +\code + H5PL_type_t H5PLget_plugin_type(void); + const void *H5PLget_plugin_info(void); +\endcode + +To show how easy this is to accomplish, here is the complete implementation of those functions in the +template VOL connector: +\code +H5PL_type_t H5PLget_plugin_type(void) { return H5PL_TYPE_VOL; } +const void *H5PLget_plugin_info(void) { return &template_class_g; } +\endcode + +\ref H5PLget_plugin_type should return the library type which should always be #H5PL_TYPE_VOL. +#H5PLget_plugin_info should return a pointer to the plugin structure defining the VOL plugin with all the callbacks. +For example, consider an external plugin defined as: +\code + static const H5VL_class_t H5VL_foo_g = { + 2, // version + 12345, // value + "foo", // name + ... + } +\endcode + +The plugin would implement the two routines as: +\code + H5PL_type_t H5PLget_plugin_type(void) + {return H5PL_TYPE_VOL;} + const void *H5PLget_plugin_info(void) + {return &H5VL_foo_g;} +\endcode + +<h4>Internal</h4> +Your VOL connector can also be constructed as a part of the HDF5 library. This works in the same way +as the stdio and multi virtual file drivers (VFDs) and does not require knowledge of HDF5 internals or +use of non-public API calls. You simply have to add your connector's files to the +Makefile.am and/or CMakeLists.txt files in the source distribution's src directory. This requires maintaining +a private build of the library, though, and is not recommended. + +\subsection subsecVOLBuild Build Files / VOL Template +We have created a template terminal VOL connector that includes both Autotools and CMake build files. The +constructed VOL connector includes no real functionality, but can be registered and loaded as a plugin. + +The VOL template can be found here: +<a href="https://github.com/HDFGroup/vol-template">VOL template</a> + +The purpose of this template is to quickly get you to the point where you can begin filling in the callback +functions and writing tests. You can copy this code to your own repository to serve as the basis for your +new connector. + +A template passthrough VOL is also available. This will be discussed in the section on passthrough connectors. + +\subsection subsecVOLBoil H5VL_class_t Boilerplate +Several fields in the H5VLclasststruct will need to be filled in. + +In HDF5 1.13.0, the <em>version</em> field will be 2, indicating the connector targets version 2 of the +#H5VL_class_t struct. Version 1 of the struct was never formally released and only available in the +develop branch of the HDF5 git repository. Version 0 is used in the deprecated HDF5 1.12.x branch. + +Every connector needs a <em>name</em> and <em>value</em>. The library will use these when loading and registering the +connector (as described in the \ref H5VL_UG), so they should be unique in your ecosystem. + +VOL connector values are integers, with a maximum value of 65535. Values from 0 to 255 are reserved +for internal use by The HDF Group. The native VOL connector has a value of 0. Values of 256 to 511 +are for connector testing and should not be found in the wild. Values of 512 to 65535 are for external +connectors. + +As is the case with HDF5 filters, The HDF Group can assign you an official VOL connector value. Please +contact <a href="help@hdfgroup.org">help@hdfgroup.org</a> for help with this. We currently do not register connector names, though the +name you've chosen will appear on the registered VOL connectors page. + +As noted above, registered VOL connectors will be listed at: +<a href="https://portal.hdfgroup.org/display/support/Registered+VOL+Connectors">Registered VOL Connectors</a> + +A new \b conn_version field has been added to the class struct for 1.13. This field is currently not used by +the library so its use is determined by the connector author. Best practices for this field will be determined +in the near future and this part of the guide will be updated. + +The \b cap_flags field is used to determine the capabilities of the VOL connector. At this time, the use of this +field is limited to indicating thread-safety, asynchronous capabilities, and ability to produce native HDF5 +files. Supported flags can be found in \ref H5VLconnector.h. +\code +// Capability flags for connector +#define H5VL_CAP_FLAG_NONE 0 // No special connector capabilities +#define H5VL_CAP_FLAG_THREADSAFE 0x01 // Connector is threadsafe +#define H5VL_CAP_FLAG_ASYNC 0x02 // Connector performs operations asynchronously +#define H5VL_CAP_FLAG_NATIVE_FILES 0x04 // Connector produces native file format +\endcode + +\subsection subsecVOLInit Initialization and Shutdown +You'll need to decide how to perform any initialization and shutdown tasks that are required by your +connector. There are initialize and terminate callbacks in the #H5VL_class_t struct to handle this. They +are invoked when the connector is registered and unregistered, respectively. The initialize callback can take +a VOL initialization property list, so any properties you need for initialization can be applied to it. The +HDF5 library currently makes no use of the vipl so there are no default vipl properties. + +If this is unsuitable, you may have to create custom connector-specific API calls to handle initialization and +termination. It may also be useful to perform operations in a custom API call used to set the VOL connector +in the fapl. + +The initialization and terminate callbacks: +\code + herr_t (*initialize)(hid_t vipl_id); // Connector initialization callback + herr_t (*terminate)(void); // Connector termination callback +\endcode + +\subsection subsecVOLMap Map Storage to HDF5 File Objects +The most difficult part of designing a new VOL connector is going to determining how to support HDF5 +file objects and operations using your storage system. There isn't much specific advice to give here, as each +connector will have unique needs, but a forthcoming "tutorial" connector will set up a simple connector and +demonstrate this process. + +\subsection subsecVOLFillIn Fill In VOL Callbacks +For each file object you support in your connector (including the file itself), you will need to create a +data struct to hold whatever file object metadata that are needed by your connector. For example, a data +structure for a VOL connector based on text files might have a file struct that contains a file pointer for the +text file, buffers used for caching data, etc. Pointers to these data structures are where your connector's +state is stored and are returned to the HDF5 library from the create/open/etc. callbacks such as +<em>dataset create</em>. + +Once you have your data structures, you'll need to create your own implementations of the callback functions +and map them via your #H5VL_class_t struct. + +\subsection subsecVOLOpt Handling Optional Operations +Handling optional operations has changed significantly in HDF5 1.13.0. In the past, optional operations were +specified using an integer <em>opt_type</em> parameter. This proved to be a problem with pass-through connectors, +though, as it was possible to have <em>opt_type</em> clash if two connectors used the same <em>opt_type</em> values. + +The new scheme allows a connector to register an optional operation with the library and receive a dynamically-allocated +<em>opt_type</em> value for the operation. + +The following API calls can be used to manage the optional operations: +\code + herr_t H5VLregister_opt_operation(H5VL_subclass_t subcls, const char *op_name, int *op_val); + herr_t H5VLfind_opt_operation(H5VL_subclass_t subcls, const char *op_name, int *op_val); + herr_t H5VLunregister_opt_operation(H5VL_subclass_t subcls, const char *op_name) +\endcode + +The <em>register</em> call is used to register an operation for a subclass (file, etc.) and the <em>opt_type</em> parameter +that the library assigned to the operation will be returned via the <em>opt_val</em> parameter. This value can then +be passed to one of the subclass-specific API calls (listed below). If you need to find an existing optional +call's assigned <em>opt_type</em> value by name, you can use the <em>find</em> call. + +One recommended way to handle optional calls is to <em>register</em> all the optional calls at startup, saving the +values in connector state, then use these cached values in your optional calls. The assigned values should be +unregistered using the <em>unregister</em> call when the connector shuts down. + +Subclass-specific optional calls: +\code +herr_t H5VLattr_optional_op(const char *app_file, const char *app_func, unsigned app_line, + hid_t attr_id, H5VL_optional_args_t *args, hid_t dxpl_id, hid_t es_id); +herr_t H5VLdataset_optional_op(const char *app_file, const char *app_func, unsigned app_line, + hid_t dset_id, H5VL_optional_args_t *args, hid_t dxpl_id, hid_t es_id); +herr_t H5VLdatatype_optional_op(const char *app_file, const char *app_func, unsigned app_line, + hid_t type_id, H5VL_optional_args_t *args, hid_t dxpl_id, hid_tes_id); +herr_t H5VLfile_optional_op(const char *app_file, const char *app_func, unsigned app_line, + hid_t file_id, H5VL_optional_args_t *args, hid_t dxpl_id, hid_t es_id); +herr_t H5VLgroup_optional_op(const char *app_file, const char *app_func, unsigned app_line, + hid_t group_id, H5VL_optional_args_t *args, hid_t dxpl_id, hid_t es_id); +herr_t H5VLlink_optional_op(const char *app_file, const char *app_func, unsigned app_line, + hid_t loc_id, const char *name, hid_t lapl_id, H5VL_optional_args_t *args, + hid_t dxpl_id, hid_t es_id); +herr_t H5VLobject_optional_op(const char *app_file, const char *app_func, unsigned app_line, + hid_t loc_id, const char *name, hid_t lapl_id, + H5VL_optional_args_t *args, hid_t dxpl_id, hid_t es_id); +herr_t H5VLrequest_optional_op(void *req, hid_t connector_id, H5VL_optional_args_t *args); +\endcode + +\subsection subsecVOLTest Testing Your Connector +At the time of writing, some of the HDF5 library tests have been abstracted out of the library with their +native-file-format-only sections removed and added to a VOL test suite available here: +<a href="https://github.com/HDFGroup/vol-tests">vol-tests</a> + +This is an evolving set of tests, so see the documentation in that repository for instructions as to its use. +You may want to clone and modify and/or extend these tests for use with your own connector. + +In the future, we plan to modify the HDF5 test suite that ships with the library to use a future VOL +capabilities flags scheme to selectively run tests that a particular connector supports. As this is a large task, +it may be some time before that work is complete. + +\subsection subsecVOLPassthrough Passthrough Connectors +Coming Soon + +\subsection subsecVOLAsync Asynchronous Operations +Coming Soon + +\section secVOLRef VOL Connector Interface Reference +Each VOL connector should be of type #H5VL_class_t: +<table> +<tr> +<td> +<em>VOL connector class, H5VLpublic.h</em> +\snippet H5VLconnector.h H5VL_class_t_snip +</td> +</tr> +</table> + +The <em>version</em> field is the version of the #H5VL_class_t struct. This is identical to how the <em>version</em> field is +used in the #H5Z_class2_t struct for filters. + +The <em>value</em> field is a unique integer identifier that should be between 512 and 65535 for external, non-library +connectors. + +The <em>name</em> field is a string that uniquely identifies the VOL connector name. + +The <em>conn_version</em> is the connector version. This is currently not used by the library. + +The <em>cap_flags</em> holds bitwise capability/feature flags that determine which operations and capabilities are +supported by a the VOL connector. These fields were enumerated in the previous section. + +The <em>initialize</em> field is a function pointer to a routine that a connector implements to set up or initialize +access to the connector. Implementing this function by the connector is not required since some connectors +do not require any set up to start accessing the connector. In that case, the value of the function pointer +should be set to NULL. Connector specific variables that are required to be passed from users should be +passed through the VOL initialize property list. Generic properties can be added to this property class +for user-defined connectors that cannot modify the HDF5 library to add internal properties. For more +information consult the property list reference manual pages. + +The <em>terminate</em> field is a function pointer to a routine that a connector implements to terminate or finalize +access to the connector. Implementing this function by the connector is not required since some connectors +do not require any termination phase to the connector. In that case, the value of the function pointer should +be set to NULL. + +The rest of the fields in the #H5VL_class_t struct are "subclasses" that define all the VOL function callbacks +that are mapped to from the HDF5 API layer. Those subclasses are categorized into three categories, VOL +Framework, Data Model, and Infrastructure / Services. + +VOL Framework classes provide functionality for working with the VOL connectors themselves (e.g., working +with connector strings) and with wrapping and unwrapping objects for passthrough connectors. + +Data Model classes are those that provide functionality for accessing an HDF5 container and objects in that +container as defined by the HDF5 data model. + +Infrastructure / Service classes are those that provide services for users that are not related to the data model +specifically. Asynchronous operations, for example, are a service that most connectors can implement, so we +add a class for it in the VOL structure. + +If a service becomes generic enough and common among many connectors, a class for it should be added +to the VOL structure. However, many connectors can/will provide services that are not shared by other +connectors. A good way to support these services is through an optional callback in the VOL structure which +can be a hook from the API to the connector that provides those services, passing any necessary arguments +needed without the HDF5 library having to worry about supporting that service. A similar API operation +to allow users to use that service will be added. This API call would be similar to an "ioctl" call where any +kind of operation can be supported and passed down to the connector that has enough knowledge from the +user to interpret the type of the operation. All classes and their defined callbacks will be detailed in the +following sub-sections. + +To handle that large set of API routines, each class in the Data Model category has three generic callbacks, +<em>get</em>, <em>specific</em>, and <em>optional</em> to handle the three set of API operations outline above respectively. To +handle the varying parameters that can be passed to the callback, each callback will take a struct parameter +that includes an enum <em>get/specific</em> or integer <em>optional</em> field indicating the operation and a union of the +possible parameters <em>get/specific</em> or void pointer to the parameters <em>optional</em>. + +The optional args struct used for all optional operations: +\code +// Struct for all 'optional' callbacks +typedef struct H5VL_optional_args_t { + int op_type; // Operation to perform + void *args; // Pointer to operation's argument struct +} H5VL_optional_args_t; +\endcode + +The <em>opt_type</em> member is the value assigned by the library when the optional operation was registered (or +<em>defined</em> in the case of the native VOL connector) and the <em>args</em> member is a pointer to the optional +operation's parameters (usually passed in as a struct). + +Note that this differs from the HDF5 1.12.x scheme, which used <em>va_lists</em>. + +The <em>optional</em> callback is a free for all callback where anything from the API layer is passed in directly. +This callback is used to support connector specific operations in the API that other connectors should or +would not know about. More information about types and the arguments for each type will be detailed in +the corresponding class arguments. + +\subsection subsecVOLRefMap Mapping the API to the Callbacks +The callback interface defined for the VOL has to be general enough to handle all the HDF5 API operations +that would access the file. Furthermore, it has to capture future additions to the HDF5 library with little to +no changes to the callback interface. Changing the interface often whenever new features are added would +be discouraging to connector developers since that would mean reworking their VOL connector structure. +To remedy this issue, every callback will contain two parameters: +<ul> +<li>A data transfer property list (DXPL) which allows that API to put some properties on for the connectors +to retrieve if they have to for particular operations, without having to add arguments to the VOL +callback function.</li> +<li>A pointer to a request <em>(void **req)</em> to handle asynchronous operations if the HDF5 library adds +support for them in future releases. hat pointer is set by the VOL connector to a request object it +creates to manage progress on that asynchronous operation. If the <em>req</em> is <em>NULL</em>, that means that the +API operation is blocking and so the connector would not execute the operation asynchronously. If +the connector does not support asynchronous operations, it needs not to worry about this field and +leaves it unset.</li> +</ul> + +In order to keep the number of the VOL object classes and callbacks concise and readable, it was decided +not to have a one-to-one mapping between API operation and callbacks. The parameter names and types +will be detailed when describing each callback in their respective sections. + +The HDF5 library provides several routines to access an object in the container. For example, to open an +attribute on a group object, the user could use #H5Aopen and pass the group identifier directly where the +attribute needs to be opened. Alternatively, the user could use #H5Aopen_by_name or #H5Aopen_by_idx +to open the attribute, which provides a more flexible way of locating the attribute, whether by a starting +object location and a path or an index type and traversal order. All those types of accesses usually map to +one VOL callback with a parameter that indicates the access type. In the example of opening an attribute, +the three API open routine will map to the same VOL open callback but with a different location parameter. +The same applies to all types of routines that have multiple types of accesses. The location parameter is a +structure defined in: + +<em>Structure to hold parameters for object locations, H5VLconnector.h</em> +\code +// +// Structure to hold parameters for object locations. +// either: BY_SELF, BY_NAME, BY_IDX, BY_TOKEN + +typedef struct H5VL_loc_params_t { + H5I_type_t obj_type; // The object type of the location object + H5VL_loc_type_t type; // The location type + union { // parameters of the location + H5VL_loc_by_token_t loc_by_token; + H5VL_loc_by_name_t loc_by_name; + H5VL_loc_by_idx_t loc_by_idx; + }loc_data; + } H5VL_loc_params_t + +// +// Types for different ways that objects are located in an +// HDF5 container. +typedef enum H5VL_loc_type_t { + // starting location is the target object + H5VL_OBJECT_BY_SELF, + + // location defined by object and path in H5VL_loc_by_name_t + H5VL_OBJECT_BY_NAME, + + // location defined by object, path, and index in H5VL_loc_by_idx_t + H5VL_OBJECT_BY_IDX, + + // location defined by token (e.g. physical address) in H5VL_loc_by_token_t + H5VL_OBJECT_BY_TOKEN, +} H5VL_loc_type_t; + +typedef struct H5VL_loc_by_name { + const char *name; // The path relative to the starting location + hid_t lapl_id; // The link access property list +}H5VL_loc_by_name_t; + +typedef struct H5VL_loc_by_idx { + const char *name; // The path relative to the starting location + H5_index_t idx_type; // Type of index + H5_iter_order_t order; // Index traversal order + hsize_t n; // Position in index + hid_t lapl_id; // The link access property list +}H5VL_loc_by_idx_t; + +typedef struct H5VL_loc_by_token { + void *token; // arbitrary token (physical address of location in native VOL) +}H5VL_loc_by_token_t; +\endcode + +\subsection subsecVOLRefConn Connector Information Callbacks +This section's callbacks involve the connector-specific information that will be associated with the VOL in +the fapl via <b>H5Pset_fapl_<name></b> et al. This data is copied into the fapl so the library needs these functions to +manage this in a way that prevents resource leaks. + +The <em>to_str</em> and <em>from_str</em> callbacks are used to convert the connector-specific data to and from a configuration +string. There is no official way to construct VOL configuration strings, so the format used (JSON, +XML, getopt-style processing, etc.) is up to the connector author. These connector configuration strings +can be used to set up a VOL connector via mechanisms like command-line parameters and environment +variables. + +<em>Info class for connector information routines, H5VLconnector.h</em> +\code +// VOL connector info fields & callbacks +typedef struct H5VL_info_class_t { + size_t size; // Size of the VOL info + void *(*copy)(const void *info); // Callback to create a copy of the VOL info + herr_t (*cmp)(int *cmp_value, const void *info1, const void *info2); // Callback to compare VOL info + herr_t (*free)(void *info); // Callback to release a VOL info + herr_t (*to_str)(const void *info, char **str); // Callback to serialize connector's info into a string + herr_t (*from_str)(const char *str, void **info); // Callback to deserialize a string into connector's info +} H5VL_info_class_t; +\endcode + +\subsubsection subsubsecVOLRefConnsize info: size +The <em>size</em> field indicates the size required to store any special information that the connector needs. + +If the connector requires no special information, set this field to zero. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + size_t size; +\endcode +</td> +</tr> +</table> + +\subsubsection subsubsecVOLRefConncopy info: copy +The <em>copy</em> callback is invoked when the connector is selected for use with <b>H5Pset_fapl_<name></b>, the +connector-specific set call, etc. Where possible, the information should be deep copied in such a way that the original +data can be freed. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + void * (*copy)(const void *info); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + info (IN): The connector-specific info to copy. +\endcode +</td> +</tr> +</table> + +\subsubsection subsubsecVOLRefConncmp info: cmp +The <em>cmp</em> callback is used to determine if two connector-specific data structs are identical and helps the library +manage connector resources. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*cmp)(int *cmp_value, const void *info1, const void *info2); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + cmp_value (OUT): A strcmp-like compare value. + info1 (IN): The 1st connector-specific info to copy. + info2 (IN): The 2nd connector-specific info to copy. +\endcode +</td> +</tr> +</table> + +\subsubsection subsubsecVOLRefConnfree info: free +The <em>free</em> callback is used to clean up the connector-specific information that was copied when set in the +fapl via the <em>copy</em> callback. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*free)(void *info); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + info (IN): The connector-specific info to free. +\endcode +</td> +</tr> +</table> + +\subsubsection subsubsecVOLRefConnto info: to_str +The <em>to_str</em> callback converts a connector-specific information structure to a connector-specific configuration +string. It is the opposite of the <em>from_str</em> callback. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*to_str)(const void *info, char **str); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + info (IN): The connector-specific info to convert to a configuration string. + str (OUT): The constructed configuration string. +\endcode +</td> +</tr> +</table> + +\subsubsection subsubsecVOLRefConnfrom info: from_str +The <em>from_str</em> callback converts a connector-specific configuration string to a connector-specific information +structure. It is the opposite of the <em>to_str</em> callback. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*from_str)(const char *str, void **info); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + str (IN): The connector-specific configuration string. + info (OUT): The connector-specific info generated from the configuration string. +\endcode +</td> +</tr> +</table> + +\subsection subsecVOLRefWrap Object Wrap Callbacks +The object wrap callbacks are used by passthrough connectors to wrap/unwrap objects and contexts when +passing them up and down the VOL chain. + +<em>Wrap class for object wrapping routines, H5VLconnector.h</em> +\code +typedef struct H5VL_wrap_class_t { + void *(*get_object)(const void *obj); // Callback to retrieve underlying object + herr_t (*get_wrap_ctx)(const void *obj, void **wrap_ctx); // Callback to retrieve the object wrapping context for the connector + void *(*wrap_object)(void *obj, H5I_type_t obj_type, void *wrap_ctx); // Callback to wrap a library object + void *(*unwrap_object)(void *obj); // Callback to unwrap a library object + herr_t (*free_wrap_ctx)(void *wrap_ctx); // Callback to release the object wrapping context for the connector +} H5VL_wrap_class_t; +\endcode + +\subsubsection subsubsecVOLRefWrapobj wrap: get_object +Retrieves an underlying object. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + void * (*get_object)(const void *obj); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): Object being unwrapped. +\endcode +</td> +</tr> +</table> + +\subsubsection subsubsecVOLRefWrapctx wrap: get_wrap_ctx +Get a VOL connector's object wrapping context. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*get_wrap_ctx)(const void *obj, void **wrap_ctx); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): Object for which we need a context. + wrap_ctx (OUT): Context. +\endcode +</td> +</tr> +</table> + +\subsubsection subsubsecVOLRefWrapwrap wrap: wrap_object +Asks a connector to wrap an underlying object. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + void * (*wrap_object)(void *obj, H5I_type_t obj_type, void *wrap_ctx); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): Object being wrapped. + obj_type (IN): Object type (see H5Ipublic.h). + wrap_ctx (IN): Context. +\endcode +</td> +</tr> +</table> + +\subsubsection subsubsecVOLRefWrapunwrap wrap: unwrap_object +Unwrap an object from connector. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + void * (*unwrap_object)(void *obj); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): Object being unwrapped. +\endcode +</td> +</tr> +</table> + +\subsubsection subsubsecVOLRefWrapfree wrap: free_wrap_ctx +Release a VOL connector's object wrapping context. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*free_wrap_ctx)(void *wrap_ctx); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + wrap_ctx (IN): Context to be freed. +\endcode +</td> +</tr> +</table> + +\subsection subsecVOLRefAttr The Attribute Function Callbacks +The attribute API routines (\ref H5A) allow HDF5 users to create and manage HDF5 attributes. All the \ref H5A +API routines that modify the HDF5 container map to one of the attribute callback routines in this class +that the connector needs to implement. + +<em>Structure for attribute callback routines, H5VLconnector.h</em> +\code +typedef struct H5VL_attr_class_t { + void *(*create)(void *obj, const H5VL_loc_params_t *loc_params, const char *attr_name, hid_t type_id, + hid_t space_id, hid_t acpl_id, hid_t aapl_id, hid_t dxpl_id, void **req); + void *(*open)(void *obj, const H5VL_loc_params_t *loc_params, const char *attr_name, hid_t aapl_id, + hid_t dxpl_id, void **req); + herr_t (*read)(void *attr, hid_t mem_type_id, void *buf, hid_t dxpl_id, void **req); + herr_t (*write)(void *attr, hid_t mem_type_id, const void *buf, hid_t dxpl_id, void **req); + herr_t (*get)(void *obj, H5VL_attr_get_args_t *args, hid_t dxpl_id, void **req); + herr_t (*specific)(void *obj, const H5VL_loc_params_t *loc_params, H5VL_attr_specific_args_t *args, + hid_t dxpl_id, void **req); + herr_t (*optional)(void *obj, H5VL_optional_args_t *args, hid_t dxpl_id, void **req); + herr_t (*close)(void *attr, hid_t dxpl_id, void **req); +} H5VL_attr_class_t; +\endcode + +\subsubsection subsubsecVOLRefAttrcreate attr: create +The <em>create</em> callback in the attribute class creates an attribute object in the container of the location object +and returns a pointer to the attribute structure containing information to access the attribute in future calls. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + void *(*create)(void *obj, H5VL_loc_params_t *loc_params, const char *attr_name, hid_t type_id, hid_t space_id, hid_t acpl_id, hid_t aapl_id, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): Pointer to an object where the attribute needs to be created or where the look-up + of the target object needs to start. + loc_params (IN): Pointer to the location parameters as explained in "Mapping the API to the Callbacks". + attr_name (IN): The name of the attribute to be created. + type_id (IN): The datatype of the attribute. + space_id (IN): The dataspace of the attribute. + acpl_id (IN): The attribute creation property list. + aapl_id (IN): The attribute access property list. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> + +\subsubsection subsubsecVOLRefAttropen attr: open +The <em>open</em> callback in the attribute class opens an attribute object in the container of the location object and +returns a pointer to the attribute structure containing information to access the attribute in future calls.<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + void *(*open)(void *obj, H5VL_loc_params_t *loc_params, const char *attr_name, hid_t aapl_id, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): Pointer to an object where the attribute needs to be opened or where the look-up + of the target object needs to start. + loc_params (IN): Pointer to the location parameters as explained in "Mapping the API to the Callbacks". + attr_name (IN): The name of the attribute to be opened. + aapl_id (IN): The attribute access property list. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> + +\subsubsection subsubsecVOLRefAttrread attr: read +The <em>read</em> callback in the attribute class reads data from the attribute object and returns an <em>herr_t</em> indicating +success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*read)(void *attr, hid_t mem_type_id, void *buf, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + attr (IN): Pointer to the attribute object. + mem_type_id (IN): The memory datatype of the attribute. + buf (OUT): Data buffer to be read into. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> + +\subsubsection subsubsecVOLRefAttrwrite attr: write +The <em>write</em> callback in the attribute class writes data to the attribute object and returns an <em>herr_t</em> indicating +success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*write)(void *attr, hid_t mem_type_id, const void *buf, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + attr (IN): Pointer to the attribute object. + mem_type_id (IN): The memory datatype of the attribute. + buf (IN): Data buffer to be written. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> + +\subsubsection subsubsecVOLRefAttrget attr: get +The <em>get</em> callback in the attribute class retrieves information about the attribute as specified in the <em>get_type</em> parameter. +It returns an <em>herr_t</em> indicating success or failure +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*get)(void *obj, H5VL_attr_get_args_t *args, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): An attribute or location object where information needs to be retrieved from. + args (IN/OUT): A pointer to the arguments struct. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> + +\code +/* Values for attribute 'get' operations */ +typedef enum H5VL_attr_get_t { + H5VL_ATTR_GET_ACPL, /* creation property list */ + H5VL_ATTR_GET_INFO, /* info */ + H5VL_ATTR_GET_NAME, /* access property list */ + H5VL_ATTR_GET_SPACE, /* dataspace */ + H5VL_ATTR_GET_STORAGE_SIZE, /* storage size */ + H5VL_ATTR_GET_TYPE /* datatype */ +} H5VL_attr_get_t; + +/* Parameters for attribute 'get_name' operation */ +typedef struct H5VL_attr_get_name_args_t { + H5VL_loc_params_t loc_params; /* Location parameters for object access */ + size_t buf_size; /* Size of attribute name buffer */ + char *buf; /* Buffer for attribute name (OUT) */ + size_t *attr_name_len; /* Actual length of attribute name (OUT) */ +} H5VL_attr_get_name_args_t; + +/* Parameters for attribute 'get_info' operation */ +typedef struct H5VL_attr_get_info_args_t { + H5VL_loc_params_t loc_params; /* Location parameters for object access */ + const char *attr_name; /* Attribute name (for get_info_by_name) */ + H5A_info_t *ainfo; /* Attribute info (OUT) */ +} H5VL_attr_get_info_args_t; + +/* Parameters for attribute 'get' operations */ +typedef struct H5VL_attr_get_args_t { + H5VL_attr_get_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_ATTR_GET_ACPL */ + struct { + hid_t acpl_id; /* Attribute creation property list ID (OUT) */ + } get_acpl; + + /* H5VL_ATTR_GET_INFO */ + H5VL_attr_get_info_args_t get_info; /* Attribute info */ + + /* H5VL_ATTR_GET_NAME */ + H5VL_attr_get_name_args_t get_name; /* Attribute name */ + + /* H5VL_ATTR_GET_SPACE */ + struct { + hid_t space_id; /* Dataspace ID (OUT) */ + } get_space; + + /* H5VL_ATTR_GET_STORAGE_SIZE */ + struct { + hsize_t *data_size; /* Size of attribute in file (OUT) */ + } get_storage_size; + + /* H5VL_ATTR_GET_TYPE */ + struct { + hid_t type_id; /* Datatype ID (OUT) */ + } get_type; + } args; +} H5VL_attr_get_args_t; +\endcode + +\subsubsection subsubsecVOLRefAttrspec attr: specific +The <em>specific</em> callback in the attribute class implements specific operations on HDF5 attributes as specified +in the <em>specific_type</em> parameter. It returns an <em>herr_t</em> indicating success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*specific)(void *obj, H5VL_loc_params_t *loc_params, H5VL_attr_specific_args_t *args, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): The location object where the operation needs to happen. + loc_params (IN): A pointer to the location parameters as explained in "Mapping the API to the Callbacks". + args (IN/OUT): A pointer to the arguments struct. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> + +\code +/* Values for attribute 'specific' operation */ +typedef enum H5VL_attr_specific_t { + H5VL_ATTR_DELETE, /* H5Adelete(_by_name) */ + H5VL_ATTR_DELETE_BY_IDX, /* H5Adelete_by_idx */ + H5VL_ATTR_EXISTS, /* H5Aexists(_by_name) */ + H5VL_ATTR_ITER, /* H5Aiterate(_by_name) */ + H5VL_ATTR_RENAME /* H5Arename(_by_name) */ +} H5VL_attr_specific_t; + +/* Parameters for attribute 'iterate' operation */ +typedef struct H5VL_attr_iterate_args_t { + H5_index_t idx_type; /* Type of index to iterate over */ + H5_iter_order_t order; /* Order of index iteration */ + hsize_t *idx; /* Start/stop iteration index (IN/OUT) */ + H5A_operator2_t op; /* Iteration callback function */ + void *op_data; /* Iteration callback context */ +} H5VL_attr_iterate_args_t; + +/* Parameters for attribute 'delete_by_idx' operation */ +typedef struct H5VL_attr_delete_by_idx_args_t { + H5_index_t idx_type; /* Type of index to iterate over */ + H5_iter_order_t order; /* Order of index iteration */ + hsize_t n; /* Iteration index */ +} H5VL_attr_delete_by_idx_args_t; + +/* Parameters for attribute 'specific' operations */ +typedef struct H5VL_attr_specific_args_t { + H5VL_attr_specific_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_ATTR_DELETE */ + struct { + const char *name; /* Name of attribute to delete */ + } del; + + /* H5VL_ATTR_DELETE_BY_IDX */ + H5VL_attr_delete_by_idx_args_t delete_by_idx; + + /* H5VL_ATTR_EXISTS */ + struct { + const char *name; /* Name of attribute to check */ + hbool_t *exists; /* Whether attribute exists (OUT) */ + } exists; + + /* H5VL_ATTR_ITER */ + H5VL_attr_iterate_args_t iterate; + + /* H5VL_ATTR_RENAME */ + struct { + const char *old_name; /* Name of attribute to rename */ + const char *new_name; /* New attribute name */ + } rename; + } args; +} H5VL_attr_specific_args_t; +\endcode + +\subsubsection subsubsecVOLRefAttropt attr: optional +The <em>optional</em> callback in the attribute class implements connector specific operations on an HDF5 attribute. +It returns an <em>herr_t</em> indicating success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*optional)(void *obj, H5VL_optional_args_t *args, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): The container or object where the operation needs to happen. + args (IN/OUT): A pointer to the arguments struct. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> +Each connector that requires connector-specific operations should compare the value of the <em>op_type</em> field of +the #H5VL_optional_args_t struct with the values returned from calling #H5VLregister_opt_operation to +determine how to handle the optional call and interpret the arguments passed in the struct. + +\subsubsection subsubsecVOLRefAttrclose attr: close +The <em>close</em> callback in the attribute class terminates access to the attribute object and free all resources it +was consuming, and returns an <em>herr_t</em> indicating success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*close)(void *attr, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + attr (IN): Pointer to the attribute object. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> + +\subsection subsecVOLRefDset Dataset Callbacks +The dataset API routines (\ref H5D) allow HDF5 users to create and manage HDF5 datasets. All the \ref H5D API +routines that modify the HDF5 container map to one of the dataset callback routines in this class that the +connector needs to implement. + +<em>Structure for dataset callback routines, H5VLconnector.h</em> +\code +typedef struct H5VL_dataset_class_t { + void *(*create)(void *obj, const H5VL_loc_params_t *loc_params, const char *name, hid_t lcpl_id, + hid_t type_id, hid_t space_id, hid_t dcpl_id, hid_t dapl_id, hid_t dxpl_id, void **req); + void *(*open)(void *obj, const H5VL_loc_params_t *loc_params, const char *name, hid_t dapl_id, + hid_t dxpl_id, void **req); + herr_t (*read)(size_t count, void *dset[], hid_t mem_type_id[], hid_t mem_space_id[], + hid_t file_space_id[], hid_t dxpl_id, void *buf[], void **req); + herr_t (*write)(size_t count, void *dset[], hid_t mem_type_id[], hid_t mem_space_id[], + hid_t file_space_id[], hid_t dxpl_id, const void *buf[], void **req); + herr_t (*get)(void *obj, H5VL_dataset_get_args_t *args, hid_t dxpl_id, void **req); + herr_t (*specific)(void *obj, H5VL_dataset_specific_args_t *args, hid_t dxpl_id, void **req); + herr_t (*optional)(void *obj, H5VL_optional_args_t *args, hid_t dxpl_id, void **req); + herr_t (*close)(void *dset, hid_t dxpl_id, void **req); +} H5VL_dataset_class_t; +\endcode + +\subsubsection subsubsecVOLRefDsetcreate dataset: create +The <em>create</em> callback in the dataset class creates a dataset object in the container of the location object and +returns a pointer to the dataset structure containing information to access the dataset in future calls. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + void *(*create)(void *obj, H5VL_loc_params_t *loc_params, const char *name, hid_t lcpl_id,hid_t type_id, hid_t space_id, hid_t dcpl_id, hid_t dapl_id, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): Pointer to an object where the dataset needs to be created or where the look-up of + the target object needs to start. + loc_params (IN): Pointer to the location parameters as explained in "Mapping the API to the Callbacks". + The type can be only H5VL_OBJECT_BY_SELF in this callback. + name (IN): The name of the dataset to be created. + lcpl_id (IN): The link creation property list. + type_id (IN): The datatype of the dataset. + space_id (IN): The dataspace of the dataset. + dcpl_id (IN): The dataset creation property list. + dapl_id (IN): The dataset access property list. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> + +\subsubsection subsubsecVOLRefDsetopen dataset: open +The <em>open</em> callback in the dataset class opens a dataset object in the container of the location object and +returns a pointer to the dataset structure containing information to access the dataset in future calls. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + void *(*open)(void *obj, H5VL_loc_params_t *loc_params, const char *name, hid_t dapl_id, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): Pointer to an object where the dataset needs to be opened or where the look-up of the target object needs to start. + loc_params (IN): Pointer to the location parameters as explained in "Mapping the API to the Callbacks". + The type can be only H5VL_OBJECT_BY_SELF in this callback. + name (IN): The name of the dataset to be opened. + dapl_id (IN): The dataset access property list. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> + +\subsubsection subsubsecVOLRefDsetread dataset: read +The <em>read</em> callback in the dataset class reads data from the dataset object and returns an <em>herr_t</em> indicating +success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*read)(void *dset, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, hid_t dxpl_id, void *buf, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + dset (IN): Pointer to the dataset object. + mem_type_id (IN): The memory datatype of the data. + mem_space_id (IN): The memory dataspace selection. + file_space_id (IN): The file dataspace selection. + dxpl_id (IN): The data transfer property list. + buf (OUT): Data buffer to be read into. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> + +\subsubsection subsubsecVOLRefDsetwrite dataset: write +The <em>write</em> callback in the dataset class writes data to the dataset object and returns an <em>herr_t</em> indicating +success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*write)(void *dset, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, hid_t dxpl_id, const void *buf, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + dset (IN): Pointer to the dataset object. + mem_type_id (IN): The memory datatype of the data. + mem_space_id (IN): The memory dataspace selection. + file_space_id (IN): The file dataspace selection. + dxpl_id (IN): The data transfer property list. + buf (IN): Data buffer to be written from. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> + +\subsubsection subsubsecVOLRefDsetget dataset: get +The <em>get</em> callback in the dataset class retrieves information about the dataset as specified in the <em>get_type</em> +parameter.It returns an <em>herr_t</em> indicating success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*get)(void *dset, H5VL_dataset_get_args_t *args, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + dset (IN): The dataset object where information needs to be retrieved from. + args (IN/OUT): A pointer to the arguments struct. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> +\code +/* Values for dataset 'get' operation */ +typedef enum H5VL_dataset_get_t { + H5VL_DATASET_GET_DAPL, /* access property list */ + H5VL_DATASET_GET_DCPL, /* creation property list */ + H5VL_DATASET_GET_SPACE, /* dataspace */ + H5VL_DATASET_GET_SPACE_STATUS, /* space status */ + H5VL_DATASET_GET_STORAGE_SIZE, /* storage size */ + H5VL_DATASET_GET_TYPE /* datatype */ +} H5VL_dataset_get_t; + +/* Parameters for dataset 'get' operations */ +typedef struct H5VL_dataset_get_args_t { + H5VL_dataset_get_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_DATASET_GET_DAPL */ + struct { + hid_t dapl_id; /* Dataset access property list ID (OUT) */ + } get_dapl; + + /* H5VL_DATASET_GET_DCPL */ + struct { + hid_t dcpl_id; /* Dataset creation property list ID (OUT) */ + } get_dcpl; + + /* H5VL_DATASET_GET_SPACE */ + struct { + hid_t space_id; /* Dataspace ID (OUT) */ + } get_space; + + /* H5VL_DATASET_GET_SPACE_STATUS */ + struct { + H5D_space_status_t *status; /* Storage space allocation status (OUT) */ + } get_space_status; + + /* H5VL_DATASET_GET_STORAGE_SIZE */ + struct { + hsize_t *storage_size; /* Size of dataset's storage (OUT) */ + } get_storage_size; + + /* H5VL_DATASET_GET_TYPE */ + struct { + hid_t type_id; /* Datatype ID (OUT) */ + } get_type; + } args; +} H5VL_dataset_get_args_t; +\endcode + +\subsubsection subsubsecVOLRefDsetspec dataset: specific +The <em>specific</em> callback in the dataset class implements specific operations on HDF5 datasets as specified in +the <em>specific_type</em> parameter. It returns an <em>herr_t</em> indicating success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*specific)(void *obj, H5VL_file_specific_args_t *args, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): The dset where the operation needs to happen. + args (IN/OUT): A pointer to the arguments struct. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> +\code +/* Values for dataset 'specific' operation */ +typedef enum H5VL_dataset_specific_t { + H5VL_DATASET_SET_EXTENT, /* H5Dset_extent */ + H5VL_DATASET_FLUSH, /* H5Dflush */ + H5VL_DATASET_REFRESH /* H5Drefresh */ +} H5VL_dataset_specific_t; + +/* Parameters for dataset 'specific' operations */ +typedef struct H5VL_dataset_specific_args_t { + H5VL_dataset_specific_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_DATASET_SET_EXTENT */ + struct { + const hsize_t *size; /* New dataspace extent */ + } set_extent; + + /* H5VL_DATASET_FLUSH */ + struct { + hid_t dset_id; /* Dataset ID (IN) */ + } flush; + + /* H5VL_DATASET_REFRESH */ + struct { + hid_t dset_id; /* Dataset ID (IN) */ + } refresh; + } args; +} H5VL_dataset_specific_args_t; +\endcode + +\subsubsection subsubsecVOLRefDsetopt dataset: optional +The <em>optional</em> callback in the dataset class implements connector specific operations on an HDF5 dataset. +It returns an <em>herr_t</em> indicating success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*optional)(void *obj, H5VL_optional_args_t *args, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): The container or object where the operation needs to happen. + args (IN/OUT): A pointer to the arguments struct. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> +Each connector that requires connector-specific operations should compare the value of the <em>op_type</em> field of +the #H5VL_optional_args_t struct with the values returned from calling #H5VLregister_opt_operation to +determine how to handle the optional call and interpret the arguments passed in the struct. + +\subsubsection subsubsecVOLRefDsetclose dataset: close +The <em>close</em> callback in the dataset class terminates access to the dataset object and free all resources it was +consuming and returns an <em>herr_t</em> indicating success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*close)(void *dset, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + dset (IN): Pointer to the dataset object. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> + +\subsection subsecVOLRefDType Datatype Callbacks +The HDF5 datatype routines (\ref H5T) allow users to create and manage HDF5 datatypes. Those routines are +divided into two categories. One that operates on all types of datatypes but do not modify the contents of the +container (all in memory), and others that operate on named datatypes by accessing the container. When +a user creates an HDF5 datatype, it is still an object in memory space (transient datatype) that has not +been added to the HDF5 containers. Only when a user commits the HDF5 datatype, it becomes persistent +in the container. Those are called named/committed datatypes. The transient H5T routines should work +on named datatypes nevertheless. + +All the \ref H5T API routines that modify the HDF5 container map to one of the named datatype callback +routines in this class that the connector needs to implement. + +<em>Structure for datatype callback routines, H5VLconnector.h</em> +\code +typedef struct H5VL_datatype_class_t { + void *(*commit)(void *obj, const H5VL_loc_params_t *loc_params, const char *name, hid_t type_id, + hid_t lcpl_id, hid_t tcpl_id, hid_t tapl_id, hid_t dxpl_id, void **req); + void *(*open)(void *obj, const H5VL_loc_params_t *loc_params, const char *name, hid_t tapl_id, + hid_t dxpl_id, void **req); + herr_t (*get)(void *obj, H5VL_datatype_get_args_t *args, hid_t dxpl_id, void **req); + herr_t (*specific)(void *obj, H5VL_datatype_specific_args_t *args, hid_t dxpl_id, void **req); + herr_t (*optional)(void *obj, H5VL_optional_args_t *args, hid_t dxpl_id, void **req); + herr_t (*close)(void *dt, hid_t dxpl_id, void **req); +} H5VL_datatype_class_t; +\endcode + +\subsubsection subsubsecVOLRefDTypecommit datatype: commit +The <em>commit</em> callback in the named datatype class creates a datatype object in the container of the location +object and returns a pointer to the datatype structure containing information to access the datatype in +future calls. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + void *(*commit)(void *obj, H5VL_loc_params_t *loc_params, const char *name, hid_t type_id, hid_t lcpl_id, hid_t tcpl_id, hid_t tapl_id, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): Pointer to an object where the datatype needs to be committed or where the look-up of the target object needs to start. + loc_params (IN): Pointer to location parameters as explained in "Mapping the API to the Callbacks". + In this call, the location type is always H5VL_OBJECT_BY_SELF. + name (IN): The name of the datatype to be created. + typeid (IN): The transient datatype identifier to be committed. + lcpl_id (IN): The link creation property list. + tcpl_id (IN): The datatype creation property list. + tapl_id (IN): The datatype access property list. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> + +\subsubsection subsubsecVOLRefDTypeopen datatype: open +The <em>open</em> callback in the named datatype class opens a previously committed datatype object in the container +of the location object and returns a pointer to the datatype structure containing information to access the +datatype in future calls. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + void *(*open) (void *obj, H5VL_loc_params_t *loc_params, const char * name, hid_t tapl_id, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): Pointer to an object where the datatype needs to be opened or where the look-up + of the target object needs to start. + loc_params (IN): Pointer to location parameters as explained in "Mapping the API to the Callbacks". + In this call, the location type is always H5VL_OBJECT_BY_SELF. + name (IN): The name of the datatype to be opened. + tapl_id (IN): The datatype access property list. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> + +\subsubsection subsubsecVOLRefDTypeget datatype: get +The <em>get</em> callback in the named datatype class retrieves information about the named datatype as specified +in thegettypeparameter.It returns an <em>herr_t</em> indicating success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*get) (void *obj, H5VL_datatype_get_args_t *args, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): The named datatype to retrieve information from. + args (IN/OUT): A pointer to the arguments struct. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> +\code +/* Values for datatype 'get' operation */ +typedef enum H5VL_datatype_get_t { + H5VL_DATATYPE_GET_BINARY_SIZE, /* Get size of serialized form of transient type */ + H5VL_DATATYPE_GET_BINARY, /* Get serialized form of transient type */ + H5VL_DATATYPE_GET_TCPL /* Datatype creation property list */ +} H5VL_datatype_get_t; + +/* Parameters for datatype 'get' operations */ +typedef struct H5VL_datatype_get_args_t { + H5VL_datatype_get_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_DATATYPE_GET_BINARY_SIZE */ + struct { + size_t *size; /* Size of serialized form of datatype (OUT) */ + } get_binary_size; + + /* H5VL_DATATYPE_GET_BINARY */ + struct { + void *buf; /* Buffer to store serialized form of datatype (OUT) */ + size_t buf_size; /* Size of serialized datatype buffer */ + } get_binary; + + /* H5VL_DATATYPE_GET_TCPL */ + struct { + hid_t tcpl_id; /* Named datatype creation property list ID (OUT) */ + } get_tcpl; + } args; +} H5VL_datatype_get_args_t; +\endcode + +\subsubsection subsubsecVOLRefDTypespec datatype: specific +The <em>specific</em> callback in the datatype class implements specific operations on HDF5 named datatypes as +specified in the <em>specific_type</em> parameter. It returns an <em>herr_t</em> indicating success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*specific)(void *obj, H5VL_loc_params_t *loc_params, H5VL_object_specific_args_t *args, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): The container or object where the operation needs to happen. + loc_params (IN): Pointer to location parameters as explained in "Mapping the API to the Callbacks". + args (IN/OUT): A pointer to the arguments struct. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> +\code +/* Values for datatype 'specific' operation */ +typedef enum H5VL_datatype_specific_t { + H5VL_DATATYPE_FLUSH, /* H5Tflush */ + H5VL_DATATYPE_REFRESH /* H5Trefresh */ +} H5VL_datatype_specific_t; + +/* Parameters for datatype 'specific' operations */ +typedef struct H5VL_datatype_specific_args_t { + H5VL_datatype_specific_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_DATATYPE_FLUSH */ + struct { + hid_t type_id; /* Named datatype ID (IN) */ + } flush; + + /* H5VL_DATATYPE_REFRESH */ + struct { + hid_t type_id; /* Named datatype ID (IN) */ + } refresh; + } args; +} H5VL_datatype_specific_args_t; +\endcode + +\subsubsection subsubsecVOLRefDTypeopt datatype: optional +The <em>optional</em> callback in the datatype class implements connector specific operations on an HDF5 datatype. +It returns an <em>herr_t</em> indicating success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*optional)(void *obj, H5VL_optional_args_t *args, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): The container or object where the operation needs to happen. + args (IN/OUT): A pointer to the arguments struct. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> + +Each connector that requires connector-specific operations should compare the value of the <em>op_type</em> field of +the #H5VL_optional_args_t struct with the values returned from calling #H5VLregister_opt_operation to +determine how to handle the optional call and interpret the arguments passed in the struct. + +\subsubsection subsubsecVOLRefDTypeclose datatype: close +The <em>close</em> callback in the named datatype class terminates access to the datatype object and free all +resources it was consuming and returns an <em>herr_t</em> indicating success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*close) (void *dt, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + dt (IN): Pointer to the datatype object. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> + +\subsection subsecVOLRefFile File Callbacks +The file API routines (\ref H5F) allow HDF5 users to create and manage HDF5 containers. All the \ref H5F API +routines that modify the HDF5 container map to one of the file callback routines in his class that the +connector needs to implement. + +<em>File class for file API routines, H5VLconnector.h</em> +\code +typedef struct H5VL_file_class_t { + void *(*create)(const char *name, unsigned flags, hid_t fcpl_id, hid_t fapl_id, hid_t dxpl_id, + void **req); + void *(*open)(const char *name, unsigned flags, hid_t fapl_id, hid_t dxpl_id, void **req); + herr_t (*get)(void *obj, H5VL_file_get_args_t *args, hid_t dxpl_id, void **req); + herr_t (*specific)(void *obj, H5VL_file_specific_args_t *args, hid_t dxpl_id, void **req); + herr_t (*optional)(void *obj, H5VL_optional_args_t *args, hid_t dxpl_id, void **req); + herr_t (*close)(void *file, hid_t dxpl_id, void **req); +} H5VL_file_class_t; +\endcode + +\subsubsection subsubsecVOLRefFilecreate file: create +The <em>create</em> callback in the file class should create a container and returns a pointer to the file structure +created by the connector containing information to access the container in future calls. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + void *(*create)(const char *name, unsigned flags, hid_t fcpl_id, hid_t fapl_id, hid_tdxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + name (IN): The name of the container to be created. + flags (IN): The creation flags of the container. + fcpl_id (IN): The file creation property list. + fapl_id (IN): The file access property list. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> + +\subsubsection subsubsecVOLRefFileopen file: open +The <em>open</em> callback in the file class should open a container and returns a pointer to the file structure created +by the connector containing information to access the container in future calls. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + void *(*open)(const char *name, unsigned flags, hid_t fapl_id, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + name (IN): The name of the container to open. + flags (IN): The open flags of the container. + fapl_id (IN): The file access property list. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> + +\subsubsection subsubsecVOLRefFileget file: get +The <em>get</em> callback in the file class should retrieve information about the container as specified in the <em>get_type</em> +parameter. It returns an <em>herr_t</em> indicating success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*get)(void *obj, H5VL_file_get_args_t *args, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): The container or object where information needs to be retrieved from. + args (IN/OUT): A pointer to the arguments struct. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> +\code +/* Info for H5VL_FILE_GET_CONT_INFO */ +typedef struct H5VL_file_cont_info_t { + unsigned version; /* version information (keep first) */ + uint64_t feature_flags; /* Container feature flags */ + /* (none currently defined) */ + size_t token_size; /* Size of tokens */ + size_t blob_id_size; /* Size of blob IDs */ +} H5VL_file_cont_info_t; + +/* Values for file 'get' operation */ +typedef enum H5VL_file_get_t { + H5VL_FILE_GET_CONT_INFO, /* file get container info */ + H5VL_FILE_GET_FAPL, /* file access property list */ + H5VL_FILE_GET_FCPL, /* file creation property list */ + H5VL_FILE_GET_FILENO, /* file number */ + H5VL_FILE_GET_INTENT, /* file intent */ + H5VL_FILE_GET_NAME, /* file name */ + H5VL_FILE_GET_OBJ_COUNT, /* object count in file */ + H5VL_FILE_GET_OBJ_IDS /* object ids in file */ +} H5VL_file_get_t; + +/* Parameters for file 'get_name' operation */ +typedef struct H5VL_file_get_name_args_t { + H5I_type_t type; /* ID type of object pointer */ + size_t buf_size; /* Size of file name buffer (IN) */ + char *buf; /* Buffer for file name (OUT) */ + size_t *file_name_len; /* Actual length of file name (OUT) */ +} H5VL_file_get_name_args_t; + +/* Parameters for file 'get_obj_ids' operation */ +typedef struct H5VL_file_get_obj_ids_args_t { + unsigned types; /* Type of objects to count */ + size_t max_objs; /* Size of array of object IDs */ + hid_t *oid_list; /* Array of object IDs (OUT) */ + size_t *count; /* # of objects (OUT) */ +} H5VL_file_get_obj_ids_args_t; + +/* Parameters for file 'get' operations */ +typedef struct H5VL_file_get_args_t { + H5VL_file_get_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_FILE_GET_CONT_INFO */ + struct { + H5VL_file_cont_info_t *info; /* Container info (OUT) */ + } get_cont_info; + + /* H5VL_FILE_GET_FAPL */ + struct { + hid_t fapl_id; /* File access property list (OUT) */ + } get_fapl; + + /* H5VL_FILE_GET_FCPL */ + struct { + hid_t fcpl_id; /* File creation property list (OUT) */ + } get_fcpl; + + /* H5VL_FILE_GET_FILENO */ + struct { + unsigned long *fileno; /* File "number" (OUT) */ + } get_fileno; + + /* H5VL_FILE_GET_INTENT */ + struct { + unsigned *flags; /* File open/create intent flags (OUT) */ + } get_intent; + + /* H5VL_FILE_GET_NAME */ + H5VL_file_get_name_args_t get_name; + + /* H5VL_FILE_GET_OBJ_COUNT */ + struct { + unsigned types; /* Type of objects to count */ + size_t *count; /* # of objects (OUT) */ + } get_obj_count; + + /* H5VL_FILE_GET_OBJ_IDS */ + H5VL_file_get_obj_ids_args_t get_obj_ids; + } args; +} H5VL_file_get_args_t; +\endcode + +\subsubsection subsubsecVOLRefFilespec file: specific +The <em>specific</em> callback in the file class implements specific operations on HDF5 files as specified in the +<em>specific_type</em> parameter. It returns an <em>herr_t</em> indicating success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*specific)(void *obj, H5VL_file_specific_args_t *args, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): The container or object where the operation needs to happen. + args (IN/OUT): A pointer to the arguments struct. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> +\code +/* Values for file 'specific' operation */ +typedef enum H5VL_file_specific_t { + H5VL_FILE_FLUSH, /* Flush file */ + H5VL_FILE_REOPEN, /* Reopen the file */ + H5VL_FILE_IS_ACCESSIBLE, /* Check if a file is accessible */ + H5VL_FILE_DELETE, /* Delete a file */ + H5VL_FILE_IS_EQUAL /* Check if two files are the same */ +} H5VL_file_specific_t; + +/* Parameters for file 'specific' operations */ +typedef struct H5VL_file_specific_args_t { + H5VL_file_specific_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_FILE_FLUSH */ + struct { + H5I_type_t obj_type; /* Type of object to use */ + H5F_scope_t scope; /* Scope of flush operation */ + } flush; + + /* H5VL_FILE_REOPEN */ + struct { + void **file; /* File object for new file (OUT) */ + } reopen; + + /* H5VL_FILE_IS_ACCESSIBLE */ + struct { + const char *filename; /* Name of file to check */ + hid_t fapl_id; /* File access property list to use */ + hbool_t *accessible; /* Whether file is accessible with FAPL settings (OUT) */ + } is_accessible; + + /* H5VL_FILE_DELETE */ + struct { + const char *filename; /* Name of file to delete */ + hid_t fapl_id; /* File access property list to use */ + } del; + + /* H5VL_FILE_IS_EQUAL */ + struct { + void *obj2; /* Second file object to compare against */ + hbool_t *same_file; /* Whether files are the same (OUT) */ + } is_equal; + } args; +} H5VL_file_specific_args_t; +\endcode + +\subsubsection subsubsecVOLRefFileopt file: optional +The <em>optional</em> callback in the file class implements connector specific operations on an HDF5 container. It +returns an <em>herr_t</em> indicating success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*optional)(void *obj, H5VL_optional_args_t *args, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): The container or object where the operation needs to happen. + args (IN/OUT): A pointer to the arguments struct. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> +Each connector that requires connector-specific operations should compare the value of the <em>op_type</em> field of +the #H5VL_optional_args_t struct with the values returned from calling #H5VLregister_opt_operation to +determine how to handle the optional call and interpret the arguments passed in the struct. + +\subsubsection subsubsecVOLRefFileclose file: close +The <em>close</em> callback in the file class should terminate access to the file object and free all resources it was +consuming, and returns an <em>herr_t</em> indicating success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*close)(void *file, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + file (IN): Pointer to the file. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> + +\subsection subsecVOLRefGrp Group Callbacks +The group API routines (\ref H5G) allow HDF5 users to create and manage HDF5 groups. All the \ref H5G API +routines that modify the HDF5 container map to one of the group callback routines in this class that the +connector needs to implement. + +<em>Structure for group callback routines, H5VLconnector.h</em> +\code +typedef struct H5VL_group_class_t { + void *(*create)(void *obj, const H5VL_loc_params_t *loc_params, const char *name, hid_t lcpl_id, + hid_t gcpl_id, hid_t gapl_id, hid_t dxpl_id, void **req); + void *(*open)(void *obj, const H5VL_loc_params_t *loc_params, const char *name, hid_t gapl_id, + hid_t dxpl_id, void **req); + herr_t (*get)(void *obj, H5VL_group_get_args_t *args, hid_t dxpl_id, void **req); + herr_t (*specific)(void *obj, H5VL_group_specific_args_t *args, hid_t dxpl_id, void **req); + herr_t (*optional)(void *obj, H5VL_optional_args_t *args, hid_t dxpl_id, void **req); + herr_t (*close)(void *grp, hid_t dxpl_id, void **req); +} H5VL_group_class_t; +\endcode + +\subsubsection subsubsecVOLRefGrpcreate group: create +The <em>create</em> callback in the group class creates a group object in the container of the location object and +returns a pointer to the group structure containing information to access the group in future calls. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + void *(*create)(void *obj, H5VL_loc_params_t *loc_params, const char *name, hid_t gcpl_id,hid_t gapl_id, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): Pointer to an object where the group needs to be created or where the look-up of + the target object needs to start. + loc_params (IN): Pointer to the location parameters as explained in "Mapping the API to the Callbacks". + The type can be only H5VL_OBJECT_BY_SELF in this callback. + name (IN): The name of the group to be created. + dcpl_id (IN): The group creation property list. It contains all the group creation properties in + addition to the link creation property list of the create operation (an hid_t) that can be + retrieved with the property H5VL_GRP_LCPL_ID. + gapl_id (IN): The group access property list. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> + +\subsubsection subsubsecVOLRefGrpopen group: open +The <em>open</em> callback in the group class opens a group object in the container of the location object and returns +a pointer to the group structure containing information to access the group in future calls. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + void *(*open)(void *obj, H5VL_loc_params_t *loc_params, const char *name, hid_t gapl_id, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): Pointer to an object where the group needs to be opened or where the look-up of the target object needs to start. + loc_params (IN): Pointer to the location parameters as explained in "Mapping the API to the Callbacks". + The type can be only H5VL_OBJECT_BY_SELF in this callback. + name (IN): The name of the group to be opened. + gapl_id (IN): The group access property list. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> + +\subsubsection subsubsecVOLRefGrpget group: get +The <em>get</em> callback in the group class retrieves information about the group as specified in the <em>get_type</em> +parameter. It returns an <em>herr_t</em> indicating success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*get)(void *obj, H5VL_group_get_args_t *args, hid_t dxpl_id, void **req) +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): The group object where information needs to be retrieved from. + args (IN/OUT): A pointer to the arguments struct. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> +\code +/* Values for group 'get' operation */ +typedef enum H5VL_group_get_t { + H5VL_GROUP_GET_GCPL, /* group creation property list */ + H5VL_GROUP_GET_INFO /* group info */ +} H5VL_group_get_t; + +/* Parameters for group 'get_info' operation */ +typedef struct H5VL_group_get_info_args_t { + H5VL_loc_params_t loc_params; /* Location parameters for object access */ + H5G_info_t *ginfo; /* Group info (OUT) */ +} H5VL_group_get_info_args_t; + +/* Parameters for group 'get' operations */ +typedef struct H5VL_group_get_args_t { + H5VL_group_get_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_GROUP_GET_GCPL */ + struct { + hid_t gcpl_id; /* Group creation property list (OUT) */ + } get_gcpl; + + /* H5VL_GROUP_GET_INFO */ + H5VL_group_get_info_args_t get_info; /* Group info */ + } args; +} H5VL_group_get_args_t; +\endcode + +\subsubsection subsubsecVOLRefGrpspec group: specific +The <em>specific</em> callback in the group class implements specific operations on HDF5 groups as specified in the +<em>specific_type</em> parameter. It returns an <em>herr_t</em> indicating success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*specific)(void *obj, H5VL_loc_params_t *loc_params, H5VL_object_specific_args_t *args, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): The container or object where the operation needs to happen. + loc_params (IN): Pointer to the location parameters as explained in "Mapping the API to the Callbacks". + args (IN/OUT): A pointer to the arguments struct. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> +\code +/* Values for group 'specific' operation */ +typedef enum H5VL_group_specific_t { + H5VL_GROUP_MOUNT, /* Mount a file on a group */ + H5VL_GROUP_UNMOUNT, /* Unmount a file on a group */ + H5VL_GROUP_FLUSH, /* H5Gflush */ + H5VL_GROUP_REFRESH /* H5Grefresh */ +} H5VL_group_specific_t; + +/* Parameters for group 'mount' operation */ +typedef struct H5VL_group_spec_mount_args_t { + const char *name; /* Name of location to mount child file */ + void *child_file; /* Pointer to child file object */ + hid_t fmpl_id; /* File mount property list to use */ +} H5VL_group_spec_mount_args_t; + +/* Parameters for group 'specific' operations */ +typedef struct H5VL_group_specific_args_t { + H5VL_group_specific_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_GROUP_MOUNT */ + H5VL_group_spec_mount_args_t mount; + + /* H5VL_GROUP_UNMOUNT */ + struct { + const char *name; /* Name of location to unmount child file */ + } unmount; + + /* H5VL_GROUP_FLUSH */ + struct { + hid_t grp_id; /* Group ID (IN) */ + } flush; + + /* H5VL_GROUP_REFRESH */ + struct { + hid_t grp_id; /* Group ID (IN) */ + } refresh; + } args; +} H5VL_group_specific_args_t; +\endcode + +\subsubsection subsubsecVOLRefGrpopt group: optional +The <em>optional</em> callback in the group class implements connector specific operations on an HDF5 group. It +returns an <em>herr_t</em> indicating success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*optional)(void *obj, H5VL_optional_args_t *args, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): The container or object where the operation needs to happen. + args (IN/OUT): A pointer to the arguments struct. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> +Each connector that requires connector-specific operations should compare the value of the <em>op_type</em> field of +the #H5VL_optional_args_t struct with the values returned from calling #H5VLregister_opt_operation to +determine how to handle the optional call and interpret the arguments passed in the struct. + +\subsubsection subsubsecVOLRefGrpclose group: close +The <em>close</em> callback in the group class terminates access to the group object and frees all resources it was +consuming, and returns an <em>herr_t</em> indicating success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*close)(void *group, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + group (IN): Pointer to the group object. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> + +\subsection subsecVOLRefLink Link Callbacks +The link API routines (\ref H5L) allow HDF5 users to create and manage HDF5 links. All the \ref H5L API routines +that modify the HDF5 container map to one of the link callback routines in this class that the connector +needs to implement. + +<em>Structure for link callback routines, H5VLconnector.h</em> +\code +typedef struct H5VL_link_class_t { + herr_t (*create)(H5VL_link_create_args_t *args, void *obj, const H5VL_loc_params_t *loc_params, + hid_t lcpl_id, hid_t lapl_id, hid_t dxpl_id, void **req); + herr_t (*copy)(void *src_obj, const H5VL_loc_params_t *loc_params1, void *dst_obj, + const H5VL_loc_params_t *loc_params2, hid_t lcpl_id, hid_t lapl_id, hid_t dxpl_id, + void **req); + herr_t (*move)(void *src_obj, const H5VL_loc_params_t *loc_params1, void *dst_obj, + const H5VL_loc_params_t *loc_params2, hid_t lcpl_id, hid_t lapl_id, hid_t dxpl_id, + void **req); + herr_t (*get)(void *obj, const H5VL_loc_params_t *loc_params, H5VL_link_get_args_t *args, hid_t dxpl_id, + void **req); + herr_t (*specific)(void *obj, const H5VL_loc_params_t *loc_params, H5VL_link_specific_args_t *args, + hid_t dxpl_id, void **req); + herr_t (*optional)(void *obj, const H5VL_loc_params_t *loc_params, H5VL_optional_args_t *args, + hid_t dxpl_id, void **req); +} H5VL_link_class_t; +\endcode + +\subsubsection subsubsecVOLRefLinkcreate link: create +The <em>create</em> callback in the group class creates a hard, soft, external, or user-defined link in the container. +It returns an <em>herr_t</em> indicating success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*create)(H5VL_link_create_args_t *args, void *obj, H5VL_loc_params_t *loc_params, hid_t lcpl_id, hid_t lapl_id, hid_t dxpl_id, void **req) +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + args (IN/OUT): A pointer to the arguments struct. + obj (IN): Pointer to an object where the link needs to be created from. + loc_params (IN): Pointer to the location parameters as explained in "Mapping the API to the Callbacks" for the source object. + lcplid (IN): The link creation property list. It contains all the link creation properties in + addition to other API parameters depending on the creation type, which will be detailed next. + laplid (IN): The link access property list. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> +\code +/* Link create types for VOL */ +typedef enum H5VL_link_create_t { + H5VL_LINK_CREATE_HARD, + H5VL_LINK_CREATE_SOFT, + H5VL_LINK_CREATE_UD +} H5VL_link_create_t; + +/* Parameters for link 'create' operations */ +typedef struct H5VL_link_create_args_t { + H5VL_link_create_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_LINK_CREATE_HARD */ + struct { + void *curr_obj; /* Current object */ + H5VL_loc_params_t curr_loc_params; /* Location parameters for current object */ + } hard; + + /* H5VL_LINK_CREATE_SOFT */ + struct { + const char *target; /* Target of soft link */ + } soft; + + /* H5VL_LINK_CREATE_UD */ + struct { + H5L_type_t type; /* Type of link to create */ + const void *buf; /* Buffer that contains link info */ + size_t buf_size; /* Size of link info buffer */ + } ud; + } args; +} H5VL_link_create_args_t; +\endcode + +\subsubsection subsubsecVOLRefLinkcopy link: copy +The <em>copy</em> callback in the link class copies a link within the HDF5 container. It returns an <em>herr_t</em> indicating +success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*copy)(void *src_obj, H5VL_loc_params_t *loc_params1, void *dst_obj, H5VL_loc_params_t *loc_params2, hid_t lcpl_id, hid_t lapl_id, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + src_obj (IN): original/source object or file. + loc_params1 (IN): Pointer to the location parameters for the source object as explained in "Mapping the API to the Callbacks". + The type can be only H5VL_OBJECT_BY_NAME in this callback. + dst_obj (IN): destination object or file. + loc_params2 (IN): Pointer to the location parameters for the destination object as explained in "Mapping the API to the Callbacks". + The type can be only H5VL_OBJECT_BY_NAME in this callback. + lcpl_id (IN): The link creation property list. + lapl_id (IN): The link access property list. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> + +\subsubsection subsubsecVOLRefLinkmove link: move +The <em>move</em> callback in the link class moves a link within the HDF5 container. It returns an <em>herr_t</em> indicating +success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*move)(void *src_obj, H5VL_loc_params_t *loc_params1, void *dst_obj, H5VL_loc_params_t *loc_params2, hid_t lcpl_id, hid_t lapl_id, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + src_obj (IN): original/source object or file. + loc_params1 (IN): Pointer to the location parameters for the source object as explained in "Mapping the API to the Callbacks". + The type can be only H5VL_OBJECT_BY_NAME in this callback. + dst_obj (IN): destination object or file. + loc_params2 (IN): Pointer to the location parameters for the destination object as explained in "Mapping the API to the Callbacks". + The type can be only H5VL_OBJECT_BY_NAME in this callback. + lcpl_id (IN): The link creation property list. + lapl_id (IN): The link access property list. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> + +\subsubsection subsubsecVOLRefLinkget link: get +The <em>get</em> callback in the link class retrieves information about links as specified in the <em>get_type</em> parameter. +It returns an <em>herr_t</em> indicating success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*get)(void *obj, H5VL_loc_params_t *loc_params, H5VL_link_get_args_t *args, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): The file or group object where information needs to be retrieved from. + loc_params (IN): Pointer to the location parameters for the destination object as explained in "Mapping the API to the Callbacks". + The type can be only H5VL_OBJECT_BY_NAME or H5VL_OBJECT_BY_IDX in this callback. + args (IN/OUT): A pointer to the arguments struct. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> +\code +/* Values for link 'get' operation */ +typedef enum H5VL_link_get_t { + H5VL_LINK_GET_INFO, /* link info */ + H5VL_LINK_GET_NAME, /* link name */ + H5VL_LINK_GET_VAL /* link value */ +} H5VL_link_get_t; + +/* Parameters for link 'get' operations */ +typedef struct H5VL_link_get_args_t { + H5VL_link_get_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_LINK_GET_INFO */ + struct { + H5L_info2_t *linfo; /* Pointer to link's info (OUT) */ + } get_info; + + /* H5VL_LINK_GET_NAME */ + struct { + size_t name_size; /* Size of link name buffer (IN) */ + char *name; /* Buffer for link name (OUT) */ + size_t *name_len; /* Actual length of link name (OUT) */ + } get_name; + + /* H5VL_LINK_GET_VAL */ + struct { + size_t buf_size; /* Size of link value buffer (IN) */ + void *buf; /* Buffer for link value (OUT) */ + } get_val; + } args; +} H5VL_link_get_args_t; +\endcode + +\subsubsection subsubsecVOLRefLinkspec link: specific +The <em>specific</em> callback in the link class implements specific operations on HDF5 links as specified in +the <em>specific_type</em> parameter. It returns an <em>herr_t</em> indicating success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*specific)(void *obj, H5VL_loc_params_t *loc_params, H5VL_link_specific_args_t *args, hid_t dxpl_id, void **req) +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): The location object where operation needs to happen. + loc_params (IN): Pointer to the location parameters for the destination object as explained in "Mapping the API to the Callbacks". + args (IN/OUT): A pointer to the arguments struct. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> +\code +/* Values for link 'specific' operation */ +typedef enum H5VL_link_specific_t { + H5VL_LINK_DELETE, /* H5Ldelete(_by_idx) */ + H5VL_LINK_EXISTS, /* link existence */ + H5VL_LINK_ITER /* H5Literate/visit(_by_name) */ +} H5VL_link_specific_t; + +/* Parameters for link 'iterate' operation */ +typedef struct H5VL_link_iterate_args_t { + hbool_t recursive; /* Whether iteration is recursive */ + H5_index_t idx_type; /* Type of index to iterate over */ + H5_iter_order_t order; /* Order of index iteration */ + hsize_t *idx_p; /* Start/stop iteration index (OUT) */ + H5L_iterate2_t op; /* Iteration callback function */ + void *op_data; /* Iteration callback context */ +} H5VL_link_iterate_args_t; + +/* Parameters for link 'specific' operations */ +typedef struct H5VL_link_specific_args_t { + H5VL_link_specific_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_LINK_DELETE */ + /* No args */ + + /* H5VL_LINK_EXISTS */ + struct { + hbool_t *exists; /* Whether link exists (OUT) */ + } exists; + + /* H5VL_LINK_ITER */ + H5VL_link_iterate_args_t iterate; + } args; +} H5VL_link_specific_args_t; +\endcode + +\subsubsection subsubsecVOLRefLinkopt link: optional +The <em>optional</em> callback in the link class implements connector specific operations on an HDF5 link. It returns +an <em>herr_t</em> indicating success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*optional)(void *obj, const H5VL_loc_params_t *loc_params, H5VL_optional_args_t *args, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): The container or object where operation needs to happen. + loc_params (IN): Pointer to the location parameters for the destination object as explained in "Mapping the API to the Callbacks". + args (IN/OUT): A pointer to the arguments struct. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> +Each connector that requires connector-specific operations should compare the value of the <em>op_type</em> field of +the #H5VL_optional_args_t struct with the values returned from calling #H5VLregister_opt_operation to +determine how to handle the optional call and interpret the arguments passed in the struct. + +\subsection subsecVOLRefObj Object Callbacks +The object API routines (\ref H5O) allow HDF5 users to manage HDF5 group, dataset, and named datatype +objects. All the \ref H5O API routines that modify the HDF5 container map to one of the object callback +routines in this class that the connector needs to implement. + +<em>Structure for object callback routines, H5VLconnector.h</em> +\code +typedef struct H5VL_object_class_t { + void *(*open)(void *obj, const H5VL_loc_params_t *loc_params, H5I_type_t *opened_type, hid_t dxpl_id, + void **req); + herr_t (*copy)(void *src_obj, const H5VL_loc_params_t *loc_params1, const char *src_name, void *dst_obj, + const H5VL_loc_params_t *loc_params2, const char *dst_name, hid_t ocpypl_id, hid_t lcpl_id, + hid_t dxpl_id, void **req); + herr_t (*get)(void *obj, const H5VL_loc_params_t *loc_params, H5VL_object_get_args_t *args, hid_t dxpl_id, + void **req); + herr_t (*specific)(void *obj, const H5VL_loc_params_t *loc_params, H5VL_object_specific_args_t *args, + hid_t dxpl_id, void **req); + herr_t (*optional)(void *obj, const H5VL_loc_params_t *loc_params, H5VL_optional_args_t *args, + hid_t dxpl_id, void **req); +} H5VL_object_class_t; +\endcode + +\subsubsection subsubsecVOLRefObjopen object: open +The <em>open</em> callback in the object class opens the object in the container of the location object and returns a +pointer to the object structure containing information to access the object in future calls. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + void *(*open)(void *obj, H5VL_loc_params_t *loc_params, H5I_type_t *opened_type, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): The container or object where operation needs to happen. + loc_params (IN): Pointer to the location parameters for the destination object as explained in "Mapping the API to the Callbacks". + opened_type (OUT): Buffer to return the type of the object opened (H5I_GROUP or H5I_DATASET or H5I_DATATYPE). + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> + +\subsubsection subsubsecVOLRefObjcopy object: copy +The <em>copy</em> callback in the object class copies the object from the source object to the destination object. It +returns an <em>herr_t</em> indicating success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*copy)(void *src_obj, H5VL_loc_params_t *loc_params1, const char *src_name, void *dst_obj, H5VL_loc_params_t *loc_params2, const char *dst_name, hid_t ocpypl_id, hid_t lcpl_id, hid_t dxpl_id, void **req) +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + src_obj (IN): Pointer to location of the source object to be copied. + loc_params1 (IN): Pointer to the location parameters for the source object as explained in "Mapping the API to the Callbacks". + The type can be only H5VL_OBJECT_BY_SELF in this callback. + src_name (IN): Name of the source object to be copied. + dst_obj (IN): Pointer to location of the destination object or file. + loc_params2 (IN): Pointer to the location parameters for the destination object as explained in "Mapping the API to the Callbacks". + The type can be only H5VL_OBJECT_BY_SELF in this callback. + dst_name (IN): Name o be assigned to the new copy. + ocpypl_id (IN): The object copy property list. + lcpl_id (IN): The link creation property list. + dxpl_id (IN): The data transfer property list. + req (IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> + +\subsubsection subsubsecVOLRefObjget object: get +The <em>get</em> callback in the object class retrieves information about the object as specified in +the <em>get_type</em> parameter.It returns an <em>herr_t</em> indicating success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*get)(void *obj, H5VL_loc_params_t *loc_params, H5VL_object_get_args_t *args, hid_t dxpl_id, void **req) +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): A location object where information needs to be retrieved from. + loc_params (IN): Pointer to the location parameters for the destination object as explained in "Mapping the API to the Callbacks". + args (IN/OUT): A pointer to the arguments struct. + dxpl_id (IN): The data transfer property list. + req IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> +\code +/* Values for object 'get' operation */ +typedef enum H5VL_object_get_t { + H5VL_OBJECT_GET_FILE, /* object file */ + H5VL_OBJECT_GET_NAME, /* object name */ + H5VL_OBJECT_GET_TYPE, /* object type */ + H5VL_OBJECT_GET_INFO /* H5Oget_info(_by_idx|name) */ +} H5VL_object_get_t; + +/* Parameters for object 'get' operations */ +typedef struct H5VL_object_get_args_t { + H5VL_object_get_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_OBJECT_GET_FILE */ + struct { + void **file; /* File object (OUT) */ + } get_file; + + /* H5VL_OBJECT_GET_NAME */ + struct { + size_t buf_size; /* Size of name buffer (IN) */ + char *buf; /* Buffer for name (OUT) */ + size_t *name_len; /* Actual length of name (OUT) */ + } get_name; + + /* H5VL_OBJECT_GET_TYPE */ + struct { + H5O_type_t *obj_type; /* Type of object (OUT) */ + } get_type; + + /* H5VL_OBJECT_GET_INFO */ + struct { + unsigned fields; /* Flags for fields to retrieve */ + H5O_info2_t *oinfo; /* Pointer to object info (OUT) */ + } get_info; + } args; +} H5VL_object_get_args_t; +\endcode + +\subsubsection subsubsecVOLRefObjspec object: specific +The <em>specific</em> callback in the object class implements specific operations on HDF5 objects as specified in +the <em>specific_type</em> parameter. It returns an <em>herr_t</em> indicating success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*specific)(void *obj, H5VL_loc_params_t *loc_params, H5VL_object_specific_args_t *args, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): A location object where he operation needs to happen. + loc_params (IN): Pointer to the location parameters for the destination object as explained in "Mapping the API to the Callbacks". + args (IN/OUT): A pointer to the arguments struct. + dxpl_id (IN): The data transfer property list. + req IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> +\code +/* Values for object 'specific' operation */ +typedef enum H5VL_object_specific_t { + H5VL_OBJECT_CHANGE_REF_COUNT, /* H5Oincr/decr_refcount */ + H5VL_OBJECT_EXISTS, /* H5Oexists_by_name */ + H5VL_OBJECT_LOOKUP, /* Lookup object */ + H5VL_OBJECT_VISIT, /* H5Ovisit(_by_name) */ + H5VL_OBJECT_FLUSH, /* H5{D|G|O|T}flush */ + H5VL_OBJECT_REFRESH /* H5{D|G|O|T}refresh */ +} H5VL_object_specific_t; + +/* Parameters for object 'visit' operation */ +typedef struct H5VL_object_visit_args_t { + H5_index_t idx_type; /* Type of index to iterate over */ + H5_iter_order_t order; /* Order of index iteration */ + unsigned fields; /* Flags for fields to provide in 'info' object for 'op' callback */ + H5O_iterate2_t op; /* Iteration callback function */ + void *op_data; /* Iteration callback context */ +} H5VL_object_visit_args_t; + +/* Parameters for object 'specific' operations */ +typedef struct H5VL_object_specific_args_t { + H5VL_object_specific_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_OBJECT_CHANGE_REF_COUNT */ + struct { + int delta; /* Amount to modify object's refcount */ + } change_rc; + + /* H5VL_OBJECT_EXISTS */ + struct { + hbool_t *exists; /* Whether object exists (OUT) */ + } exists; + + /* H5VL_OBJECT_LOOKUP */ + struct { + H5O_token_t *token_ptr; /* Pointer to token for lookup (OUT) */ + } lookup; + + /* H5VL_OBJECT_VISIT */ + H5VL_object_visit_args_t visit; + + /* H5VL_OBJECT_FLUSH */ + struct { + hid_t obj_id; /* Object ID (IN) */ + } flush; + + /* H5VL_OBJECT_REFRESH */ + struct { + hid_t obj_id; /* Object ID (IN) */ + } refresh; + } args; +} H5VL_object_specific_args_t; +\endcode + +\subsubsection subsubsecVOLRefObjopt object: optional +The <em>optional</em> callback in the object class implements connector specific operations on an HDF5 object. It +returns an <em>herr_t</em> indicating success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*optional)(void *obj, const H5VL_loc_params_t *loc_params, H5VL_optional_args_t *args, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): A container or object where he operation needs to happen. + loc_params (IN): Pointer to the location parameters for the destination object as explained in "Mapping the API to the Callbacks". + args (IN/OUT): A pointer to the arguments struct. + dxpl_id (IN): The data transfer property list. + req IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> +Each connector that requires connector-specific operations should compare the value of the <em>op_type</em> field of +the #H5VL_optional_args_t struct with the values returned from calling #H5VLregister_opt_operation to +determine how to handle the optional call and interpret the arguments passed in the struct. + +\subsection subsecVOLRefIntrospect Introspection Callbacks +<em>Structure for VOL connector introspection callback routines, H5VLconnector.h</em> +\code +typedef struct H5VL_introspect_class_t { + herr_t (*get_conn_cls)(void *obj, H5VL_get_conn_lvl_t lvl, const struct H5VL_class_t **conn_cls); + herr_t (*get_cap_flags)(const void *info, uint64_t *cap_flags); + herr_t (*opt_query)(void *obj, H5VL_subclass_t cls, int opt_type, uint64_t *flags); +} H5VL_introspect_class_t; +\endcode + +\subsubsection subsubsecVOLRefIntrospectcls introspect: get_conn_cls +Get a connector's #H5VL_class_t struct. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*get_conn_cls)(void *obj, H5VL_get_conn_lvl_t lvl, const struct H5VL_class_t **conn_cls); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): The VOL object. + lvl (IN): Current or terminal connector. + cls (OUT): A const pointer to the connector. +\endcode +</td> +</tr> +</table> +<em>The "lvl" argument is an enum:</em> +\code +/* "Levels" for 'get connector class' introspection callback */ +typedef enum H5VL_get_conn_lvl_t { + H5VL_GET_CONN_LVL_CURR, /* Get "current" connector (for this object) */ + H5VL_GET_CONN_LVL_TERM /* Get "terminal" connector (for this object) */ + /* (Recursively called, for pass-through connectors) */ + /* (Connectors that "split" must choose which connector to return) */ +} H5VL_get_conn_lvl_t; +\endcode + +\subsubsection subsubsecVOLRefIntrospecflags introspect: get_cap_flags +Get a connector's capability flags. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*get_cap_flags)(const void *info, unsigned *cap_flags) +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + info (IN): A const pointer to pertinent VOL info. + cap_flags (OUT): A pointer to capability flags. +\endcode +</td> +</tr> +</table> + +\subsubsection subsubsecVOLRefIntrospecquery introspect: opt_query +Query a class for a capability or functionality. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*opt_query)(void *obj, H5VL_subclass_t cls, int opt_type, hbool_t *supported); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): The VOL object. + cls (IN): The VOL 'class' to query. + opt_type (IN): The specific option to query. + supported (OUT): Whether the operation is supported or not. +\endcode +</td> +</tr> +</table> +<em>The "cls" argument is an enum:</em> +\code +// Enum type for each VOL subclass +// (Used for various queries, etc) +typedef enum H5VL_subclass_t { + H5VL_SUBCLS_NONE, // Operations outside of a subclass + H5VL_SUBCLS_INFO, // 'Info' subclass + H5VL_SUBCLS_WRAP, // 'Wrap' subclass + H5VL_SUBCLS_ATTR, // 'Attribute' subclass + H5VL_SUBCLS_DATASET, // 'Dataset' subclass + H5VL_SUBCLS_DATATYPE, // 'Named datatype' subclass + H5VL_SUBCLS_FILE, // 'File' subclass + H5VL_SUBCLS_GROUP, // 'Group' subclass + H5VL_SUBCLS_LINK, // 'Link' subclass + H5VL_SUBCLS_OBJECT, // 'Object' subclass + H5VL_SUBCLS_REQUEST, // 'Request' subclass + H5VL_SUBCLS_BLOB, // 'Blob' subclass + H5VL_SUBCLS_TOKEN // 'Token' subclass +} H5VL_subclass_t; +\endcode + +\subsection subsecVOLRefReq Request (Async) Callbacks +<em>Structure for async request callback routines, H5VLconnector.h</em> +\code +typedef struct H5VL_request_class_t { + herr_t (*wait)(void *req, uint64_t timeout, H5VL_request_status_t *status); + herr_t (*notify)(void *req, H5VL_request_notify_t cb, void *ctx); + herr_t (*cancel)(void *req, H5VL_request_status_t *status); + herr_t (*specific)(void *req, H5VL_request_specific_args_t *args); + herr_t (*optional)(void *req, H5VL_optional_args_t *args); + herr_t (*free)(void *req); +} H5VL_request_class_t; +\endcode + +\subsubsection subsubsecVOLRefReqwait request: wait +Wait (with a timeout) for an async operation to complete. Releases the request if the operation has completed +and the connector callback succeeds. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*wait)(void *req, uint64_t timeout, H5VL_request_status_t *status); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + req (IN): The async request on which to wait. + timeout (IN): The timeout value. + status (IN): The status. +\endcode +</td> +</tr> +</table> +<em>The "status" argument is an enum:</em> +\code +/* Status values for async request operations */ +typedef enum H5VL_request_status_t { + H5VL_REQUEST_STATUS_IN_PROGRESS, /* Operation has not yet completed */ + H5VL_REQUEST_STATUS_SUCCEED, /* Operation has completed, successfully */ + H5VL_REQUEST_STATUS_FAIL, /* Operation has completed, but failed */ + H5VL_REQUEST_STATUS_CANT_CANCEL, /* An attempt to cancel this operation was made, but it */ + /* can't be canceled immediately. The operation has */ + /* not completed successfully or failed, and is not yet */ + /* in progress. Another attempt to cancel it may be */ + /* attempted and may (or may not) succeed. */ + H5VL_REQUEST_STATUS_CANCELED /* Operation has not completed and was canceled */ +} H5VL_request_status_t; +\endcode + +\subsubsection subsubsecVOLRefReqnotify request: notify +Registers a user callback to be invoked when an asynchronous operation completes. Releases the request if +connector callback succeeds. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*notify)(void *req, H5VL_request_notify_t cb, void *ctx); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + req (IN): The async request that will receive the notify callback. + cb (IN): The notify callback for the request. + ctx (IN): The request's context. +\endcode +</td> +</tr> +</table> +<em>The "cb" argument is an enum:</em> +\code + typedef herr_t (*H5VL_request_notify_t)(void *ctx, H5ES_status_t status) +\endcode + +\subsubsection subsubsecVOLRefReqcancel request: cancel +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*cancel)(void *req, H5VL_request_status_t *status); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + req (IN): The async request to be cancelled. + status (IN): The status. +\endcode +</td> +</tr> +</table> +<em>The "status" argument is an enum:</em> +\code +/* Status values for async request operations */ +typedef enum H5VL_request_status_t { + H5VL_REQUEST_STATUS_IN_PROGRESS, /* Operation has not yet completed */ + H5VL_REQUEST_STATUS_SUCCEED, /* Operation has completed, successfully */ + H5VL_REQUEST_STATUS_FAIL, /* Operation has completed, but failed */ + H5VL_REQUEST_STATUS_CANT_CANCEL, /* An attempt to cancel this operation was made, but it */ + /* can't be canceled immediately. The operation has */ + /* not completed successfully or failed, and is not yet */ + /* in progress. Another attempt to cancel it may be */ + /* attempted and may (or may not) succeed. */ + H5VL_REQUEST_STATUS_CANCELED /* Operation has not completed and was canceled */ +} H5VL_request_status_t; +\endcode + +\subsubsection subsubsecVOLRefReqspec request: specific +Perform a specific operation on an asynchronous request. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*specific)(void *req, H5VL_request_specific_args_t *args); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + req (IN): The async request on which to perform the operation. + args (IN/OUT): A pointer to the arguments struct. +\endcode +</td> +</tr> +</table> +\code +/* Values for async request 'specific' operation */ +typedef enum H5VL_request_specific_t { + H5VL_REQUEST_GET_ERR_STACK, /* Retrieve error stack for failed operation */ + H5VL_REQUEST_GET_EXEC_TIME /* Retrieve execution time for operation */ +} H5VL_request_specific_t; + +/* Parameters for request 'specific' operations */ +typedef struct H5VL_request_specific_args_t { + H5VL_request_specific_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_REQUEST_GET_ERR_STACK */ + struct { + hid_t err_stack_id; /* Error stack ID for operation (OUT) */ + } get_err_stack; + + /* H5VL_REQUEST_GET_EXEC_TIME */ + struct { + uint64_t *exec_ts; /* Timestamp for start of task execution (OUT) */ + uint64_t *exec_time; /* Duration of task execution (in ns) (OUT) */ + } get_exec_time; + } args; +} H5VL_request_specific_args_t; +\endcode + +\subsubsection subsubsecVOLRefReqopt request: optional +Perform a connector-specific operation for a request. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*optional)(void *req, H5VL_optional_args_t *args); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + req (IN): The async request on which to perform the operation. + args (IN/OUT): A pointer to the arguments struct. +\endcode +</td> +</tr> +</table> +Each connector that requires connector-specific operations should compare the value of the <em>op_type</em> field of +the #H5VL_optional_args_t struct with the values returned from calling #H5VLregister_opt_operation to +determine how to handle the optional call and interpret the arguments passed in the struct. + +\subsubsection subsubsecVOLRefReqfree request: free +Frees an asynchronous request. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*free)(void *req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + req (IN): The async request to be freed. +\endcode +</td> +</tr> +</table> + +\subsection subsecVOLRefBlob Blob Callbacks +<em>Structure for blob callback routines, H5VLconnector.h</em> +\code +typedef struct H5VL_blob_class_t { + herr_t (*put)(void *obj, const void *buf, size_t size, void *blob_id, void *ctx); + herr_t (*get)(void *obj, const void *blob_id, void *buf, size_t size, void *ctx); + herr_t (*specific)(void *obj, void *blob_id, H5VL_blob_specific_args_t *args); + herr_t (*optional)(void *obj, void *blob_id, H5VL_optional_args_t *args); +} H5VL_blob_class_t; +\endcode + +\subsubsection subsubsecVOLRefBlobput blob: put +Put a blob through the VOL. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*put)(void *obj, const void *buf, size_t size, void *blob_id, void *ctx); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): Pointer to the blob container. + buf (IN): Pointer to the blob. + size (IN): Size of the blob. + blob_id (OUT): Pointer to the blob's connector-specific ID. + ctx (IN): Connector-specific blob context. +\endcode +</td> +</tr> +</table> + +\subsubsection subsubsecVOLRefBlobget blob: get +Get a blob through the VOL. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*get)(void *obj, const void *blob_id, void *buf, size_t size, void *ctx); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): Pointer to the blob container. + blob_id (IN): Pointer to the blob's connector-specific ID. + buf (IN/OUT): Pointer to the blob. + size (IN): Size of the blob. + ctx (IN): Connector-specific blob context. +\endcode +</td> +</tr> +</table> + +\subsubsection subsubsecVOLRefBlobspec blob: specific +Perform a defined operation on a blob via the VOL. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*specific)(void *obj, void *blob_id, H5VL_blob_specific_args_t *args); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): Pointer to the blob container. + blob_id (IN): Pointer to the blob's connector-specific ID. + args (IN/OUT): A pointer to the arguments struct. +\endcode +</td> +</tr> +</table> +\code +/* Values for 'blob' 'specific' operation */ +typedef enum H5VL_blob_specific_t { + H5VL_BLOB_DELETE, /* Delete a blob (by ID) */ + H5VL_BLOB_ISNULL, /* Check if a blob ID is "null" */ + H5VL_BLOB_SETNULL /* Set a blob ID to the connector's "null" blob ID value */ +} H5VL_blob_specific_t; + +/* Parameters for blob 'specific' operations */ +typedef struct H5VL_blob_specific_args_t { + H5VL_blob_specific_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_BLOB_DELETE */ + /* No args */ + + /* H5VL_BLOB_ISNULL */ + struct { + hbool_t *isnull; /* Whether blob ID is "null" (OUT) */ + } is_null; + + /* H5VL_BLOB_SETNULL */ + /* No args */ + } args; +} H5VL_blob_specific_args_t; +\endcode + +\subsubsection subsubsecVOLRefBlobopt blob: optional +Perform a connector-specific operation on a blob via the VOL +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*optional)(void *obj, void *blob_id, H5VL_optional_args_t *args); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): Pointer to the blob container. + blob_id (IN): Pointer to the blob's connector-specific ID. + args (IN/OUT): A pointer to the arguments struct. +\endcode +</td> +</tr> +</table> +Each connector that requires connector-specific operations should compare the value of the <em>op_type</em> field of +the #H5VL_optional_args_t struct with the values returned from calling #H5VLregister_opt_operation to +determine how to handle the optional call and interpret the arguments passed in the struct + +\subsection subsecVOLRefToken Token Callbacks +<em>Structure for token callback routines, H5VLconnector.h</em> +\code +typedef struct H5VL_token_class_t { + herr_t (*cmp)(void *obj, const H5O_token_t *token1, const H5O_token_t *token2, int *cmp_value); + herr_t (*to_str)(void *obj, H5I_type_t obj_type, const H5O_token_t *token, char **token_str); + herr_t (*from_str)(void *obj, H5I_type_t obj_type, const char *token_str, H5O_token_t *token); +} H5VL_token_class_t; +\endcode + +\subsubsection subsubsecVOLRefTokencmp token: cmp +Compares two tokens and outputs a value like strcmp. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*cmp)(void *obj, const H5O_token_t *token1, const H5O_token_t *token2, int *cmp_value); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): The underlying VOL object. + token1 (IN): The first token to compare. + token2 (IN): The second token to compare. + cmp_value (OUT): A value like strcmp. +\endcode +</td> +</tr> +</table> + +\subsubsection subsubsecVOLRefTokento token: to_str +Converts a token to a string representation. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*to_str)(void *obj, H5I_type_t obj_type, const H5O_token_t *token, char **token_str) +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): The underlying VOL object. + obj_type (IN): The type of the object. + token (IN): The token to turn into a string representation. + token_str (OUT): The string representation of the token. +\endcode +</td> +</tr> +</table> +<em>The "obj_type" argument is an enum: (from H5Ipublic.h)</em> +\snippet H5Ipublic.h H5I_type_t_snip +The only values which should be used for this call are: +\li #H5I_GROUP +\li #H5I_DATATYPE +\li #H5I_DATASET +\li #H5I_MAP + +as these are the only objects for which tokens are valid. + +\subsubsection subsubsecVOLRefTokenfrom token: from_str +Converts a string representation of a token to a token. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*from_str)(void *obj, H5I_type_t obj_type, const char *token_str, H5O_token_t *token); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): The underlying VOL object. + obj_type (IN): The type of the object. + token_str (IN): The string representation of the token. + token (OUT): The token reated from the string representation. +\endcode +</td> +</tr> +</table> +<em>The "obj_type" argument is an enum: (from H5Ipublic.h)</em> +\snippet H5Ipublic.h H5I_type_t_snip +The only values which should be used for this call are: +\li #H5I_GROUP +\li #H5I_DATATYPE +\li #H5I_DATASET +\li #H5I_MAP + +as these are the only objects for which tokens are valid. + +\subsection subsecVOLRefOpt Optional Generic Callback +A <em>generic</em> optional callback is provided for services that are specific to a connector. +The <em>optional</em> callback has the following definition. It returns an <em>herr_t</em> indicating success or failure. +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t (*optional)(void *obj, H5VL_optional_args_t *args, hid_t dxpl_id, void **req); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): A container or object where he operation needs to happen. + args (IN/OUT): A pointer to the arguments struct. + dxpl_id (IN): The data transfer property list. + req IN/OUT): A pointer to the asynchronous request of the operation created by the connector. +\endcode +</td> +</tr> +</table> + +\section secVOLNew New VOL API Routines +API routines have been added to the HDF5 library to manage VOL connectors. This section details each +new API call and explains its intended usage. Additionally, a set of API calls that map directly to the VOL +callbacks themselves have been added to aid in the development of passthrough connectors which can be +stacked and/or split. A list of these API calls is given in an appendix. + +\subsection subsecVOLNewPub H5VLpublic.h +The API calls in this header are for VOL management and general use (i.e., not limited to VOL connector authors). + +\subsubsection subsubsecVOLNewPubregname H5VLregister_connector_by_name +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + hid_t H5VLregister_connector_by_name(const char *connector_name, hid_t vipl_id); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + connector_name (IN): The connector name to search for and register. + vipl_id (IN): An ID for a VOL initialization property list (vipl). +\endcode +</td> +</tr> +</table> +Registers a VOL connector with the HDF5 library given the name of the connector and returns an identifier +for it (#H5I_INVALID_HID on errors). If the connector is already registered, the library will create a new +identifier for it and returns it to the user; otherwise the library will search the plugin path for a connector +of that name, loading and registering it, returning an ID for it, if found. See the \ref H5VL_UG for more +information on loading plugins and the search paths. + +\subsubsection subsubsecVOLNewPubregval H5VLregister_connector_by_value +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + hid_t H5VLregister_connector_by_value(H5VL_class_value_t connector_value, hid_t vipl_id); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + connector_value (IN): The connector value to search for and register. + vipl_id (IN): An ID for a VOL initialization property list (vipl). +\endcode +</td> +</tr> +</table> +Registers a VOL connector with the HDF5 library given a value for the connector and returns an identifier +for it (#H5I_INVALID_HID on errors). If the connector is already registered, the library will create a new +identifier for it and returns it to the user; otherwise the library will search the plugin path for a connector +of that name, loading and registering it, returning an ID for it, if found. See the VOL User Guide for more +information on loading plugins and the search paths. + +\subsubsection subsubsecVOLNewPubis_name H5VLis_connector_registered_by_name +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + htri_t H5VLis_connector_registered_by_name(const char *name); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + name (IN): The connector name to check for. +\endcode +</td> +</tr> +</table> +Checks if a VOL connector is registered with the library given the connector name and returns TRUE/FALSE +on success, otherwise it returns a negative value. + +\subsubsection subsubsecVOLNewPubis_value H5VLis_connector_registered_by_value +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + htri_t H5VLis_connector_registered_by_value(H5VL_class_value_t connector_value); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + connector_value (IN): The connector value to check for. +\endcode +</td> +</tr> +</table> +Checks if a VOL connector is registered with the library given the connector value and returns TRUE/FALSE +on success, otherwise it returns a negative value. + +\subsubsection subsubsecVOLNewPubget_id H5VLget_connector_id +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + hid_t H5VLget_connector_id(hid_t obj_id); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj_id (IN): An ID for an HDF5 VOL object. +\endcode +</td> +</tr> +</table> +Given a VOL object such as a dataset or an attribute, this function returns an identifier for its associated +connector. If the ID is not a VOL object (such as a dataspace or uncommitted datatype), #H5I_INVALID_HID +is returned. The identifier must be released with a call to #H5VLclose. + +\subsubsection subsubsecVOLNewPubget_by_name H5VLget_connector_id_by_name +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + hid_t H5VLget_connector_id_by_name(const char *name); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + name (IN): The connector name to check for. +\endcode +</td> +</tr> +</table> +Given a connector name that is registered with the library, this function returns an identifier for the connector. +If the connector is not registered with the library, #H5I_INVALID_HID is returned.The identifier must be +released with a call to #H5VLclose. + +\subsubsection subsubsecVOLNewPubget_by_value H5VLget_connector_id_by_value +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + hid_t H5VLget_connector_id_by_value(H5VL_class_value_t connector_value); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + connector_value (IN): The connector value to check for. +\endcode +</td> +</tr> +</table> +Given a connector value that is registered with the library, this function returns an identifier for the connector. +If the connector is not registered with the library, #H5I_INVALID_HID is returned.The identifier must be +released with a call to #H5VLclose. + +\subsubsection subsubsecVOLNewPubget_name H5VLget_connector_name +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + ssize_t H5VLget_connector_name(hid_t id, char *name /*out*/, size_t size); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + id (IN): The object identifier to check. + name (OUT): Buffer pointer to put the connector name. If NULL, the library just returns thesize required to store the connector name. + size (IN): the size of the passed in buffer. +\endcode +</td> +</tr> +</table> +Retrieves the name of a VOL connector given an object identifier that was created/opened ith it. On +success, the name length is returned. + +\subsubsection subsubsecVOLNewPubclose H5VLclose +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t H5VLclose(hid_t connector_id); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + connector_id (IN): A valid identifier of the connector to close. +\endcode +</td> +</tr> +</table> +Shuts down access to the connector that the identifier points to and release resources associated with it. + +\subsubsection subsubsecVOLNewPubunreg H5VLunregister_connector +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t H5VLunregister_connector(hid_t connector_id); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + connector_id (IN): A valid identifier of the connector to unregister. +\endcode +</td> +</tr> +</table> +Unregisters a connector from the library and return a positive value on success otherwise return a negative +value. The native VOL connector cannot be unregistered (this will return a negative #herr_t value). + +\subsubsection subsubsecVOLNewPubquery H5VLquery_optional +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t H5VLquery_optional(hid_t obj_id, H5VL_subclass_t subcls, int opt_type, uint64_t *flags); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj_id (IN): A valid identifier of a VOL-managed object. + subcls (IN): The subclass of the optional operation. + opt_type (IN): The optional operation. The native VOL connector uses hard-coded values. Other + VOL connectors get this value when the optional operations are registered. + flags (OUT): Bitwise flags indicating support and behavior. +\endcode +</td> +</tr> +</table> +Determines if a connector or connector stack (determined from the passed-in object) supports an optional +operation. The returned flags (listed below) not only indicate whether the operation is supported or not, +but also give a sense of the option's behavior (useful for pass-through connectors). + +Bitwise query flag values: +\code + #define H5VL_OPT_QUERY_SUPPORTED 0x0001 /* VOL connector supports this operation */ + #define H5VL_OPT_QUERY_READ_DATA 0x0002 /* Operation reads data for object */ + #define H5VL_OPT_QUERY_WRITE_DATA 0x0004 /* Operation writes data for object */ + #define H5VL_OPT_QUERY_QUERY_METADATA 0x0008 /* Operation reads metadata for object */ + #define H5VL_OPT_QUERY_MODIFY_METADATA 0x0010 /* Operation modifies metadata for object */ + #define H5VL_OPT_QUERY_COLLECTIVE 0x0020 /* Operation is collective (operations without this flag are assumed to be independent) */ + #define H5VL_OPT_QUERY_NO_ASYNC 0x0040 /* Operation may NOT be executed asynchronously */ + #define H5VL_OPT_QUERY_MULTI_OBJ 0x0080 /* Operation involves multiple objects */ +\endcode + +\subsection subsecVOLNewConn H5VLconnector.h +This functionality is intended for VOL connector authors and includes helper functions that are useful for +writing connectors. + +API calls to manage optional operations are also found in this header file. These are discussed in the section +on optional operations, above. + +\subsubsection subsubsecVOLNewConnreg H5VLregister_connector +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + hid_t H5VLregister_connector(const H5VL_class_t *cls, hid_t vipl_id); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + cls (IN): A pointer to the connector structure to register. + vipl_id (IN): An ID for a VOL initialization property list (vipl). +\endcode +</td> +</tr> +</table> +Registers a user-defined VOL connector with the HDF5 library and returns an identifier for that connector +(#H5I_INVALID_HID on errors). This function is used when the application has direct access to the connector +it wants to use and is able to obtain a pointer for the connector structure to pass to the HDF5 library. + +\subsubsection subsubsecVOLNewConnobj H5VLobject +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + void *H5VLobject(hid_t obj_id); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj_id (IN): identifier of the object to dereference. +\endcode +</td> +</tr> +</table> +Retrieves a pointer to the VOL object from an HDF5 file or object identifier. + +\subsubsection subsubsecVOLNewConnget H5VLget_file_type +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + hid_t H5VLget_file_type(void *file_obj, hid_t connector_id, hid_t dtype_id); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + file_obj (IN): pointer to a file or file object's connector-specific data. + connector_id (IN): A valid identifier of the connector to use. + dtype_id (IN): A valid identifier for the type. +\endcode +</td> +</tr> +</table> +Returns a copy of the <em>dtype_id</em> parameter but with the location set to be in the file. Returns a negative +value (#H5I_INVALID_HID) on errors. + +\subsubsection subsubsecVOLNewConnpeek_name H5VLpeek_connector_id_by_name +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + hid_t H5VLpeek_connector_id_by_name(const char *name); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + name (IN): name of the connector to query. +\endcode +</td> +</tr> +</table> +Retrieves the ID for a registered VOL connector based on a connector name. This is done without duplicating +the ID and transferring ownership to the caller (as it normally the case in the HDF5 library). The ID returned +from this operation should not be closed. This is intended for use by VOL connectors to find their own ID. +Returns a negative value (#H5I_INVALID_HID) on errors. + +\subsubsection subsubsecVOLNewConnpeek_value H5VLpeek_connector_id_by_value +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + hid_t H5VLpeek_connector_id_by_value(H5VL_class_value_t value); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + value (IN): value of the connector to query. +\endcode +</td> +</tr> +</table> +Retrieves the ID for a registered VOL connector based on a connector value. This is done without duplicating +the ID and transferring ownership to the caller (as it normally the case in the HDF5 library). The ID returned +from this operation should not be closed. This is intended for use by VOL connectors to find their own ID. +Returns a negative value (#H5I_INVALID_HID) on errors. + +\subsection subsecVOLNewPass H5VLconnector_passthru.h +This functionality is intended for VOL connector authors who are writing pass-through connectors and +includes helper functions that are useful for writing such connectors. Callback equivalent functions can be +found in this header as well. A list of these functions is included as an appendix to this document. + +\subsubsection subsubsecVOLNewPasscmp H5VLcmp_connector_cls +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t H5VLcmp_connector_cls(int *cmp, hid_t connector_id1, hid_t connector_id2); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + cmp (OUT): a value like strcmp. + connector_id1 (IN): the ID of the first connector to compare. + connector_id2 (IN): the ID of the second connector to compare +\endcode +</td> +</tr> +</table> +Compares two connectors (given by the connector IDs) to see if they refer to the same connector underneath. +Returns a positive value on success and a negative value on errors. + +\subsubsection subsubsecVOLNewPasswrap H5VLwrap_register +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + hid_t H5VLwrap_register(void *obj, H5I_type_t type); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + obj (IN): an object to wrap. + type (IN): the type of the object (see below). +\endcode +</td> +</tr> +</table> +Wrap an internal object with a "wrap context" and register and return an hidt for the resulting object. +This routine is mainly targeted toward wrapping objects for iteration routine callbacks +(i.e. the callbacks from H5Aiterate*, H5Literate* / H5Lvisit*, and H5Ovisit* ). Using it in an application +will return an error indicating the API context isn't available or can't be retrieved. +he type must be a VOL-managed object class: +\li #H5I_FILE +\li #H5I_GROUP +\li #H5I_DATATYPE +\li #H5I_DATASET +\li #H5I_MAP +\li #H5I_ATTR + +\subsubsection subsubsecVOLNewPassretrieve H5VLretrieve_lib_state +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t H5VLretrieve_lib_state(void **state); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + state (OUT): the library state. +\endcode +</td> +</tr> +</table> +Retrieves a copy of the internal state of the HDF5 library, so that it can be restored later. Returns a positive +value on success and a negative value on errors. + +\subsubsection subsubsecVOLNewPassstar H5VLstart_lib_state +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t H5VLstart_lib_state(void); +\endcode +</td> +</tr> +</table> +Opens a new internal state for the HDF5 library. Returns a positive value on success and a negative value +on errors. + +\subsubsection subsubsecVOLNewPassrestore H5VLrestore_lib_state +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t H5VLrestore_lib_state(const void *state); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + state (IN): the library state. +\endcode +</td> +</tr> +</table> +Restores the internal state of the HDF5 library. Returns a positive value on success and a negative value on errors. + +\subsubsection subsubsecVOLNewPassfinish H5VLfinish_lib_state +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t H5VLfinish_lib_state(void); +\endcode +</td> +</tr> +</table> +Closes the state of the library, undoing the effects of #H5VLstart_lib_state. Returns a positive value on +success and a negative value on errors. + +\subsubsection subsubsecVOLNewPassfree H5VLfree_lib_state +<table> +<tr> +<th>Signature:</th> +</tr> +<tr> +<td> +\code + herr_t H5VLfree_lib_state(void *state); +\endcode +</td> +</tr> +<tr> +<th>Arguments:</th> +</tr> +<tr> +<td> +\code + state (IN): the library state. +\endcode +</td> +</tr> +</table> +Free a retrieved library state. Returns a positive value on success and a negative value on errors. + +\section secVOLAppA Appendix A Mapping of VOL Callbacks to HDF5 API Calls +<table> +<tr> +<td>VOL Callback</td> +<td>HDF5 API Call</td> +</tr> +<tr> +<th colspan="2">FILE</th> +</tr> +<tr> +<td>create</td> +<td>\li #H5Fcreate</td> +</tr> +<tr> +<td>open</td> +<td> +\li #H5Fopen +</td> +</tr> +<tr> +<td>get</td> +<td> +\li #H5Fget_access_plist +\li #H5Fget_create_plist +\li #H5Fget_fileno +\li #H5Fget_intent +\li #H5Fget_name +\li #H5Fget_obj_count +\li #H5Fget_obj_ids +</td> +</tr> +<tr> +<td>specific</td> +<td> +\li #H5Fdelete +\li #H5Fflush +\li #H5Fis_accessible +\li #H5Fis_hdf5 (deprecated, hard-coded to use native connector) +\li #H5Freopen +</td> +</tr> +<tr> +<td>close</td> +<td> +\li #H5Fclose +</td> +</tr> +<tr> +<th colspan="2">GROUP</th> +</tr> +<tr> +<td>create</td> +<td> +\li #H5Gcreate1 (deprecated) +\li #H5Gcreate2 +\li #H5Gcreate_anon +</td> +</tr> +<tr> +<td>open</td> +<td> +\li #H5Gopen1 (deprecated) +\li #H5Gopen2 +</td> +</tr> +<tr> +<td>get</td> +<td> +\li #H5Gget_create_plist +\li #H5Gget_info +\li #H5Gget_info_by_idx +\li #H5Gget_info_by_name +\li #H5Gget_num_objs (deprecated) +</td> +</tr> +<tr> +<td>specific</td> +<td> +\li #H5Fmount +\li #H5Funmount +\li #H5Gflush +\li #H5Grefresh +</td> +</tr> +<tr> +<td>close</td> +<td> +\li #H5Gclose +</td> +</tr> +<tr> +<th colspan="2">DATASET</th> +</tr> +<tr> +<td>create</td> +<td> +\li #H5Dcreate1 (deprecated) +\li #H5Dcreate2 +</td> +</tr> +<tr> +<td>open</td> +<td> +\li #H5Dopen1 (deprecated) +\li #H5Dopen2 +</td> +</tr> +<tr> +<td>read</td> +<td> +\li #H5Dread +</td> +</tr> +<tr> +<td>write</td> +<td> +\li #H5Dwrite +</td> +</tr> +<tr> +<td>get</td> +<td> +\li #H5Dget_access_plist +\li #H5Dget_create_plist +\li #H5Dget_space +\li #H5Dget_space_status +\li #H5Dget_storage_size +\li #H5Dget_type +</td> +</tr> +<tr> +<td>specific</td> +<td> +\li #H5Dextend (deprecated) +\li #H5Dflush +\li #H5Drefresh +\li #H5Dset_extent +</td> +</tr> +<tr> +<td>close</td> +<td> +\li #H5Dclose +</td> +</tr> +<tr> +<th colspan="2">OBJECT</th> +</tr> +<tr> +<td>open</td> +<td> +\li #H5Oopen +\li #H5Oopen_by_addr (deprecated) +\li #H5Oopen_by_idx +\li #H5Oopen_by_token +</td> +</tr> +<tr> +<td>copy</td> +<td> +\li #H5Ocopy +</td> +</tr> +<tr> +<td>get</td> +<td> +\li #H5Oget_info1 (deprecated) +\li #H5Oget_info2 (deprecated) +\li #H5Oget_info3 +</td> +</tr> +<tr> +<td>specific</td> +<td> +\li #H5Odecr_refcount +\li #H5Oexists_by_name +\li #H5Oflush +\li #H5Oincr_refcount +\li #H5Orefresh +\li #H5Ovisit_by_name1 (deprecated) +\li #H5Ovisit_by_name2 (deprecated) +\li #H5Ovisit_by_name3 +\li #H5Ovisit1 (deprecated) +\li #H5Ovisit2 (deprecated) +\li #H5Ovisit3 +</td> +</tr> +<tr> +<td>close</td> +<td> +\li #H5Oclose +</td> +</tr> +<tr> +<th colspan="2">LINK</th> +</tr> +<tr> +<td>create</td> +<td> +\li #H5Glink (deprecated) +\li #H5Glink2 (deprecated) +\li #H5Lcreate_hard +\li #H5Lcreate_soft +\li #H5Lcreate_ud +\li #H5Olink +</td> +</tr> +<tr> +<td>copy</td> +<td> +\li #H5Lcopy +</td> +</tr> +<tr> +<td>move</td> +<td> +\li #H5Gmove (deprecated) +\li #H5Gmove2 (deprecated) +\li #H5Lmove +</td> +</tr> +<tr> +<td>get</td> +<td> +\li #H5Gget_linkval (deprecated) +\li #H5Lget_info1 (deprecated) +\li #H5Lget_info2 +\li #H5Lget_info_by_idx +\li #H5Lget_name_by_idx +\li #H5Lget_val +\li #H5Lget_val_by_idx +</td> +</tr> +<tr> +<td>specific</td> +<td> +\li #H5Gunlink (deprecated) +\li #H5Ldelete +\li #H5Ldelete_by_idx +\li #H5Lexists +\li #H5Literate1 (deprecated) +\li #H5Literate2 +\li #H5Literate_by_name1 (deprecated) +\li #H5Literate_by_name2 +\li #H5Lvisit1 (deprecated) +\li #H5Lvisit2 +\li #H5Lvisit_by_name1 (deprecated) +\li #H5Lvisit_by_name2 +</td> +</tr> +<tr> +<th colspan="2">DATATYPE</th> +</tr> +<tr> +<td>commit</td> +<td> +\li #H5Tcommit1 (deprecated) +\li #H5Tcommit2 +\li #H5Tcommit+anon +</td> +</tr> +<tr> +<td>open</td> +<td> +\li #H5Topen1 (deprecated) +\li #H5Topen2 +</td> +</tr> +<tr> +<td>get</td> +<td> +\li #H5Tget_create_plist +</td> +</tr> +<tr> +<td>specific</td> +<td> +\li #H5Tflush +\li #H5Trefresh +</td> +</tr> +<tr> +<td>close</td> +<td> +\li #H5Tclose +</td> +</tr> +<tr> +<th colspan="2">ATTRIBUTE</th> +</tr> +<tr> +<td>create</td> +<td> +\li #H5Acreate1 (deprecated) +\li #H5Acreate2 +\li #H5Acreate_by_name +</td> +</tr> +<tr> +<td>open</td> +<td> +\li #H5Aopen +\li #H5Aopen_by_idx +\li #H5Aopen_by_name +\li #H5Aopen_idx (deprecated) +\li #H5Aopen_name (deprecated) +</td> +</tr> +<tr> +<td>read</td> +<td> +\li #H5Aread +</td> +</tr> +<tr> +<td>write</td> +<td> +\li #H5Awrite +</td> +</tr> +<tr> +<td>get</td> +<td> +\li #H5Aget_create_plist +\li #H5Aget_info +\li #H5Aget_info_by_idx +\li #H5Aget_info_by_name +\li #H5Aget_name +\li #H5Aget_name_by_idx +\li #H5Aget_space +\li #H5Aget_storage_size +\li #H5Aget_type +</td> +</tr> +<tr> +<td>specific</td> +<td> +\li #H5Adelete +\li #H5Adelete_by_idx +\li #H5Adelete_by_name +\li #H5Aexists +\li #H5Aexists_by_name +\li #H5Aiterate1 (deprecated) +\li #H5Aiterate2 +\li #H5Aiterate_by_name +\li #H5Arename +\li #H5Arename_by_name +</td> +</tr> +<tr> +<td>close</td> +<td> +\li #H5Aclose +</td> +</tr> +</table> + +\section secVOLAppB Appendix B Callback Wrapper API Calls for Passthrough Connector Authors +\code +/* Pass-through callbacks */ +H5_DLL void *H5VLget_object(void *obj, hid_t connector_id); +H5_DLL herr_t H5VLget_wrap_ctx(void *obj, hid_t connector_id, void **wrap_ctx); +H5_DLL void *H5VLwrap_object(void *obj, H5I_type_t obj_type, hid_t connector_id, void *wrap_ctx); +H5_DLL void *H5VLunwrap_object(void *obj, hid_t connector_id); +H5_DLL herr_t H5VLfree_wrap_ctx(void *wrap_ctx, hid_t connector_id); + +/* Public wrappers for generic callbacks */ +H5_DLL herr_t H5VLinitialize(hid_t connector_id, hid_t vipl_id); +H5_DLL herr_t H5VLterminate(hid_t connector_id); +H5_DLL herr_t H5VLget_cap_flags(hid_t connector_id, uint64_t *cap_flags); +H5_DLL herr_t H5VLget_value(hid_t connector_id, H5VL_class_value_t *conn_value); + +/* Public wrappers for info fields and callbacks */ +H5_DLL herr_t H5VLcopy_connector_info(hid_t connector_id, void **dst_vol_info, void *src_vol_info); +H5_DLL herr_t H5VLcmp_connector_info(int *cmp, hid_t connector_id, const void *info1, const void *info2); +H5_DLL herr_t H5VLfree_connector_info(hid_t connector_id, void *vol_info); +H5_DLL herr_t H5VLconnector_info_to_str(const void *info, hid_t connector_id, char **str); +H5_DLL herr_t H5VLconnector_str_to_info(const char *str, hid_t connector_id, void **info); + +/* Public wrappers for attribute callbacks */ +H5_DLL void *H5VLattr_create(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, + const char *attr_name, hid_t type_id, hid_t space_id, hid_t acpl_id, + hid_t aapl_id, hid_t dxpl_id, void **req); +H5_DLL void *H5VLattr_open(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, + const char *name, hid_t aapl_id, hid_t dxpl_id, void **req); +H5_DLL herr_t H5VLattr_read(void *attr, hid_t connector_id, hid_t dtype_id, void *buf, hid_t dxpl_id, + void **req); +H5_DLL herr_t H5VLattr_write(void *attr, hid_t connector_id, hid_t dtype_id, const void *buf, hid_t dxpl_id, + void **req); +H5_DLL herr_t H5VLattr_get(void *obj, hid_t connector_id, H5VL_attr_get_args_t *args, hid_t dxpl_id, + void **req); +H5_DLL herr_t H5VLattr_specific(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, + H5VL_attr_specific_args_t *args, hid_t dxpl_id, void **req); +H5_DLL herr_t H5VLattr_optional(void *obj, hid_t connector_id, H5VL_optional_args_t *args, hid_t dxpl_id, + void **req); +H5_DLL herr_t H5VLattr_close(void *attr, hid_t connector_id, hid_t dxpl_id, void **req); + +/* Public wrappers for dataset callbacks */ +H5_DLL void *H5VLdataset_create(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, + const char *name, hid_t lcpl_id, hid_t type_id, hid_t space_id, hid_t dcpl_id, + hid_t dapl_id, hid_t dxpl_id, void **req); +H5_DLL void *H5VLdataset_open(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, + const char *name, hid_t dapl_id, hid_t dxpl_id, void **req); +H5_DLL herr_t H5VLdataset_read(size_t count, void *dset[], hid_t connector_id, hid_t mem_type_id[], + hid_t mem_space_id[], hid_t file_space_id[], hid_t plist_id, void *buf[], + void **req); +H5_DLL herr_t H5VLdataset_write(size_t count, void *dset[], hid_t connector_id, hid_t mem_type_id[], + hid_t mem_space_id[], hid_t file_space_id[], hid_t plist_id, + const void *buf[], void **req); +H5_DLL herr_t H5VLdataset_get(void *dset, hid_t connector_id, H5VL_dataset_get_args_t *args, hid_t dxpl_id, + void **req); +H5_DLL herr_t H5VLdataset_specific(void *obj, hid_t connector_id, H5VL_dataset_specific_args_t *args, + hid_t dxpl_id, void **req); +H5_DLL herr_t H5VLdataset_optional(void *obj, hid_t connector_id, H5VL_optional_args_t *args, hid_t dxpl_id, + void **req); +H5_DLL herr_t H5VLdataset_close(void *dset, hid_t connector_id, hid_t dxpl_id, void **req); + +/* Public wrappers for named datatype callbacks */ +H5_DLL void *H5VLdatatype_commit(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, + const char *name, hid_t type_id, hid_t lcpl_id, hid_t tcpl_id, hid_t tapl_id, + hid_t dxpl_id, void **req); +H5_DLL void *H5VLdatatype_open(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, + const char *name, hid_t tapl_id, hid_t dxpl_id, void **req); +H5_DLL herr_t H5VLdatatype_get(void *dt, hid_t connector_id, H5VL_datatype_get_args_t *args, hid_t dxpl_id, + void **req); +H5_DLL herr_t H5VLdatatype_specific(void *obj, hid_t connector_id, H5VL_datatype_specific_args_t *args, + hid_t dxpl_id, void **req); +H5_DLL herr_t H5VLdatatype_optional(void *obj, hid_t connector_id, H5VL_optional_args_t *args, hid_t dxpl_id, + void **req); +H5_DLL herr_t H5VLdatatype_close(void *dt, hid_t connector_id, hid_t dxpl_id, void **req); + +/* Public wrappers for file callbacks */ +H5_DLL void *H5VLfile_create(const char *name, unsigned flags, hid_t fcpl_id, hid_t fapl_id, hid_t dxpl_id, + void **req); +H5_DLL void *H5VLfile_open(const char *name, unsigned flags, hid_t fapl_id, hid_t dxpl_id, void **req); +H5_DLL herr_t H5VLfile_get(void *file, hid_t connector_id, H5VL_file_get_args_t *args, hid_t dxpl_id, + void **req); +H5_DLL herr_t H5VLfile_specific(void *obj, hid_t connector_id, H5VL_file_specific_args_t *args, hid_t dxpl_id, + void **req); +H5_DLL herr_t H5VLfile_optional(void *obj, hid_t connector_id, H5VL_optional_args_t *args, hid_t dxpl_id, + void **req); +H5_DLL herr_t H5VLfile_close(void *file, hid_t connector_id, hid_t dxpl_id, void **req); + +/* Public wrappers for group callbacks */ +H5_DLL void *H5VLgroup_create(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, + const char *name, hid_t lcpl_id, hid_t gcpl_id, hid_t gapl_id, hid_t dxpl_id, + void **req); +H5_DLL void *H5VLgroup_open(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, + const char *name, hid_t gapl_id, hid_t dxpl_id, void **req); +H5_DLL herr_t H5VLgroup_get(void *obj, hid_t connector_id, H5VL_group_get_args_t *args, hid_t dxpl_id, + void **req); +H5_DLL herr_t H5VLgroup_specific(void *obj, hid_t connector_id, H5VL_group_specific_args_t *args, + hid_t dxpl_id, void **req); +H5_DLL herr_t H5VLgroup_optional(void *obj, hid_t connector_id, H5VL_optional_args_t *args, hid_t dxpl_id, + void **req); +H5_DLL herr_t H5VLgroup_close(void *grp, hid_t connector_id, hid_t dxpl_id, void **req); + +/* Public wrappers for link callbacks */ +H5_DLL herr_t H5VLlink_create(H5VL_link_create_args_t *args, void *obj, const H5VL_loc_params_t *loc_params, + hid_t connector_id, hid_t lcpl_id, hid_t lapl_id, hid_t dxpl_id, void **req); +H5_DLL herr_t H5VLlink_copy(void *src_obj, const H5VL_loc_params_t *loc_params1, void *dst_obj, + const H5VL_loc_params_t *loc_params2, hid_t connector_id, hid_t lcpl_id, + hid_t lapl_id, hid_t dxpl_id, void **req); +H5_DLL herr_t H5VLlink_move(void *src_obj, const H5VL_loc_params_t *loc_params1, void *dst_obj, + const H5VL_loc_params_t *loc_params2, hid_t connector_id, hid_t lcpl_id, + hid_t lapl_id, hid_t dxpl_id, void **req); +H5_DLL herr_t H5VLlink_get(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, + H5VL_link_get_args_t *args, hid_t dxpl_id, void **req); +H5_DLL herr_t H5VLlink_specific(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, + H5VL_link_specific_args_t *args, hid_t dxpl_id, void **req); +H5_DLL herr_t H5VLlink_optional(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, + H5VL_optional_args_t *args, hid_t dxpl_id, void **req); + +/* Public wrappers for object callbacks */ +H5_DLL void *H5VLobject_open(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, + H5I_type_t *opened_type, hid_t dxpl_id, void **req); +H5_DLL herr_t H5VLobject_copy(void *src_obj, const H5VL_loc_params_t *loc_params1, const char *src_name, + void *dst_obj, const H5VL_loc_params_t *loc_params2, const char *dst_name, + hid_t connector_id, hid_t ocpypl_id, hid_t lcpl_id, hid_t dxpl_id, void **req); +H5_DLL herr_t H5VLobject_get(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, + H5VL_object_get_args_t *args, hid_t dxpl_id, void **req); +H5_DLL herr_t H5VLobject_specific(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, + H5VL_object_specific_args_t *args, hid_t dxpl_id, void **req); +H5_DLL herr_t H5VLobject_optional(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, + H5VL_optional_args_t *args, hid_t dxpl_id, void **req); + +/* Public wrappers for connector/container introspection callbacks */ +H5_DLL herr_t H5VLintrospect_get_conn_cls(void *obj, hid_t connector_id, H5VL_get_conn_lvl_t lvl, + const H5VL_class_t **conn_cls); +H5_DLL herr_t H5VLintrospect_get_cap_flags(const void *info, hid_t connector_id, uint64_t *cap_flags); +H5_DLL herr_t H5VLintrospect_opt_query(void *obj, hid_t connector_id, H5VL_subclass_t subcls, int opt_type, + uint64_t *flags); + +/* Public wrappers for asynchronous request callbacks */ +H5_DLL herr_t H5VLrequest_wait(void *req, hid_t connector_id, uint64_t timeout, + H5VL_request_status_t *status); +H5_DLL herr_t H5VLrequest_notify(void *req, hid_t connector_id, H5VL_request_notify_t cb, void *ctx); +H5_DLL herr_t H5VLrequest_cancel(void *req, hid_t connector_id, H5VL_request_status_t *status); +H5_DLL herr_t H5VLrequest_specific(void *req, hid_t connector_id, H5VL_request_specific_args_t *args); +H5_DLL herr_t H5VLrequest_optional(void *req, hid_t connector_id, H5VL_optional_args_t *args); +H5_DLL herr_t H5VLrequest_free(void *req, hid_t connector_id); + +/* Public wrappers for blob callbacks */ +H5_DLL herr_t H5VLblob_put(void *obj, hid_t connector_id, const void *buf, size_t size, void *blob_id, + void *ctx); +H5_DLL herr_t H5VLblob_get(void *obj, hid_t connector_id, const void *blob_id, void *buf, size_t size, + void *ctx); +H5_DLL herr_t H5VLblob_specific(void *obj, hid_t connector_id, void *blob_id, + H5VL_blob_specific_args_t *args); +H5_DLL herr_t H5VLblob_optional(void *obj, hid_t connector_id, void *blob_id, H5VL_optional_args_t *args); + +/* Public wrappers for token callbacks */ +H5_DLL herr_t H5VLtoken_cmp(void *obj, hid_t connector_id, const H5O_token_t *token1, + const H5O_token_t *token2, int *cmp_value); +H5_DLL herr_t H5VLtoken_to_str(void *obj, H5I_type_t obj_type, hid_t connector_id, const H5O_token_t *token, + char **token_str); +H5_DLL herr_t H5VLtoken_from_str(void *obj, H5I_type_t obj_type, hid_t connector_id, const char *token_str, + H5O_token_t *token); + +/* Public wrappers for generic 'optional' callback */ +H5_DLL herr_t H5VLoptional(void *obj, hid_t connector_id, H5VL_optional_args_t *args, hid_t dxpl_id, + void **req); +\endcode + +\section secVOLAppC Appendix C Native VOL Connector Optional Values By Subclass +\code +/* H5VL_SUBCLS_ATTR */ +#define H5VL_NATIVE_ATTR_ITERATE_OLD 0 /* H5Aiterate (deprecated routine) */ + +/* H5VL_SUBCLS_DATASET */ +#define H5VL_NATIVE_DATASET_FORMAT_CONVERT 0 /* H5Dformat_convert (internal) */ +#define H5VL_NATIVE_DATASET_GET_CHUNK_INDEX_TYPE 1 /* H5Dget_chunk_index_type */ +#define H5VL_NATIVE_DATASET_GET_CHUNK_STORAGE_SIZE 2 /* H5Dget_chunk_storage_size */ +#define H5VL_NATIVE_DATASET_GET_NUM_CHUNKS 3 /* H5Dget_num_chunks */ +#define H5VL_NATIVE_DATASET_GET_CHUNK_INFO_BY_IDX 4 /* H5Dget_chunk_info */ +#define H5VL_NATIVE_DATASET_GET_CHUNK_INFO_BY_COORD 5 /* H5Dget_chunk_info_by_coord */ +#define H5VL_NATIVE_DATASET_CHUNK_READ 6 /* H5Dchunk_read */ +#define H5VL_NATIVE_DATASET_CHUNK_WRITE 7 /* H5Dchunk_write */ +#define H5VL_NATIVE_DATASET_GET_VLEN_BUF_SIZE 8 /* H5Dvlen_get_buf_size */ +#define H5VL_NATIVE_DATASET_GET_OFFSET 9 /* H5Dget_offset */ +#define H5VL_NATIVE_DATASET_CHUNK_ITER 10 /* H5Dchunk_iter */ + +/* H5VL_SUBCLS_FILE */ +#define H5VL_NATIVE_FILE_CLEAR_ELINK_CACHE 0 /* H5Fclear_elink_file_cache */ +#define H5VL_NATIVE_FILE_GET_FILE_IMAGE 1 /* H5Fget_file_image */ +#define H5VL_NATIVE_FILE_GET_FREE_SECTIONS 2 /* H5Fget_free_sections */ +#define H5VL_NATIVE_FILE_GET_FREE_SPACE 3 /* H5Fget_freespace */ +#define H5VL_NATIVE_FILE_GET_INFO 4 /* H5Fget_info1/2 */ +#define H5VL_NATIVE_FILE_GET_MDC_CONF 5 /* H5Fget_mdc_config */ +#define H5VL_NATIVE_FILE_GET_MDC_HR 6 /* H5Fget_mdc_hit_rate */ +#define H5VL_NATIVE_FILE_GET_MDC_SIZE 7 /* H5Fget_mdc_size */ +#define H5VL_NATIVE_FILE_GET_SIZE 8 /* H5Fget_filesize */ +#define H5VL_NATIVE_FILE_GET_VFD_HANDLE 9 /* H5Fget_vfd_handle */ +#define H5VL_NATIVE_FILE_RESET_MDC_HIT_RATE 10 /* H5Freset_mdc_hit_rate_stats */ +#define H5VL_NATIVE_FILE_SET_MDC_CONFIG 11 /* H5Fset_mdc_config */ +#define H5VL_NATIVE_FILE_GET_METADATA_READ_RETRY_INFO 12 /* H5Fget_metadata_read_retry_info */ +#define H5VL_NATIVE_FILE_START_SWMR_WRITE 13 /* H5Fstart_swmr_write */ +#define H5VL_NATIVE_FILE_START_MDC_LOGGING 14 /* H5Fstart_mdc_logging */ +#define H5VL_NATIVE_FILE_STOP_MDC_LOGGING 15 /* H5Fstop_mdc_logging */ +#define H5VL_NATIVE_FILE_GET_MDC_LOGGING_STATUS 16 /* H5Fget_mdc_logging_status */ +#define H5VL_NATIVE_FILE_FORMAT_CONVERT 17 /* H5Fformat_convert */ +#define H5VL_NATIVE_FILE_RESET_PAGE_BUFFERING_STATS 18 /* H5Freset_page_buffering_stats */ +#define H5VL_NATIVE_FILE_GET_PAGE_BUFFERING_STATS 19 /* H5Fget_page_buffering_stats */ +#define H5VL_NATIVE_FILE_GET_MDC_IMAGE_INFO 20 /* H5Fget_mdc_image_info */ +#define H5VL_NATIVE_FILE_GET_EOA 21 /* H5Fget_eoa */ +#define H5VL_NATIVE_FILE_INCR_FILESIZE 22 /* H5Fincrement_filesize */ +#define H5VL_NATIVE_FILE_SET_LIBVER_BOUNDS 23 /* H5Fset_latest_format/libver_bounds */ +#define H5VL_NATIVE_FILE_GET_MIN_DSET_OHDR_FLAG 24 /* H5Fget_dset_no_attrs_hint */ +#define H5VL_NATIVE_FILE_SET_MIN_DSET_OHDR_FLAG 25 /* H5Fset_dset_no_attrs_hint */ +#ifdef H5_HAVE_PARALLEL +#define H5VL_NATIVE_FILE_GET_MPI_ATOMICITY 26 /* H5Fget_mpi_atomicity */ +#define H5VL_NATIVE_FILE_SET_MPI_ATOMICITY 27 /* H5Fset_mpi_atomicity */ +#endif +#define H5VL_NATIVE_FILE_POST_OPEN 28 /* Adjust file after open, with wrapping context */ + +/* H5VL_SUBCLS_GROUP */ +#define H5VL_NATIVE_GROUP_ITERATE_OLD 0 /* HG5Giterate (deprecated routine) */ +#define H5VL_NATIVE_GROUP_GET_OBJINFO 1 /* HG5Gget_objinfo (deprecated routine) */ + +/* H5VL_SUBCLS_OBJECT */ +#define H5VL_NATIVE_OBJECT_GET_COMMENT 0 /* H5G|H5Oget_comment, H5Oget_comment_by_name */ +#define H5VL_NATIVE_OBJECT_SET_COMMENT 1 /* H5G|H5Oset_comment, H5Oset_comment_by_name */ +#define H5VL_NATIVE_OBJECT_DISABLE_MDC_FLUSHES 2 /* H5Odisable_mdc_flushes */ +#define H5VL_NATIVE_OBJECT_ENABLE_MDC_FLUSHES 3 /* H5Oenable_mdc_flushes */ +#define H5VL_NATIVE_OBJECT_ARE_MDC_FLUSHES_DISABLED 4 /* H5Oare_mdc_flushes_disabled */ +#define H5VL_NATIVE_OBJECT_GET_NATIVE_INFO 5 /* H5Oget_native_info(_by_idx, _by_name) */ +\endcode + +<hr> +Navigate back: \ref index "Main" / \ref VOL_Connector +*/ diff --git a/doxygen/examples/tables/propertyLists.dox b/doxygen/examples/tables/propertyLists.dox index 498a820..375fd50 100644 --- a/doxygen/examples/tables/propertyLists.dox +++ b/doxygen/examples/tables/propertyLists.dox @@ -86,7 +86,7 @@ <td>Iterates over properties in a property class or list</td> </tr> <tr> -<td>#H5Pregister/H5Punregister</td> +<td>#H5Pregister/#H5Punregister</td> <td>Registers/removes a permanent property with/from a property list class</td> </tr> <tr> @@ -124,14 +124,6 @@ <td>Sets/retrieves size of parameter used to control B-trees for indexing chunked datasets.</td> </tr> <tr> -<td>#H5Pset_file_image</td> -<td>Sets an initial file image in a memory buffer.</td> -</tr> -<tr> -<td>#H5Pget_file_image</td> -<td>Retrieves a copy of the file image designated as the initial content and structure of a file.</td> -</tr> -<tr> <td>#H5Pset_file_space_page_size/#H5Pget_file_space_page_size</td> <td>Sets or retrieves the file space page size used in paged aggregation and paged buffering.</td> </tr> @@ -179,11 +171,19 @@ creation property list.</td> <td>Sets/retrieves metadata cache and raw data chunk cache parameters.</td> </tr> <tr> +<td>#H5Pset_core_write_tracking/#H5Pget_core_write_tracking</td> +<td>Sets/retrieves write tracking information for core driver.</td> +</tr> +<tr> <td>#H5Pset_elink_file_cache_size/#H5Pget_elink_file_cache_size</td> <td>Sets/retrieves the size of the external link open file cache from the specified file access property list.</td> </tr> <tr> +<td>#H5Pset_evict_on_close/#H5Pget_evict_on_close</td> +<td>Set/get the file access property list setting that determines whether an HDF5 object will be evicted from the library's metadata cache when it is closed.</td> +</tr> +<tr> <td>#H5Pset_gc_references/#H5Pget_gc_references</td> <td>Sets/retrieves garbage collecting references flag.</td> </tr> @@ -196,18 +196,56 @@ file access property list.</td> <td>Retrieves a data offset from the file access property list.</td> </tr> <tr> +<td>#H5Pset_fclose_degree/#H5Pget_fclose_degree</td> +<td>Sets/retrieves file close degree property.</td> +</tr> +<tr> +<td>#H5Pset_file_image</td> +<td>Sets an initial file image in a memory buffer.</td> +</tr> +<tr> +<td>#H5Pget_file_image</td> +<td>Retrieves a copy of the file image designated as the initial content and structure of a file.</td> +</tr> +<tr> +<td>#H5Pset_file_image_callbacks/#H5Pget_file_image_callbacks</td> +<td>Sets/gets the callbacks for working with file images.</td> +</tr> +<tr> +<td>#H5Pset_file_locking/#H5Pget_file_locking</td> +<td>Sets/retrieves file locking property values.</td> +</tr> +<tr> <td>#H5Pset_meta_block_size/#H5Pget_meta_block_size</td> <td>Sets the minimum metadata blocksize or retrieves the current metadata block size setting.</td> </tr> <tr> -<td>#H5Pset_mdc_config</td> -<td>Set the initial metadata cache configuration in the indicated File Access Property List -to the supplied value.</td> +<td>#H5Pset_metadata_read_attempts/#H5Pget_metadata_read_attempts</td> +<td>Sets/gets the number of read attempts from a file access property list.</td> +</tr> +<tr> +<td>#H5Pset_mdc_config/#H5Pget_mdc_config</td> +<td>Set/get the initial metadata cache configuration in the indicated file access property list.</td> +</tr> +<tr> +<td>#H5Pset_mdc_image_config/#H5Pget_mdc_image_config</td> +<td>Set/get the metadata cache image option for a file access property list.</td> +</tr> +<tr> +<td>#H5Pset_mdc_log_options/#H5Pget_mdc_log_options</td> +<td>Set/get the metadata cache logging options.</td> +</tr> +<tr> +<td>#H5Pset_multi_type/#H5Pget_multi_type</td> +<td>Sets/gets the type of data property for the MULTI driver.</td> +</tr> +<tr> +<td>#H5Pset_object_flush_cb/#H5Pget_object_flush_cb</td> +<td>Set/get the object flush property values from the file access property list.</td> </tr> <tr> -<td>#H5Pget_mdc_config</td> -<td>Get the current initial metadata cache config-uration from the indicated File Access -Property List.</td> +<td>#H5Pset_page_buffer_size/#H5Pget_page_buffer_size</td> +<td>Set/get the the maximum size for the page buffer.</td> </tr> <tr> <td>#H5Pset_sieve_buf_size/#H5Pget_sieve_buf_size</td> @@ -231,6 +269,30 @@ versions used when creating objects.</td> <td>#H5Pget_small_data_block_size</td> <td>Retrieves the current small data block size setting.</td> </tr> +<tr> +<td>#H5Pset_vol</td> +<td>Sets the file VOL connector for a file access property list.</td> +</tr> +<tr> +<td>#H5Pget_vol_cap_flags</td> +<td>Retrieves the capability flags for the VOL connector that will be used with a file access property list.</td> +</tr> +<tr> +<td>#H5Pget_vol_id</td> +<td>Retrieves the identifier of the current VOL connector.</td> +</tr> +<tr> +<td>#H5Pget_vol_info</td> +<td>Retrieves a copy of the VOL information for a connector.</td> +</tr> +<tr> +<td>#H5Pset_mpi_params/#H5Pget_mpi_params</td> +<td>Sets/retrieves the MPI communicator and info.</td> +</tr> +<tr> +<td>#H5Pset_coll_metadata_write/#H5Pget_coll_metadata_write</td> +<td>Sets/retrieves metadata write mode setting.</td> +</tr> </table> //! [fapl_table] * @@ -254,6 +316,18 @@ versions used when creating objects.</td> <td>Returns a pointer to file driver information.</td> </tr> <tr> +<td>#H5Pset_driver_by_name</td> +<td>Sets a file driver according to a given driver name.</td> +</tr> +<tr> +<td>#H5Pset_driver_by_value</td> +<td>Sets a file driver according to a given driver value.</td> +</tr> +<tr> +<td>#H5Pget_driver_config_str</td> +<td>Retrieves a string representation of the configuration for the driver.</td> +</tr> +<tr> <td>#H5Pset_fapl_core/#H5Pget_fapl_core</td> <td>Sets the driver for buffered memory files (in RAM) or retrieves information regarding the driver.</td> @@ -268,10 +342,22 @@ the driver.</td> larger than 2 gigabytes, or retrieves information regarding driver.</td> </tr> <tr> +<td>#H5Pset_fapl_hdfs/#H5Pget_fapl_hdfs</td> +<td>.</td> +</tr> +<tr> +<td>#H5Pset_fapl_ioc/#H5Pget_fapl_ioc</td> +<td>Modifies/queries the file driver properties of the I/O concentrator driver.</td> +</tr> +<tr> <td>#H5Pset_fapl_log</td> <td>Sets logging driver.</td> </tr> <tr> +<td>#H5Pset_fapl_mirror/#H5Pget_fapl_mirror</td> +<td>Modifies/queries the file driver properties of the mirror driver.</td> +</tr> +<tr> <td>#H5Pset_fapl_mpio/#H5Pget_fapl_mpio</td> <td>Sets driver for files on parallel file systems (MPI I/O) or retrieves information regarding the driver.</td> @@ -286,6 +372,10 @@ regarding the driver.</td> or retrieves information regarding driver.</td> </tr> <tr> +<td>#H5Pset_fapl_onion/#H5Pget_fapl_onion</td> +<td>Modifies/queries the file driver properties of the onion driver.</td> +</tr> +<tr> <td>#H5Pset_fapl_sec2</td> <td>Sets driver for unbuffered permanent files or retrieves information regarding driver.</td> </tr> @@ -299,6 +389,10 @@ and one raw data file.</td> <td>Sets driver for buffered permanent files.</td> </tr> <tr> +<td>#H5Pset_fapl_subfiling/#H5Pget_fapl_subfiling</td> +<td>Modifies/queries the file driver properties of the subfiling driver.</td> +</tr> +<tr> <td>#H5Pset_fapl_windows</td> <td>Sets the Windows I/O driver.</td> </tr> @@ -337,6 +431,10 @@ and one raw data file.</td> <td>Retrieves the size of chunks for the raw data of a chunked layout dataset.</td> </tr> <tr> +<td>#H5Pset_chunk_opts/#H5Pget_chunk_opts</td> +<td>Sets/gets the edge chunk option setting from a dataset creation property list.</td> +</tr> +<tr> <td>#H5Pset_deflate</td> <td>Sets compression method and compression level.</td> </tr> @@ -439,6 +537,34 @@ encoding for object names.</td> <td>#H5Pget_char_encoding</td> <td>Retrieves the character encoding used to create a string.</td> </tr> +<tr> +<td>#H5Pset_virtual</td> +<td>Sets the mapping between virtual and source datasets.</td> +</tr> +<tr> +<td>#H5Pget_virtual_count</td> +<td>Gets the number of mappings for the virtual dataset.</td> +</tr> +<tr> +<td>#H5Pget_virtual_dsetname</td> +<td>Gets the name of a source dataset used in the mapping.</td> +</tr> +<tr> +<td>#H5Pget_virtual_filename</td> +<td>Gets the filename of a source dataset used in the mapping.</td> +</tr> +<tr> +<td>#H5Pget_virtual_srcspace</td> +<td>Gets a dataspace identifier for the selection within the source dataset used in the mapping.</td> +</tr> +<tr> +<td>#H5Pget_virtual_vspace</td> +<td>Gets a dataspace identifier for the selection within the virtual dataset used in the mapping.</td> +</tr> +<tr> +<td>#H5Pset_dset_no_attrs_hint/#H5Pget_dset_no_attrs_hint</td> +<td>Sets/gets the flag to create minimized dataset object headers.</td> +</tr> </table> //! [dcpl_table] * @@ -458,32 +584,77 @@ encoding for object names.</td> <td>Reads buffer settings.</td> </tr> <tr> +<td>#H5Pset_append_flush/#H5Pget_append_flush</td> +<td>Sets/gets the values of the append property that is set up in the dataset access property list.</td> +</tr> +<tr> <td>#H5Pset_chunk_cache/#H5Pget_chunk_cache</td> <td>Sets/gets the raw data chunk cache parameters.</td> </tr> <tr> -<td>#H5Pset_edc_check/#H5Pget_edc_check</td> -<td>Sets/gets whether to enable error-detection when reading a dataset.</td> +<td>#H5Pset_efile_prefix/#H5Pget_efile_prefix</td> +<td>Sets/gets the prefix for external raw data storage files as set in the dataset access property list.</td> </tr> <tr> -<td>#H5Pset_filter_callback</td> -<td>Sets user-defined filter callback function.</td> +<td>#H5Pset_virtual_prefix/#H5Pget_virtual_prefix</td> +<td>Sets/gets the prefix to be applied to VDS source file paths.</td> +</tr> +<tr> +<td>#H5Pset_virtual_printf_gap/#H5Pget_virtual_printf_gap</td> +<td>Sets/gets the maximum number of missing source files and/or datasets with the printf-style names when getting the extent for an unlimited virtual dataset.</td> +</tr> +<tr> +<td>#H5Pset_virtual_view/#H5Pget_virtual_view</td> +<td>Sets/gets the view of the virtual dataset (VDS) to include or exclude missing mapped elements.</td> +</tr> +</table> +//! [dapl_table] + * +//! [dxpl_table] +<table> +<caption id="table_dxpl_id" border="1" style="background-color:whitesmoke;">Data transfer property list functions (H5P)</caption> +<tr> +<th>C Function</th> +<th>Purpose</th> +</tr> +<tr> +<td>#H5Pset_btree_ratios/#H5Pget_btree_ratios</td> +<td>Sets/gets B-tree split ratios for a dataset transfer property list.</td> +</tr> +<tr> +<td>#H5Pset_buffer</td> +<td>Maximum size for the type conversion buffer and the background buffer. May also supply +pointers to application-allocated buffers.</td> </tr> <tr> <td>#H5Pset_data_transform/#H5Pget_data_transform</td> <td>Sets/gets a data transform expression.</td> </tr> <tr> -<td>#H5Pset_type_conv_cb/#H5Pget_type_conv_cb</td> -<td>Sets/gets user-defined datatype conversion callback function.</td> +<td>#H5Pset_dataset_io_hyperslab_selection</td> +<td>Sets a hyperslab file selection for a dataset I/O operation.</td> +</tr> +<tr> +<td>#H5Pset_edc_check/#H5Pget_edc_check</td> +<td>Sets/gets whether to enable error-detection when reading a dataset.</td> +</tr> +<tr> +<td>#H5Pset_hyper_vector_size</td> +<td>set the number of "I/O vectors" (offset and length pairs) which are to be +accumulated in memory before being issued to the lower levels +of the library for reading or writing the actual data.</td> +</tr> +<tr> +<td>#H5Pset_filter_callback</td> +<td>Sets user-defined filter callback function.</td> </tr> <tr> <td>#H5Pset_hyper_vector_size/#H5Pget_hyper_vector_size</td> <td>Sets/gets number of I/O vectors to be read/written in hyperslab I/O.</td> </tr> <tr> -<td>#H5Pset_btree_ratios/#H5Pget_btree_ratios</td> -<td>Sets/gets B-tree split ratios for a dataset transfer property list.</td> +<td>#H5Pset_type_conv_cb/#H5Pget_type_conv_cb</td> +<td>Sets/gets user-defined datatype conversion callback function.</td> </tr> <tr> <td>#H5Pset_vlen_mem_manager/#H5Pget_vlen_mem_manager</td> @@ -511,38 +682,20 @@ encoding for object names.</td> <td>Sets a flag governing the use of independent versus collective I/O.</td> </tr> <tr> -<td>#H5Pset_multi_type/#H5Pget_multi_type</td> -<td>Sets/gets the type of data property for the MULTI driver.</td> -</tr> -<tr> -<td>#H5Pset_small_data_block_size/#H5Pget_small_data_block_size</td> -<td>Sets/gets the size of a contiguous block reserved for small data.</td> -</tr> -</table> -//! [dapl_table] - * -//! [dxpl_table] -<table> -<caption id="table_dxpl_id" border="1" style="background-color:whitesmoke;">Data transfer property list functions (H5P)</caption> -<tr> -<th>C Function</th> -<th>Purpose</th> +<td>#H5Pget_mpio_actual_chunk_opt_mode</td> +<td>Gets the type of chunk optimization that HDF5 actually performed on the last parallel I/O call.</td> </tr> <tr> -<td>#H5Pset_buffer</td> -<td>Maximum size for the type conversion buffer and the background buffer. May also supply -pointers to application-allocated buffers.</td> +<td>#H5Pget_mpio_actual_io_mode</td> +<td>Gets the type of I/O that HDF5 actually performed on the last parallel I/O call.</td> </tr> <tr> -<td>#H5Pset_hyper_vector_size</td> -<td>set the number of "I/O vectors" (offset and length pairs) which are to be -accumulated in memory before being issued to the lower levels -of the library for reading or writing the actual data.</td> +<td>#H5Pget_mpio_no_collective_cause</td> +<td>Gets local and global causes that broke collective I/O on the last parallel I/O call.</td> </tr> <tr> -<td>#H5Pset_btree_ratios</td> -<td>Set the B-tree split ratios for a dataset transfer property list. The split ratios determine -what percent of children go in the first node when a node splits.</td> +<td>H5Pset_preserve/H5Pget_preserve</td> +<td>No longer available, deprecated as it no longer has any effect.</td> </tr> </table> //! [dxpl_table] @@ -593,6 +746,10 @@ C function is a macro: \see \ref api-compat-macros.</td> <td>Sets up use of the Fletcher32 checksum filter.</td> </tr> <tr> +<td>#H5Pset_local_heap_size_hint#H5Pget_local_heap_size_hint/</td> +<td>Sets/gets the anticipated maximum size of a local heap.</td> +</tr> +<tr> <td>#H5Pset_link_phase_change</td> <td>Sets the parameters for conversion between compact and dense groups.</td> </tr> @@ -625,14 +782,6 @@ C function is a macro: \see \ref api-compat-macros.</td> <td>Queries whether link creation order is tracked and/or indexed in a group.</td> </tr> <tr> -<td>#H5Pset_create_intermediate_group</td> -<td>Specifies in the property list whether to create missing intermediate groups.</td> -</tr> -<tr> -<td>#H5Pget_create_intermediate_group</td> -<td>Determines whether the property is set to enable creating missing intermediate groups.</td> -</tr> -<tr> <td>#H5Pset_char_encoding</td> <td>Sets the character encoding used to encode a string. Use to set ASCII or UTF-8 character encoding for object names.</td> @@ -771,10 +920,6 @@ encoding for object names.</td> <td>#H5Pset_char_encoding/#H5Pget_char_encoding</td> <td>Sets/gets the character encoding used to encode link and attribute names.</td> </tr> -<tr> -<td>#H5Pset_create_intermediate_group/#H5Pget_create_intermediate_group</td> -<td>Specifies/retrieves whether to create missing intermediate groups.</td> -</tr> </table> //! [strcpl_table] * diff --git a/doxygen/hdf5doxy_layout.xml b/doxygen/hdf5doxy_layout.xml index d156f2c..77900a3 100644 --- a/doxygen/hdf5doxy_layout.xml +++ b/doxygen/hdf5doxy_layout.xml @@ -11,6 +11,8 @@ <tab type="user" url="@ref SPEC" title="Specifications" /> <tab type="user" url="@ref Cookbook" title="Cookbook" /> <tab type="user" url="@ref TN" title="Technical Notes" /> + <tab type="user" url="@ref VOL_Connector" title="HDF5 VOL Connector Author Guide" /> + <tab type="user" url="https://portal.hdfgroup.org/display/HDF5/HDF5+VOL+User%27s+Guide" title="HDF5 VOL User's Guide" /> <tab type="user" url="@ref RFC" title="RFCs" /> <tab type="user" url="@ref FTS" title="Full-Text Search" /> <tab type="user" url="@ref About" title="About" /> diff --git a/java/src/hdf/hdf5lib/callbacks/package-info.java b/java/src/hdf/hdf5lib/callbacks/package-info.java index 1f15034..bf7bf3c 100644 --- a/java/src/hdf/hdf5lib/callbacks/package-info.java +++ b/java/src/hdf/hdf5lib/callbacks/package-info.java @@ -8,7 +8,6 @@ * 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. * - * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /** diff --git a/release_docs/RELEASE.txt b/release_docs/RELEASE.txt index dae4a39..6ec7f04 100644 --- a/release_docs/RELEASE.txt +++ b/release_docs/RELEASE.txt @@ -120,7 +120,11 @@ New Features Documentation: -------------- - - + - Ported the existing VOL Connector Author Guide document to doxygen. + + Added new dox file, VOLConnGuide.dox. + + (ADB - 2022/12/20) Support for new platforms, languages and compilers diff --git a/src/H5Apublic.h b/src/H5Apublic.h index 7ed2938..e21e808 100644 --- a/src/H5Apublic.h +++ b/src/H5Apublic.h @@ -392,6 +392,9 @@ H5_DLL herr_t H5Aexists_by_name_async(hid_t loc_id, const char *obj_name, const * creation property list associated with the attribute specified * by \p attr_id. * + * The creation property list identifier should be released with + * H5Pclose() to prevent resource leaks. + * * \since 1.8.0 * */ diff --git a/src/H5Dpublic.h b/src/H5Dpublic.h index fbce3d6..45b941a 100644 --- a/src/H5Dpublic.h +++ b/src/H5Dpublic.h @@ -501,6 +501,9 @@ H5_DLL hid_t H5Dget_type(hid_t dset_id); * a copy of the dataset creation property list associated with * the dataset specified by \p dset_id. * + * The creation property list identifier should be released with + * H5Pclose() to prevent resource leaks. + * */ H5_DLL hid_t H5Dget_create_plist(hid_t dset_id); diff --git a/src/H5FDhdfs.h b/src/H5FDhdfs.h index 9c2cb70..e3888d2 100644 --- a/src/H5FDhdfs.h +++ b/src/H5FDhdfs.h @@ -8,7 +8,6 @@ * 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. * - * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* diff --git a/src/H5Gpublic.h b/src/H5Gpublic.h index d6cebf3..ace2071 100644 --- a/src/H5Gpublic.h +++ b/src/H5Gpublic.h @@ -119,7 +119,7 @@ extern "C" { * * \since 1.8.0 * - * \see H5Gopen2(), H5Gclose() + * \see H5Gopen2() * */ H5_DLL hid_t H5Gcreate2(hid_t loc_id, const char *name, hid_t lcpl_id, hid_t gcpl_id, hid_t gapl_id); @@ -211,7 +211,7 @@ H5_DLL hid_t H5Gcreate_anon(hid_t loc_id, hid_t gcpl_id, hid_t gapl_id); * * \since 1.8.0 * - * \see H5Gcreate2(), H5Gclose() + * \see H5Gcreate2() * */ H5_DLL hid_t H5Gopen2(hid_t loc_id, const char *name, hid_t gapl_id); @@ -242,12 +242,10 @@ H5_DLL hid_t H5Gopen_async(hid_t loc_id, const char *name, hid_t gapl_id, hid_t * property list associated with the group specified by \p group_id. * * The creation property list identifier should be released with - * H5Gclose() to prevent resource leaks. + * H5Pclose() to prevent resource leaks. * * \since 1.8.0 * - * \see H5Gcreate2(), H5Gclose() - * */ H5_DLL hid_t H5Gget_create_plist(hid_t group_id); @@ -274,8 +272,6 @@ H5_DLL hid_t H5Gget_create_plist(hid_t group_id); * * \since 1.8.0 * - * \see H5Gcreate2(), H5Gclose() - * */ H5_DLL herr_t H5Gget_info(hid_t loc_id, H5G_info_t *ginfo); @@ -320,8 +316,6 @@ H5_DLL herr_t H5Gget_info_async(hid_t loc_id, H5G_info_t *ginfo /*out*/, hid_t e * * \since 1.8.0 * - * \see H5Gcreate2(), H5Gclose() - * */ H5_DLL herr_t H5Gget_info_by_name(hid_t loc_id, const char *name, H5G_info_t *ginfo, hid_t lapl_id); @@ -381,8 +375,6 @@ H5_DLL herr_t H5Gget_info_by_name_async(hid_t loc_id, const char *name, H5G_info * * \since 1.8.0 * - * \see H5Gcreate2(), H5Gclose() - * */ H5_DLL herr_t H5Gget_info_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5G_info_t *ginfo, hid_t lapl_id); @@ -426,8 +418,6 @@ H5_DLL herr_t H5Gget_info_by_idx_async(hid_t loc_id, const char *group_name, H5_ * * \since 1.8.0 * - * \see H5Gcreate2(), H5Gclose() - * */ H5_DLL herr_t H5Gflush(hid_t group_id); @@ -451,8 +441,6 @@ H5_DLL herr_t H5Gflush(hid_t group_id); * * \since 1.8.0 * - * \see H5Gcreate2(), H5Gclose() - * */ H5_DLL herr_t H5Grefresh(hid_t group_id); diff --git a/src/H5Lpublic.h b/src/H5Lpublic.h index d2d9e9d..6feefcd 100644 --- a/src/H5Lpublic.h +++ b/src/H5Lpublic.h @@ -884,10 +884,12 @@ H5_DLL ssize_t H5Lget_name_by_idx(hid_t loc_id, const char *group_name, H5_index * not been indexed by the index type, they will first be sorted by * that index then the iteration will begin; if the links have been * so indexed, the sorting step will be unnecessary, so the iteration - * may begin more quickly. + * may begin more quickly. Valid values include the following: + * \indexes * * \p order specifies the order in which objects are to be inspected - * along the index \p idx_type. + * along the index \p idx_type. Valid values include the following: + * \orders * * \p idx_p tracks the iteration and allows an iteration to be * resumed if it was stopped before all members were processed. It is @@ -1641,10 +1643,12 @@ H5_DLL herr_t H5Lget_info_by_idx1(hid_t loc_id, const char *group_name, H5_index * not been indexed by the index type, they will first be sorted by * that index then the iteration will begin; if the links have been * so indexed, the sorting step will be unnecessary, so the iteration - * may begin more quickly. + * may begin more quickly. Valid values include the following: + * \indexes * * \p order specifies the order in which objects are to be inspected - * along the index \p idx_type. + * along the index \p idx_type. Valid values include the following: + * \orders * * \p idx_p tracks the iteration and allows an iteration to be * resumed if it was stopped before all members were processed. It is diff --git a/src/H5Mpublic.h b/src/H5Mpublic.h index 2cea579..86fe433 100644 --- a/src/H5Mpublic.h +++ b/src/H5Mpublic.h @@ -352,6 +352,9 @@ H5_DLL hid_t H5Mget_val_type(hid_t map_id); * \details H5Mget_create_plist() returns an identifier for a copy of the * creation property list for a map object specified by \p map_id. * + * The creation property list identifier should be released with + * H5Pclose() to prevent resource leaks. + * * \since 1.12.0 * */ diff --git a/src/H5Pmodule.h b/src/H5Pmodule.h index 38d06e2..f2a1e5a 100644 --- a/src/H5Pmodule.h +++ b/src/H5Pmodule.h @@ -904,6 +904,7 @@ * * \ref PLCR * \snippet{doc} tables/propertyLists.dox fapl_table + * \snippet{doc} tables/propertyLists.dox fd_pl_table * * \ref PLCR * \snippet{doc} tables/propertyLists.dox lapl_table @@ -1007,6 +1008,7 @@ * can be adjusted at runtime before a file is created or opened. * * \snippet{doc} tables/propertyLists.dox fapl_table + * \snippet{doc} tables/propertyLists.dox fd_pl_table * * \defgroup FCPL File Creation Properties * \ingroup GCPL |