 |
HDF5
1.15.0.f39b228
API Reference
|
|
|
HDF5
1.15.0.f39b228
API Reference
|
|
You can create and customize user-defined property list classes using the functions described below. Arbitrary user-defined properties can also be inserted into existing property lists as so-called temporary properties.
| Function | Purpose |
|---|---|
| H5Pclose_class | Closes an existing property list class. |
| H5Pcopy_prop | Copies a property from one list or class to another. |
| H5Pcreate_class | Creates a new property list class. |
| H5Pequal | Compares two property lists or classes for equality. |
| H5Pexist | Queries whether a property name exists in a property list or class. |
| H5Pget_class_name | Retrieves the name of a class. |
| H5Pget_class_parent | Retrieves the parent class of a property class. |
| H5Pget_nprops | Queries the number of properties in a property list or class. |
| H5Pget_size | Queries the size of a property value in bytes. |
| H5Pinsert | Registers a temporary property with a property list. |
| H5Pisa_class | Determines whether a property list is a member of a class. |
| H5Piterate | Iterates over properties in a property class or list |
| H5Pregister/H5Punregister | Registers/removes a permanent property with/from a property list class |
| H5Premove | Removes a property from a property list. |
| H5Pset/H5Pget | Sets/queries a property list value |
Collaboration diagram for Property List Class Root (Advanced):Functions | |
| herr_t | H5Pclose_class (hid_t plist_id) |
| Closes an existing property list class. More... | |
| herr_t | H5Pcopy_prop (hid_t dst_id, hid_t src_id, const char *name) |
| Copies a property from one list or class to another. More... | |
| hid_t | H5Pcreate_class (hid_t parent, const char *name, H5P_cls_create_func_t create, void *create_data, H5P_cls_copy_func_t copy, void *copy_data, H5P_cls_close_func_t close, void *close_data) |
| Creates a new property list class. More... | |
| htri_t | H5Pequal (hid_t id1, hid_t id2) |
| Compares two property lists or classes for equality. More... | |
| htri_t | H5Pexist (hid_t plist_id, const char *name) |
| Queries whether a property name exists in a property list or class. More... | |
| herr_t | H5Pget (hid_t plist_id, const char *name, void *value) |
| Queries the value of a property. More... | |
| char * | H5Pget_class_name (hid_t pclass_id) |
| Retrieves the name of a class. More... | |
| hid_t | H5Pget_class_parent (hid_t pclass_id) |
| Retrieves the parent class of a property class. More... | |
| herr_t | H5Pget_nprops (hid_t id, size_t *nprops) |
| Queries the number of properties in a property list or class. More... | |
| herr_t | H5Pget_size (hid_t id, const char *name, size_t *size) |
| Queries the size of a property value in bytes. More... | |
| herr_t | H5Pinsert2 (hid_t plist_id, const char *name, size_t size, void *value, H5P_prp_set_func_t set, H5P_prp_get_func_t get, H5P_prp_delete_func_t prp_del, H5P_prp_copy_func_t copy, H5P_prp_compare_func_t compare, H5P_prp_close_func_t close) |
| Registers a temporary property with a property list. More... | |
| htri_t | H5Pisa_class (hid_t plist_id, hid_t pclass_id) |
| Determines whether a property list is a member of a class. More... | |
| int | H5Piterate (hid_t id, int *idx, H5P_iterate_t iter_func, void *iter_data) |
| Iterates over properties in a property class or list. More... | |
| herr_t | H5Pregister2 (hid_t cls_id, const char *name, size_t size, void *def_value, H5P_prp_create_func_t create, H5P_prp_set_func_t set, H5P_prp_get_func_t get, H5P_prp_delete_func_t prp_del, H5P_prp_copy_func_t copy, H5P_prp_compare_func_t compare, H5P_prp_close_func_t close) |
| Registers a permanent property with a property list class. More... | |
| herr_t | H5Premove (hid_t plist_id, const char *name) |
| Removes a property from a property list. More... | |
| herr_t | H5Pset (hid_t plist_id, const char *name, const void *value) |
| Sets a property list value. More... | |
| herr_t | H5Punregister (hid_t pclass_id, const char *name) |
| Removes a property from a property list class. More... | |
| herr_t | H5Pregister1 (hid_t cls_id, const char *name, size_t size, void *def_value, H5P_prp_create_func_t prp_create, H5P_prp_set_func_t prp_set, H5P_prp_get_func_t prp_get, H5P_prp_delete_func_t prp_del, H5P_prp_copy_func_t prp_copy, H5P_prp_close_func_t prp_close) |
| Registers a permanent property with a property list class. More... | |
| herr_t | H5Pinsert1 (hid_t plist_id, const char *name, size_t size, void *value, H5P_prp_set_func_t prp_set, H5P_prp_get_func_t prp_get, H5P_prp_delete_func_t prp_delete, H5P_prp_copy_func_t prp_copy, H5P_prp_close_func_t prp_close) |
| Registers a temporary property with a property list. More... | |
| herr_t | H5Pencode1 (hid_t plist_id, void *buf, size_t *nalloc) |
| Encodes the property values in a property list into a binary buffer. More... | |
Closes an existing property list class.
| [in] | plist_id | Property list class identifier |
H5Pclose_class() removes a property list class from the library. Existing property lists of this class will continue to exist, but new ones are not able to be created.
Copies a property from one list or class to another.
| [in] | dst_id | Identifier of the destination property list or class |
| [in] | src_id | Identifier of the source property list or class |
| [in] | name | Name of the property to copy |
H5Pcopy_prop() copies a property from one property list or class to another.
If a property is copied from one class to another, all the property information will be first deleted from the destination class and then the property information will be copied from the source class into the destination class.
If a property is copied from one list to another, the property will be first deleted from the destination list (generating a call to the close callback for the property, if one exists) and then the property is copied from the source list to the destination list (generating a call to the copy callback for the property, if one exists).
If the property does not exist in the class or list, this call is equivalent to calling H5Pregister() or H5Pinsert() (for a class or list, as appropriate) and the create callback will be called in the case of the property being copied into a list (if such a callback exists for the property).
| hid_t H5Pcreate_class | ( | hid_t | parent, |
| const char * | name, | ||
| H5P_cls_create_func_t | create, | ||
| void * | create_data, | ||
| H5P_cls_copy_func_t | copy, | ||
| void * | copy_data, | ||
| H5P_cls_close_func_t | close, | ||
| void * | close_data | ||
| ) |
Creates a new property list class.
| [in] | parent | Property list class identifier |
| [in] | name | Name of property list class to register |
| [in] | create | Callback routine called when a property list is created |
| [in] | create_data | Pointer to user-defined class create data, to be passed along to class create callback |
| [in] | copy | Callback routine called when a property list is copied |
| [in] | copy_data | Pointer to user-defined class copy data, to be passed along to class copy callback |
| [in] | close | Callback routine called when a property list is being closed |
| [in] | close_data | Pointer to user-defined class close data, to be passed along to class close callback |
H5Pcreate_class() registers a new property list class with the library. The new property list class can inherit from an existing property list class, parent, or may be derived from the default “empty” class, NULL. New classes with inherited properties from existing classes may not remove those existing properties, only add or remove their own class properties. Property list classes defined and supported in the HDF5 library distribution are listed and briefly described in H5Pcreate(). The create, copy, close functions are called when a property list of the new class is created, copied, or closed, respectively.
H5Pclose_class() must be used to release the property list class identifier returned by this function.
Encodes the property values in a property list into a binary buffer.
| [in] | plist_id | Property list identifier |
| [out] | buf | Buffer into which the property list will be encoded. If the provided buffer is NULL, the size of the buffer required is returned through nalloc; the function does nothing more. |
| [out] | nalloc | The size of the required buffer |
H5Pencode1() encodes the property list plist_id into the binary buffer buf.
If the required buffer size is unknown, buf can be passed in as NULL and the function will set the required buffer size in nalloc. The buffer can then be created and the property list encoded with a subsequent H5Pencode1() call.
If the buffer passed in is not big enough to hold the encoded properties, the H5Pencode1() call can be expected to fail with a segmentation fault.
Properties that do not have encode callbacks will be skipped. There is currently no mechanism to register an encode callback for a user-defined property, so user-defined properties cannot currently be encoded.
Some properties cannot be encoded, particularly properties that are reliant on local context.
Compares two property lists or classes for equality.
| [in] | id1 | First property object to be compared |
| [in] | id2 | Second property object to be compared |
H5Pequal() compares two property lists or classes to determine whether they are equal to one another.
Either both id1 and id2 must be property lists or both must be classes; comparing a list to a class is an error.
Queries whether a property name exists in a property list or class.
| [in] | plist_id | Identifier for the property list or class to query |
| [in] | name | Name of property to check for |
H5Pexist() determines whether a property exists within a property list or class.
Queries the value of a property.
| [in] | plist_id | Property list identifier |
| [in] | name | Name of property to query |
| [out] | value | Pointer to a location to which to copy the value of the property |
H5Pget() retrieves a copy of the value for a property in a property list. If there is a get callback routine registered for this property, the copy of the value of the property will first be passed to that routine and any changes to the copy of the value will be used when returning the property value from this routine.
This routine may be called for zero-sized properties with the value set to NULL. The get routine will be called with a NULL value if the callback exists.
The property name must exist or this routine will fail.
If the get callback routine returns an error, \ value will not be modified.
| char* H5Pget_class_name | ( | hid_t | pclass_id | ) |
Retrieves the name of a class.
| [in] | pclass_id | Property list class identifier |
H5Pget_class_name() retrieves the name of a generic property list class. The pointer to the name must be freed by the user with a call to H5free_memory() after each successful call.
| Class Name (class identifier) Returned | Property List Class | Expanded Name of the Property List Class | The Class Identifier Used with H5Pcreate | Comments |
|---|---|---|---|---|
| attribute create | acpl | Attribute Creation Property List | H5P_ATTRIBUTE_CREATE | |
| dataset access | dapl | Dataset Access Property List | H5P_DATASET_ACCESS | |
| dataset create | dcpl | Dataset Creation Property List | H5P_DATASET_CREATE | |
| data transfer | dxpl | Data Transfer Property List | H5P_DATASET_XFER | |
| datatype access | H5P_DATATYPE_ACCESS | This class can be created, but there are no properties in the class currently. | ||
| datatype create | H5P_DATATYPE_CREATE | This class can be created, but there are no properties in the class currently. | ||
| file access | fapl | File Access Property List | H5P_FILE_ACCESS | |
| file create | fcpl | File Creation Property List | H5P_FILE_CREATE | |
| file mount | fmpl | File Mount Property List | H5P_FILE_MOUNT | |
| group access | H5P_GROUP_ACCESS | This class can be created, but there are no properties in the class currently. | ||
| group create | gcpl | Group Creation Property List | H5P_GROUP_CREATE | |
| link access | lapl | Link Access Property List | H5P_LINK_ACCESS | |
| link create | lcpl | Link Creation Property List | H5P_LINK_CREATE | |
| object copy | ocpypl | Object Copy Property List | H5P_OBJECT_COPY | |
| object create | ocpl | Object Creation Property List | H5P_OBJECT_CREATE | |
| string create | strcpl | String Creation Property List | H5P_STRING_CREATE |
Retrieves the parent class of a property class.
| [in] | pclass_id | Property list class identifier |
H5Pget_class_parent() retrieves an identifier for the parent class of a property class.
Queries the number of properties in a property list or class.
| [in] | id | Identifier for property object to query |
| [out] | nprops | Number of properties in object |
H5Pget_nprops() retrieves the number of properties in a property list or property list class.
If id is a property list identifier, the current number of properties in the list is returned in nprops.
If id is a property list class identifier, the number of registered properties in the class is returned in nprops.
Queries the size of a property value in bytes.
| [in] | id | Identifier of property object to query |
| [in] | name | Name of property to query |
| [out] | size | Size of property in bytes |
H5Pget_size() retrieves the size of a property's value in bytes. This function operates on both property lists and property classes.
Zero-sized properties are allowed and return 0.
| herr_t H5Pinsert1 | ( | hid_t | plist_id, |
| const char * | name, | ||
| size_t | size, | ||
| void * | value, | ||
| H5P_prp_set_func_t | prp_set, | ||
| H5P_prp_get_func_t | prp_get, | ||
| H5P_prp_delete_func_t | prp_delete, | ||
| H5P_prp_copy_func_t | prp_copy, | ||
| H5P_prp_close_func_t | prp_close | ||
| ) |
Registers a temporary property with a property list.
| [in] | plist_id | Property list identifier |
| [in] | name | Name of property to create |
| [in] | size | Size of property in bytes |
| [in] | value | Initial value for the property |
| [in] | prp_set | Callback routine called before a new value is copied into the property's value |
| [in] | prp_get | Callback routine called when a property value is retrieved from the property |
| [in] | prp_delete | Callback routine called when a property is deleted from a property list |
| [in] | prp_copy | Callback routine called when a property is copied from an existing property list |
| [in] | prp_close | Callback routine called when a property list is being closed and the property value will be disposed of |
H5Pinsert1() creates a new property in a property list. The property will exist only in this property list and copies made from it.
The initial property value must be provided in value and the property value will be set accordingly.
The name of the property must not already exist in this list, or this routine will fail.
The prp_set and prp_get callback routines may be set to NULL if they are not needed.
Zero-sized properties are allowed and do not store any data in the property list. The default value of a zero-size property may be set to NULL. They may be used to indicate the presence or absence of a particular piece of information.
The prp_set routine is called before a new value is copied into the property. The H5P_prp_set_func_t callback function is defined as H5P_prp_cb2_t. The prp_set routine may modify the value pointer to be set and those changes will be used when setting the property's value. If the prp_set routine returns a negative value, the new property value is not copied into the property and the set routine returns an error value. The prp_set routine will be called for the initial value.
Note: The prp_set callback function may be useful to range check the value being set for the property or may perform some transformation or translation of the value set. The prp_get callback would then reverse the transformation or translation. A single prp_get or prp_set callback could handle multiple properties by performing different actions based on the property name or other properties in the property list.
The prp_get routine is called when a value is retrieved from a property value. The H5P_prp_get_func_t callback function is defined as H5P_prp_cb2_t.
The prp_get routine may modify the value to be returned from the query and those changes will be preserved. If the prp_get routine returns a negative value, the query routine returns an error value.
The prp_delete routine is called when a property is being deleted from a property list. The H5P_prp_delete_func_t callback function is defined as H5P_prp_cb2_t.
The prp_copy routine is called when a new property list with this property is being created through a prp_copy operation. The H5P_prp_copy_func_t callback function is defined as H5P_prp_cb1_t.
The prp_copy routine may modify the value to be set and those changes will be stored as the new value of the property. If the prp_copy routine returns a negative value, the new property value is not copied into the property and the prp_copy routine returns an error value.
The prp_close routine is called when a property list with this property is being closed. The H5P_prp_close_func_t callback function is defined as H5P_prp_cb1_t.
The prp_close routine may modify the value passed in, the value is not used by the library when the close routine returns. If the prp_close routine returns a negative value, the property list prp_close routine returns an error value but the property list is still closed.
Note: There is no prp_create callback routine for temporary property list objects; the initial value is assumed to have any necessary setup already performed on it.
The H5P_prp_cb1_t is as follows:
The H5P_prp_cb2_t is as follows:
| herr_t H5Pinsert2 | ( | hid_t | plist_id, |
| const char * | name, | ||
| size_t | size, | ||
| void * | value, | ||
| H5P_prp_set_func_t | set, | ||
| H5P_prp_get_func_t | get, | ||
| H5P_prp_delete_func_t | prp_del, | ||
| H5P_prp_copy_func_t | copy, | ||
| H5P_prp_compare_func_t | compare, | ||
| H5P_prp_close_func_t | close | ||
| ) |
Registers a temporary property with a property list.
| [in] | plist_id | Property list identifier |
| [in] | name | Name of property to create |
| [in] | size | Size of property in bytes |
| [in] | value | Initial value for the property |
| [in] | set | Callback routine called before a new value is copied into the property's value |
| [in] | get | Callback routine called when a property value is retrieved from the property |
| [in] | prp_del | Callback routine called when a property is deleted from a property list |
| [in] | copy | Callback routine called when a property is copied from an existing property list |
| [in] | compare | Callback routine called when a property is compared with another property list |
| [in] | close | Callback routine called when a property list is being closed and the property value will be disposed of |
H5Pinsert2() creates a new property in a property list. The property will exist only in this property list and copies made from it.
The initial property value must be provided in value and the property value will be set accordingly.
The name of the property must not already exist in this list, or this routine will fail.
The set and get callback routines may be set to NULL if they are not needed.
Zero-sized properties are allowed and do not store any data in the property list. The default value of a zero-size property may be set to NULL. They may be used to indicate the presence or absence of a particular piece of information.
The set routine is called before a new value is copied into the property. The H5P_prp_set_func_t callback function is defined as follows:
The parameters to the callback function are defined as follows:
hid_t prop_id | IN: The identifier of the property list being modified |
const char * name | IN: The name of the property being modified |
size_t size | IN: The size of the property in bytes |
void * value | IN: Pointer to new value pointer for the property being modified |
The set routine may modify the value pointer to be set and those changes will be used when setting the property's value. If the set routine returns a negative value, the new property value is not copied into the property and the set routine returns an error value. The set routine will be called for the initial value.
Note: The set callback function may be useful to range check the value being set for the property or may perform some transformation or translation of the value set. The get callback would then reverse the transformation or translation. A single get or set callback could handle multiple properties by performing different actions based on the property name or other properties in the property list.
The get routine is called when a value is retrieved from a property value. The H5P_prp_get_func_t callback function is defined as follows:
The parameters to the above callback function are:
hid_t prop_id | IN: The identifier of the property list being queried |
const char * name | IN: The name of the property being queried |
size_t size | IN: The size of the property in bytes |
void * value | IN: The value of the property being returned |
The get routine may modify the value to be returned from the query and those changes will be preserved. If the get routine returns a negative value, the query routine returns an error value.
The prp_del routine is called when a property is being deleted from a property list. The H5P_prp_delete_func_t callback function is defined as follows:
The parameters to the above callback function are:
hid_t prop_id | IN: The identifier of the property list the property is being deleted from |
const char * name | IN: The name of the property in the list |
size_t size | IN: The size of the property in bytes |
void * value | IN: The value for the property being deleted |
The prp_del routine may modify the value passed in, but the value is not used by the library when the prp_del routine returns. If the prp_del routine returns a negative value, the property list prp_del routine returns an error value but the property is still deleted.
The copy routine is called when a new property list with this property is being created through a copy operation.
The H5P_prp_copy_func_t callback function is defined as follows:
The parameters to the above callback function are:
const char * name | IN: The name of the property being copied |
size_t size | IN: The size of the property in bytes |
void * value | IN/OUT: The value for the property being copied |
The copy routine may modify the value to be set and those changes will be stored as the new value of the property. If the copy routine returns a negative value, the new property value is not copied into the property and the copy routine returns an error value.
The compare routine is called when a property list with this property is compared to another property list with the same property.
The H5P_prp_compare_func_t callback function is defined as follows:
The parameters to the callback function are defined as follows:
const void * value1 | IN: The value of the first property to compare |
const void * value2 | IN: The value of the second property to compare |
size_t size | IN: The size of the property in bytes |
The compare routine may not modify the values. The compare routine should return a positive value if value1 is greater than value2, a negative value if value2 is greater than value1 and zero if value1 and value2 are equal.
The close routine is called when a property list with this property is being closed.
The H5P_prp_close_func_t callback function is defined as follows:
The parameters to the callback function are defined as follows:
const char * name | IN: The name of the property in the list |
size_t size | IN: The size of the property in bytes |
void * value | IN: The value for the property being closed |
The close routine may modify the value passed in, the value is not used by the library when the close routine returns. If the close routine returns a negative value, the property list close routine returns an error value but the property list is still closed.
Note: There is no create callback routine for temporary property list objects; the initial value is assumed to have any necessary setup already performed on it.
Determines whether a property list is a member of a class.
| [in] | plist_id | Property list identifier |
| [in] | pclass_id | Property list class identifier |
H5Pisa_class() checks to determine whether the property list plist_id is a member of the property list class pclass_id.
| int H5Piterate | ( | hid_t | id, |
| int * | idx, | ||
| H5P_iterate_t | iter_func, | ||
| void * | iter_data | ||
| ) |
Iterates over properties in a property class or list.
| [in] | id | Identifier of property object to iterate over |
| [in,out] | idx | Index of the property to begin with |
| [in] | iter_func | Function pointer to function to be called with each property iterated over |
| [in,out] | iter_data | Pointer to iteration data from user |
iter_func if it was non-zero; zero if all properties have been processed. On Failure, a negative valueH5Piterate() iterates over the properties in the property object specified in id, which may be either a property list or a property class, performing a specified operation on each property in turn.
For each property in the object, iter_func and the additional information specified below are passed to the H5P_iterate_t operator function.
The iteration begins with the idx-th property in the object; the next element to be processed by the operator is returned in idx. If idx is NULL, the iterator starts at the first property; since no stopping point is returned in this case, the iterator cannot be restarted if one of the calls to its operator returns non-zero.
The operation iter_func receives the property list or class identifier for the object being iterated over, id, the name of the current property within the object, name, and the pointer to the operator data passed in to H5Piterate(), iter_data.
id remain unchanged through the iteration. If the membership changes during the iteration, the function's behavior is undefined.| herr_t H5Pregister1 | ( | hid_t | cls_id, |
| const char * | name, | ||
| size_t | size, | ||
| void * | def_value, | ||
| H5P_prp_create_func_t | prp_create, | ||
| H5P_prp_set_func_t | prp_set, | ||
| H5P_prp_get_func_t | prp_get, | ||
| H5P_prp_delete_func_t | prp_del, | ||
| H5P_prp_copy_func_t | prp_copy, | ||
| H5P_prp_close_func_t | prp_close | ||
| ) |
Registers a permanent property with a property list class.
| [in] | cls_id | Property list class identifier |
| [in] | name | Name of property to register |
| [in] | size | Size of property in bytes |
| [in] | def_value | Default value for property in newly created property lists |
| [in] | prp_create | Callback routine called when a property list is being created and the property value will be initialized |
| [in] | prp_set | Callback routine called before a new value is copied into the property's value |
| [in] | prp_get | Callback routine called when a property value is retrieved from the property |
| [in] | prp_del | Callback routine called when a property is deleted from a property list |
| [in] | prp_copy | Callback routine called when a property is copied from a property list |
| [in] | prp_close | Callback routine called when a property list is being closed and the property value will be disposed of |
H5Pregister1() registers a new property with a property list class. The property will exist in all property list objects of that class after this routine is finished. The name of the property must not already exist. The default property value must be provided and all new property lists created with this property will have the property value set to the default provided. Any of the callback routines may be set to NULL if they are not needed.
Zero-sized properties are allowed and do not store any data in the property list. These may be used as flags to indicate the presence or absence of a particular piece of information. The default pointer for a zero-sized property may be set to NULL. The property prp_create and prp_close callbacks are called for zero-sized properties, but the prp_set and prp_get callbacks are never called.
The prp_create routine is called when a new property list with this property is being created. The H5P_prp_create_func_t callback function is defined as H5P_prp_cb1_t.
The prp_create routine may modify the value to be set and those changes will be stored as the initial value of the property. If the prp_create routine returns a negative value, the new property value is not copied into the property and the prp_create routine returns an error value.
The prp_set routine is called before a new value is copied into the property. The H5P_prp_set_func_t callback function is defined as H5P_prp_cb2_t.
The prp_set routine may modify the value pointer to be set and those changes will be used when setting the property's value. If the prp_set routine returns a negative value, the new property value is not copied into the property and the prp_set routine returns an error value. The prp_set routine will not be called for the initial value; only the prp_create routine will be called.
Note: The prp_set callback function may be useful to range check the value being set for the property or may perform some transformation or translation of the value set. The prp_get callback would then reverse the transformation or translation. A single prp_get or prp_set callback could handle multiple properties by performing different actions based on the property name or other properties in the property list.
The prp_get routine is called when a value is retrieved from a property value. The H5P_prp_get_func_t callback function is defined as H5P_prp_cb2_t.
The prp_get routine may modify the value to be returned from the query and those changes will be returned to the calling routine. If the prp_set routine returns a negative value, the query routine returns an error value.
The prp_del routine is called when a property is being deleted from a property list. The H5P_prp_delete_func_t callback function is defined as H5P_prp_cb2_t.
The prp_del routine may modify the value passed in, but the value is not used by the library when the prp_del routine returns. If the prp_del routine returns a negative value, the property list deletion routine returns an error value but the property is still deleted.
The prp_copy routine is called when a new property list with this property is being created through a prp_copy operation. The H5P_prp_copy_func_t callback function is defined as H5P_prp_cb1_t.
The prp_copy routine may modify the value to be set and those changes will be stored as the new value of the property. If the prp_copy routine returns a negative value, the new property value is not copied into the property and the prp_copy routine returns an error value.
The prp_close routine is called when a property list with this property is being closed. The H5P_prp_close_func_t callback function is defined as H5P_prp_cb1_t.
The prp_close routine may modify the value passed in, but the value is not used by the library when the prp_close routine returns. If the prp_close routine returns a negative value, the property list close routine returns an error value but the property list is still closed.
The H5P_prp_cb1_t is as follows:
The H5P_prp_cb2_t is as follows:
| herr_t H5Pregister2 | ( | hid_t | cls_id, |
| const char * | name, | ||
| size_t | size, | ||
| void * | def_value, | ||
| H5P_prp_create_func_t | create, | ||
| H5P_prp_set_func_t | set, | ||
| H5P_prp_get_func_t | get, | ||
| H5P_prp_delete_func_t | prp_del, | ||
| H5P_prp_copy_func_t | copy, | ||
| H5P_prp_compare_func_t | compare, | ||
| H5P_prp_close_func_t | close | ||
| ) |
Registers a permanent property with a property list class.
| [in] | cls_id | Property list class identifier |
| [in] | name | Name of property to register |
| [in] | size | Size of property in bytes |
| [in] | def_value | Default value for property in newly created property lists |
| [in] | create | Callback routine called when a property list is being created and the property value will be initialized |
| [in] | set | Callback routine called before a new value is copied into the property's value |
| [in] | get | Callback routine called when a property value is retrieved from the property |
| [in] | prp_del | Callback routine called when a property is deleted from a property list |
| [in] | copy | Callback routine called when a property is copied from a property list |
| [in] | compare | Callback routine called when a property is compared with another property list |
| [in] | close | Callback routine called when a property list is being closed and the property value will be disposed of |
H5Pregister2() registers a new property with a property list class. The cls_id identifier can be obtained by calling H5Pcreate_class(). The property will exist in all property list objects of cl_id created after this routine finishes. The name of the property must not already exist, or this routine will fail. The default property value must be provided and all new property lists created with this property will have the property value set to the default value. Any of the callback routines may be set to NULL if they are not needed.
Zero-sized properties are allowed and do not store any data in the property list. These may be used as flags to indicate the presence or absence of a particular piece of information. The default pointer for a zero-sized property may be set to NULL. The property create and close callbacks are called for zero-sized properties, but the set and get callbacks are never called.
The create routine is called when a new property list with this property is being created. The H5P_prp_create_func_t callback function is defined as follows:
The parameters to this callback function are defined as follows:
const char * name | IN: The name of the property being modified |
size_t size | IN: The size of the property in bytes |
void * value | IN/OUT: The default value for the property being created, which will be passed to H5Pregister2() |
The create routine may modify the value to be set and those changes will be stored as the initial value of the property. If the create routine returns a negative value, the new property value is not copied into the property and the create routine returns an error value.
The set routine is called before a new value is copied into the property. The H5P_prp_set_func_t callback function is defined as follows:
The parameters to this callback function are defined as follows:
hid_t prop_id | IN: The identifier of the property list being modified |
const char * name | IN: The name of the property being modified |
size_t size | IN: The size of the property in bytes |
void *value | IN/OUT: Pointer to new value pointer for the property being modified |
The set routine may modify the value pointer to be set and those changes will be used when setting the property's value. If the set routine returns a negative value, the new property value is not copied into the property and the set routine returns an error value. The set routine will not be called for the initial value; only the create routine will be called.
Note: The set callback function may be useful to range check the value being set for the property or may perform some transformation or translation of the value set. The get callback would then reverse the transformation or translation. A single get or set callback could handle multiple properties by performing different actions based on the property name or other properties in the property list.
The get routine is called when a value is retrieved from a property value. The H5P_prp_get_func_t callback function is defined as follows:
The parameters to the callback function are defined as follows:
hid_t prop_id | IN: The identifier of the property list being queried |
const char * name | IN: The name of the property being queried |
size_t size | IN: The size of the property in bytes |
void * value | IN/OUT: The value of the property being returned |
The get routine may modify the value to be returned from the query and those changes will be returned to the calling routine. If the set routine returns a negative value, the query routine returns an error value.
The prp_del routine is called when a property is being deleted from a property list. The H5P_prp_delete_func_t callback function is defined as follows:
The parameters to the callback function are defined as follows:
hid_t prop_id | IN: The identifier of the property list the property is being deleted from |
const char * name | IN: The name of the property in the list |
size_t size | IN: The size of the property in bytes |
void * value | IN: The value for the property being deleted |
The prp_del routine may modify the value passed in, but the value is not used by the library when the prp_del routine returns. If the prp_del routine returns a negative value, the property list delete routine returns an error value but the property is still deleted.
The copy routine is called when a new property list with this property is being created through a copy operation. The H5P_prp_copy_func_t callback function is defined as follows:
The parameters to the callback function are defined as follows:
const char * name | IN: The name of the property being copied |
size_t size | IN: The size of the property in bytes |
void * value | IN/OUT: The value for the property being copied |
The copy routine may modify the value to be set and those changes will be stored as the new value of the property. If the copy routine returns a negative value, the new property value is not copied into the property and the copy routine returns an error value.
The compare routine is called when a property list with this property is compared to another property list with the same property. The H5P_prp_compare_func_t callback function is defined as follows:
The parameters to the callback function are defined as follows:
const void * value1 | IN: The value of the first property to compare |
const void * value2 | IN: The value of the second property to compare |
size_t size | IN: The size of the property in bytes |
The compare routine may not modify the values. The compare routine should return a positive value if value1 is greater than value2, a negative value if value2 is greater than value1 and zero if value1 and value2 are equal.
The close routine is called when a property list with this property is being closed. The H5P_prp_close_func_t callback function is defined as follows:
The parameters to the callback function are defined as follows:
const char * name | IN: The name of the property in the list |
size_t size | IN: The size of the property in bytes |
void * value | IN: The value for the property being closed |
The close routine may modify the value passed in, but the value is not used by the library when the close routine returns. If the close routine returns a negative value, the property list close routine returns an error value but the property list is still closed.
Removes a property from a property list.
| [in] | plist_id | Property list identifier |
| [in] | name | Name of property to remove |
H5Premove() removes a property from a property list. Both properties which were in existence when the property list was created (i.e. properties registered with H5Pregister()) and properties added to the list after it was created (i.e. added with H5Pinsert1() may be removed from a property list. Properties do not need to be removed from a property list before the list itself is closed; they will be released automatically when H5Pclose() is called.
If a close callback exists for the removed property, it will be called before the property is released.
Sets a property list value.
| [in] | plist_id | Property list identifier |
| [in] | name | Name of property to modify |
| [in] | value | Pointer to value to set the property to |
H5Pset() sets a new value for a property in a property list. If there is a set callback routine registered for this property, the value will be passed to that routine and any changes to the value will be used when setting the property value. The information pointed to by the value pointer (possibly modified by the set callback) is copied into the property list value and may be changed by the application making the H5Pset() call without affecting the property value.
The property name must exist or this routine will fail.
If the set callback routine returns an error, the property value will not be modified.
This routine may not be called for zero-sized properties and will return an error in that case.
Removes a property from a property list class.
| [in] | pclass_id | Property list class identifier |
| [in] | name | Name of property to remove |
H5Punregister() removes a property from a property list class. Future property lists created of that class will not contain this property; existing property lists containing this property are not affected.
1.9.1