H5Ppkg.h

00001 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
00002  * Copyright by The HDF Group.                                               *
00003  * Copyright by the Board of Trustees of the University of Illinois.         *
00004  * All rights reserved.                                                      *
00005  *                                                                           *
00006  * This file is part of HDF5.  The full HDF5 copyright notice, including     *
00007  * terms governing use, modification, and redistribution, is contained in    *
00008  * the files COPYING and Copyright.html.  COPYING can be found at the root   *
00009  * of the source code distribution tree; Copyright.html can be found at the  *
00010  * root level of an installed copy of the electronic HDF5 document set and   *
00011  * is linked from the top-level documents page.  It can also be found at     *
00012  * http://hdfgroup.org/HDF5/doc/Copyright.html.  If you do not have          *
00013  * access to either file, you may request a copy from help@hdfgroup.org.     *
00014  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
00015 
00016 /*
00017  * Programmer:  Quincey Koziol <koziol@ncsa.uiuc.edu>
00018  *              Friday, November 16, 2001
00019  *
00020  * Purpose:     This file contains declarations which are visible only within
00021  *              the H5P package.  Source files outside the H5P package should
00022  *              include H5Pprivate.h instead.
00023  */
00024 #ifndef H5P_PACKAGE
00025 #error "Do not include this file outside the H5P package!"
00026 #endif
00027 
00028 #ifndef _H5Ppkg_H
00029 #define _H5Ppkg_H
00030 
00031 /* Get package's private header */
00032 #include "H5Pprivate.h"
00033 
00034 /* Other private headers needed by this file */
00035 #include "H5SLprivate.h"        /* Skip lists                           */
00036 
00037 /**************************/
00038 /* Package Private Macros */
00039 /**************************/
00040 
00041 
00042 /****************************/
00043 /* Package Private Typedefs */
00044 /****************************/
00045 
00046 /* Define enum for type of object that property is within */
00047 typedef enum {
00048     H5P_PROP_WITHIN_UNKNOWN=0,  /* Property container is unknown */
00049     H5P_PROP_WITHIN_LIST,       /* Property is within a list */
00050     H5P_PROP_WITHIN_CLASS       /* Property is within a class */
00051 } H5P_prop_within_t;
00052 
00053 /* Define enum for modifications to class */
00054 typedef enum {
00055     H5P_MOD_ERR=(-1),   /* Indicate an error */
00056     H5P_MOD_INC_CLS,    /* Increment the dependant class count*/
00057     H5P_MOD_DEC_CLS,    /* Decrement the dependant class count*/
00058     H5P_MOD_INC_LST,    /* Increment the dependant list count*/
00059     H5P_MOD_DEC_LST,    /* Decrement the dependant list count*/
00060     H5P_MOD_INC_REF,    /* Increment the ID reference count*/
00061     H5P_MOD_DEC_REF,    /* Decrement the ID reference count*/
00062     H5P_MOD_MAX         /* Upper limit on class modifications */
00063 } H5P_class_mod_t;
00064 
00065 /* Define structure to hold property information */
00066 typedef struct H5P_genprop_t {
00067     /* Values for this property */
00068     char *name;         /* Name of property */
00069     size_t size;        /* Size of property value */
00070     void *value;        /* Pointer to property value */
00071     H5P_prop_within_t type;     /* Type of object the property is within */
00072     hbool_t shared_name;   /* Whether the name is shared or not */
00073 
00074     /* Callback function pointers & info */
00075     H5P_prp_create_func_t create;   /* Function to call when a property is created */
00076     H5P_prp_set_func_t set; /* Function to call when a property value is set */
00077     H5P_prp_get_func_t get; /* Function to call when a property value is retrieved */
00078     H5P_prp_delete_func_t del; /* Function to call when a property is deleted */
00079     H5P_prp_copy_func_t copy;  /* Function to call when a property is copied */
00080     H5P_prp_compare_func_t cmp; /* Function to call when a property is compared */
00081     H5P_prp_close_func_t close; /* Function to call when a property is closed */
00082 } H5P_genprop_t;
00083 
00084 /* Define structure to hold class information */
00085 struct H5P_genclass_t {
00086     struct H5P_genclass_t *parent;     /* Pointer to parent class */
00087     char *name;         /* Name of property list class */
00088     size_t  nprops;     /* Number of properties in class */
00089     unsigned   plists;     /* Number of property lists that have been created since the last modification to the class */
00090     unsigned   classes;    /* Number of classes that have been derived since the last modification to the class */
00091     unsigned   ref_count;  /* Number of oustanding ID's open on this class object */
00092     hbool_t    internal;   /* Whether this class is internal to the library or not */
00093     hbool_t    deleted;    /* Whether this class has been deleted and is waiting for dependent classes & proplists to close */
00094     unsigned   revision;   /* Revision number of a particular class (global) */
00095     H5SL_t *props;      /* Skip list containing properties */
00096 
00097     /* Callback function pointers & info */
00098     H5P_cls_create_func_t create_func;  /* Function to call when a property list is created */
00099     void *create_data;  /* Pointer to user data to pass along to create callback */
00100     H5P_cls_copy_func_t copy_func;   /* Function to call when a property list is copied */
00101     void *copy_data;    /* Pointer to user data to pass along to copy callback */
00102     H5P_cls_close_func_t close_func;   /* Function to call when a property list is closed */
00103     void *close_data;   /* Pointer to user data to pass along to close callback */
00104 };
00105 
00106 /* Define structure to hold property list information */
00107 struct H5P_genplist_t {
00108     H5P_genclass_t *pclass; /* Pointer to class info */
00109     hid_t   plist_id;   /* Copy of the property list ID (for use in close callback) */
00110     size_t  nprops;     /* Number of properties in class */
00111     hbool_t class_init; /* Whether the class initialization callback finished successfully */
00112     H5SL_t *del;        /* Skip list containing names of deleted properties */
00113     H5SL_t *props;      /* Skip list containing properties */
00114 };
00115 
00116 /* Function pointer for library classes with properties to register */
00117 typedef herr_t (*H5P_init_class_op_t)(H5P_genclass_t *pclass);
00118 typedef herr_t (*H5P_reg_prop_func_t)(H5P_genclass_t *pclass);
00119 
00120 /*
00121  * Each library property list class has a variable of this type that contains
00122  * class variables and methods used to initialize the class.
00123  */
00124 typedef struct H5P_libclass_t {
00125     const char  *name;                  /* Class name */
00126 
00127     hid_t const * const par_class_id;   /* Pointer to global parent class property list class ID */
00128     hid_t * const class_id;             /* Pointer to global property list class ID */
00129     hid_t * const def_plist_id;         /* Pointer to global default property list ID */
00130     H5P_reg_prop_func_t reg_prop_func;  /* Register class's properties */
00131 
00132     /* Class callback function pointers & info */
00133     H5P_cls_create_func_t create_func;  /* Function to call when a property list is created */
00134     void *create_data;                  /* Pointer to user data to pass along to create callback */
00135     H5P_cls_copy_func_t copy_func;      /* Function to call when a property list is copied */
00136     void *copy_data;                    /* Pointer to user data to pass along to copy callback */
00137     H5P_cls_close_func_t close_func;    /* Function to call when a property list is closed */
00138     void *close_data;                   /* Pointer to user data to pass along to close callback */
00139 } H5P_libclass_t;
00140 
00141 
00142 /*****************************/
00143 /* Package Private Variables */
00144 /*****************************/
00145 
00146 
00147 /******************************/
00148 /* Package Private Prototypes */
00149 /******************************/
00150 
00151 /* Private functions, not part of the publicly documented API */
00152 H5_DLL H5P_genclass_t *H5P_create_class(H5P_genclass_t *par_class,
00153     const char *name, unsigned internal,
00154     H5P_cls_create_func_t cls_create, void *create_data,
00155     H5P_cls_copy_func_t cls_copy, void *copy_data,
00156     H5P_cls_close_func_t cls_close, void *close_data);
00157 H5_DLL H5P_genclass_t *H5P_copy_pclass(H5P_genclass_t *pclass);
00158 H5_DLL herr_t H5P_register_real(H5P_genclass_t *pclass, const char *name, size_t size,
00159     const void *def_value, H5P_prp_create_func_t prp_create, H5P_prp_set_func_t prp_set,
00160     H5P_prp_get_func_t prp_get, H5P_prp_delete_func_t prp_delete,
00161     H5P_prp_copy_func_t prp_copy, H5P_prp_compare_func_t prp_cmp,
00162     H5P_prp_close_func_t prp_close);
00163 H5_DLL herr_t H5P_register(H5P_genclass_t **pclass, const char *name, size_t size,
00164     const void *def_value, H5P_prp_create_func_t prp_create, H5P_prp_set_func_t prp_set,
00165     H5P_prp_get_func_t prp_get, H5P_prp_delete_func_t prp_delete,
00166     H5P_prp_copy_func_t prp_copy, H5P_prp_compare_func_t prp_cmp,
00167     H5P_prp_close_func_t prp_close);
00168 H5_DLL herr_t H5P_add_prop(H5SL_t *props, H5P_genprop_t *prop);
00169 H5_DLL herr_t H5P_access_class(H5P_genclass_t *pclass, H5P_class_mod_t mod);
00170 H5_DLL htri_t H5P_exist_pclass(H5P_genclass_t *pclass, const char *name);
00171 H5_DLL herr_t H5P_get_size_plist(H5P_genplist_t *plist, const char *name,
00172     size_t *size);
00173 H5_DLL herr_t H5P_get_size_pclass(H5P_genclass_t *pclass, const char *name,
00174     size_t *size);
00175 H5_DLL H5P_genclass_t *H5P_get_class(const H5P_genplist_t *plist);
00176 H5_DLL herr_t H5P_get_nprops_plist(const H5P_genplist_t *plist, size_t *nprops);
00177 H5_DLL int H5P_cmp_class(const H5P_genclass_t *pclass1, const H5P_genclass_t *pclass2);
00178 H5_DLL int H5P_cmp_plist(const H5P_genplist_t *plist1, const H5P_genplist_t *plist2);
00179 H5_DLL int H5P_iterate_plist(hid_t plist_id, int *idx, H5P_iterate_t iter_func,
00180     void *iter_data);
00181 H5_DLL int H5P_iterate_pclass(hid_t pclass_id, int *idx, H5P_iterate_t iter_func,
00182     void *iter_data);
00183 H5_DLL herr_t H5P_copy_prop_plist(hid_t dst_id, hid_t src_id, const char *name);
00184 H5_DLL herr_t H5P_copy_prop_pclass(hid_t dst_id, hid_t src_id, const char *name);
00185 H5_DLL herr_t H5P_unregister(H5P_genclass_t *pclass, const char *name);
00186 H5_DLL char *H5P_get_class_path(H5P_genclass_t *pclass);
00187 H5_DLL H5P_genclass_t *H5P_open_class_path(const char *path);
00188 H5_DLL H5P_genclass_t *H5P_get_class_parent(const H5P_genclass_t *pclass);
00189 H5_DLL herr_t H5P_close_class(void *_pclass);
00190 H5_DLL herr_t H5P_get_filter(const H5Z_filter_info_t *filter,
00191     unsigned int *flags, size_t *cd_nelmts, unsigned cd_values[],
00192     size_t namelen, char name[], unsigned *filter_config);
00193 
00194 /* Testing functions */
00195 #ifdef H5P_TESTING
00196 H5_DLL char *H5P_get_class_path_test(hid_t pclass_id);
00197 H5_DLL hid_t H5P_open_class_path_test(const char *path);
00198 H5_DLL herr_t H5P_reset_external_file_test(hid_t dcpl_id);
00199 #endif /* H5P_TESTING */
00200 
00201 #endif /* _H5Ppkg_H */
00202