summaryrefslogtreecommitdiffstats
path: root/src/H5Pdeprec.c
diff options
context:
space:
mode:
Diffstat (limited to 'src/H5Pdeprec.c')
-rw-r--r--src/H5Pdeprec.c168
1 files changed, 168 insertions, 0 deletions
diff --git a/src/H5Pdeprec.c b/src/H5Pdeprec.c
index 924e68f..e6ff099 100644
--- a/src/H5Pdeprec.c
+++ b/src/H5Pdeprec.c
@@ -272,5 +272,173 @@ done:
FUNC_LEAVE_API(ret_value);
} /* H5Pregister1() */
+
+/*--------------------------------------------------------------------------
+ NAME
+ H5Pinsert1
+ PURPOSE
+ Routine to insert a new property in a property list.
+ USAGE
+ herr_t H5Pinsert1(plist, name, size, value, prp_set, prp_get, prp_close)
+ hid_t plist; IN: Property list to add property to
+ const char *name; IN: Name of property to add
+ size_t size; IN: Size of property in bytes
+ void *value; IN: Pointer to the value for the property
+ H5P_prp_set_func_t prp_set; IN: Function pointer to property set callback
+ H5P_prp_get_func_t prp_get; IN: Function pointer to property get callback
+ H5P_prp_delete_func_t prp_delete; IN: Function pointer to property delete callback
+ H5P_prp_copy_func_t prp_copy; IN: Function pointer to property copy callback
+ H5P_prp_compare_func_t prp_cmp; IN: Function pointer to property compare callback
+ H5P_prp_close_func_t prp_close; IN: Function pointer to property close
+ callback
+ RETURNS
+ Returns non-negative on success, negative on failure.
+ DESCRIPTION
+ Inserts a temporary property into a property list. The property will
+ exist only in this property list object. The name of the property must not
+ already exist. The value must be provided unless the property is zero-
+ sized. 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 'value' pointer for a
+ zero-sized property may be set to NULL. The property 'close' callback is
+ called for zero-sized properties, but the 'set' and 'get' callbacks are
+ never called.
+
+ The 'set' callback 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 *value);
+ where the parameters to the callback function are:
+ 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 value
+ void *new_value; IN/OUT: The value being set for the property.
+ The 'set' routine may modify the value to be set and those changes will be
+ stored as the value of the property. If the 'set' routine returns a
+ negative value, the new property value is not copied into the property and
+ the property list set routine returns an error value.
+
+ The 'get' callback is called before a value is retrieved from the
+ property. 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);
+ where the parameters to the callback function are:
+ 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 value
+ void *value; IN/OUT: The value being retrieved for the property.
+ The 'get' routine may modify the value to be retrieved and those changes
+ will be returned to the calling function. If the 'get' routine returns a
+ negative value, the property value is returned and the property list get
+ routine returns an error value.
+
+ The 'delete' callback is called when a property is deleted from a
+ property list. H5P_prp_del_func_t is defined as:
+ typedef herr_t (*H5P_prp_del_func_t)(hid_t prop_id, const char *name,
+ size_t size, void *value);
+ where the parameters to the callback function are:
+ hid_t prop_id; IN: The ID of the property list the property is deleted from.
+ const char *name; IN: The name of the property being deleted.
+ size_t size; IN: The size of the property value
+ void *value; IN/OUT: The value of the property being deleted.
+ The 'delete' routine may modify the value passed in, but the value is not
+ used by the library when the 'delete' routine returns. If the
+ 'delete' routine returns a negative value, the property list deletion
+ routine returns an error value but the property is still deleted.
+
+ The 'copy' callback is called when a property list with this
+ property is copied. H5P_prp_copy_func_t is defined as:
+ typedef herr_t (*H5P_prp_copy_func_t)(const char *name, size_t size,
+ void *value);
+ where the parameters to the callback function are:
+ const char *name; IN: The name of the property being copied.
+ size_t size; IN: The size of the property value
+ void *value; IN: The value of the property being copied.
+ The 'copy' routine may modify the value to be copied and those changes will be
+ stored as the value of the property. If the 'copy' routine returns a
+ negative value, the new property value is not copied into the property and
+ the property list copy routine returns an error value.
+
+ The 'compare' callback is called when a property list with this
+ property is compared to another property list. H5P_prp_compare_func_t is
+ defined as:
+ typedef int (*H5P_prp_compare_func_t)( void *value1, void *value2,
+ size_t size);
+ where the parameters to the callback function are:
+ const void *value1; IN: The value of the first property being compared.
+ const void *value2; IN: The value of the second property being compared.
+ size_t size; IN: The size of the property value
+ The 'compare' routine may not modify the values to be compared. 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' callback is called when a property list with this
+ property is being destroyed. H5P_prp_close_func_t is defined as:
+ typedef herr_t (*H5P_prp_close_func_t)(const char *name, size_t size,
+ void *value);
+ where the parameters to the callback function are:
+ const char *name; IN: The name of the property being closed.
+ size_t size; IN: The size of the property value
+ void *value; IN: The value of 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.
+
+ GLOBAL VARIABLES
+ 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? -QAK
+
+ EXAMPLES
+ REVISION LOG
+--------------------------------------------------------------------------*/
+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)
+{
+ H5P_genplist_t *plist; /* Property list to modify */
+ herr_t ret_value; /* return value */
+
+ FUNC_ENTER_API(H5Pinsert1, FAIL);
+ H5TRACE9("e","iszxxxxxx",plist_id,name,size,value,prp_set,prp_get,
+ prp_delete,prp_copy,prp_close);
+
+ /* Check arguments. */
+ if(NULL == (plist = H5I_object_verify(plist_id, H5I_GENPROP_LST)))
+ HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a property list")
+ if(!name || !*name)
+ HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "invalid property name")
+ if(size > 0 && value == NULL)
+ HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "properties >0 size must have default")
+
+ /* Create the new property list class */
+ if((ret_value = H5P_insert(plist, name, size, value, prp_set, prp_get, prp_delete, prp_copy, NULL, prp_close)) < 0)
+ HGOTO_ERROR(H5E_PLIST, H5E_CANTREGISTER, FAIL, "unable to register property in plist")
+
+done:
+ FUNC_LEAVE_API(ret_value);
+} /* H5Pinsert1() */
#endif /* H5_NO_DEPRECATED_SYMBOLS */