Please, help us to better serve our user community by answering the following short survey: https://www.hdfgroup.org/website-survey/
HDF5 1.14.5
API Reference
Loading...
Searching...
No Matches
Modules | Functions
VOL connector (H5VL)

Detailed Description

Todo:
Describe the VOL plugin life cycle.

Modules

 Definitions
 
 Native VOL
 
 Pass-through VOL
 
 VOL Developer
 

Functions

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.
 
hid_t H5VLregister_connector_by_name (const char *connector_name, hid_t vipl_id)
 Registers a new VOL connector by name.
 
hid_t H5VLregister_connector_by_value (H5VL_class_value_t connector_value, hid_t vipl_id)
 Registers a new VOL connector by value.
 
htri_t H5VLis_connector_registered_by_name (const char *name)
 Tests whether a VOL class has been registered under a certain name.
 
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.
 
hid_t H5VLget_connector_id (hid_t obj_id)
 Retrieves the VOL connector identifier for a given object identifier.
 
hid_t H5VLget_connector_id_by_name (const char *name)
 Retrieves the identifier for a registered VOL connector name.
 
hid_t H5VLget_connector_id_by_value (H5VL_class_value_t connector_value)
 Retrieves the identifier for a registered VOL connector value.
 
ssize_t H5VLget_connector_name (hid_t id, char *name, size_t size)
 Retrieves a connector name for a VOL.
 
herr_t H5VLclose (hid_t connector_id)
 Closes a VOL connector identifier.
 
herr_t H5VLunregister_connector (hid_t connector_id)
 Removes a VOL connector identifier from the library.
 
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.
 
herr_t H5VLobject_is_native (hid_t obj_id, hbool_t *is_native)
 Determines whether an object ID represents a native VOL connector object.
 

Function Documentation

◆ H5VLclose()

herr_t H5VLclose ( hid_t  connector_id)

Closes a VOL connector identifier.

Parameters
[in]connector_idConnector identifier
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5VLclose() closes a VOL connector identifier. This does not affect the file access property lists which have been defined to use this VOL connector or files which are already opened under this connector.

Since
1.12.0

◆ H5VLget_connector_id()

hid_t H5VLget_connector_id ( hid_t  obj_id)

Retrieves the VOL connector identifier for a given object identifier.

Parameters
[in]obj_idObject identifier
Returns
Returns a VOL connector identifier if successful; otherwise returns H5I_INVALID_HID.

H5VLget_connector_id() retrieves the registered VOL connector identifier for the specified object identifier obj_id. The VOL connector identifier must be closed with H5VLclose() when no longer in use.

Since
1.12.0

◆ H5VLget_connector_id_by_name()

hid_t H5VLget_connector_id_by_name ( const char *  name)

Retrieves the identifier for a registered VOL connector name.

Parameters
[in]nameConnector name
Returns
Returns a VOL connector identifier if successful; otherwise returns H5I_INVALID_HID.

H5VLget_connector_id_by_name() retrieves the identifier for a registered VOL connector with the name name. The identifier must be closed with H5VLclose() when no longer in use.

Since
1.12.0

◆ H5VLget_connector_id_by_value()

hid_t H5VLget_connector_id_by_value ( H5VL_class_value_t  connector_value)

Retrieves the identifier for a registered VOL connector value.

Parameters
[in]connector_valueConnector value
Returns
Returns a VOL connector identifier if successful; otherwise returns H5I_INVALID_HID.

H5VLget_connector_id_by_value() retrieves the identifier for a registered VOL connector with the value connector_value. The identifier will need to be closed by H5VLclose().

connector_value has a type of H5VL_class_value_t, which is defined in H5VLpublic.h as follows:

typedef int H5VL_class_value_t;
H5VL_class_value_t
int H5VL_class_value_t
VOL connector identifiers.
Definition H5VLpublic.h:144

Valid VOL connector identifiers can have values from 0 through 255 for connectors defined by the HDF5 library. Values 256 through 511 are available for testing new connectors. Subsequent values should be obtained by contacting the The HDF Help Desk.

Since
1.12.0

◆ H5VLget_connector_name()

ssize_t H5VLget_connector_name ( hid_t  id,
char *  name,
size_t  size 
)

Retrieves a connector name for a VOL.

Parameters
[in]idObject identifier or file identifier
[out]nameConnector name
[in]sizeMaximum length of the name to retrieve
Returns
Returns the length of the connector name on success, and a negative value on failure.

H5VLget_connector_name() retrieves up to size elements of the VOL name name associated with the object or file identifier id.

Passing in a NULL pointer for size will return the size of the connector name. This can be used to determine the size of the buffer to allocate for the name.

Since
1.12.0

◆ H5VLis_connector_registered_by_name()

htri_t H5VLis_connector_registered_by_name ( const char *  name)

Tests whether a VOL class has been registered under a certain name.

Parameters
[in]nameAlleged name of connector
Returns
Returns zero (false), a positive (true) or a negative (failure) value.

H5VLis_connector_registered_by_name() tests whether a VOL class has been registered or not, according to the supplied connector name name.

Since
1.12.0

◆ H5VLis_connector_registered_by_value()

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.

Parameters
[in]connector_valueConnector value
Returns
Returns zero (false), a positive (true) or a negative (failure) value.

H5VLis_connector_registered_by_value() tests whether a VOL class has been registered, according to the supplied connector value connector_value.

connector_value has a type of H5VL_class_value_t, which is defined in H5VLpublic.h as follows:

typedef int H5VL_class_value_t;

Valid VOL connector identifiers can have values from 0 through 255 for connectors defined by the HDF5 library. Values 256 through 511 are available for testing new connectors. Subsequent values should be obtained by contacting the The HDF Help Desk.

Since
1.12.0

◆ H5VLobject_is_native()

herr_t H5VLobject_is_native ( hid_t  obj_id,
hbool_t *  is_native 
)

Determines whether an object ID represents a native VOL connector object.

Parameters
[in]obj_idObject identifier
[out]is_nativeBoolean determining whether object is a native VOL connector object
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.
Since
1.12.2

◆ H5VLquery_optional()

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.

Parameters
[in]obj_idObject identifier
[in]subclsVOL subclass
[in]opt_typeOption type
[out]flagsOperation flags
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.
Since
1.12.1

◆ H5VLregister_connector_by_name()

hid_t H5VLregister_connector_by_name ( const char *  connector_name,
hid_t  vipl_id 
)

Registers a new VOL connector by name.

Parameters
[in]connector_nameConnector name
[in]vipl_idVOL initialization property list identifier
Returns
Returns a VOL connector identifier if successful; otherwise returns H5I_INVALID_HID.

H5VLregister_connector_by_name() registers a new VOL connector with the name connector_name as a member of the virtual object layer class. This VOL connector identifier is good until the library is closed or the connector is unregistered.

vipl_id is either H5P_DEFAULT or the identifier of a VOL initialization property list of class H5P_VOL_INITIALIZE created with H5Pcreate(). When created, this property list contains no library properties. If a VOL connector author decides that initialization-specific data are needed, they can be added to the empty list and retrieved by the connector in the VOL connector's initialize callback. Use of the VOL initialization property list is uncommon, as most VOL-specific properties are added to the file access property list via the connector's API calls which set the VOL connector for the file open/create. For more information, see VOL documentation.

Since
1.12.0

◆ H5VLregister_connector_by_value()

hid_t H5VLregister_connector_by_value ( H5VL_class_value_t  connector_value,
hid_t  vipl_id 
)

Registers a new VOL connector by value.

Parameters
[in]connector_valueConnector value
[in]vipl_idVOL initialization property list identifier
Returns
Returns a VOL connector identifier if successful; otherwise returns H5I_INVALID_HID.

H5VLregister_connector_by_value() registers a new VOL connector with value connector_value as a member of the virtual object layer class. This VOL connector identifier is good until the library is closed or the connector is unregistered.

connector_value has a type of H5VL_class_value_t, which is defined in H5VLpublic.h as follows:

typedef int H5VL_class_value_t;

Valid VOL connector identifiers can have values from 0 through 255 for connectors defined by the HDF5 library. Values 256 through 511 are available for testing new connectors. Subsequent values should be obtained by contacting the The HDF Help Desk.

vipl_id is either H5P_DEFAULT or the identifier of a VOL initialization property list of class H5P_VOL_INITIALIZE created with H5Pcreate(). When created, this property list contains no library properties. If a VOL connector author decides that initialization-specific data are needed, they can be added to the empty list and retrieved by the connector in the VOL connector's initialize callback. Use of the VOL initialization property list is uncommon, as most VOL-specific properties are added to the file access property list via the connector's API calls which set the VOL connector for the file open/create. For more information, see the VOL documentation.

Since
1.12.0

◆ H5VLunregister_connector()

herr_t H5VLunregister_connector ( hid_t  connector_id)

Removes a VOL connector identifier from the library.

Parameters
[in]connector_idConnector identifier
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5VLunregister_connector() removes a VOL connector identifier from the library. This does not affect the file access property lists which have been defined to use the VOL connector or any files which are already opened with this connector.

Attention
H5VLunregister_connector() will fail if attempting to unregister the native VOL connector.
Since
1.12.0

◆ H5VLwrap_register()

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.

Parameters
[in]objVOL object.
[in]typeVOL-managed object class. Allowable values are:
Returns
Returns a VOL connector identifier if successful; otherwise returns H5I_INVALID_HID.
Note
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.