![]() |
HDF5
1.15.0.08e115b
API Reference
|
Navigate back: Main
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 The HDF5 Virtual Object Layer (VOL) 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.
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:
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.
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.
Use of the VOL, including topics such as registration and loading VOL plugins, is described in the The HDF5 Virtual Object Layer (VOL).
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
When building a VOL connector, you have several options:
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.
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 The HDF5 Virtual Object Layer (VOL) 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:
To show how easy this is to accomplish, here is the complete implementation of those functions in the template VOL connector:
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:
The plugin would implement the two routines as:
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.
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.
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 The HDF5 Virtual Object Layer (VOL)), 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 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 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 H5VLconnector.h.
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:
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.
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.
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:
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:
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.
Coming Soon
Coming Soon
Each VOL connector should be of type H5VL_class_t:
VOL connector class, H5VLpublic.h /* Overall connector fields & callbacks */
unsigned version;
unsigned conn_version;
uint64_t cap_flags;
/* VOL framework */
/* Data Model */
/* Infrastructure / Services */
/* Catch-all */
void **req);
} H5VL_class_t;
Definition: H5VLconnector.h:862 Definition: H5VLconnector.h:992 herr_t(* optional)(void *obj, H5VL_optional_args_t *args, hid_t dxpl_id, void **req) Definition: H5VLconnector.h:1041 Definition: H5VLconnector.h:877 Definition: H5VLconnector.h:893 Definition: H5VLconnector.h:905 Definition: H5VLconnector.h:916 Definition: H5VLconnector.h:837 Definition: H5VLconnector.h:975 Definition: H5VLconnector.h:928 Definition: H5VLconnector.h:946 Definition: H5VLconnector.h:982 Definition: H5VLconnector.h:1000 Definition: H5VLconnector.h:849 |
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:
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.
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
This section's callbacks involve the connector-specific information that will be associated with the VOL in the fapl via H5Pset_fapl_<name> 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
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: |
---|
size_t size;
|
The copy callback is invoked when the connector is selected for use with H5Pset_fapl_<name>, 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: |
---|
void * (*copy)(const void *info);
|
Arguments: |
info (IN): The connector-specific info to copy.
|
The cmp callback is used to determine if two connector-specific data structs are identical and helps the library manage connector resources.
Signature: |
---|
Arguments: |
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.
|
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: |
---|
herr_t (*free)(void *info);
|
Arguments: |
info (IN): The connector-specific info to free.
|
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: |
---|
Arguments: |
info (IN): The connector-specific info to convert to a configuration string.
str (OUT): The constructed configuration string.
|
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: |
---|
Arguments: |
str (IN): The connector-specific configuration string.
info (OUT): The connector-specific info generated from the configuration string.
|
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
Retrieves an underlying object.
Signature: |
---|
void * (*get_object)(const void *obj);
|
Arguments: |
obj (IN): Object being unwrapped.
|
Get a VOL connector's object wrapping context.
Signature: |
---|
Arguments: |
obj (IN): Object for which we need a context.
wrap_ctx (OUT): Context.
|
Asks a connector to wrap an underlying object.
Signature: |
---|
Arguments: |
obj (IN): Object being wrapped.
obj_type (IN): Object type (see H5Ipublic.h).
wrap_ctx (IN): Context.
|
Unwrap an object from connector.
Signature: |
---|
void * (*unwrap_object)(void *obj);
|
Arguments: |
obj (IN): Object being unwrapped.
|
Release a VOL connector's object wrapping context.
Signature: |
---|
herr_t (*free_wrap_ctx)(void *wrap_ctx);
|
Arguments: |
wrap_ctx (IN): Context to be freed.
|
The attribute API routines (Attributes (H5A)) allow HDF5 users to create and manage HDF5 attributes. All the Attributes (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
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: |
---|
Arguments: |
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.
|
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: |
---|
void *(*open)(void *obj, H5VL_loc_params_t *loc_params, const char *attr_name, hid_t aapl_id, hid_t dxpl_id, void **req);
|
Arguments: |
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.
|
The read callback in the attribute class reads data from the attribute object and returns an herr_t indicating success or failure.
Signature: |
---|
Arguments: |
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.
|
The write callback in the attribute class writes data to the attribute object and returns an herr_t indicating success or failure.
Signature: |
---|
Arguments: |
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.
|
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: |
---|
Arguments: |
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.
|
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: |
---|
herr_t (*specific)(void *obj, H5VL_loc_params_t *loc_params, H5VL_attr_specific_args_t *args, hid_t dxpl_id, void **req);
|
Arguments: |
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.
|
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: |
---|
Arguments: |
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.
|
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.
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: |
---|
Arguments: |
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.
|
The dataset API routines (Datasets (H5D)) allow HDF5 users to create and manage HDF5 datasets. All the Datasets (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
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: |
---|
Arguments: |
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.
|
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: |
---|
void *(*open)(void *obj, H5VL_loc_params_t *loc_params, const char *name, hid_t dapl_id, hid_t dxpl_id, void **req);
|
Arguments: |
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.
|
The read callback in the dataset class reads data from the dataset object and returns an herr_t indicating success or failure.
Signature: |
---|
Arguments: |
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.
|
The write callback in the dataset class writes data to the dataset object and returns an herr_t indicating success or failure.
Signature: |
---|
Arguments: |
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.
|
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: |
---|
Arguments: |
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.
|
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: |
---|
Definition: H5VLconnector.h:449 |
Arguments: |
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.
|
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: |
---|
Arguments: |
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.
|
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.
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: |
---|
Arguments: |
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.
|
The HDF5 datatype routines (Datatypes (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 Datatypes (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
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: |
---|
Arguments: |
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.
|
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: |
---|
void *(*open) (void *obj, H5VL_loc_params_t *loc_params, const char * name, hid_t tapl_id, hid_t dxpl_id, void **req);
|
Arguments: |
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.
|
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: |
---|
Arguments: |
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.
|
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: |
---|
herr_t (*specific)(void *obj, H5VL_loc_params_t *loc_params, H5VL_object_specific_args_t *args, hid_t dxpl_id, void **req);
Definition: H5VLconnector.h:726 |
Arguments: |
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.
|
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: |
---|
Arguments: |
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.
|
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.
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: |
---|
Arguments: |
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.
|
The file API routines (Files (H5F)) allow HDF5 users to create and manage HDF5 containers. All the Files (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
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: |
---|
Arguments: |
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.
|
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: |
---|
Arguments: |
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.
|
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: |
---|
Arguments: |
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.
|
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: |
---|
Arguments: |
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.
|
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: |
---|
Arguments: |
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.
|
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.
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: |
---|
Arguments: |
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.
|
The group API routines (Groups (H5G)) allow HDF5 users to create and manage HDF5 groups. All the Groups (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
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: |
---|
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);
|
Arguments: |
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.
|
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: |
---|
void *(*open)(void *obj, H5VL_loc_params_t *loc_params, const char *name, hid_t gapl_id, hid_t dxpl_id, void **req);
|
Arguments: |
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.
|
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: |
---|
Arguments: |
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.
|
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: |
---|
herr_t (*specific)(void *obj, H5VL_loc_params_t *loc_params, H5VL_object_specific_args_t *args, hid_t dxpl_id, void **req);
|
Arguments: |
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.
|
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: |
---|
Arguments: |
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.
|
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.
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: |
---|
Arguments: |
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.
|
The link API routines (Links (H5L)) allow HDF5 users to create and manage HDF5 links. All the Links (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
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: |
---|
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)
|
Arguments: |
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.
|
The copy callback in the link class copies a link within the HDF5 container. It returns an herr_t indicating success or failure.
Signature: |
---|
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);
|
Arguments: |
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.
|
The move callback in the link class moves a link within the HDF5 container. It returns an herr_t indicating success or failure.
Signature: |
---|
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);
|
Arguments: |
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.
|
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: |
---|
herr_t (*get)(void *obj, H5VL_loc_params_t *loc_params, H5VL_link_get_args_t *args, hid_t dxpl_id, void **req);
|
Arguments: |
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.
|
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: |
---|
herr_t (*specific)(void *obj, H5VL_loc_params_t *loc_params, H5VL_link_specific_args_t *args, hid_t dxpl_id, void **req)
|
Arguments: |
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.
|
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: |
---|
herr_t (*optional)(void *obj, const H5VL_loc_params_t *loc_params, H5VL_optional_args_t *args, hid_t dxpl_id, void **req);
|
Arguments: |
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.
|
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.
The object API routines (Objects (H5O)) allow HDF5 users to manage HDF5 group, dataset, and named datatype objects. All the Objects (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
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: |
---|
void *(*open)(void *obj, H5VL_loc_params_t *loc_params, H5I_type_t *opened_type, hid_t dxpl_id, void **req);
|
Arguments: |
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.
|
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: |
---|
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)
|
Arguments: |
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.
|
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: |
---|
herr_t (*get)(void *obj, H5VL_loc_params_t *loc_params, H5VL_object_get_args_t *args, hid_t dxpl_id, void **req)
|
Arguments: |
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.
|
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: |
---|
herr_t (*specific)(void *obj, H5VL_loc_params_t *loc_params, H5VL_object_specific_args_t *args, hid_t dxpl_id, void **req);
|
Arguments: |
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.
|
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: |
---|
herr_t (*optional)(void *obj, const H5VL_loc_params_t *loc_params, H5VL_optional_args_t *args, hid_t dxpl_id, void **req);
|
Arguments: |
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.
|
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.
Structure for VOL connector introspection callback routines, H5VLconnector.h
Get a connector's H5VL_class_t struct.
Signature: |
---|
Arguments: |
obj (IN): The VOL object.
lvl (IN): Current or terminal connector.
cls (OUT): A const pointer to the connector.
|
The "lvl" argument is an enum:
Get a connector's capability flags.
Signature: |
---|
Arguments: |
info (IN): A const pointer to pertinent VOL info.
cap_flags (OUT): A pointer to capability flags.
|
Query a class for a capability or functionality.
Signature: |
---|
Arguments: |
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.
|
The "cls" argument is an enum:
Structure for async request callback routines, H5VLconnector.h
Wait (with a timeout) for an async operation to complete. Releases the request if the operation has completed and the connector callback succeeds.
Signature: |
---|
Arguments: |
req (IN): The async request on which to wait.
timeout (IN): The timeout value.
status (IN): The status.
|
The "status" argument is an enum:
Registers a user callback to be invoked when an asynchronous operation completes. Releases the request if connector callback succeeds.
Signature: |
---|
Arguments: |
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.
|
The "cb" argument is an enum:
Signature: |
---|
Arguments: |
req (IN): The async request to be cancelled.
status (IN): The status.
|
The "status" argument is an enum:
Perform a specific operation on an asynchronous request.
Signature: |
---|
Arguments: |
req (IN): The async request on which to perform the operation.
args (IN/OUT): A pointer to the arguments struct.
|
Perform a connector-specific operation for a request.
Signature: |
---|
Arguments: |
req (IN): The async request on which to perform the operation.
args (IN/OUT): A pointer to the arguments struct.
|
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.
Frees an asynchronous request.
Signature: |
---|
herr_t (*free)(void *req);
|
Arguments: |
req (IN): The async request to be freed.
|
Structure for blob callback routines, H5VLconnector.h
Put a blob through the VOL.
Signature: |
---|
Arguments: |
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.
|
Get a blob through the VOL.
Signature: |
---|
Arguments: |
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.
|
Perform a defined operation on a blob via the VOL.
Signature: |
---|
Arguments: |
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.
|
Perform a connector-specific operation on a blob via the VOL
Signature: |
---|
Arguments: |
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.
|
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
Structure for token callback routines, H5VLconnector.h
Compares two tokens and outputs a value like strcmp.
Signature: |
---|
Arguments: |
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.
|
Converts a token to a string representation.
Signature: |
---|
Arguments: |
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.
|
The "obj_type" argument is an enum: (from H5Ipublic.h)
The only values which should be used for this call are:
as these are the only objects for which tokens are valid.
Converts a string representation of a token to a token.
Signature: |
---|
Arguments: |
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.
|
The "obj_type" argument is an enum: (from H5Ipublic.h)
The only values which should be used for this call are:
as these are the only objects for which tokens are valid.
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: |
---|
Arguments: |
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.
|
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.
The API calls in this header are for VOL management and general use (i.e., not limited to VOL connector authors).
Signature: |
---|
hid_t H5VLregister_connector_by_name(const char *connector_name, hid_t vipl_id) Registers a new VOL connector by name. |
Arguments: |
connector_name (IN): The connector name to search for and register.
vipl_id (IN): An ID for a VOL initialization property list (vipl).
|
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 The HDF5 Virtual Object Layer (VOL) for more information on loading plugins and the search paths.
Signature: |
---|
hid_t H5VLregister_connector_by_value(H5VL_class_value_t connector_value, hid_t vipl_id) Registers a new VOL connector by value. |
Arguments: |
connector_value (IN): The connector value to search for and register.
vipl_id (IN): An ID for a VOL initialization property list (vipl).
|
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.
Signature: |
---|
htri_t H5VLis_connector_registered_by_name(const char *name) Tests whether a VOL class has been registered under a certain name. |
Arguments: |
name (IN): The connector name to check for.
|
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.
Signature: |
---|
htri_t H5VLis_connector_registered_by_value(H5VL_class_value_t connector_value) Tests whether a VOL class has been registered for a given value. |
Arguments: |
connector_value (IN): The connector value to check for.
|
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.
Signature: |
---|
hid_t H5VLget_connector_id(hid_t obj_id) Retrieves the VOL connector identifier for a given object identifier. |
Arguments: |
obj_id (IN): An ID for an HDF5 VOL object.
|
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.
Signature: |
---|
hid_t H5VLget_connector_id_by_name(const char *name) Retrieves the identifier for a registered VOL connector name. |
Arguments: |
name (IN): The connector name to check for.
|
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.
Signature: |
---|
hid_t H5VLget_connector_id_by_value(H5VL_class_value_t connector_value) Retrieves the identifier for a registered VOL connector value. |
Arguments: |
connector_value (IN): The connector value to check for.
|
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.
Signature: |
---|
ssize_t H5VLget_connector_name(hid_t id, char *name, size_t size) Retrieves a connector name for a VOL. |
Arguments: |
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.
|
Retrieves the name of a VOL connector given an object identifier that was created/opened ith it. On success, the name length is returned.
Signature: |
---|
Arguments: |
connector_id (IN): A valid identifier of the connector to close.
|
Shuts down access to the connector that the identifier points to and release resources associated with it.
Signature: |
---|
herr_t H5VLunregister_connector(hid_t connector_id) Removes a VOL connector identifier from the library. |
Arguments: |
connector_id (IN): A valid identifier of the connector to unregister.
|
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).
Signature: |
---|
herr_t H5VLquery_optional(hid_t obj_id, H5VL_subclass_t subcls, int opt_type, uint64_t *flags) Determine if a VOL connector supports a particular optional callback operation. |
Arguments: |
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.
|
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:
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.
Signature: |
---|
hid_t H5VLregister_connector(const H5VL_class_t *cls, hid_t vipl_id) Registers a new VOL connector. |
Arguments: |
cls (IN): A pointer to the connector structure to register.
vipl_id (IN): An ID for a VOL initialization property list (vipl).
|
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.
Signature: |
---|
void * H5VLobject(hid_t obj_id) |
Arguments: |
obj_id (IN): identifier of the object to dereference.
|
Retrieves a pointer to the VOL object from an HDF5 file or object identifier.
Signature: |
---|
hid_t H5VLget_file_type(void *file_obj, hid_t connector_id, hid_t dtype_id) |
Arguments: |
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.
|
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.
Signature: |
---|
hid_t H5VLpeek_connector_id_by_name(const char *name) |
Arguments: |
name (IN): name of the connector to query.
|
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.
Signature: |
---|
hid_t H5VLpeek_connector_id_by_value(H5VL_class_value_t value) |
Arguments: |
value (IN): value of the connector to query.
|
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.
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.
Signature: |
---|
herr_t H5VLcmp_connector_cls(int *cmp, hid_t connector_id1, hid_t connector_id2) |
Arguments: |
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
|
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.
Signature: |
---|
hid_t H5VLwrap_register(void *obj, H5I_type_t type) Wrap an internal object with a "wrap context" and register an hid_t for the resulting object. |
Arguments: |
obj (IN): an object to wrap.
type (IN): the type of the object (see below).
|
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:
Signature: |
---|
herr_t H5VLretrieve_lib_state(void **state) |
Arguments: |
state (OUT): the library state.
|
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.
Signature: |
---|
herr_t H5VLstart_lib_state(void) |
Opens a new internal state for the HDF5 library. Returns a positive value on success and a negative value on errors.
Signature: |
---|
herr_t H5VLrestore_lib_state(const void *state) |
Arguments: |
state (IN): the library state.
|
Restores the internal state of the HDF5 library. Returns a positive value on success and a negative value on errors.
Signature: |
---|
herr_t H5VLfinish_lib_state(void) |
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.
Signature: |
---|
herr_t H5VLfree_lib_state(void *state) |
Arguments: |
state (IN): the library state.
|
Free a retrieved library state. Returns a positive value on success and a negative value on errors.
Navigate back: Main / HDF5 Virtual Object Layer (VOL) Connector Author Guide