Detailed Description

Todo:: Describe the VOL plugin life cycle.

Collaboration diagram for VOL connector (H5VL):

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

hid_t	H5VLregister_connector_by_name (const char *connector_name, hid_t vipl_id)
	Registers a new VOL connector by name. More...

hid_t	H5VLregister_connector_by_value (H5VL_class_value_t connector_value, hid_t vipl_id)
	Registers a new VOL connector by value. More...

htri_t	H5VLis_connector_registered_by_name (const char *name)
	Tests whether a VOL class has been registered under a certain name. More...

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

hid_t	H5VLget_connector_id (hid_t obj_id)
	Retrieves the VOL connector identifier for a given object identifier. More...

hid_t	H5VLget_connector_id_by_name (const char *name)
	Retrieves the identifier for a registered VOL connector name. More...

hid_t	H5VLget_connector_id_by_value (H5VL_class_value_t connector_value)
	Retrieves the identifier for a registered VOL connector value. More...

ssize_t	H5VLget_connector_name (hid_t id, char *name, size_t size)
	Retrieves a connector name for a VOL. More...

herr_t	H5VLclose (hid_t connector_id)
	Closes a VOL connector identifier. More...

herr_t	H5VLunregister_connector (hid_t connector_id)
	Removes a VOL connector identifier from the library. More...

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

herr_t	H5VLobject_is_native (hid_t obj_id, hbool_t *is_native)
	Determines whether an object ID represents a native VOL connector object. More...

Function Documentation

◆ H5VLclose()

herr_t H5VLclose ( hid_t connector_id )

Closes a VOL connector identifier.

Parameters

[in] connector_id Connector 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_id Object 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] name Connector 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_value Connector 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]	id	Object identifier or file identifier
[out]	name	Connector name
[in]	size	Maximum 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] name Alleged 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_value Connector 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_id	Object identifier
[out]	is_native	Boolean 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_id	Object identifier
[in]	subcls	VOL subclass
[in]	opt_type	Option type
[out]	flags	Operation 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_name	Connector name
[in]	vipl_id	VOL 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_value	Connector value
[in]	vipl_id	VOL 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_id Connector 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]	obj	VOL object.
[in]	type	VOL-managed object class. Allowable values are: H5I_FILE H5I_GROUP H5I_DATATYPE H5I_DATASET H5I_MAP H5I_ATTR

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.

Detailed Description

Modules

Functions

Function Documentation

◆ H5VLclose()

◆ H5VLget_connector_id()

◆ H5VLget_connector_id_by_name()

◆ H5VLget_connector_id_by_value()

◆ H5VLget_connector_name()

◆ H5VLis_connector_registered_by_name()

◆ H5VLis_connector_registered_by_value()

◆ H5VLobject_is_native()

◆ H5VLquery_optional()

◆ H5VLregister_connector_by_name()

◆ H5VLregister_connector_by_value()

◆ H5VLunregister_connector()

◆ H5VLwrap_register()