From d51c97e7f5efb4dac91f7135018ab85eca81999c Mon Sep 17 00:00:00 2001 From: Allen Byrne <50328838+byrnHDF@users.noreply.github.com> Date: Tue, 28 Feb 2023 19:08:02 -0600 Subject: 1.14 Merge doxygen plist tables changes #2470 from develop (#2503) * Merge doxygen plist tables changes from develop * Doxy corrections --- doxygen/dox/VOLConnGuide.dox | 4908 ++++++++++++++++++++++ doxygen/examples/tables/propertyLists.dox | 267 +- doxygen/hdf5doxy_layout.xml | 2 + java/src/hdf/hdf5lib/callbacks/package-info.java | 1 - release_docs/RELEASE.txt | 6 +- src/H5Apublic.h | 3 + src/H5Dpublic.h | 3 + src/H5FDhdfs.h | 1 - src/H5Gpublic.h | 18 +- src/H5Lpublic.h | 12 +- src/H5Mpublic.h | 3 + src/H5Pmodule.h | 2 + 12 files changed, 5143 insertions(+), 83 deletions(-) create mode 100644 doxygen/dox/VOLConnGuide.dox 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" +
+ +\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 VOL connectors. 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: + + + + + + + + + + + + + + + + + + + + + +
H5VLpublic.h +Public VOL header. +
H5VLconnector.h +Main header for connector authors. Contains definitions for the main VOL struct and callbacks, enum values, etc. +
H5VLconnector_passthru.h +Helper routines for passthrough connector authors. +
H5VLnative.h +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. +
H5PLextern.h +Needed if your connector will be built as a plugin. +
+ +Many VOL connectors are listed on The HDF Group's VOL plugin registration page, located at: +Registered VOL Connectors. +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: + +

Library

+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. + +

Plugin

+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 H5PLextern.h +(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 + +

Internal

+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: +VOL template + +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 version 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 name and value. 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 help@hdfgroup.org 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: +Registered VOL Connectors + +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 +dataset create. + +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 opt_type parameter. This proved to be a problem with pass-through connectors, +though, as it was possible to have opt_type clash if two connectors used the same opt_type values. + +The new scheme allows a connector to register an optional operation with the library and receive a dynamically-allocated +opt_type 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 register call is used to register an operation for a subclass (file, etc.) and the opt_type parameter +that the library assigned to the operation will be returned via the opt_val 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 opt_type value by name, you can use the find call. + +One recommended way to handle optional calls is to register 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 unregister 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: +vol-tests + +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: + + + + +
+VOL connector class, H5VLpublic.h +\snippet H5VLconnector.h H5VL_class_t_snip +
+ +The version field is the version of the #H5VL_class_t struct. This is identical to how the version field is +used in the #H5Z_class2_t struct for filters. + +The value field is a unique integer identifier that should be between 512 and 65535 for external, non-library +connectors. + +The name field is a string that uniquely identifies the VOL connector name. + +The conn_version is the connector version. This is currently not used by the library. + +The cap_flags 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 initialize 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 terminate 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, +get, specific, and optional 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 get/specific or integer optional field indicating the operation and a union of the +possible parameters get/specific or void pointer to the parameters optional. + +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 opt_type member is the value assigned by the library when the optional operation was registered (or +defined in the case of the native VOL connector) and the args 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 va_lists. + +The optional 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: + + +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: + +Structure to hold parameters for object locations, H5VLconnector.h +\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 H5Pset_fapl_ 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 to_str and from_str 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. + +Info class for connector information routines, H5VLconnector.h +\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 size 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. + + + + + + + +
Signature:
+\code + size_t size; +\endcode +
+ +\subsubsection subsubsecVOLRefConncopy info: copy +The copy callback is invoked when the connector is selected for use with H5Pset_fapl_, 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. + + + + + + + + + + + + + +
Signature:
+\code + void * (*copy)(const void *info); +\endcode +
Arguments:
+\code + info (IN): The connector-specific info to copy. +\endcode +
+ +\subsubsection subsubsecVOLRefConncmp info: cmp +The cmp callback is used to determine if two connector-specific data structs are identical and helps the library +manage connector resources. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*cmp)(int *cmp_value, const void *info1, const void *info2); +\endcode +
Arguments:
+\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 +
+ +\subsubsection subsubsecVOLRefConnfree info: free +The free callback is used to clean up the connector-specific information that was copied when set in the +fapl via the copy callback. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*free)(void *info); +\endcode +
Arguments:
+\code + info (IN): The connector-specific info to free. +\endcode +
+ +\subsubsection subsubsecVOLRefConnto info: to_str +The to_str callback converts a connector-specific information structure to a connector-specific configuration +string. It is the opposite of the from_str callback. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*to_str)(const void *info, char **str); +\endcode +
Arguments:
+\code + info (IN): The connector-specific info to convert to a configuration string. + str (OUT): The constructed configuration string. +\endcode +
+ +\subsubsection subsubsecVOLRefConnfrom info: from_str +The from_str callback converts a connector-specific configuration string to a connector-specific information +structure. It is the opposite of the to_str callback. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*from_str)(const char *str, void **info); +\endcode +
Arguments:
+\code + str (IN): The connector-specific configuration string. + info (OUT): The connector-specific info generated from the configuration string. +\endcode +
+ +\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. + +Wrap class for object wrapping routines, H5VLconnector.h +\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. + + + + + + + + + + + + + +
Signature:
+\code + void * (*get_object)(const void *obj); +\endcode +
Arguments:
+\code + obj (IN): Object being unwrapped. +\endcode +
+ +\subsubsection subsubsecVOLRefWrapctx wrap: get_wrap_ctx +Get a VOL connector's object wrapping context. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*get_wrap_ctx)(const void *obj, void **wrap_ctx); +\endcode +
Arguments:
+\code + obj (IN): Object for which we need a context. + wrap_ctx (OUT): Context. +\endcode +
+ +\subsubsection subsubsecVOLRefWrapwrap wrap: wrap_object +Asks a connector to wrap an underlying object. + + + + + + + + + + + + + +
Signature:
+\code + void * (*wrap_object)(void *obj, H5I_type_t obj_type, void *wrap_ctx); +\endcode +
Arguments:
+\code + obj (IN): Object being wrapped. + obj_type (IN): Object type (see H5Ipublic.h). + wrap_ctx (IN): Context. +\endcode +
+ +\subsubsection subsubsecVOLRefWrapunwrap wrap: unwrap_object +Unwrap an object from connector. + + + + + + + + + + + + + +
Signature:
+\code + void * (*unwrap_object)(void *obj); +\endcode +
Arguments:
+\code + obj (IN): Object being unwrapped. +\endcode +
+ +\subsubsection subsubsecVOLRefWrapfree wrap: free_wrap_ctx +Release a VOL connector's object wrapping context. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*free_wrap_ctx)(void *wrap_ctx); +\endcode +
Arguments:
+\code + wrap_ctx (IN): Context to be freed. +\endcode +
+ +\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. + +Structure for attribute callback routines, H5VLconnector.h +\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 create 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. + + + + + + + + + + + + + +
Signature:
+\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 +
Arguments:
+\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 +
+ +\subsubsection subsubsecVOLRefAttropen attr: open +The open 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. + + + + + + + + + + + + +
Signature:
+\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 +
Arguments:
+\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 +
+ +\subsubsection subsubsecVOLRefAttrread attr: read +The read callback in the attribute class reads data from the attribute object and returns an herr_t indicating +success or failure. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*read)(void *attr, hid_t mem_type_id, void *buf, hid_t dxpl_id, void **req); +\endcode +
Arguments:
+\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 +
+ +\subsubsection subsubsecVOLRefAttrwrite attr: write +The write callback in the attribute class writes data to the attribute object and returns an herr_t indicating +success or failure. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*write)(void *attr, hid_t mem_type_id, const void *buf, hid_t dxpl_id, void **req); +\endcode +
Arguments:
+\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 +
+ +\subsubsection subsubsecVOLRefAttrget attr: get +The get callback in the attribute class retrieves information about the attribute as specified in the get_type parameter. +It returns an herr_t indicating success or failure + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*get)(void *obj, H5VL_attr_get_args_t *args, hid_t dxpl_id, void **req); +\endcode +
Arguments:
+\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 +
+ +\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 specific callback in the attribute class implements specific operations on HDF5 attributes as specified +in the specific_type parameter. It returns an herr_t indicating success or failure. + + + + + + + + + + + + + +
Signature:
+\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 +
Arguments:
+\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 +
+ +\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 optional callback in the attribute class implements connector specific operations on an HDF5 attribute. +It returns an herr_t indicating success or failure. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*optional)(void *obj, H5VL_optional_args_t *args, hid_t dxpl_id, void **req); +\endcode +
Arguments:
+\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 +
+Each connector that requires connector-specific operations should compare the value of the op_type 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 close callback in the attribute class terminates access to the attribute object and free all resources it +was consuming, and returns an herr_t indicating success or failure. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*close)(void *attr, hid_t dxpl_id, void **req); +\endcode +
Arguments:
+\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 +
+ +\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. + +Structure for dataset callback routines, H5VLconnector.h +\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 create 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. + + + + + + + + + + + + + +
Signature:
+\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 +
Arguments:
+\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 +
+ +\subsubsection subsubsecVOLRefDsetopen dataset: open +The open 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. + + + + + + + + + + + + + +
Signature:
+\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 +
Arguments:
+\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 +
+ +\subsubsection subsubsecVOLRefDsetread dataset: read +The read callback in the dataset class reads data from the dataset object and returns an herr_t indicating +success or failure. + + + + + + + + + + + + + +
Signature:
+\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 +
Arguments:
+\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 +
+ +\subsubsection subsubsecVOLRefDsetwrite dataset: write +The write callback in the dataset class writes data to the dataset object and returns an herr_t indicating +success or failure. + + + + + + + + + + + + + +
Signature:
+\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 +
Arguments:
+\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 +
+ +\subsubsection subsubsecVOLRefDsetget dataset: get +The get callback in the dataset class retrieves information about the dataset as specified in the get_type +parameter.It returns an herr_t indicating success or failure. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*get)(void *dset, H5VL_dataset_get_args_t *args, hid_t dxpl_id, void **req); +\endcode +
Arguments:
+\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 +
+\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 specific callback in the dataset class implements specific operations on HDF5 datasets as specified in +the specific_type parameter. It returns an herr_t indicating success or failure. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*specific)(void *obj, H5VL_file_specific_args_t *args, hid_t dxpl_id, void **req); +\endcode +
Arguments:
+\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 +
+\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 optional callback in the dataset class implements connector specific operations on an HDF5 dataset. +It returns an herr_t indicating success or failure. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*optional)(void *obj, H5VL_optional_args_t *args, hid_t dxpl_id, void **req); +\endcode +
Arguments:
+\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 +
+Each connector that requires connector-specific operations should compare the value of the op_type 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 close callback in the dataset class terminates access to the dataset object and free all resources it was +consuming and returns an herr_t indicating success or failure. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*close)(void *dset, hid_t dxpl_id, void **req); +\endcode +
Arguments:
+\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 +
+ +\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. + +Structure for datatype callback routines, H5VLconnector.h +\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 commit 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. + + + + + + + + + + + + + +
Signature:
+\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 +
Arguments:
+\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 +
+ +\subsubsection subsubsecVOLRefDTypeopen datatype: open +The open 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. + + + + + + + + + + + + + +
Signature:
+\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 +
Arguments:
+\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 +
+ +\subsubsection subsubsecVOLRefDTypeget datatype: get +The get callback in the named datatype class retrieves information about the named datatype as specified +in thegettypeparameter.It returns an herr_t indicating success or failure. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*get) (void *obj, H5VL_datatype_get_args_t *args, hid_t dxpl_id, void **req); +\endcode +
Arguments:
+\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 +
+\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 specific callback in the datatype class implements specific operations on HDF5 named datatypes as +specified in the specific_type parameter. It returns an herr_t indicating success or failure. + + + + + + + + + + + + + +
Signature:
+\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 +
Arguments:
+\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 +
+\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 optional callback in the datatype class implements connector specific operations on an HDF5 datatype. +It returns an herr_t indicating success or failure. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*optional)(void *obj, H5VL_optional_args_t *args, hid_t dxpl_id, void **req); +\endcode +
Arguments:
+\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 +
+ +Each connector that requires connector-specific operations should compare the value of the op_type 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 close callback in the named datatype class terminates access to the datatype object and free all +resources it was consuming and returns an herr_t indicating success or failure. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*close) (void *dt, hid_t dxpl_id, void **req); +\endcode +
Arguments:
+\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 +
+ +\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. + +File class for file API routines, H5VLconnector.h +\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 create 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. + + + + + + + + + + + + + +
Signature:
+\code + void *(*create)(const char *name, unsigned flags, hid_t fcpl_id, hid_t fapl_id, hid_tdxpl_id, void **req); +\endcode +
Arguments:
+\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 +
+ +\subsubsection subsubsecVOLRefFileopen file: open +The open 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. + + + + + + + + + + + + + +
Signature:
+\code + void *(*open)(const char *name, unsigned flags, hid_t fapl_id, hid_t dxpl_id, void **req); +\endcode +
Arguments:
+\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 +
+ +\subsubsection subsubsecVOLRefFileget file: get +The get callback in the file class should retrieve information about the container as specified in the get_type +parameter. It returns an herr_t indicating success or failure. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*get)(void *obj, H5VL_file_get_args_t *args, hid_t dxpl_id, void **req); +\endcode +
Arguments:
+\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 +
+\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 specific callback in the file class implements specific operations on HDF5 files as specified in the +specific_type parameter. It returns an herr_t indicating success or failure. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*specific)(void *obj, H5VL_file_specific_args_t *args, hid_t dxpl_id, void **req); +\endcode +
Arguments:
+\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 +
+\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 optional callback in the file class implements connector specific operations on an HDF5 container. It +returns an herr_t indicating success or failure. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*optional)(void *obj, H5VL_optional_args_t *args, hid_t dxpl_id, void **req); +\endcode +
Arguments:
+\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 +
+Each connector that requires connector-specific operations should compare the value of the op_type 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 close callback in the file class should terminate access to the file object and free all resources it was +consuming, and returns an herr_t indicating success or failure. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*close)(void *file, hid_t dxpl_id, void **req); +\endcode +
Arguments:
+\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 +
+ +\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. + +Structure for group callback routines, H5VLconnector.h +\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 create 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. + + + + + + + + + + + + + +
Signature:
+\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 +
Arguments:
+\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 +
+ +\subsubsection subsubsecVOLRefGrpopen group: open +The open 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. + + + + + + + + + + + + + +
Signature:
+\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 +
Arguments:
+\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 +
+ +\subsubsection subsubsecVOLRefGrpget group: get +The get callback in the group class retrieves information about the group as specified in the get_type +parameter. It returns an herr_t indicating success or failure. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*get)(void *obj, H5VL_group_get_args_t *args, hid_t dxpl_id, void **req) +\endcode +
Arguments:
+\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 +
+\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 specific callback in the group class implements specific operations on HDF5 groups as specified in the +specific_type parameter. It returns an herr_t indicating success or failure. + + + + + + + + + + + + + +
Signature:
+\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 +
Arguments:
+\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 +
+\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 optional callback in the group class implements connector specific operations on an HDF5 group. It +returns an herr_t indicating success or failure. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*optional)(void *obj, H5VL_optional_args_t *args, hid_t dxpl_id, void **req); +\endcode +
Arguments:
+\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 +
+Each connector that requires connector-specific operations should compare the value of the op_type 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 close callback in the group class terminates access to the group object and frees all resources it was +consuming, and returns an herr_t indicating success or failure. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*close)(void *group, hid_t dxpl_id, void **req); +\endcode +
Arguments:
+\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 +
+ +\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. + +Structure for link callback routines, H5VLconnector.h +\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 create callback in the group class creates a hard, soft, external, or user-defined link in the container. +It returns an herr_t indicating success or failure. + + + + + + + + + + + + + +
Signature:
+\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 +
Arguments:
+\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 +
+\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 copy callback in the link class copies a link within the HDF5 container. It returns an herr_t indicating +success or failure. + + + + + + + + + + + + + +
Signature:
+\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 +
Arguments:
+\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 +
+ +\subsubsection subsubsecVOLRefLinkmove link: move +The move callback in the link class moves a link within the HDF5 container. It returns an herr_t indicating +success or failure. + + + + + + + + + + + + + +
Signature:
+\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 +
Arguments:
+\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 +
+ +\subsubsection subsubsecVOLRefLinkget link: get +The get callback in the link class retrieves information about links as specified in the get_type parameter. +It returns an herr_t indicating success or failure. + + + + + + + + + + + + + +
Signature:
+\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 +
Arguments:
+\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 +
+\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 specific callback in the link class implements specific operations on HDF5 links as specified in +the specific_type parameter. It returns an herr_t indicating success or failure. + + + + + + + + + + + + + +
Signature:
+\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 +
Arguments:
+\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 +
+\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 optional callback in the link class implements connector specific operations on an HDF5 link. It returns +an herr_t indicating success or failure. + + + + + + + + + + + + + +
Signature:
+\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 +
Arguments:
+\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 +
+Each connector that requires connector-specific operations should compare the value of the op_type 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. + +Structure for object callback routines, H5VLconnector.h +\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 open 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. + + + + + + + + + + + + + +
Signature:
+\code + void *(*open)(void *obj, H5VL_loc_params_t *loc_params, H5I_type_t *opened_type, hid_t dxpl_id, void **req); +\endcode +
Arguments:
+\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 +
+ +\subsubsection subsubsecVOLRefObjcopy object: copy +The copy callback in the object class copies the object from the source object to the destination object. It +returns an herr_t indicating success or failure. + + + + + + + + + + + + + +
Signature:
+\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 +
Arguments:
+\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 +
+ +\subsubsection subsubsecVOLRefObjget object: get +The get callback in the object class retrieves information about the object as specified in +the get_type parameter.It returns an herr_t indicating success or failure. + + + + + + + + + + + + + +
Signature:
+\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 +
Arguments:
+\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 +
+\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 specific callback in the object class implements specific operations on HDF5 objects as specified in +the specific_type parameter. It returns an herr_t indicating success or failure. + + + + + + + + + + + + + +
Signature:
+\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 +
Arguments:
+\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 +
+\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 optional callback in the object class implements connector specific operations on an HDF5 object. It +returns an herr_t indicating success or failure. + + + + + + + + + + + + + +
Signature:
+\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 +
Arguments:
+\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 +
+Each connector that requires connector-specific operations should compare the value of the op_type 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 +Structure for VOL connector introspection callback routines, H5VLconnector.h +\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. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*get_conn_cls)(void *obj, H5VL_get_conn_lvl_t lvl, const struct H5VL_class_t **conn_cls); +\endcode +
Arguments:
+\code + obj (IN): The VOL object. + lvl (IN): Current or terminal connector. + cls (OUT): A const pointer to the connector. +\endcode +
+The "lvl" argument is an enum: +\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. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*get_cap_flags)(const void *info, unsigned *cap_flags) +\endcode +
Arguments:
+\code + info (IN): A const pointer to pertinent VOL info. + cap_flags (OUT): A pointer to capability flags. +\endcode +
+ +\subsubsection subsubsecVOLRefIntrospecquery introspect: opt_query +Query a class for a capability or functionality. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*opt_query)(void *obj, H5VL_subclass_t cls, int opt_type, hbool_t *supported); +\endcode +
Arguments:
+\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 +
+The "cls" argument is an enum: +\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 +Structure for async request callback routines, H5VLconnector.h +\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. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*wait)(void *req, uint64_t timeout, H5VL_request_status_t *status); +\endcode +
Arguments:
+\code + req (IN): The async request on which to wait. + timeout (IN): The timeout value. + status (IN): The status. +\endcode +
+The "status" argument is an enum: +\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. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*notify)(void *req, H5VL_request_notify_t cb, void *ctx); +\endcode +
Arguments:
+\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 +
+The "cb" argument is an enum: +\code + typedef herr_t (*H5VL_request_notify_t)(void *ctx, H5ES_status_t status) +\endcode + +\subsubsection subsubsecVOLRefReqcancel request: cancel + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*cancel)(void *req, H5VL_request_status_t *status); +\endcode +
Arguments:
+\code + req (IN): The async request to be cancelled. + status (IN): The status. +\endcode +
+The "status" argument is an enum: +\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. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*specific)(void *req, H5VL_request_specific_args_t *args); +\endcode +
Arguments:
+\code + req (IN): The async request on which to perform the operation. + args (IN/OUT): A pointer to the arguments struct. +\endcode +
+\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. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*optional)(void *req, H5VL_optional_args_t *args); +\endcode +
Arguments:
+\code + req (IN): The async request on which to perform the operation. + args (IN/OUT): A pointer to the arguments struct. +\endcode +
+Each connector that requires connector-specific operations should compare the value of the op_type 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. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*free)(void *req); +\endcode +
Arguments:
+\code + req (IN): The async request to be freed. +\endcode +
+ +\subsection subsecVOLRefBlob Blob Callbacks +Structure for blob callback routines, H5VLconnector.h +\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. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*put)(void *obj, const void *buf, size_t size, void *blob_id, void *ctx); +\endcode +
Arguments:
+\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 +
+ +\subsubsection subsubsecVOLRefBlobget blob: get +Get a blob through the VOL. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*get)(void *obj, const void *blob_id, void *buf, size_t size, void *ctx); +\endcode +
Arguments:
+\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 +
+ +\subsubsection subsubsecVOLRefBlobspec blob: specific +Perform a defined operation on a blob via the VOL. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*specific)(void *obj, void *blob_id, H5VL_blob_specific_args_t *args); +\endcode +
Arguments:
+\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 +
+\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 + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*optional)(void *obj, void *blob_id, H5VL_optional_args_t *args); +\endcode +
Arguments:
+\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 +
+Each connector that requires connector-specific operations should compare the value of the op_type 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 +Structure for token callback routines, H5VLconnector.h +\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. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*cmp)(void *obj, const H5O_token_t *token1, const H5O_token_t *token2, int *cmp_value); +\endcode +
Arguments:
+\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 +
+ +\subsubsection subsubsecVOLRefTokento token: to_str +Converts a token to a string representation. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*to_str)(void *obj, H5I_type_t obj_type, const H5O_token_t *token, char **token_str) +\endcode +
Arguments:
+\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 +
+The "obj_type" argument is an enum: (from H5Ipublic.h) +\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. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*from_str)(void *obj, H5I_type_t obj_type, const char *token_str, H5O_token_t *token); +\endcode +
Arguments:
+\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 +
+The "obj_type" argument is an enum: (from H5Ipublic.h) +\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 generic optional callback is provided for services that are specific to a connector. +The optional callback has the following definition. It returns an herr_t indicating success or failure. + + + + + + + + + + + + + +
Signature:
+\code + herr_t (*optional)(void *obj, H5VL_optional_args_t *args, hid_t dxpl_id, void **req); +\endcode +
Arguments:
+\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 +
+ +\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 + + + + + + + + + + + + + +
Signature:
+\code + hid_t H5VLregister_connector_by_name(const char *connector_name, hid_t vipl_id); +\endcode +
Arguments:
+\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 +
+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 + + + + + + + + + + + + + +
Signature:
+\code + hid_t H5VLregister_connector_by_value(H5VL_class_value_t connector_value, hid_t vipl_id); +\endcode +
Arguments:
+\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 +
+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 + + + + + + + + + + + + + +
Signature:
+\code + htri_t H5VLis_connector_registered_by_name(const char *name); +\endcode +
Arguments:
+\code + name (IN): The connector name to check for. +\endcode +
+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 + + + + + + + + + + + + + +
Signature:
+\code + htri_t H5VLis_connector_registered_by_value(H5VL_class_value_t connector_value); +\endcode +
Arguments:
+\code + connector_value (IN): The connector value to check for. +\endcode +
+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 + + + + + + + + + + + + + +
Signature:
+\code + hid_t H5VLget_connector_id(hid_t obj_id); +\endcode +
Arguments:
+\code + obj_id (IN): An ID for an HDF5 VOL object. +\endcode +
+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 + + + + + + + + + + + + + +
Signature:
+\code + hid_t H5VLget_connector_id_by_name(const char *name); +\endcode +
Arguments:
+\code + name (IN): The connector name to check for. +\endcode +
+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 + + + + + + + + + + + + + +
Signature:
+\code + hid_t H5VLget_connector_id_by_value(H5VL_class_value_t connector_value); +\endcode +
Arguments:
+\code + connector_value (IN): The connector value to check for. +\endcode +
+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 + + + + + + + + + + + + + +
Signature:
+\code + ssize_t H5VLget_connector_name(hid_t id, char *name /*out*/, size_t size); +\endcode +
Arguments:
+\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 +
+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 + + + + + + + + + + + + + +
Signature:
+\code + herr_t H5VLclose(hid_t connector_id); +\endcode +
Arguments:
+\code + connector_id (IN): A valid identifier of the connector to close. +\endcode +
+Shuts down access to the connector that the identifier points to and release resources associated with it. + +\subsubsection subsubsecVOLNewPubunreg H5VLunregister_connector + + + + + + + + + + + + + +
Signature:
+\code + herr_t H5VLunregister_connector(hid_t connector_id); +\endcode +
Arguments:
+\code + connector_id (IN): A valid identifier of the connector to unregister. +\endcode +
+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 + + + + + + + + + + + + + +
Signature:
+\code + herr_t H5VLquery_optional(hid_t obj_id, H5VL_subclass_t subcls, int opt_type, uint64_t *flags); +\endcode +
Arguments:
+\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 +
+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 + + + + + + + + + + + + + +
Signature:
+\code + hid_t H5VLregister_connector(const H5VL_class_t *cls, hid_t vipl_id); +\endcode +
Arguments:
+\code + cls (IN): A pointer to the connector structure to register. + vipl_id (IN): An ID for a VOL initialization property list (vipl). +\endcode +
+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 + + + + + + + + + + + + + +
Signature:
+\code + void *H5VLobject(hid_t obj_id); +\endcode +
Arguments:
+\code + obj_id (IN): identifier of the object to dereference. +\endcode +
+Retrieves a pointer to the VOL object from an HDF5 file or object identifier. + +\subsubsection subsubsecVOLNewConnget H5VLget_file_type + + + + + + + + + + + + + +
Signature:
+\code + hid_t H5VLget_file_type(void *file_obj, hid_t connector_id, hid_t dtype_id); +\endcode +
Arguments:
+\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 +
+Returns a copy of the dtype_id 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 + + + + + + + + + + + + + +
Signature:
+\code + hid_t H5VLpeek_connector_id_by_name(const char *name); +\endcode +
Arguments:
+\code + name (IN): name of the connector to query. +\endcode +
+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 + + + + + + + + + + + + + +
Signature:
+\code + hid_t H5VLpeek_connector_id_by_value(H5VL_class_value_t value); +\endcode +
Arguments:
+\code + value (IN): value of the connector to query. +\endcode +
+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 + + + + + + + + + + + + + +
Signature:
+\code + herr_t H5VLcmp_connector_cls(int *cmp, hid_t connector_id1, hid_t connector_id2); +\endcode +
Arguments:
+\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 +
+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 + + + + + + + + + + + + + +
Signature:
+\code + hid_t H5VLwrap_register(void *obj, H5I_type_t type); +\endcode +
Arguments:
+\code + obj (IN): an object to wrap. + type (IN): the type of the object (see below). +\endcode +
+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 + + + + + + + + + + + + + +
Signature:
+\code + herr_t H5VLretrieve_lib_state(void **state); +\endcode +
Arguments:
+\code + state (OUT): the library state. +\endcode +
+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 + + + + + + + +
Signature:
+\code + herr_t H5VLstart_lib_state(void); +\endcode +
+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 + + + + + + + + + + + + + +
Signature:
+\code + herr_t H5VLrestore_lib_state(const void *state); +\endcode +
Arguments:
+\code + state (IN): the library state. +\endcode +
+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 + + + + + + + +
Signature:
+\code + herr_t H5VLfinish_lib_state(void); +\endcode +
+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 + + + + + + + + + + + + + +
Signature:
+\code + herr_t H5VLfree_lib_state(void *state); +\endcode +
Arguments:
+\code + state (IN): the library state. +\endcode +
+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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
VOL CallbackHDF5 API Call
FILE
create\li #H5Fcreate
open +\li #H5Fopen +
get +\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 +
specific +\li #H5Fdelete +\li #H5Fflush +\li #H5Fis_accessible +\li #H5Fis_hdf5 (deprecated, hard-coded to use native connector) +\li #H5Freopen +
close +\li #H5Fclose +
GROUP
create +\li #H5Gcreate1 (deprecated) +\li #H5Gcreate2 +\li #H5Gcreate_anon +
open +\li #H5Gopen1 (deprecated) +\li #H5Gopen2 +
get +\li #H5Gget_create_plist +\li #H5Gget_info +\li #H5Gget_info_by_idx +\li #H5Gget_info_by_name +\li #H5Gget_num_objs (deprecated) +
specific +\li #H5Fmount +\li #H5Funmount +\li #H5Gflush +\li #H5Grefresh +
close +\li #H5Gclose +
DATASET
create +\li #H5Dcreate1 (deprecated) +\li #H5Dcreate2 +
open +\li #H5Dopen1 (deprecated) +\li #H5Dopen2 +
read +\li #H5Dread +
write +\li #H5Dwrite +
get +\li #H5Dget_access_plist +\li #H5Dget_create_plist +\li #H5Dget_space +\li #H5Dget_space_status +\li #H5Dget_storage_size +\li #H5Dget_type +
specific +\li #H5Dextend (deprecated) +\li #H5Dflush +\li #H5Drefresh +\li #H5Dset_extent +
close +\li #H5Dclose +
OBJECT
open +\li #H5Oopen +\li #H5Oopen_by_addr (deprecated) +\li #H5Oopen_by_idx +\li #H5Oopen_by_token +
copy +\li #H5Ocopy +
get +\li #H5Oget_info1 (deprecated) +\li #H5Oget_info2 (deprecated) +\li #H5Oget_info3 +
specific +\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 +
close +\li #H5Oclose +
LINK
create +\li #H5Glink (deprecated) +\li #H5Glink2 (deprecated) +\li #H5Lcreate_hard +\li #H5Lcreate_soft +\li #H5Lcreate_ud +\li #H5Olink +
copy +\li #H5Lcopy +
move +\li #H5Gmove (deprecated) +\li #H5Gmove2 (deprecated) +\li #H5Lmove +
get +\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 +
specific +\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 +
DATATYPE
commit +\li #H5Tcommit1 (deprecated) +\li #H5Tcommit2 +\li #H5Tcommit+anon +
open +\li #H5Topen1 (deprecated) +\li #H5Topen2 +
get +\li #H5Tget_create_plist +
specific +\li #H5Tflush +\li #H5Trefresh +
close +\li #H5Tclose +
ATTRIBUTE
create +\li #H5Acreate1 (deprecated) +\li #H5Acreate2 +\li #H5Acreate_by_name +
open +\li #H5Aopen +\li #H5Aopen_by_idx +\li #H5Aopen_by_name +\li #H5Aopen_idx (deprecated) +\li #H5Aopen_name (deprecated) +
read +\li #H5Aread +
write +\li #H5Awrite +
get +\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 +
specific +\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 +
close +\li #H5Aclose +
+ +\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 + +
+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 @@ Iterates over properties in a property class or list -#H5Pregister/H5Punregister +#H5Pregister/#H5Punregister Registers/removes a permanent property with/from a property list class @@ -124,14 +124,6 @@ Sets/retrieves size of parameter used to control B-trees for indexing chunked datasets. -#H5Pset_file_image -Sets an initial file image in a memory buffer. - - -#H5Pget_file_image -Retrieves a copy of the file image designated as the initial content and structure of a file. - - #H5Pset_file_space_page_size/#H5Pget_file_space_page_size Sets or retrieves the file space page size used in paged aggregation and paged buffering. @@ -179,11 +171,19 @@ creation property list. Sets/retrieves metadata cache and raw data chunk cache parameters. +#H5Pset_core_write_tracking/#H5Pget_core_write_tracking +Sets/retrieves write tracking information for core driver. + + #H5Pset_elink_file_cache_size/#H5Pget_elink_file_cache_size Sets/retrieves the size of the external link open file cache from the specified file access property list. +#H5Pset_evict_on_close/#H5Pget_evict_on_close +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. + + #H5Pset_gc_references/#H5Pget_gc_references Sets/retrieves garbage collecting references flag. @@ -196,18 +196,56 @@ file access property list. Retrieves a data offset from the file access property list. +#H5Pset_fclose_degree/#H5Pget_fclose_degree +Sets/retrieves file close degree property. + + +#H5Pset_file_image +Sets an initial file image in a memory buffer. + + +#H5Pget_file_image +Retrieves a copy of the file image designated as the initial content and structure of a file. + + +#H5Pset_file_image_callbacks/#H5Pget_file_image_callbacks +Sets/gets the callbacks for working with file images. + + +#H5Pset_file_locking/#H5Pget_file_locking +Sets/retrieves file locking property values. + + #H5Pset_meta_block_size/#H5Pget_meta_block_size Sets the minimum metadata blocksize or retrieves the current metadata block size setting. -#H5Pset_mdc_config -Set the initial metadata cache configuration in the indicated File Access Property List -to the supplied value. +#H5Pset_metadata_read_attempts/#H5Pget_metadata_read_attempts +Sets/gets the number of read attempts from a file access property list. + + +#H5Pset_mdc_config/#H5Pget_mdc_config +Set/get the initial metadata cache configuration in the indicated file access property list. + + +#H5Pset_mdc_image_config/#H5Pget_mdc_image_config +Set/get the metadata cache image option for a file access property list. + + +#H5Pset_mdc_log_options/#H5Pget_mdc_log_options +Set/get the metadata cache logging options. + + +#H5Pset_multi_type/#H5Pget_multi_type +Sets/gets the type of data property for the MULTI driver. + + +#H5Pset_object_flush_cb/#H5Pget_object_flush_cb +Set/get the object flush property values from the file access property list. -#H5Pget_mdc_config -Get the current initial metadata cache config-uration from the indicated File Access -Property List. +#H5Pset_page_buffer_size/#H5Pget_page_buffer_size +Set/get the the maximum size for the page buffer. #H5Pset_sieve_buf_size/#H5Pget_sieve_buf_size @@ -231,6 +269,30 @@ versions used when creating objects. #H5Pget_small_data_block_size Retrieves the current small data block size setting. + +#H5Pset_vol +Sets the file VOL connector for a file access property list. + + +#H5Pget_vol_cap_flags +Retrieves the capability flags for the VOL connector that will be used with a file access property list. + + +#H5Pget_vol_id +Retrieves the identifier of the current VOL connector. + + +#H5Pget_vol_info +Retrieves a copy of the VOL information for a connector. + + +#H5Pset_mpi_params/#H5Pget_mpi_params +Sets/retrieves the MPI communicator and info. + + +#H5Pset_coll_metadata_write/#H5Pget_coll_metadata_write +Sets/retrieves metadata write mode setting. + //! [fapl_table] * @@ -254,6 +316,18 @@ versions used when creating objects. Returns a pointer to file driver information. +#H5Pset_driver_by_name +Sets a file driver according to a given driver name. + + +#H5Pset_driver_by_value +Sets a file driver according to a given driver value. + + +#H5Pget_driver_config_str +Retrieves a string representation of the configuration for the driver. + + #H5Pset_fapl_core/#H5Pget_fapl_core Sets the driver for buffered memory files (in RAM) or retrieves information regarding the driver. @@ -268,10 +342,22 @@ the driver. larger than 2 gigabytes, or retrieves information regarding driver. +#H5Pset_fapl_hdfs/#H5Pget_fapl_hdfs +. + + +#H5Pset_fapl_ioc/#H5Pget_fapl_ioc +Modifies/queries the file driver properties of the I/O concentrator driver. + + #H5Pset_fapl_log Sets logging driver. +#H5Pset_fapl_mirror/#H5Pget_fapl_mirror +Modifies/queries the file driver properties of the mirror driver. + + #H5Pset_fapl_mpio/#H5Pget_fapl_mpio Sets driver for files on parallel file systems (MPI I/O) or retrieves information regarding the driver. @@ -286,6 +372,10 @@ regarding the driver. or retrieves information regarding driver. +#H5Pset_fapl_onion/#H5Pget_fapl_onion +Modifies/queries the file driver properties of the onion driver. + + #H5Pset_fapl_sec2 Sets driver for unbuffered permanent files or retrieves information regarding driver. @@ -299,6 +389,10 @@ and one raw data file. Sets driver for buffered permanent files. +#H5Pset_fapl_subfiling/#H5Pget_fapl_subfiling +Modifies/queries the file driver properties of the subfiling driver. + + #H5Pset_fapl_windows Sets the Windows I/O driver. @@ -337,6 +431,10 @@ and one raw data file. Retrieves the size of chunks for the raw data of a chunked layout dataset. +#H5Pset_chunk_opts/#H5Pget_chunk_opts +Sets/gets the edge chunk option setting from a dataset creation property list. + + #H5Pset_deflate Sets compression method and compression level. @@ -439,6 +537,34 @@ encoding for object names. #H5Pget_char_encoding Retrieves the character encoding used to create a string. + +#H5Pset_virtual +Sets the mapping between virtual and source datasets. + + +#H5Pget_virtual_count +Gets the number of mappings for the virtual dataset. + + +#H5Pget_virtual_dsetname +Gets the name of a source dataset used in the mapping. + + +#H5Pget_virtual_filename +Gets the filename of a source dataset used in the mapping. + + +#H5Pget_virtual_srcspace +Gets a dataspace identifier for the selection within the source dataset used in the mapping. + + +#H5Pget_virtual_vspace +Gets a dataspace identifier for the selection within the virtual dataset used in the mapping. + + +#H5Pset_dset_no_attrs_hint/#H5Pget_dset_no_attrs_hint +Sets/gets the flag to create minimized dataset object headers. + //! [dcpl_table] * @@ -458,32 +584,77 @@ encoding for object names. Reads buffer settings. +#H5Pset_append_flush/#H5Pget_append_flush +Sets/gets the values of the append property that is set up in the dataset access property list. + + #H5Pset_chunk_cache/#H5Pget_chunk_cache Sets/gets the raw data chunk cache parameters. -#H5Pset_edc_check/#H5Pget_edc_check -Sets/gets whether to enable error-detection when reading a dataset. +#H5Pset_efile_prefix/#H5Pget_efile_prefix +Sets/gets the prefix for external raw data storage files as set in the dataset access property list. -#H5Pset_filter_callback -Sets user-defined filter callback function. +#H5Pset_virtual_prefix/#H5Pget_virtual_prefix +Sets/gets the prefix to be applied to VDS source file paths. + + +#H5Pset_virtual_printf_gap/#H5Pget_virtual_printf_gap +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. + + +#H5Pset_virtual_view/#H5Pget_virtual_view +Sets/gets the view of the virtual dataset (VDS) to include or exclude missing mapped elements. + + +//! [dapl_table] + * +//! [dxpl_table] + + + + + + + + + + + + + - - + + + + + + + + + + + + + + - - + + @@ -511,38 +682,20 @@ encoding for object names. - - - - - - - -
Data transfer property list functions (H5P)
C FunctionPurpose
#H5Pset_btree_ratios/#H5Pget_btree_ratiosSets/gets B-tree split ratios for a dataset transfer property list.
#H5Pset_bufferMaximum size for the type conversion buffer and the background buffer. May also supply +pointers to application-allocated buffers.
#H5Pset_data_transform/#H5Pget_data_transform Sets/gets a data transform expression.
#H5Pset_type_conv_cb/#H5Pget_type_conv_cbSets/gets user-defined datatype conversion callback function.#H5Pset_dataset_io_hyperslab_selectionSets a hyperslab file selection for a dataset I/O operation.
#H5Pset_edc_check/#H5Pget_edc_checkSets/gets whether to enable error-detection when reading a dataset.
#H5Pset_hyper_vector_sizeset 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.
#H5Pset_filter_callbackSets user-defined filter callback function.
#H5Pset_hyper_vector_size/#H5Pget_hyper_vector_size Sets/gets number of I/O vectors to be read/written in hyperslab I/O.
#H5Pset_btree_ratios/#H5Pget_btree_ratiosSets/gets B-tree split ratios for a dataset transfer property list.#H5Pset_type_conv_cb/#H5Pget_type_conv_cbSets/gets user-defined datatype conversion callback function.
#H5Pset_vlen_mem_manager/#H5Pget_vlen_mem_manager Sets a flag governing the use of independent versus collective I/O.
#H5Pset_multi_type/#H5Pget_multi_typeSets/gets the type of data property for the MULTI driver.
#H5Pset_small_data_block_size/#H5Pget_small_data_block_sizeSets/gets the size of a contiguous block reserved for small data.
-//! [dapl_table] - * -//! [dxpl_table] - - - - - + + - - + + - - + + - - + +
Data transfer property list functions (H5P)
C FunctionPurpose#H5Pget_mpio_actual_chunk_opt_modeGets the type of chunk optimization that HDF5 actually performed on the last parallel I/O call.
#H5Pset_bufferMaximum size for the type conversion buffer and the background buffer. May also supply -pointers to application-allocated buffers.#H5Pget_mpio_actual_io_modeGets the type of I/O that HDF5 actually performed on the last parallel I/O call.
#H5Pset_hyper_vector_sizeset 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.#H5Pget_mpio_no_collective_causeGets local and global causes that broke collective I/O on the last parallel I/O call.
#H5Pset_btree_ratiosSet 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.H5Pset_preserve/H5Pget_preserveNo longer available, deprecated as it no longer has any effect.
//! [dxpl_table] @@ -593,6 +746,10 @@ C function is a macro: \see \ref api-compat-macros. Sets up use of the Fletcher32 checksum filter. +#H5Pset_local_heap_size_hint#H5Pget_local_heap_size_hint/ +Sets/gets the anticipated maximum size of a local heap. + + #H5Pset_link_phase_change Sets the parameters for conversion between compact and dense groups. @@ -625,14 +782,6 @@ C function is a macro: \see \ref api-compat-macros. Queries whether link creation order is tracked and/or indexed in a group. -#H5Pset_create_intermediate_group -Specifies in the property list whether to create missing intermediate groups. - - -#H5Pget_create_intermediate_group -Determines whether the property is set to enable creating missing intermediate groups. - - #H5Pset_char_encoding Sets the character encoding used to encode a string. Use to set ASCII or UTF-8 character encoding for object names. @@ -771,10 +920,6 @@ encoding for object names. #H5Pset_char_encoding/#H5Pget_char_encoding Sets/gets the character encoding used to encode link and attribute names. - -#H5Pset_create_intermediate_group/#H5Pget_create_intermediate_group -Specifies/retrieves whether to create missing intermediate groups. - //! [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 @@ + + 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 -- cgit v0.12