Help us improve by taking our short survey: https://www.hdfgroup.org/website-survey/

| HDF5 Last Updated on 2026-03-23 The HDF5 Field Guide

Loading...
Searching...
No Matches
H5Zdevelop.h File Reference
`#include "H5Zpublic.h"`

## Data Structures
struct | H5Z_cb_t
struct | H5Z_class1_t
struct | H5Z_class2_t

## Macros
#define | H5Z_CLASS_T_VERS (1)

## Typedefs
typedef htri_t(* | H5Z_can_apply_func_t) (hid_t dcpl_id, hid_t type_id, hid_t space_id)
| This callback determines if a filter can be applied to the dataset with the characteristics provided.
typedef size_t(* | H5Z_func_t) (unsigned int flags, size_t cd_nelmts, const unsigned int cd_values[], size_t nbytes, size_t *buf_size, void **buf)
| The filter operation callback function, defining a filter's operation on data.
typedef herr_t(* | H5Z_set_local_func_t) (hid_t dcpl_id, hid_t type_id, hid_t space_id)
| The filter operation callback function, defining a filter's operation on data.

## Functions
herr_t | H5Zregister (const void *cls)
| Registers a new filter with the HDF5 library.
herr_t | H5Zunregister (H5Z_filter_t id)
| Unregisters a filter.

## Macro Definition Documentation

## ◆ H5Z_CLASS_T_VERS

#define H5Z_CLASS_T_VERS (1)

Current version of the H5Z_class_t struct

## Typedef Documentation

## ◆ H5Z_can_apply_func_t

typedef htri_t(* H5Z_can_apply_func_t) (hid_t dcpl_id, hid_t type_id, hid_t space_id)

This callback determines if a filter can be applied to the dataset with the characteristics provided.

Parameters

  [in] | dcpl_id | Dataset creation property list identifier
  [in] | type_id | Datatype identifier
  [in] | space_id | Dataspace identifier

Returns
  Returns zero (false), a positive (true) or a negative (failure) value.

Before a dataset gets created, the H5Z_can_apply_func_t callbacks for any filters used in the dataset creation property list are called with the dataset's dataset creation property list, the dataset's datatype and a dataspace describing a chunk (for chunked dataset storage).

The H5Z_can_apply_func_t callback must determine if the combination of the dataset creation property list setting, the datatype and the dataspace represent a valid combination to apply this filter to. For example, some cases of invalid combinations may involve the filter not operating correctly on certain datatypes (or certain datatype sizes), or certain sizes of the chunk dataspace.

The H5Z_can_apply_func_t callback can be the NULL pointer, in which case, the library will assume that it can apply to any combination of dataset creation property list values, datatypes and dataspaces.

The H5Z_can_apply_func_t callback returns positive a valid combination, zero for an invalid combination and negative for an error.

## ◆ H5Z_func_t

typedef size_t(* H5Z_func_t) (unsigned int flags, size_t cd_nelmts, const unsigned int cd_values[], size_t nbytes, size_t *buf_size, void **buf)

The filter operation callback function, defining a filter's operation on data.

Parameters

  [in] | flags | Bit vector specifying certain general properties of the filter
  [in] | cd_nelmts | Number of elements in `cd_values`
  [in] | cd_values | Auxiliary data for the filter
  [in] | nbytes | The number of valid bytes in `buf` to be filtered
  [in,out] | buf_size | The size of `buf`
  [in,out] | buf | The filter buffer

Returns
  Returns the number of valid bytes of data contained in `buf`. In the case of failure, the return value is 0 (zero) and all pointer arguments are left unchanged.

A filter gets definition flags and invocation flags (defined above), the client data array and size defined when the filter was added to the pipeline, the size in bytes of the data on which to operate, and pointers to a buffer and its allocated size.

The filter should store the result in the supplied buffer if possible, otherwise it can allocate a new buffer, freeing the original. The allocated size of the new buffer should be returned through the `buf_size` pointer and the new buffer through the `buf` pointer.

The return value from the filter is the number of bytes in the output buffer. If an error occurs then the function should return zero and leave all pointer arguments unchanged.

Since
  1.0.0

## ◆ H5Z_set_local_func_t

typedef herr_t(* H5Z_set_local_func_t) (hid_t dcpl_id, hid_t type_id, hid_t space_id)

The filter operation callback function, defining a filter's operation on data.

Parameters

  [in] | dcpl_id | Dataset creation property list identifier
  [in] | type_id | Datatype identifier
  [in] | space_id | Dataspace identifier

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

After the H5Z_can_apply_func_t callbacks are checked for new datasets, the H5Z_set_local_func_t callbacks for any filters used in the dataset creation property list are called. These callbacks receive the dataset's private copy of the dataset creation property list passed in to H5Dcreate() (i.e. not the actual property list passed in to H5Dcreate()) and the datatype ID passed in to H5Dcreate() (which is not copied and should not be modified) and a dataspace describing the chunk (for chunked dataset storage) (which should also not be modified).

The H5Z_set_local_func_t callback must set any parameters that are specific to this dataset, based on the combination of the dataset creation property list values, the datatype and the dataspace. For example, some filters perform different actions based on different datatypes (or datatype sizes) or different number of dimensions or dataspace sizes.

The H5Z_set_local_func_t callback can be the NULL pointer, in which case, the library will assume that there are no dataset-specific settings for this filter.

The H5Z_set_local_func_t callback must return non-negative on success and negative for an error.