HDF5 C++ Interfaces
                           ===================

// HDF5 dataset and attribute have some common characteristics, so the
// term abstract dataset is used to name the element that can represent 
// both objects, dataset and attribute.
//
// Class AbstractDs is an abstract base class, from which Attribute and 
// DataSet inherit.  It provides the services that are common to both 
// Attribute and DataSet.  It also inherits from H5Object and passes down 
// the services that H5Object provides.
class AbstractDs : public H5Object

	// Gets the dataspace of this abstract dataset - pure virtual
	virtual DataSpace getSpace() const = 0;

        // Gets the class of the datatype that is used by this abstract 
	// dataset        
	H5T_class_t getTypeClass() const;

	// Gets a copy of the datatype that this abstract dataset uses.  
	// Note that this datatype is a generic one and can only be accessed 
	// via generic member functions, i.e., member functions belong to 
	// DataType.  To get specific datatype, i.e. EnumType, FloatType, 
	// etc..., use the specific functions, that follow, instead.
	DataType getDataType() const;

        // Gets a copy of the specific datatype of this abstract dataset
        EnumType getEnumType() const;
        CompType getCompType() const;
        IntType getIntType() const;
        FloatType getFloatType() const;
        StrType getStrType() const;

	// Copy constructor
	AbstractDs( const AbstractDs& original );

	virtual ~AbstractDs();

// end of class AbstractDs

// Atomic datatype can be an integer, float, string, or predefined datatype.
//
// Class AtomType is a base class, from which IntType, FloatType, StrType, 
// and PredType inherit.  It provides the services that are common to these
// subclasses.  It also inherits from DataType and passes down the  
// services that are common to all the datatypes.
class AtomType : public DataType

	// Sets the total size for an atomic datatype. 
	void setSize( size_t size ) const;

	// Returns the byte order of an atomic datatype. 
	H5T_order_t getOrder( string& order_string ) const;

	// Sets the byte ordering of an atomic datatype. 
	void setOrder( H5T_order_t order ) const;

	// Returns the precision of an atomic datatype. 
	size_t getPrecision() const;

	// Sets the precision of an atomic datatype. 
	void setPrecision( size_t precision ) const;

	// Gets the bit offset of the first significant bit. 
	int getOffset() const;

	// Sets the bit offset of the first significant bit. 
	void setOffset( size_t offset ) const;

	// Copy constructor 
	AtomType( const AtomType& original );

	virtual ~AtomType();

// end of class AtomType


// An attribute is an abstract dataset because it has some characteristics
// that a dataset also has, but not all.
//
// Class Attribute inherits from AbstractDs and provides accesses to an 
// attribute.
class Attribute : public AbstractDs

	// Writes data to this attribute.
	void write(const DataType& mem_type, void *buf ) const;

	// Reads data from this attribute.
	void read( const DataType& mem_type, void *buf ) const;

	// Gets a copy of the dataspace for this attribute.
	virtual DataSpace getSpace() const;

	// Gets the name of this attribute.
	string getName( size_t buf_size ) const;

	// An attribute doesn't have the ability to iterate, simply because
	// it doesn't have any attributes associated with it.  Thus, the
	// implementation of this member which is inherited from H5Object
	// is overwritten to do nothing here.
	int iterateAttrs() const;

        // Creates a copy of an existing attribute using the attribute id
        Attribute( const hid_t attr_id );

	// Copy constructor
	Attribute( const Attribute& original );

	virtual ~Attribute();


// CommonFG is a protocol class.  Its existence is simply to provide the
// common services that are provided by H5File and Group.  The file or 
// group in the context of this class is referred to as 'location'.
class CommonFG
	// Creates a new group at this location.
	Group createGroup( const string& name, size_t size_hint = 0 ) const;
	Group createGroup( const char* name, size_t size_hint = 0 ) const;

	// Opens an existing group in a location.
	Group openGroup( const string& name ) const;
	Group openGroup( const char* name ) const;

	// Creates a new dataset at this location.
	DataSet createDataSet( const string& name, const DataType& data_type, const DataSpace& data_space, const DSetCreatPropList& create_plist = DSetCreatPropList::DEFAULT ) const;
	DataSet createDataSet( const char* name, const DataType& data_type, const DataSpace& data_space, const DSetCreatPropList& create_plist = DSetCreatPropList::DEFAULT ) const;

	// Opens an existing dataset at this location.
	DataSet openDataSet( const string& name ) const;
	DataSet openDataSet( const char* name ) const;

	// Creates a link of the specified type from new_name to current_name;
	// both names are interpreted relative to this location.
	void link( H5G_link_t link_type, const string& curr_name, const string& new_name ) const;
	void link( H5G_link_t link_type, const char* curr_name, const char* new_name ) const;

	// Removes the specified name at this location.
	void unlink( const string& name ) const;
	void unlink( const char* name ) const;

	// Renames an HDF5 object at this location.
	void move( const string& src, const string& dst ) const;
	void move( const char* src, const char* dst ) const;

	// Returns information about an HDF5 object, given by its name, at this location.
	void getObjinfo( const string& name, hbool_t follow_link, H5G_stat_t& statbuf ) const;
	void getObjinfo( const char* name, hbool_t follow_link, H5G_stat_t& statbuf ) const;

	// Returns the name of the HDF5 object that the symbolic link points to.
	string getLinkval( const string& name, size_t size ) const;
	string getLinkval( const char* name, size_t size ) const;

	// Sets the comment for the HDF5 object specified by its name.
	void setComment( const string& name, const string& comment ) const;
	void setComment( const char* name, const char* comment ) const;

	// Retrieves comment for the HDF5 object specified by its name.
	string getComment( const string& name, size_t bufsize ) const;
	string getComment( const char* name, size_t bufsize ) const;

	// Mounts the file 'child' onto this location.
	void mount( const string& name, H5File& child, PropList& plist ) const;
	void mount( const char* name, H5File& child, PropList& plist) const;

	// Unmounts the file named 'name' from this location.
	void unmount( const string& name ) const;
	void unmount( const char* name ) const;

	// Iterates over the elements of this location - not implemented in
	// C++ style yet
	int iterateElems( const string& name, int *idx, H5G_iterate_t op, void *op_data );
	int iterateElems( const char* name, int *idx, H5G_iterate_t op, void *op_data );

	// Opens a generic named datatype at this location
	DataType openDataType( const string& name ) const;
	DataType openDataType( const char* name ) const;

	// Opens a named enumeration datatype at this location
	EnumType openEnumType( const string& name ) const;
	EnumType openEnumType( const char* name ) const;

	// Opens a named compound datatype at this location
	CompType openCompType( const string& name ) const;
	CompType openCompType( const char* name ) const;

	// Opens a named integer datatype at this location
	IntType openIntType( const string& name ) const;
	IntType openIntType( const char* name ) const;

	// Opens a named floating-point datatype at this location
	FloatType openFloatType( const string& name ) const;
	FloatType openFloatType( const char* name ) const;

	// Opens a named string datatype at this location
	StrType openStrType( const string& name ) const;
	StrType openStrType( const char* name ) const;

	// For H5File and Group to throw appropriate exception - pure virtual
	virtual void throwException() const = 0;

	// Get id of the location, either group or file - pure virtual 
	virtual hid_t getLocId() const = 0; 

	CommonFG();
	virtual ~CommonFG();

// end of CommonFG declaration


// Class CompType inherits from DataType and provides accesses to a compound 
// datatype.
class CompType : public DataType

	// Creates a new compound datatype, given the type's size.
	CompType( size_t size );

	// Creates a compound datatype using an existing id.
	CompType( const hid_t existing_id );

	// Gets the compound datatype of the specified dataset.
	CompType( const DataSet& dataset );

	// Returns the number of members in this compound datatype. 
	int getNmembers() const;

	// Returns the name of a member of this compound datatype. 
	string getMemberName( unsigned member_num ) const;

	// Returns the offset of a member of this compound datatype. 
	size_t getMemberOffset( unsigned memb_no ) const;

	// Returns the dimensionality of the specified member of this compound datatype. 
	int getMemberDims( int member_num, size_t* dims, int* perm ) const;

	// Returns the type class of the specified member of this compound 
	// datatype.  It provides to the user a way of knowing what type 
	// to create another datatype of the same class.
	H5T_class_t getMemberClass( unsigned member_num ) const;

	// Returns the generic datatype of the specified member in 
	// this compound datatype.
	DataType getMemberDataType( int member_num ) const;

	// Returns the enumeration datatype of the specified member in 
	// this compound datatype.
	EnumType getMemberEnumType( int member_num ) const;

	// Returns the compound datatype of the specified member in 
	// this compound datatype.
	CompType getMemberCompType( int member_num ) const;

	// Returns the integer datatype of the specified member in 
	// this compound datatype.
	IntType getMemberIntType( int member_num ) const;

	// Returns the floating-point datatype of the specified member in 
	// this compound datatype.
	FloatType getMemberFloatType( int member_num ) const;

	// Returns the string datatype of the specified member in 
	// this compound datatype.
	StrType getMemberStrType( int member_num ) const;

	// Adds a new member to this compound datatype.
	void insertMember( const string name, size_t offset, const DataType& new_member ) const;

	// Recursively removes padding from within this compound datatype. 
	void pack() const;

	// Default constructor
	CompType();

	// Copy constructor
	CompType( const CompType& original );

	virtual ~CompType();

// end of class CompType


// Class DataSet inherits from AbstractDs and provides accesses to a dataset.
class DataSet : public AbstractDs

	// Gets the dataspace of this dataset.
	virtual DataSpace getSpace() const;

	// Gets the creation property list of this dataset.
	DSetCreatPropList getCreatePlist() const;

	// Gets the storage size of this dataset.
	hsize_t getStorageSize() const;

	// Reads the data of this dataset and stores it in the provided buffer.
	// The memory and file dataspaces and the transferring property list
	// can be defaults.
	void read( void* buf, const DataType& mem_type, const DataSpace& mem_space = DataSpace::ALL, const DataSpace& file_space = DataSpace::ALL, const DSetMemXferPropList& xfer_plist = DSetMemXferPropList::DEFAULT ) const;

	// Writes the buffered data to this dataset.
	// The memory and file dataspaces and the transferring property list
	// can be defaults.
	void write( const void* buf, const DataType& mem_type, const DataSpace& mem_space = DataSpace::ALL, const DataSpace& file_space = DataSpace::ALL, const DSetMemXferPropList& xfer_plist = DSetMemXferPropList::DEFAULT ) const;

	// Extends the dataset with unlimited dimension.
	void extend( const hsize_t* size ) const;

	// Default constructor
	DataSet();

	// Copy constructor
	DataSet( const DataSet& original );

	virtual ~DataSet();

// end of class DataSet


// Class DataSpace provides accesses to the dataspace.
class DataSpace : public IdComponent

	// Default DataSpace objects
	static const DataSpace ALL;

	// Creates a dataspace object given the space type.
	DataSpace( H5S_class_t type );

	// Creates a simple dataspace.
	DataSpace( int rank, const hsize_t * dims, const hsize_t * maxdims = NULL);

	// Makes copy of an existing dataspace.
	void copy( const DataSpace& like_space );

	// Determines if this dataspace is a simple one.
	bool isSimple () const;

	// Sets the offset of this simple dataspace.
	void offsetSimple ( const hssize_t* offset ) const;

	// Retrieves dataspace dimension size and maximum size.
	int getSimpleExtentDims ( hsize_t *dims, hsize_t *maxdims = NULL ) const;

	// Gets the dimensionality of this dataspace.
	int getSimpleExtentNdims () const;

	// Gets the number of elements in this dataspace.
	hssize_t getSimpleExtentNpoints () const;

	// Gets the current class of this dataspace.
	H5S_class_t getSimpleExtentType () const;

	// Copies the extent of this dataspace.
	void extentCopy ( DataSpace& dest_space ) const;

	// Sets or resets the size of this dataspace.
	void setExtentSimple( int rank, const hsize_t *current_size, const hsize_t *maximum_size = NULL ) const;

	// Removes the extent from this dataspace.
	void setExtentNone () const;

	// Gets the number of elements in this dataspace selection.
	hssize_t getSelectNpoints () const;

	// Get number of hyperslab blocks.
	hssize_t getSelectHyperNblocks () const;

	// Gets the list of hyperslab blocks currently selected.
	void getSelectHyperBlocklist( hsize_t startblock, hsize_t numblocks, hsize_t *buf ) const;

	// Gets the number of element points in the current selection.
	hssize_t getSelectElemNpoints () const;

	// Retrieves the list of element points currently selected.
	void getSelectElemPointlist ( hsize_t startpoint, hsize_t numpoints, hsize_t *buf ) const;

	// Gets the bounding box containing the current selection.
	void getSelectBounds ( hsize_t* start, hsize_t* end ) const;

	// Selects array elements to be included in the selection for 
	// this dataspace.
	void selectElements ( H5S_seloper_t op, const size_t num_elements, const hsize_t* coord[ ] ) const;

	// Selects the entire dataspace.
	void selectAll () const;

	// Resets the selection region to include no elements.
	void selectNone () const;

	// Verifies that the selection is within the extent of the dataspace.
	bool selectValid () const;

	// Selects a hyperslab region to add to the current selected region.
	void selectHyperslab( H5S_seloper_t op, const hsize_t *count, const hsize_t *start, const hsize_t *stride = NULL, const hsize_t *block = NULL ) const;

	// Default constructor
	DataSpace();

	// Create a dataspace object from a dataspace identifier
	DataSpace( const hid_t space_id );

	// Copy constructor
	DataSpace( const DataSpace& original );

	virtual ~DataSpace();
// end of class DataSpace


// HDF5 datatype can be an atom datatype, a compound datatype, or an 
// enumeration datatype.  A datatype is itself a kind of HDF5 object.
//
// Class DataType provides accesses to a generic HDF5 datatype.  It has 
// characteristics which AtomType, CompType, and EnumType inherit.  It also 
// inherits from H5Object and passes down the services to its subclasses.
class DataType : public H5Object

	// Creates a datatype given its class and size.
	DataType( const H5T_class_t type_class, size_t size );

	// Copies an existing datatype to this datatype instance.
	void copy( const DataType& like_type );

	// Returns the datatype class identifier of this datatype. 
	H5T_class_t getClass() const;

	// Commits a transient datatype to a file; this datatype becomes 
	// a named datatype which can be accessed from the location.
	void commit( H5Object& loc, const string& name ) const;
	void commit( H5Object& loc, const char* name ) const;

	// Determines whether this datatype is a named datatype or 
	// a transient datatype. 
	bool committed() const;

        // Finds a conversion function that can handle the conversion 
        // of this datatype to the given datatype, dest.
	H5T_conv_t find( const DataType& dest, H5T_cdata_t **pcdata ) const;

	// Converts data from this datatype into the specified datatype, dest. 
	void convert( const DataType& dest, size_t nelmts, void *buf, void *background, PropList& plist ) const;

	// Sets the overflow handler to a specified function. 
	void setOverflow(H5T_overflow_t func) const;

	// Returns a pointer to the current global overflow function. 
	H5T_overflow_t getOverflow(void) const;

	// Locks a datatype. 
	void lock() const;

	// Returns the size of this datatype. 
	size_t getSize() const;

	// Returns the base datatype from which a datatype is derived. 
	// Not implemented yet
	DataType getSuper() const;

	// Registers a conversion function. 
	void registerFunc(H5T_pers_t pers, const string& name, const DataType& dest, H5T_conv_t func ) const;
	void registerFunc(H5T_pers_t pers, const char* name, const DataType& dest, H5T_conv_t func ) const;

	// Removes a conversion function from all conversion paths. 
	void unregister( H5T_pers_t pers, const string& name, const DataType& dest, H5T_conv_t func ) const;
	void unregister( H5T_pers_t pers, const char* name, const DataType& dest, H5T_conv_t func ) const;

	// Tags an opaque datatype. 
	void setTag( const string& tag ) const;
	void setTag( const char* tag ) const;

	// Gets the tag associated with an opaque datatype. 
	string getTag() const;

	// Creates a DataType using an existing id - this datatype is
	// not a predefined type
	DataType( const hid_t type_id, bool predtype = false );

	// Default constructor
	DataType();

	// Copy constructor
	DataType( const DataType& original );

	virtual ~DataType();

// end of class DataType


// Class DSetCreatPropList provides accesses to a dataset creation 
// property list.
class DSetCreatPropList : public PropList

	// Default DSetCreatPropList object
	static const DSetCreatPropList DEFAULT;

	// Copies a dataset creation property list using assignment statement.
	DSetCreatPropList& operator=( const DSetCreatPropList& rhs );

	// Sets the type of storage used to store the raw data for the 
	// dataset that uses this property list.
	void setLayout( hid_t plist, H5D_layout_t layout ) const;

	// Gets the layout of the raw data storage of the data that uses this
	// property list.
	H5D_layout_t getLayout() const;

	// Sets the size of the chunks used to store a chunked layout dataset.
	void setChunk( int ndims, const hsize_t* dim ) const;

	// Retrieves the size of the chunks used to store a chunked layout dataset.
	int getChunk( int max_ndims, hsize_t* dim ) const;

	// Sets compression method and compression level
	void setDeflate( int level ) const;

	// Sets a dataset fill value.
	void setFillValue( DataType& fvalue_type, const void* value ) const;

	// Retrieves a dataset fill value.
	void getFillValue( DataType& fvalue_type, void* value ) const;

	// Adds a filter to the filter pipeline
	void setFilter( H5Z_filter_t filter, unsigned int flags, size_t cd_nelmts, const unsigned int cd_values[] ) const;

	// Returns the number of filters in the pipeline. 
	int getNfilters() const;

	// Returns information about a filter in a pipeline.
	H5Z_filter_t getFilter( int filter_number, unsigned int& flags, size_t& cd_nelmts, unsigned int* cd_values, size_t namelen, char name[] ) const;

	// Adds an external file to the list of external files.
	void setExternal( const char* name, off_t offset, hsize_t size ) const;

	// Returns the number of external files for a dataset. 
	int getExternalCount() const;

	// Returns information about an external file
	void getExternal( unsigned idx, size_t name_size, char* name, off_t& offset, hsize_t& size ) const;

	// Creates a copy of an existing dataset creation property list 
	// using the property list id
	DSetCreatPropList( const hid_t plist_id );

	// Default constructor
	DSetCreatPropList();

	// Copy constructor
	DSetCreatPropList( const DSetCreatPropList& original );

	virtual ~DSetCreatPropList();

// end of class DSetCreatPropList


// Class DSetMemXferPropList provides accesses to a dataset memory and 
// transfer property list.
class DSetMemXferPropList : public PropList

	// Default object for dataset memory and transfer property list
	static const DSetMemXferPropList DEFAULT;

	// Copies a dataset memory and transfer property list using 
	// assignment statement
	DSetMemXferPropList& operator=( const DSetMemXferPropList& rhs );

	// Sets type conversion and background buffers
	void setBuffer( size_t size, void* tconv, void* bkg ) const;

	// Reads buffer settings
	size_t getBuffer( void** tconv, void** bkg ) const;

	// Sets the dataset transfer property list status to TRUE or FALSE
	void setPreserve( bool status ) const;

	// Checks status of the dataset transfer property list
	bool getPreserve() const;

	// Indicates whether to cache hyperslab blocks during I/O
	void setHyperCache( bool cache, unsigned limit = 0 ) const;

	// Returns information regarding the caching of hyperslab blocks during I/O
	void getHyperCache( bool& cache, unsigned& limit ) const;

	// Sets B-tree split ratios for a dataset transfer property list 
	void setBtreeRatios( double left, double middle, double right ) const;

	// Gets B-tree split ratios for a dataset transfer property list
	void getBtreeRatios( double& left, double& middle, double& right ) const;

	// Sets the memory manager for variable-length datatype 
	// allocation in H5Dread and H5Dvlen_reclaim
	void setVlenMemManager( H5MM_allocate_t alloc, void* alloc_info, 
				H5MM_free_t free, void* free_info ) const;

	// alloc and free are set to NULL, indicating that system 
	// malloc and free are to be used
	void setVlenMemManager() const;

	// Gets the memory manager for variable-length datatype 
	// allocation in H5Dread and H5Tvlen_reclaim
	void getVlenMemManager( H5MM_allocate_t& alloc, void** alloc_info, 
				H5MM_free_t& free, void** free_info ) const;

	// Sets the transfer mode - parallel mode, not currently supported
	//void setXfer( H5D_transfer_t data_xfer_mode = H5D_XFER_INDEPENDENT ) const;

	// Gets the transfer mode - parallel mode, not currently supported
	//H5D_transfer_t getXfer() const;

	// Creates a copy of an existing dataset memory and transfer 
	// property list using the property list id
	DSetMemXferPropList (const hid_t plist_id)

	// Default constructor
	DSetMemXferPropList();

	// Copy constructor
	DSetMemXferPropList( const DSetMemXferPropList& original );

	// Default destructor
	virtual ~DSetMemXferPropList();

// end of class DSetMemXferPropList


class EnumType : public DataType

	// Creates an empty enumeration datatype based on a native signed 
	// integer type, whose size is given by size.
	EnumType( size_t size );

	// Gets the enum datatype of the specified dataset
	EnumType( const DataSet& dataset );  // H5Dget_type

	// Creates a new enum datatype based on an integer datatype
	EnumType( const IntType& data_type );  // H5Tenum_create

	// Inserts a new member to this enumeration type. 
	void insert( const string& name, void *value ) const;
	void insert( const char* name, void *value ) const;

	// Returns the symbol name corresponding to a specified member 
	// of this enumeration datatype. 
	string nameOf( void *value, size_t size ) const;

	// Returns the value corresponding to a specified member of this 
	// enumeration datatype. 
	void valueOf( const string& name, void *value ) const;
	void valueOf( const char* name, void *value ) const;

	// Returns the value of an enumeration datatype member
	void getMemberValue( unsigned memb_no, void *value ) const;

	// Default constructor
	EnumType();

	// Creates an enumeration datatype using an existing id
	EnumType( const hid_t existing_id );

	// Copy constructor
	EnumType( const EnumType& original );

	virtual ~EnumType();
// end of class EnumType


class Exception

	// Creates an exception with a detailed message
	Exception( const string& message );

	Exception( const char* message);

	// Returns the character string that describes an error specified by
	// a major error number.
	string getMajorString( H5E_major_t major_num ) const;

	// Returns the character string that describes an error specified by
	// a minor error number.
	string getMinorString( H5E_minor_t minor_num ) const;

	// Returns the detailed message set at the time the exception is thrown
	string getDetailMesg() const;

	// Turns on the automatic error printing.
	void setAutoPrint( H5E_auto_t func, 
				void* client_data ) const;

	// Turns off the automatic error printing.
	static void dontPrint();

	// Retrieves the current settings for the automatic error stack 
	// traversal function and its data.
	void getAutoPrint( H5E_auto_t& func, 
				void** client_data ) const;

	// Clears the error stack for the current thread.
	void clearErrorStack() const;

	// Walks the error stack for the current thread, calling the 
	// specified function.
	void walkErrorStack( H5E_direction_t direction, 
				H5E_walk_t func, void* client_data ) const;

	// Default error stack traversal callback function that prints 
	// error messages to the specified output stream.
	void walkDefErrorStack( int n, H5E_error_t& err_desc,
				void* client_data ) const;

	// Prints the error stack in a default manner.
	//void printError() const;
	void printError( FILE* stream = NULL ) const;

	// Creates an exception with no message
	Exception();

	// copy constructor
	Exception( const Exception& original );

// end of class Exception


// Class FileIException inherits from Exception to provide exception 
// handling for H5File.
class FileIException : public Exception
	FileIException();
	FileIException( string message );
// end of class FileIException


// Class GroupIException inherits from Exception to provide exception 
// handling for Group.
class GroupIException : public Exception
	GroupIException();
	GroupIException( string message );
// end of class GroupIException


// Class DataSpaceIException inherits from Exception to provide exception 
// handling for DataSpace.
class DataSpaceIException : public Exception
	DataSpaceIException();
	DataSpaceIException( string message );
// end of class DataSpaceIException


// Class DataTypeIException inherits from Exception to provide exception 
// handling for DataType.
class DataTypeIException : public Exception
	DataTypeIException();
	DataTypeIException( string message );
// end of class DataTypeIException


// Class PropListIException inherits from Exception to provide exception 
// handling for PropList.
class PropListIException : public Exception
	PropListIException();
	PropListIException( string message );
// end of class PropListIException


// Class DataSetIException inherits from Exception to provide exception 
// handling for DataSet.
class DataSetIException : public Exception
	DataSetIException();
	DataSetIException( string message );
// end of class DataSetIException


// Class AttributeIException inherits from Exception to provide exception 
// handling for Attribute.
class AttributeIException : public Exception
	AttributeIException();
	AttributeIException( string message );
// end of class AttributeIException


// Class LibraryIException inherits from Exception to provide exception 
// handling for H5Library.
class LibraryIException : public Exception
	LibraryIException();
	LibraryIException( string message );
// end of class LibraryIException


// Class IdComponentException inherits from Exception to provide exception 
// handling for IdComponent.
class IdComponentException : public Exception
	IdComponentException();
	IdComponentException( string message );
// end of class IdComponentException


// Class FileAccPropList provides accesses to a file access property list.
class FileAccPropList : public PropList

	// Default file access property list object 
	static const FileAccPropList DEFAULT;

	// Copies a file access property list using assignment statement.
	FileAccPropList& operator=( const FileAccPropList& rhs );

	// Sets alignment properties of this file access property list.
	void setAlignment( hsize_t threshold = 1, hsize_t alignment = 1 ) const;

	// Retrieves the current settings for alignment properties from
	// this file access property list.
	void getAlignment( hsize_t& threshold, hsize_t& alignment ) const;

	// Sets the meta data cache and raw data chunk cache parameters.
	void setCache( int mdc_nelmts, size_t rdcc_nelmts, size_t rdcc_nbytes, double rdcc_w0 ) const;

	// Retrieves maximum sizes of data caches and the preemption 
	// policy value.
	void getCache( int& mdc_nelmts, size_t& rdcc_nelmts, size_t& rdcc_nbytes, double& rdcc_w0 ) const;

	// Sets garbage collecting references flag.
	void setGcReferences( unsigned gc_ref = 0 ) const;

	// Returns garbage collecting references setting.
	unsigned getGcReferences() const;

	// Creates a copy of an existing file access property list
	// using the property list id.
	FileAccPropList (const hid_t plist_id);

	// Default constructor
	FileAccPropList();

	// Copy constructor
	FileAccPropList( const FileAccPropList& original );

	// Default destructor
	virtual ~FileAccPropList();

// end of class FileAccPropList


// Class FileCreatPropList provides accesses to a file creation property list.
class FileCreatPropList : public PropList

	// Default file creation property list object
	static const FileCreatPropList DEFAULT;
	
	// Copies a file creation property list using assignment statement.
	FileCreatPropList& operator=( const FileCreatPropList& rhs );

	// Retrieves version information for various parts of a file.
	void getVersion( unsigned& boot, unsigned& freelist, unsigned& stab, unsigned& shhdr ) const;

	// Sets the userblock size field of a file creation property list.
	void setUserblock( hsize_t size ) const;

	// Gets the size of a user block in this file creation property list.
	hsize_t getUserblock() const;

	// Sets file size-of addresses and sizes.
	void setSizes( size_t sizeof_addr = 4, size_t sizeof_size = 4 ) const;

	// Retrieves the size-of address and size quantities stored in a 
	// file according to this file creation property list.
	void getSizes( size_t& sizeof_addr, size_t& sizeof_size ) const;

	// Sets the size of parameters used to control the symbol table nodes.
	void setSymk( unsigned int_nodes_k, unsigned leaf_nodes_k ) const;

	// Retrieves the size of the symbol table B-tree 1/2 rank and the
	// symbol table leaf node 1/2 size.
	void getSymk( unsigned& int_nodes_k, unsigned& leaf_nodes_k ) const;

	// Sets the size of parameter used to control the B-trees for
	// indexing chunked datasets.
	void setIstorek( unsigned ik ) const;

	// Returns the 1/2 rank of an indexed storage B-tree.
	unsigned getIstorek() const;

	// Creates a copy of an existing file create property list
	// using the property list id.
	FileCreatPropList (const hid_t plist_id);

	// Default constructor
	FileCreatPropList();

	// Copy constructor
	FileCreatPropList( const FileCreatPropList& original );

	// Default destructor
	virtual ~FileCreatPropList();

// end of class FileCreatPropList

// Class H5File provides accesses to an HDF5 file.  It uses the services
// provided by CommonFG beside inheriting the HDF5 id management from the
// IdComponent class.
class H5File : public IdComponent, public CommonFG

	// Creates or opens an HDF5 file.  The file creation and access 
	// property lists can be default.
	H5File( const string& name, unsigned int flags, const FileCreatPropList& create_plist = FileCreatPropList::DEFAULT, const FileAccPropList& access_plist = FileAccPropList::DEFAULT );
	H5File( const char* name, unsigned int flags, const FileCreatPropList& create_plist = FileCreatPropList::DEFAULT, const FileAccPropList& access_plist = FileAccPropList::DEFAULT );

	// Throw file exception - used by CommonFG to specifically throw
	// FileIException.
	virtual void throwException() const;

	// Determines if a file, specified by its name, is in HDF5 format.
	static bool isHdf5(const string& name );
	static bool isHdf5(const char* name );

	// Reopens this file.
	void reopen();

	// Gets the creation property list of this file.
	FileCreatPropList getCreatePlist() const;

	// Gets the access property list of this file.
	FileAccPropList getAccessPlist() const;

	// Copy constructor
	H5File(const H5File& original );

	virtual ~H5File();

// end of class H5File


// Class FloatType inherits from AtomType and provides accesses to a 
// floating-point datatype.
class FloatType : public AtomType

        // Creates a floating-point type using a predefined type.
        FloatType( const PredType& pred_type );

	// Gets the floating-point datatype of the specified dataset.
	FloatType( const DataSet& dataset );

	// Retrieves floating point datatype bit field information. 
	void getFields( size_t& spos, size_t& epos, size_t& esize, size_t& mpos, size_t& msize ) const;

	// Sets locations and sizes of floating point bit fields. 
	void setFields( size_t spos, size_t epos, size_t esize, size_t mpos, size_t msize ) const;

	// Retrieves the exponent bias of a floating-point type. 
	size_t getEbias() const;

	// Sets the exponent bias of a floating-point type. 
	void setEbias( size_t ebias ) const;

	// Retrieves mantissa normalization of a floating-point datatype. 
	H5T_norm_t getNorm( string& norm_string ) const;

	// Sets the mantissa normalization of a floating-point datatype. 
	void setNorm( H5T_norm_t norm ) const;

	// Retrieves the internal padding type for unused bits in 
	// floating-point datatypes. 
	H5T_pad_t getInpad( string& pad_string ) const;
	
	// Fills unused internal floating point bits. 
	void setInpad( H5T_pad_t inpad ) const;

	// Default constructor
	FloatType();

	// Creates a floating-point datatype using an existing id.
	FloatType( const hid_t existing_id );

	// Copy constructor
	FloatType( const FloatType& original );

	virtual ~FloatType();

// end of class FloatType


// Class Group provides accesses to an HDF5 group.  As H5File, it uses the 
// services provided by CommonFG.  This class also inherits from H5Object.
class Group : public H5Object, public CommonFG
   public:

        // Throw group exception - used by CommonFG to specifically throw
	// GroupIException.
        virtual void throwException() const;

	// Default constructor
	Group();

	// Copy constructor
	Group( const Group& original );

	virtual ~Group();

// end of class Group

// Class IdComponent provides a mechanism to handle reference counting 
// for an identifier of any HDF5 object.
class IdComponent
	// Sets the identifier of this object to a new value.
	void setId( hid_t new_id );

	// Creates an object to hold an HDF5 identifier.
	IdComponent( const hid_t h5_id );

	// Gets the value of the current HDF5 object id which is held
	// by this IdComponent object.
	hid_t getId () const;

	// Increment reference counter.
	void incRefCount();

	// Decrement reference counter.
	void decRefCount();

	// Get the reference counter to this identifier.
	int getCounter();

	// Decrements the reference counter then determines if there are 
	// no more reference to this object.
	bool noReference();

	// Reset this object by deleting its reference counter of the old id.
	void reset();

	// Copy constructor
	IdComponent( const IdComponent& original );

	// Destructor
	virtual ~IdComponent();

}; // end class IdComponent


// Class IntType inherits from AtomType and provides accesses to 
// integer datatypes.
class IntType : public AtomType

	// Creates a integer type using a predefined type.
	IntType( const PredType& pred_type );

	// Gets the integer datatype of the specified dataset.
	IntType( const DataSet& dataset );

	// Retrieves the sign type for an integer type.
	H5T_sign_t getSign() const;

	// Sets the sign proprety for an integer type. 
	void setSign( H5T_sign_t sign ) const;

	// Default constructor
	IntType();

	// Creates a integer datatype using an existing id.
	IntType( const hid_t existing_id );

	// Copy constructor
	IntType( const IntType& original );

	virtual ~IntType();

// end of class IntType


// Class H5Library provides accesses to the HDF5 library.  All of its
// member functions are static.
class H5Library

	// Initializes the HDF5 library. 
	static void open(); 

	// Flushes all data to disk, closes files, and cleans up memory. 
	static void close(); 

	// Instructs library not to install atexit cleanup routine
	static void dontAtExit(); 

	// Returns the HDF library release number. 
	static void getLibVersion( unsigned& majnum, unsigned& minnum, unsigned& relnum ); 

	// Verifies that the arguments match the version numbers compiled
	// into the library
	static void checkVersion( unsigned majnum, unsigned minnum, unsigned relnum ); 

// end of class H5Library


// An HDF5 object can be a group, dataset, attribute, or named datatype.
//
// Class H5Object provides the services that are typical to an HDF5 object
// so Group, DataSet, Attribute, and DataType can use them.  It also 
// inherits the HDF5 id management from the class IdComponent.
class H5Object : public IdComponent

	// Flushes all buffers associated with this HDF5 object to disk.
	void flush( H5F_scope_t scope ) const;

	// Creates an attribute for a group, dataset, or named datatype.
	// PropList is currently not used, it should always be default.
	Attribute createAttribute( const char* name, const DataType& type, const DataSpace& space, const PropList& create_plist = PropList::DEFAULT ) const;
	Attribute createAttribute( const string& name, const DataType& type, const DataSpace& space, const PropList& create_plist = PropList::DEFAULT ) const;

	// Opens an attribute that belongs to this object, given the 
	// attribute name.
	Attribute openAttribute( const string& name ) const;
	Attribute openAttribute( const char* name ) const;

	// Opens an attribute that belongs to this object, given the
	// attribute index.
	Attribute openAttribute( const unsigned int idx ) const;

	// Iterate user's function over the attributes of this HDF5 object
	int iterateAttrs( attr_operator_t user_op, unsigned* idx = NULL, void* op_data = NULL );

	// Determines the number of attributes attached to this HDF5 object.
	int getNumAttrs() const;

	// Removes an attribute from this HDF5 object, given the attribute 
	// name.
	void removeAttr( const string& name ) const;
	void removeAttr( const char* name ) const;

	// Copy constructor
	H5Object( const H5Object& original );

	virtual ~H5Object();

// end of class H5Object


// Class PredType contains all the predefined datatype objects that are
// currently available.
class PredType : public AtomType

	static const PredType STD_I8BE;
	static const PredType STD_I8LE;
	static const PredType STD_I16BE;
	static const PredType STD_I16LE;
	static const PredType STD_I32BE;
	static const PredType STD_I32LE;
	static const PredType STD_I64BE;
	static const PredType STD_I64LE;
	static const PredType STD_U8BE;
	static const PredType STD_U8LE;
	static const PredType STD_U16BE;
	static const PredType STD_U16LE;
	static const PredType STD_U32BE;
	static const PredType STD_U32LE;
	static const PredType STD_U64BE;
	static const PredType STD_U64LE;
	static const PredType STD_B8BE;
	static const PredType STD_B8LE;
	static const PredType STD_B16BE;
	static const PredType STD_B16LE;
	static const PredType STD_B32BE;
	static const PredType STD_B32LE;
	static const PredType STD_B64BE;
	static const PredType STD_B64LE;
	static const PredType STD_REF_OBJ;
	static const PredType STD_REF_DSETREG;

	static const PredType C_S1;
	static const PredType FORTRAN_S1;

	static const PredType IEEE_F32BE;
	static const PredType IEEE_F32LE;
	static const PredType IEEE_F64BE;
	static const PredType IEEE_F64LE;

	static const PredType UNIX_D32BE;
	static const PredType UNIX_D32LE;
	static const PredType UNIX_D64BE;
	static const PredType UNIX_D64LE;

	static const PredType INTEL_I8;
	static const PredType INTEL_I16;
	static const PredType INTEL_I32;
	static const PredType INTEL_I64;
	static const PredType INTEL_U8;
	static const PredType INTEL_U16;
	static const PredType INTEL_U32;
	static const PredType INTEL_U64;
	static const PredType INTEL_B8;
	static const PredType INTEL_B16;
	static const PredType INTEL_B32;
	static const PredType INTEL_B64;
	static const PredType INTEL_F32;
	static const PredType INTEL_F64;

	static const PredType ALPHA_I8;
	static const PredType ALPHA_I16;
	static const PredType ALPHA_I32;
	static const PredType ALPHA_I64;
	static const PredType ALPHA_U8;
	static const PredType ALPHA_U16;
	static const PredType ALPHA_U32;
	static const PredType ALPHA_U64;
	static const PredType ALPHA_B8;
	static const PredType ALPHA_B16;
	static const PredType ALPHA_B32;
	static const PredType ALPHA_B64;
	static const PredType ALPHA_F32;
	static const PredType ALPHA_F64;

	static const PredType MIPS_I8;
	static const PredType MIPS_I16;
	static const PredType MIPS_I32;
	static const PredType MIPS_I64;
	static const PredType MIPS_U8;
	static const PredType MIPS_U16;
	static const PredType MIPS_U32;
	static const PredType MIPS_U64;
	static const PredType MIPS_B8;
	static const PredType MIPS_B16;
	static const PredType MIPS_B32;
	static const PredType MIPS_B64;
	static const PredType MIPS_F32;
	static const PredType MIPS_F64;

	static const PredType NATIVE_CHAR;
	static const PredType NATIVE_SCHAR;
	static const PredType NATIVE_UCHAR;
	static const PredType NATIVE_SHORT;
	static const PredType NATIVE_USHORT;
	static const PredType NATIVE_INT;
	static const PredType NATIVE_UINT;
	static const PredType NATIVE_LONG;
	static const PredType NATIVE_ULONG;
	static const PredType NATIVE_LLONG;
	static const PredType NATIVE_ULLONG;
	static const PredType NATIVE_FLOAT;
	static const PredType NATIVE_DOUBLE;
	static const PredType NATIVE_LDOUBLE;
	static const PredType NATIVE_B8;
	static const PredType NATIVE_B16;
	static const PredType NATIVE_B32;
	static const PredType NATIVE_B64;
	static const PredType NATIVE_OPAQUE;
	static const PredType NATIVE_HSIZE;
	static const PredType NATIVE_HSSIZE;
	static const PredType NATIVE_HERR;
	static const PredType NATIVE_HBOOL;

	static const PredType NATIVE_INT8;
	static const PredType NATIVE_UINT8;
	static const PredType NATIVE_INT_LEAST8;
	static const PredType NATIVE_UINT_LEAST8;
	static const PredType NATIVE_INT_FAST8;
	static const PredType NATIVE_UINT_FAST8;

	static const PredType NATIVE_INT16;
	static const PredType NATIVE_UINT16;
	static const PredType NATIVE_INT_LEAST16;
	static const PredType NATIVE_UINT_LEAST16;
	static const PredType NATIVE_INT_FAST16;
	static const PredType NATIVE_UINT_FAST16;

	static const PredType NATIVE_INT32;
	static const PredType NATIVE_UINT32;
	static const PredType NATIVE_INT_LEAST32;
	static const PredType NATIVE_UINT_LEAST32;
	static const PredType NATIVE_INT_FAST32;
	static const PredType NATIVE_UINT_FAST32;

	static const PredType NATIVE_INT64;
	static const PredType NATIVE_UINT64;
	static const PredType NATIVE_INT_LEAST64;
	static const PredType NATIVE_UINT_LEAST64;
	static const PredType NATIVE_INT_FAST64;
	static const PredType NATIVE_UINT_FAST64;

	// Copy constructor
	PredType( const PredType& original );

	// Default destructor
	virtual ~PredType();

   protected:
	// Default constructor
	PredType();

	// Creates a pre-defined type using an HDF5 pre-defined constant
	PredType( const hid_t predtype_id );  // used by the library only

// end of class PredType


// An HDF5 property list can be a file creation property list, a file
// access property list, a dataset creation property list, or a dataset
// memory and transfer property list.  
//
// Class PropList provides accesses to an HDF5 property list.  Its
// services are inherited by classes FileCreatPropList, FileAccPropList,
// DSetCreatPropList, and DSetMemXferPropList.  It also inherits the HDF5
// id management from the class IdComponent.
class PropList : public IdComponent

	// Default property list object
        static const PropList DEFAULT;

	// Creates a property list given the property list type.
	PropList( H5P_class_t type );

	// Makes a copy of the given property list.
	void copy( const PropList& like_plist );

	// Gets the class of this property list, i.e. H5P_FILE_CREATE,
	// H5P_FILE_ACCESS, ...
	H5P_class_t getClass() const;

	// Default constructor
	PropList();

	// Copy constructor
	PropList( const PropList& original );

	// Creates a default property list or creates a copy of an 
	// existing property list giving the property list id
	PropList( const hid_t plist_id );

	virtual ~PropList();

// end of class PropList

// Class RefCounter provides a reference counting mechanism.  It is used
// mainly by IdComponent to keep track of the references to an HDF5 object 
// identifier.
class RefCounter

	// Returns the value of the counter.
        int getCounter () const;

	// Increments and decrements the counter.
        void increment();
        void decrement();

	// This bool function is used to determine whether to close an
	// HDF5 object when there are no more reference to that object.
	// It decrements the counter, then returns true if there are no
	// other object references the associated identifier.  When the
	// function returns true, the associated identifier can be closed
	// safely.
	bool noReference();

	// Default constructor
	RefCounter();

	~RefCounter();

// end of class RefCounter


// Class StrType inherits from AtomType and provides accesses to a 
// string datatype.
class StrType : public AtomType
   public:
	// Creates a string type using a predefined type.
	StrType( const PredType& pred_type );

        // Gets the string datatype of the specified dataset.
	StrType( const DataSet& dataset );

	// Returns the character set type of this string datatype. 
	H5T_cset_t getCset() const;

	// Sets character set to be used. 
	void setCset( H5T_cset_t cset ) const;

	// Returns the string padding method for this string datatype. 
	H5T_str_t getStrpad() const;

	// Defines the storage mechanism for character strings. 
	void setStrpad( H5T_str_t strpad ) const;

	// Default constructor 
	StrType();

	// Copy constructor
	StrType( const StrType& original );

	// Creates a string datatype using an existing id.
	StrType( const hid_t existing_id );

	virtual ~StrType();
// end of class StrType


// This template function, resetIdComponent, is used to reset an 
// IdComponent object, which includes closing the associated HDF5 
// identifier if it has no other references.
// 'Type' can be of the following classes: Attribute, DataSet, DataSpace,
// DataType, H5File, Group, and PropList.
template 
void resetIdComponent( 
	Type* obj )	// pointer to object to be reset


The HDF Group Help Desk:
Describes HDF5 Development Trunk, Release 1.11.x.
Highest current public release is HDF5 Release 1.8.x.
  Copyright by The HDF Group
and the Board of Trustees of the University of Illinois
Last modified: 17 December 2000