H5Z_REGISTER

Procedure:

Signature:

Parameters:

const H5Z_class_t *filter_class

IN: A pointer to a buffer for the struct containing filter-definition information

Description:

H5Z_REGISTER registers a new filter with the HDF5 library.

Making a new filter available to an application is a two-step process. The first step is to write the three filter callback functions described below:can_apply,set_local, andfilter. This call to H5Z_REGISTER,registeringthe filter with the library, is the second step. Thecan_applyandset_localfields can be set toNULLif they are not required for the filter being registered.

H5Z_REGISTER accepts a single parameter, a pointer to a buffer for thefilter_classdata structure. That data structure must conform to one of the following definitions:

versionis a library-defined value reporting the version number of theH5Z_class_tstruct. This currently must be set to H5Z_CLASS_T_VERS.

idis the identifier for the new filter. This is a user-defined value betweenH5Z_FILTER_RESERVEDandH5Z_FILTER_MAX. These values are defined in the HDF5 source fileH5Zpublic.h, but the symbolsH5Z_FILTER_RESERVEDandH5Z_FILTER_MAXshould always be used instead of the literal values.

encoder_presentis a library-defined value indicating whether the filter’s encoding capability is available to the application.

decoder_presentis a library-defined value indicating whether the filter’s encoding capability is available to the application.

nameis a descriptive comment used for debugging, may contain a descriptive name for the filter, and may be the null pointer.

can_apply, described in detail below, is a user-defined callback function which determines whether the combination of the dataset creation property list values, the datatype, and the dataspace represent a valid combination to apply this filter to.

set_local, described in detail below, is a user-defined callback function which sets any parameters that are specific to this dataset, based on the combination of the dataset creation property list values, the datatype, and the dataspace.

filter, described in detail below, is a user-defined callback function which performs the action of the filter.

The statistics associated with a filter are not reset by this function; they accumulate over the life of the library.

H5Z_class_tis a macro which maps to eitherH5Z_class1_torH5Z_class2_t, depending on the needs of the application. To affect only this macro,H5Z_class_t_versmay be defined to either1or2. Otherwise, it will behave in the same manner as other API compatibility macros. See API Compatibility Macros in HDF5 for more information.H5Z_class1_tmatches theH5Z_class_tstructure that is used in the 1.6.x versions of the HDF5 library.

H5Z_REGISTER will automatically detect which structure type has been passed in, regardless of the mapping of theH5Z_class_tmacro. However, the application must make sure that the fields are filled in according to the correct structure definition if the macro is used to declare the structure.

The callback functionsBefore H5Z_REGISTERcan link a filter into an application, three callback functions must be defined as described in the HDF5 library header fileH5Zpublic.h.

When a filter is applied to the fractal heap for a group (e.g., when compressing group metadata) and if thecan applyandset localcallback functions have been defined for that filter, HDF5 passes the value-1for all parameters for those callback functions. This is done to ensure that the filter will not be applied to groups if it relies on these parameters, as they are not applicable to group fractal heaps; to operate on group fractal heaps, a filter must be capable of operating on an opaque block of binary data.

Before a dataset is created, thecan applycallbacks for any filters used in the dataset creation property list are called with the dataset's dataset creation property list,dcpl_id, the dataset's datatype,type_id, and a dataspace describing a chunk,space_id, (for chunked dataset storage).

This callback must determine whether the combination of the dataset creation property list settings, the datatype, and the dataspace represent a valid combination to which to apply this filter. For example, an invalid combination may involve the filter not operating correctly on certain datatypes, on certain datatype sizes, or on certain sizes of the chunk dataspace. If this filter is enabled throughH5P_SET_FILTERas optional and thecan applyfunction returnsFALSE, the library will skip the filter in the filter pipeline.

This callback can be theNULLpointer, in which case the library will assume that the filter can be applied to a dataset with any combination of dataset creation property list values, datatypes, and dataspaces.

Thecan applycallback function must return a positive value for a valid combination, zero for an invalid combination, and a negative value for an error.

After thecan applycallbacks are checked for a new dataset, theset localcallback functions for any filters used in the dataset creation property list are called. These callbacks receivedcpl_id, the dataset's private copy of the dataset creation property list passed in toH5Dcreate(i.e. not the actual property list passed in toH5Dcreate);type_id, the datatype identifier passed in toH5Dcreate, which is not copied and should not be modified; andspace_id, a dataspace describing the chunk (for chunked dataset storage), which should also not be modified.

Theset localcallback must set any filter 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, datatype sizes, numbers of dimensions, or dataspace sizes.

Theset localcallback may be theNULLpointer, in which case, the library will assume that there are no dataset-specific settings for this filter.

Theset localcallback function must return a non-negative value on success and a negative value for an error.

Thefilter operationcallback function, defining the filter's operation on the data, is defined as follows:

The parametersflags,cd_nelmts, andcd_valuesare the same as for the functionH5Pset_filter. The one exception is that an additional flag,H5Z_FLAG_REVERSE, is set when the filter is called as part of the input pipeline.

The parameter*bufpoints to the input buffer which has a size of*buf_sizebytes,nbytesof which are valid data.

The filter should perform the transformation in place if possible. If the transformation cannot be done in place, then the filter should allocate a new buffer withmalloc()and assign it to*buf, assigning the allocated size of that buffer to*buf_size. The old buffer should be freed by callingfree().

If successful, thefilter operationcallback function returns the number of valid bytes of data contained in*buf. In the case of failure, the return value is0(zero) and all pointer arguments are left unchanged.

Programming Note for C++ Developers Using C Functions:

If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally.

Examples of this kind of routine include callbacks such asH5Pset_elink_cbandH5Pset_type_conv_cband functions such asH5TconvertandH5Ewalk2.

Exiting the routine in its normal fashion allows the HDF5 C library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ “catch” statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.