summaryrefslogtreecommitdiffstats
path: root/src/H5Pdeprec.c
diff options
context:
space:
mode:
Diffstat (limited to 'src/H5Pdeprec.c')
-rw-r--r--src/H5Pdeprec.c276
1 files changed, 276 insertions, 0 deletions
diff --git a/src/H5Pdeprec.c b/src/H5Pdeprec.c
new file mode 100644
index 0000000..924e68f
--- /dev/null
+++ b/src/H5Pdeprec.c
@@ -0,0 +1,276 @@
+/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+ * Copyright by The HDF Group. *
+ * Copyright by the Board of Trustees of the University of Illinois. *
+ * All rights reserved. *
+ * *
+ * This file is part of HDF5. The full HDF5 copyright notice, including *
+ * terms governing use, modification, and redistribution, is contained in *
+ * the files COPYING and Copyright.html. COPYING can be found at the root *
+ * of the source code distribution tree; Copyright.html can be found at the *
+ * root level of an installed copy of the electronic HDF5 document set and *
+ * is linked from the top-level documents page. It can also be found at *
+ * http://hdfgroup.org/HDF5/doc/Copyright.html. If you do not have *
+ * access to either file, you may request a copy from help@hdfgroup.org. *
+ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
+
+/*-------------------------------------------------------------------------
+ *
+ * Created: H5Pdeprec.c
+ * October 11 2007
+ * Quincey Koziol <koziol@hdfgroup.org>
+ *
+ * Purpose: Deprecated functions from the H5P interface. These
+ * functions are here for compatibility purposes and may be
+ * removed in the future. Applications should switch to the
+ * newer APIs.
+ *
+ *-------------------------------------------------------------------------
+ */
+
+/****************/
+/* Module Setup */
+/****************/
+
+#define H5P_PACKAGE /*suppress error about including H5Ppkg */
+
+/* Interface initialization */
+#define H5_INTERFACE_INIT_FUNC H5P_init_deprec_interface
+
+
+/***********/
+/* Headers */
+/***********/
+#include "H5private.h" /* Generic Functions */
+#include "H5Eprivate.h" /* Error handling */
+#include "H5Iprivate.h" /* IDs */
+#include "H5Ppkg.h" /* Property lists */
+
+
+/****************/
+/* Local Macros */
+/****************/
+
+
+/******************/
+/* Local Typedefs */
+/******************/
+
+
+/********************/
+/* Package Typedefs */
+/********************/
+
+
+/********************/
+/* Local Prototypes */
+/********************/
+
+
+/*********************/
+/* Package Variables */
+/*********************/
+
+
+/*****************************/
+/* Library Private Variables */
+/*****************************/
+
+
+/*******************/
+/* Local Variables */
+/*******************/
+
+
+
+/*--------------------------------------------------------------------------
+NAME
+ H5P_init_deprec_interface -- Initialize interface-specific information
+USAGE
+ herr_t H5P_init_deprec_interface()
+RETURNS
+ Non-negative on success/Negative on failure
+DESCRIPTION
+ Initializes any interface-specific data or routines. (Just calls
+ H5P_init() currently).
+
+--------------------------------------------------------------------------*/
+static herr_t
+H5P_init_deprec_interface(void)
+{
+ FUNC_ENTER_NOAPI_NOINIT_NOFUNC(H5P_init_deprec_interface)
+
+ FUNC_LEAVE_NOAPI(H5P_init())
+} /* H5P_init_deprec_interface() */
+
+#ifndef H5_NO_DEPRECATED_SYMBOLS
+
+/*--------------------------------------------------------------------------
+ NAME
+ H5Pregister1
+ PURPOSE
+ Routine to register a new property in a property list class.
+ USAGE
+ herr_t H5Pregister1(class, name, size, default, prp_create, prp_set, prp_get, prp_close)
+ hid_t class; IN: Property list class to close
+ const char *name; IN: Name of property to register
+ size_t size; IN: Size of property in bytes
+ void *def_value; IN: Pointer to buffer containing default value
+ for property in newly created property lists
+ H5P_prp_create_func_t prp_create; IN: Function pointer to property
+ creation callback
+ 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_close_func_t prp_close; IN: Function pointer to property close
+ callback
+ RETURNS
+ Returns non-negative on success, negative on failure.
+ DESCRIPTION
+ 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 'create' & 'close'
+ callbacks are called for zero-sized properties, but the 'set' and 'get'
+ callbacks are never called.
+
+ The 'create' callback 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)(hid_t prop_id, const char *name,
+ size_t size, void *initial_value);
+ where the parameters to the callback function are:
+ hid_t prop_id; IN: The ID of the property list being created.
+ const char *name; IN: The name of the property being modified.
+ size_t size; IN: The size of the property value
+ void *initial_value; IN/OUT: The initial value for the property being created.
+ (The 'default' value passed to H5Pregister1)
+ 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 property list creation routine returns an error value.
+
+ 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 '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.
+
+ 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
+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_delete,
+ H5P_prp_copy_func_t prp_copy, H5P_prp_close_func_t prp_close)
+{
+ H5P_genclass_t *pclass; /* Property list class to modify */
+ herr_t ret_value; /* return value */
+
+ FUNC_ENTER_API(H5Pregister1, FAIL);
+ H5TRACE10("e","iszxxxxxxx",cls_id,name,size,def_value,prp_create,prp_set,
+ prp_get,prp_delete,prp_copy,prp_close);
+
+ /* Check arguments. */
+ if(NULL == (pclass = H5I_object_verify(cls_id, H5I_GENPROP_CLS)))
+ HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a property list class");
+ if(!name || !*name)
+ HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "invalid class name");
+ if(size > 0 && def_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_register(pclass, name, size, def_value, prp_create, prp_set, prp_get, prp_delete, prp_copy, NULL, prp_close)) < 0)
+ HGOTO_ERROR(H5E_PLIST, H5E_CANTREGISTER, FAIL, "unable to register property in class");
+
+done:
+ FUNC_LEAVE_API(ret_value);
+} /* H5Pregister1() */
+
+#endif /* H5_NO_DEPRECATED_SYMBOLS */
+