It would also be useful to give users the ability to create and set properties which are temporary in nature and do not need to be stored longer than the application is active. These would allow users to set application specific properties which can be set and queried during the application's execution.
The existing property list classes would be modified so that the existing properties are generic properties which are registered when the library starts up. The existing property list API functions would become wrappers around the new "generic" get/set functions. This would allow the library to become more modular, with each driver or API registering it's own properties without hard- wiring new fields in the property list class.
The library will provide a default or "empty" property list class with no property values defined for property lists of that class. A mechanism for deriving a new property list class will be defined by inheriting from an existing property list class. The existing property list classes defined by the library (file access, dataset creation, etc) will be created during library initialization and will have global constants available for applications to use. (This is similar to the way the library-defined datatypes are created at run-time)
Users may derive new property list classes from any existing property list class, including the completely new classes derived from the default "empty" property list class, or other user-derived property list classes. User-derived property list classes which are derived from the library-defined classes may be passed to API functions which expect library-defined property lists and the API functions will traverse the inherited classes to find the correct class to retrieve information.
The new generic property list API functions allow properties to be registered for each property list class (library or user defined) to create a set of initial properties for newly created property lists of that class. These registered properties can have default values for each new property list created for that class.
Temporary generic properties can also be attached to any existing property list without affecting new property lists of that class.
Property names beginning with "H5" are reserved for library use and should not be used by third-party applications or libraries.
The names and sizes of property values for each property are local to each property list and changing them in a property list class do not affect existing property lists.
H5Pcreate_class | - | Create a new property list class. |
H5Pcreate_list | - | Create a new property list of a given class. |
H5Pregister | - | Register a permanent property with a class. |
H5Pinsert | - | Create a temporary property for a property list. |
H5Pset | - | Set an existing property (permanent or temporary) to a value. |
H5Pexist | - | Query whether a property exists in a property list or class. |
H5Pget_size | - | Query size of property value in bytes. |
H5Pget_nprops | - | Query number of properties in list or class |
H5Pget_class_name | - | Retrieve the name of a class object |
H5Pget_class_parent | - | Retrieve a property class's parent class |
H5Pisa_class | - | Checks if a property list is a member of a property class |
H5Pget | - | Retrieve property value. |
H5Pequal | - | Compares two property lists or classes for equality |
H5Piterate | - | Iterates over properties in a property class or list |
H5Pcopy_prop | - | Copies a property from one list to another |
H5Premove | - | Removes a property from a property list. |
H5Punregister | - | Un-register a permanent property from a class. |
H5Pclose_list | - | Close a property list. |
H5Pclose_class | - | Remove a property list class. |
H5Pcreate and H5Pclose are replaced with H5Pcreate_list and H5Pclose_list.Changes to Existing Functions:
All the existing H5Pget/set routines would need to be changed to use the new generic register/unregister and get/set routines for the properties they manage, but that shouldn't be a user-visible change. Also, H5Pget_class will change from returning a H5P_class_t to the ID of a generic property class.
NAME
PURPOSE
USAGE
hid_t
H5Pcreate_class(class, name, create, copy, close)
hid_t class;
| IN: Property list class to inherit from. |
const char * name;
| IN: Name of property list class to register. |
H5P_cls_create_func_t create;
| IN: Callback routine called when a property list is created. |
H5P_cls_copy_func_t copy;
| IN: Callback routine called when a property list is copied. |
H5P_cls_close_func_t close;
| IN: Callback routine called when a property list is being closed. |
RETURNS
DESCRIPTION
The create routine is called when a new property list of this
class is being created. The H5P_cls_create_func_t
is defined as:
typedef herr_t
(*H5P_cls_create_func_t)(
hid_t
prop_id,
void *
create_data
);
hid_t prop_id;
| IN: The ID of the property list being created. |
void * create_data;
| IN/OUT: User pointer to any class creation information needed |
The copy routine is called when an existing property list of this
class is copied. The H5P_cls_copy_func_t
is defined as:
typedef herr_t
(*H5P_cls_copy_func_t)(
hid_t
prop_id,
void *
copy_data
);
hid_t prop_id;
| IN: The ID of the property list created by copying. |
void * copy_data;
| IN/OUT: User pointer to any class copy information needed |
The close routine is called when a property list of this class is being closed. The H5P_cls_close_func_t is defined as:
typedef herr_t
(*H5P_cls_close_func_t)(
hid_t
prop_id,
void *
close_data
);
hid_t prop_id;
| IN: The ID of the property list being closed. |
void * close_data;
| IN/OUT: User pointer to any class close information needed |
COMMENTS, BUGS, ASSUMPTIONS
NAME
PURPOSE
USAGE
hid_t
H5Pcreate_list(class)
hid_t class;
| IN: Class of property list to create. |
RETURNS
DESCRIPTION
COMMENTS, BUGS, ASSUMPTIONS
NAME
PURPOSE
USAGE
herr_t
H5Pregister(class, name, size, default, create, set, get, close)
hid_t class;
| IN: Property list class to register permanent property within. |
const char * name;
| IN: Name of property to register. |
size_t size;
| IN: Size of property in bytes. |
void * default;
| IN: Default value for property in newly created property lists. |
H5P_prp_create_func_t create;
| IN: Callback routine called when a property list is being created and the property value will be initialized. |
H5P_prp_set_func_t set;
| IN: Callback routine called before a new value is copied into the property's value. |
H5P_prp_get_func_t get;
| IN: Callback routine called when a property value is retrieved from the property. |
H5P_prp_delete_func_t delete;
| IN: Callback routine called when a property is deleted from a property list. |
H5P_prp_copy_func_t copy;
| IN: Callback routine called when a property is copied from in a property list. |
H5P_prp_close_func_t close;
| IN: Callback routine called when a property list is being closed and the property value will be disposed of. |
RETURNS
DESCRIPTION
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' & '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. H5P_prp_create_func_t
is defined as:
typedef herr_t
(*H5P_prp_create_func_t)(
const char *
name,
size_t
size,
void *
initial_value);
const char * name;
| IN: The name of the property being modified. |
size_t size;
| IN: The size of the property in bytes. |
void * initial_value;
| IN/OUT: The default value for the property being created. (The default value passed to H5Pregister) |
The set routine is called before a new value is copied into the
property. H5P_prp_set_func_t
is defined as:
typedef herr_t
(*H5P_prp_set_func_t)(
hid_t
prop_id,
const char *
name,
size_t
size,
void *
new_value);
hid_t prop_id;
| IN: The ID 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 ** new_value;
| IN/OUT: Pointer to new value pointer for the property being modified. |
The get routine is called when a value is retrieved from a property
value. H5P_prp_get_func_t
is defined as:
typedef herr_t
(*H5P_prp_get_func_t)(
hid_t
prop_id,
const char *
name,
size_t
size,
void *
value);
hid_t prop_id;
| IN: The ID 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 delete routine is called when a property is being deleted
from a property list. H5P_prp_delete_func_t
is defined as:
typedef herr_t
(*H5P_prp_delete_func_t)(
hid_t
prop_id,
const char *
name,
size_t
size,
void *
value);
hid_t prop_id;
| IN: The ID 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 copy routine is called when a new property list with this
property is being created through a copy operation. H5P_prp_copy_func_t
is defined as:
typedef herr_t
(*H5P_prp_copy_func_t)(
const char *
name,
size_t
size,
void *
value);
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 close routine is called when a property list with this
property is being closed. H5P_prp_close_func_t
is defined as:
typedef herr_t
(*H5P_prp_close_func_t)(
hid_t
prop_id,
const char *
name,
size_t
size,
void *
value);
hid_t prop_id;
| IN: The ID of the property list being closed. |
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. |
COMMENTS, BUGS, ASSUMPTIONS
I would like to say "the property list is not closed" when a close routine fails, but I don't think that's possible due to other properties in the list being successfully closed & removed from the property list. I suppose that it would be possible to just remove the properties which have successful close callbacks, but I'm not happy with the ramifications of a mangled, un-closable property list hanging around... Any comments?
NAME
PURPOSE
USAGE
herr_t
H5Pinsert(plid, name, size, value, set, get, close)
hid_t plid;
| IN: Property list id to create temporary property within. |
const char * name;
| IN: Name of property to create. |
size_t size;
| IN: Size of property in bytes. |
void * value;
| IN: Initial value for the property. |
H5P_prp_set_func_t set;
| IN: Callback routine called before a new value is copied into the property's value. |
H5P_prp_get_func_t get;
| IN: Callback routine called when a property value is retrieved from the property. |
H5P_prp_delete_func_t delete;
| IN: Callback routine called when a property is deleted from a property list. |
H5P_prp_copy_func_t copy;
| IN: Callback routine called when a property is copied from an existing property list. |
H5P_prp_close_func_t close;
| IN: Callback routine called when a property list is being closed and the property value will be disposed of. |
RETURNS
DESCRIPTION
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
is defined as:
typedef herr_t
(*H5P_prp_set_func_t)(
hid_t
prop_id,
const char *
name,
size_t
size,
void *
new_value);
hid_t prop_id;
| IN: The ID 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 ** new_value;
| IN: Pointer to new value pointer for the property being modified. |
The get routine is called when a value is retrieved from a property
value. The H5P_prp_get_func_t
is defined as:
typedef herr_t
(*H5P_prp_get_func_t)(
hid_t
prop_id,
const char *
name,
size_t
size,
void *
value);
hid_t prop_id;
| IN: The ID 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 delete routine is called when a property is being deleted
from a property list. H5P_prp_delete_func_t
is defined as:
typedef herr_t
(*H5P_prp_delete_func_t)(
hid_t
prop_id,
const char *
name,
size_t
size,
void *
value);
hid_t prop_id;
| IN: The ID 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 copy routine is called when a new property list with this
property is being created through a copy operation. H5P_prp_copy_func_t
is defined as:
typedef herr_t
(*H5P_prp_copy_func_t)(
const char *
name,
size_t
size,
void *
value);
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 close routine is called when a property list with this
property is being closed. The H5P_prp_close_func_t
is defined as:
typedef herr_t
(*H5P_prp_close_func_t)(
hid_t
prop_id,
const char *
name,
size_t
size,
void *
value);
hid_t prop_id;
| IN: The ID of the property list being closed. |
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. |
COMMENTS, BUGS, ASSUMPTIONS
The set callback function may be useful to range check the value being set for the property or may perform some tranformation/translation of the value set. The get callback would then [probably] reverse the transformation, etc. 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.
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.
I would like to say "the property list is not closed" when a close routine fails, but I don't think that's possible due to other properties in the list being successfully closed & removed from the property list. I suppose that it would be possible to just remove the properties which have successful close callbacks, but I'm not happy with the ramifications of a mangled, un-closable property list hanging around... Any comments?
NAME
PURPOSE
USAGE
herr_t
H5Pset(plid, name, value)
hid_t plid;
| IN: Property list id to modify |
const char * name;
| IN: Name of property to modify. |
void * value;
| IN: Pointer to value to set the property to. |
RETURNS
DESCRIPTION
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.
COMMENTS, BUGS, ASSUMPTIONS
NAME
PURPOSE
USAGE
htri_t
H5Pexist(id, name)
hid_t id;
| IN: Property ID to query |
const char * name;
| IN: Name of property to check for. |
RETURNS
DESCRIPTION
COMMENTS, BUGS, ASSUMPTIONS
NAME
PURPOSE
USAGE
int
H5Pget_size(id, name, size)
hid_t id;
| IN: ID of property object to query |
const char * name;
| IN: Name of property to query |
size_t * size;
| OUT: Size of property in bytes |
RETURNS
DESCRIPTION
COMMENTS, BUGS, ASSUMPTIONS
NAME
PURPOSE
USAGE
int
H5Pget_nprops(id, nprops)
hid_t id;
| IN: ID of property object to query |
size_t * nprops;
| OUT: Number of properties in object |
RETURNS
DESCRIPTION
nprops
. If a property list ID is
given, the current number of properties in the list is returned in
nprops
.
COMMENTS, BUGS, ASSUMPTIONS
NAME
PURPOSE
USAGE
char *
H5Pget_class_name(pcid)
hid_t pcid;
| IN: Property class id to query |
RETURNS
DESCRIPTION
COMMENTS, BUGS, ASSUMPTIONS
NAME
PURPOSE
USAGE
hid_t
H5Pget_class_parent(pcid)
hid_t pcid;
| IN: Property class ID to query |
RETURNS
DESCRIPTION
COMMENTS, BUGS, ASSUMPTIONS
NAME
PURPOSE
USAGE
htri_t
H5Pisa_class(plist, pclass)
hid_t plist;
| IN: ID of property list to compare |
hid_t pclass;
| IN: ID of property class to compare against |
RETURNS
DESCRIPTION
COMMENTS, BUGS, ASSUMPTIONS
NAME
PURPOSE
USAGE
herr_t
H5Pget(plid, name, value)
hid_t plid;
| IN: Property list id to query |
const char * name;
| IN: Name of property to query |
void * value;
| OUT: Pointer to location to copy value of property retrieved into. |
RETURNS
DESCRIPTION
COMMENTS, BUGS, ASSUMPTIONS
NAME
PURPOSE
USAGE
htri_t
H5Pequal(id1, id2)
hid_t id1;
| IN: First property object to compare |
hid_t id2;
| IN: Second property object to compare |
RETURNS
DESCRIPTION
id1
and id2
must
be either property lists or classes, comparing a list to a class is an
error.
COMMENTS, BUGS, ASSUMPTIONS
NAME
PURPOSE
USAGE
int
H5Piterate(idass_id, idx, iter_func, iter_data)
hid_t id;
| IN: ID of property object to iterate over |
int * idx;
| IN/OUT: Index of the property to begin with |
H5P_iterate_t iter_func;
| IN: Function pointer to function to be called with each property iterated over. |
void * iter_data;
| IN/OUT: Pointer to iteration data from user |
RETURNS
Success: | Returns the return value of the last call to
iter_func if it
was non-zero, or zero if all properties have been processed.
|
Failure: | negative value |
DESCRIPTION
This routine iterates over the properties in the property object specified
with ID. The properties in both property lists and classes may be iterated
over with this function. For each property in the object, the
iter_func
and
some additional information, specified below, are passed to the
iter_func
function. The iteration begins with the idx
property in the
object and the
next element to be processed by the operator is returned in idx
.
If idx
is
NULL, then 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 prototype for H5P_iterate_t is:
name
, and the pointer to the operator data passed in to
H5Piterate, iter_data
.
The return values from an operator are:
Zero: | Causes the iterator to continue, returning zero when all properties have been processed. |
Positive: | Causes the iterator to immediately return that positive value, indicating short-circuit success. The iterator can be restarted at the index of the next property. |
Negative: | Causes the iterator to immediately return that value, indicating failure. The iterator can be restarted at the index of the next property. |
H5Piterate assumes that the properties in the object identified by ID remains unchanged through the iteration. If the membership changes during the iteration, the function's behavior is undefined.
COMMENTS, BUGS, ASSUMPTIONS
NAME
PURPOSE
USAGE
herr_t
H5Pcopy_prop(dst_id, src_id, name)
hid_t dst_id;
| IN: ID of destination property list or class |
hid_t src_id;
| IN: ID of source property list or class |
const char * name;
| IN: Name of property to copy |
RETURNS
DESCRIPTION
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).
COMMENTS, BUGS, ASSUMPTIONS
NAME
PURPOSE
USAGE
herr_t
H5Premove(plid, name)
hid_t plid;
| IN: Property list id to modify |
const char * name;
| IN: Name of property to remove |
RETURNS
DESCRIPTION
COMMENTS, BUGS, ASSUMPTIONS
NAME
PURPOSE
USAGE
herr_t
H5Punregister(class, name)
H5P_class_t class;
| IN: Property list class to remove permanent property from. |
const char * name;
| IN: Name of property to remove |
RETURNS
DESCRIPTION
COMMENTS, BUGS, ASSUMPTIONS
NAME
PURPOSE
USAGE
herr_t
H5Pclose_list(plist)
hid_t plist;
| IN: Property list to close. |
RETURNS
DESCRIPTION
COMMENTS, BUGS, ASSUMPTIONS
NAME
PURPOSE
USAGE
herr_t
H5Pclose_class(class)
hid_t class;
| IN: Property list class to close. |
RETURNS
DESCRIPTION
COMMENTS, BUGS, ASSUMPTIONS
/* Property "set" callback */ herr_t driver_set_check(hid_t prop, const char *name, void *_value) { int *value=(int *)_value; /* Check that this routine is called for proper property name */ if(strcmp(name,"property1")) return(-1); /* Range check property value */ if(*value<0 || *value>SOME_LIMIT) return(-1); /* Name and value are OK */ return(0); } /* An API routine that sets the property for this driver */ herr_t H5Pset_driver_property1(hid_t prop, int value) { /* * Call the generic H5Pset routine and let the "set" callback do the * range checking, etc. */ return(H5Pset(prop, "property1", &value)); } /* An API routine that gets the property for this driver */ herr_t H5Pget_driver_property1(hid_t prop, int *value) { /* Call the generic H5Pget routine to retrieve the value */ return(H5Pget(prop, "property1", value)); } int setup_driver() { int prop1_default=12; /* Default value for "property1" */ [Set up other driver information] /* Register new property with Dataset Creation property list class */ /* Provide a "set" callback, but no "get" callback for this property */ H5Pregister(H5P_DATASET_CREATE, "property1", sizeof(int), &prop1_default, driver_set_check, NULL); } int shutdown_driver() { [Shut down other driver information] /* Unregister property from Dataset Creation property list class */ H5Punregister(H5P_DATASET_CREATE, "property1"); }