80816a3dde
Add more C++ wrapper and documentation - incrementally check-in
Description:
Added doxygen documentation to:
H5DataSet.cpp
H5DataSpace.cpp
H5CommonFG.cpp
and a wrapper for H5Rcreate to H5Object.* with tests will be added
later.
There are more documentation need to be added to these files but
to preserve the changes, I check them in now.
Platforms:
SunOS 5.7 (arabica)
Linux 2.4 (eirene)
Misc. update:
472 lines
18 KiB
C++
472 lines
18 KiB
C++
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
|
|
* 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://hdf.ncsa.uiuc.edu/HDF5/doc/Copyright.html. If you do not have *
|
|
* access to either file, you may request a copy from hdfhelp@ncsa.uiuc.edu. *
|
|
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
|
|
|
|
#include <string>
|
|
#ifdef OLD_HEADER_FILENAME
|
|
#include <iostream.h>
|
|
#else
|
|
#include <iostream>
|
|
#endif
|
|
|
|
#include "H5Include.h"
|
|
#include "H5RefCounter.h"
|
|
#include "H5Exception.h"
|
|
#include "H5IdComponent.h"
|
|
#include "H5Idtemplates.h"
|
|
#include "H5PropList.h"
|
|
#include "H5Object.h"
|
|
#include "H5FaccProp.h"
|
|
#include "H5FcreatProp.h"
|
|
#include "H5DxferProp.h"
|
|
#include "H5DcreatProp.h"
|
|
#include "H5CommonFG.h"
|
|
#include "H5Group.h"
|
|
#include "H5AbstractDs.h"
|
|
#include "H5DataSpace.h"
|
|
#include "H5DataSet.h"
|
|
#include "H5File.h"
|
|
#include "H5Alltypes.h"
|
|
|
|
#ifndef H5_NO_NAMESPACE
|
|
namespace H5 {
|
|
#endif
|
|
|
|
//--------------------------------------------------------------------------
|
|
// Function Default constructor
|
|
///\brief Default constructor - Creates a stub hdf5 file object.
|
|
///\par Description
|
|
/// The id of this hdf5 file is set to 0.
|
|
// Programmer Binh-Minh Ribler - 2000
|
|
//--------------------------------------------------------------------------
|
|
H5File::H5File() : IdComponent() {}
|
|
|
|
//--------------------------------------------------------------------------
|
|
// Function: H5File overloaded constructor
|
|
///\brief Creates or opens an HDF5 file depending on the parameter flags.
|
|
///\param name - IN: Name of the file
|
|
///\param flags - IN: File access flags
|
|
///\param create_plist - IN: File creation property list, used when
|
|
/// modifying default file meta-data. Default to
|
|
/// FileCreatPropList::DEFAULT
|
|
///\param access_plist - IN: File access property list. Default to
|
|
/// FileCreatPropList::DEFAULT
|
|
///\par Description
|
|
/// Valid values of \a flags include:
|
|
/// \li \c H5F_ACC_TRUNC - Truncate file, if it already exists,
|
|
/// erasing all data previously stored in
|
|
/// the file.
|
|
/// \li \c H5F_ACC_EXCL - Fail if file already exists.
|
|
/// \c H5F_ACC_TRUNC and \c H5F_ACC_EXCL are mutually exclusive
|
|
/// \li \c H5F_ACC_DEBUG - print debug information. This flag is
|
|
/// used only by HDF5 library developers; it is neither
|
|
/// tested nor supported for use in applications.
|
|
///\par
|
|
/// For info on file creation in the case of an already-open file,
|
|
/// please refer to the \b Special \b case section in the C layer
|
|
/// Reference Manual at:
|
|
/// http://hdf.ncsa.uiuc.edu/HDF5/doc/RM_H5F.html#File-Create
|
|
// Programmer Binh-Minh Ribler - 2000
|
|
//--------------------------------------------------------------------------
|
|
H5File::H5File( const string& name, unsigned int flags, const FileCreatPropList& create_plist, const FileAccPropList& access_plist ) : IdComponent()
|
|
{
|
|
getFile( name.c_str(), flags, create_plist, access_plist );
|
|
}
|
|
|
|
//--------------------------------------------------------------------------
|
|
// Function: H5File overloaded constructor
|
|
///\brief This is another overloaded constructor. It differs from the
|
|
/// above constructor only in the type of the \a name argument.
|
|
///\param name - IN: Name of the file
|
|
///\param flags - IN: File access flags
|
|
///\param create_plist - IN: File creation property list, used when
|
|
/// modifying default file meta-data. Default to
|
|
/// FileCreatPropList::DEFAULT
|
|
///\param access_plist - IN: File access property list. Default to
|
|
/// FileCreatPropList::DEFAULT
|
|
///\param name - IN: Name of the file - \c std::string
|
|
// Programmer Binh-Minh Ribler - 2000
|
|
//--------------------------------------------------------------------------
|
|
H5File::H5File( const char* name, unsigned int flags, const FileCreatPropList& create_plist, const FileAccPropList& access_plist ) : IdComponent()
|
|
{
|
|
getFile( name, flags, create_plist, access_plist );
|
|
}
|
|
|
|
//--------------------------------------------------------------------------
|
|
// This function is private and contains common code between the
|
|
// constructors taking a string or a char*
|
|
// Programmer Binh-Minh Ribler - 2000
|
|
//--------------------------------------------------------------------------
|
|
void H5File::getFile( const char* name, unsigned int flags, const FileCreatPropList& create_plist, const FileAccPropList& access_plist )
|
|
{
|
|
// These bits only set for creation, so if any of them are set,
|
|
// create the file.
|
|
if( flags & (H5F_ACC_EXCL|H5F_ACC_TRUNC|H5F_ACC_DEBUG ))
|
|
{
|
|
hid_t create_plist_id = create_plist.getId();
|
|
hid_t access_plist_id = access_plist.getId();
|
|
id = H5Fcreate( name, flags, create_plist_id, access_plist_id );
|
|
if( id <= 0 ) // throw an exception when open/create fail
|
|
{
|
|
throw FileIException("H5File constructor", "H5Fcreate failed");
|
|
}
|
|
}
|
|
// Open the file if none of the bits above are set.
|
|
else
|
|
{
|
|
// use create_plist for access plist because of the default argument
|
|
hid_t access_plist_id = create_plist.getId();
|
|
id = H5Fopen( name, flags, access_plist_id );
|
|
if( id <= 0 ) // throw an exception when open/create fail
|
|
{
|
|
throw FileIException("H5File constructor", "H5Fopen failed");
|
|
}
|
|
}
|
|
}
|
|
|
|
//--------------------------------------------------------------------------
|
|
// Function: Copy Constructor
|
|
///\brief Copy Constructor: Makes a copy of the original
|
|
/// H5File object
|
|
///\param original - IN: H5File instance to copy
|
|
// Programmer Binh-Minh Ribler - 2000
|
|
//--------------------------------------------------------------------------
|
|
H5File::H5File( const H5File& original ) : IdComponent( original ) {}
|
|
|
|
//--------------------------------------------------------------------------
|
|
// Function: H5File::isHdf5
|
|
///\brief Determines whether a file in HDF5 format
|
|
///\param name - IN: Name of the file
|
|
///\return true if the file is in HDF5 format, and false, otherwise
|
|
///\exception H5::FileIException
|
|
// Programmer Binh-Minh Ribler - 2000
|
|
//--------------------------------------------------------------------------
|
|
bool H5File::isHdf5(const char* name )
|
|
{
|
|
// Calls C routine H5Fis_hdf5 to determine whether the file is in
|
|
// HDF5 format. It returns positive value, 0, or negative value
|
|
htri_t ret_value = H5Fis_hdf5( name );
|
|
if( ret_value > 0 )
|
|
return true;
|
|
else if( ret_value == 0 )
|
|
return false;
|
|
else // Raise exception when H5Fis_hdf5 returns a negative value
|
|
{
|
|
throw FileIException("H5File::isHdf5", "H5Fis_hdf5 returned negative value");
|
|
}
|
|
}
|
|
//--------------------------------------------------------------------------
|
|
// Function: H5File::isHdf5
|
|
///\brief This is an overloaded member function, provided for convenience.
|
|
/// It takes an \c std::string for \a name.
|
|
///\param name - IN: Name of the file
|
|
// Programmer Binh-Minh Ribler - 2000
|
|
//--------------------------------------------------------------------------
|
|
bool H5File::isHdf5(const string& name )
|
|
{
|
|
return( isHdf5( name.c_str()) );
|
|
}
|
|
|
|
//--------------------------------------------------------------------------
|
|
// Function: H5File::getLocId
|
|
// Purpose: Get the id of this file
|
|
// Description
|
|
// This function is a redefinition of CommonFG::getLocId. It
|
|
// is used by CommonFG member functions to get the file id.
|
|
// Programmer Binh-Minh Ribler - 2000
|
|
//--------------------------------------------------------------------------
|
|
hid_t H5File::getLocId() const
|
|
{
|
|
return( getId() );
|
|
}
|
|
|
|
//--------------------------------------------------------------------------
|
|
// Function: H5File::reopen
|
|
///\brief Reopens this file
|
|
///\exception H5::FileIException
|
|
// Description
|
|
// If this object has represented another HDF5 file, the previous
|
|
// HDF5 file need to be closed first.
|
|
// Programmer Binh-Minh Ribler - 2000
|
|
//--------------------------------------------------------------------------
|
|
void H5File::reopen()
|
|
{
|
|
// reset the identifier of this H5File - send 'this' in so that
|
|
// H5Fclose can be called appropriately
|
|
try {
|
|
resetIdComponent( this ); }
|
|
catch (Exception close_error) { // thrown by p_close
|
|
throw FileIException("H5File::reopen", close_error.getDetailMsg());
|
|
}
|
|
|
|
// call C routine to reopen the file - Note: not sure about this
|
|
// does id need to be closed later? which id to be the parameter?
|
|
id = H5Freopen( id );
|
|
if( id <= 0 ) // Raise exception when H5Freopen returns a neg value
|
|
{
|
|
throw FileIException("H5File::reopen", "H5Freopen failed");
|
|
}
|
|
}
|
|
|
|
//--------------------------------------------------------------------------
|
|
// Function: H5File::getCreatePlist
|
|
///\brief Returns the creation property list of this file
|
|
///\return FileCreatPropList object
|
|
///\exception H5::FileIException
|
|
// Programmer Binh-Minh Ribler - 2000
|
|
//--------------------------------------------------------------------------
|
|
FileCreatPropList H5File::getCreatePlist() const
|
|
{
|
|
hid_t create_plist_id = H5Fget_create_plist( id );
|
|
|
|
// if H5Fget_create_plist returns a valid id, create and return
|
|
// the FileCreatPropList object for this property list
|
|
if( create_plist_id > 0 )
|
|
{
|
|
FileCreatPropList create_plist( create_plist_id );
|
|
return( create_plist );
|
|
}
|
|
else
|
|
{
|
|
throw FileIException("H5File::getCreatePlist", "H5Fget_create_plist failed");
|
|
}
|
|
}
|
|
|
|
//--------------------------------------------------------------------------
|
|
// Function: H5File::getAccessPlist
|
|
///\brief Returns the access property list of this file
|
|
///\return FileAccPropList object
|
|
///\exception H5::FileIException
|
|
// Programmer Binh-Minh Ribler - 2000
|
|
//--------------------------------------------------------------------------
|
|
FileAccPropList H5File::getAccessPlist() const
|
|
{
|
|
hid_t access_plist_id = H5Fget_access_plist( id );
|
|
|
|
// if H5Fget_access_plist returns a valid id, create and return
|
|
// the FileAccPropList object for this property list
|
|
if( access_plist_id > 0 )
|
|
{
|
|
FileAccPropList access_plist( access_plist_id );
|
|
return access_plist;
|
|
}
|
|
else // Raise an exception
|
|
{
|
|
throw FileIException("H5File::getAccessPlist", "H5Fget_access_plist failed");
|
|
}
|
|
}
|
|
|
|
//--------------------------------------------------------------------------
|
|
// Function: H5File::getFreeSpace
|
|
///\brief Returns the amount of free space in the file.
|
|
///\return Amount of free space
|
|
///\exception H5::FileIException
|
|
// Programmer Binh-Minh Ribler - May 2004
|
|
//--------------------------------------------------------------------------
|
|
hssize_t H5File::getFreeSpace()
|
|
{
|
|
hssize_t free_space = H5Fget_freespace(id);
|
|
if( free_space < 0 )
|
|
{
|
|
throw FileIException("H5File::getFreeSpace", "H5Fget_freespace failed");
|
|
}
|
|
return (free_space);
|
|
}
|
|
|
|
|
|
//--------------------------------------------------------------------------
|
|
// Function: H5File::getObjCount
|
|
///\brief Returns the number of opened object IDs (files, datasets,
|
|
/// groups and datatypes) in the same file.
|
|
///\param types - Type of object to retrieve the count
|
|
///\return Number of opened object IDs
|
|
///\exception H5::FileIException
|
|
///\par Description
|
|
/// The valid values for \a types include:
|
|
/// \li \c H5F_OBJ_FILE Files only
|
|
/// \li \c H5F_OBJ_DATASET Datasets only
|
|
/// \li \c H5F_OBJ_GROUP Groups only
|
|
/// \li \c H5F_OBJ_DATATYPE Named datatypes only
|
|
/// \li \c H5F_OBJ_ATTR Attributes only
|
|
/// \li \c H5F_OBJ_ALL All of the above
|
|
/// \li \c (i.e., H5F_OBJ_FILE | H5F_OBJ_DATASET | H5F_OBJ_GROUP | H5F_OBJ_DATATYPE | H5F_OBJ_ATTR )
|
|
/// Multiple object types can be combined with the logical OR operator (|).
|
|
// Programmer Binh-Minh Ribler - May 2004
|
|
//--------------------------------------------------------------------------
|
|
int H5File::getObjCount(unsigned types)
|
|
{
|
|
int num_objs = H5Fget_obj_count(id, types);
|
|
if( num_objs < 0 )
|
|
{
|
|
throw FileIException("H5File::getObjCount", "H5Fget_obj_count failed");
|
|
}
|
|
return (num_objs);
|
|
}
|
|
|
|
//--------------------------------------------------------------------------
|
|
// Function: H5File::getObjCount
|
|
///\brief This is an overloaded member function, provided for convenience.
|
|
/// It takes no parameter and returns the object count of all
|
|
/// object types.
|
|
///\return Number of opened object IDs
|
|
///\exception H5::FileIException
|
|
// Programmer Binh-Minh Ribler - May 2004
|
|
//--------------------------------------------------------------------------
|
|
int H5File::getObjCount()
|
|
{
|
|
int num_objs = H5Fget_obj_count(id, H5F_OBJ_ALL);
|
|
if( num_objs < 0 )
|
|
{
|
|
throw FileIException("H5File::getObjCount", "H5Fget_obj_count failed");
|
|
}
|
|
return (num_objs);
|
|
}
|
|
|
|
//--------------------------------------------------------------------------
|
|
// Function: H5File::getObjIDs
|
|
///\brief Retrieves a list of opened object IDs (files, datasets,
|
|
/// groups and datatypes) in the same file.
|
|
///\param types - Type of object to retrieve the count
|
|
///\param max_objs - Maximum number of object identifiers to place
|
|
/// into obj_id_list.
|
|
///\param oid_list - List of open object identifiers
|
|
///\exception H5::FileIException
|
|
///\par Description
|
|
/// The valid values for \a types include:
|
|
/// \li \c H5F_OBJ_FILE Files only
|
|
/// \li \c H5F_OBJ_DATASET Datasets only
|
|
/// \li \c H5F_OBJ_GROUP Groups only
|
|
/// \li \c H5F_OBJ_DATATYPE Named datatypes only
|
|
/// \li \c H5F_OBJ_ATTR Attributes only
|
|
/// \li \c H5F_OBJ_ALL All of the above
|
|
/// \li \c (I.e., H5F_OBJ_FILE | H5F_OBJ_DATASET | H5F_OBJ_GROUP | H5F_OBJ_DATATYPE | H5F_OBJ_ATTR )
|
|
/// Multiple object types can be combined with the logical OR operator (|).
|
|
//
|
|
// Notes: will do the overload for this one after hearing from Quincey???
|
|
// Programmer Binh-Minh Ribler - May 2004
|
|
//--------------------------------------------------------------------------
|
|
void H5File::getObjIDs(unsigned types, int max_objs, hid_t *oid_list)
|
|
{
|
|
herr_t ret_value = H5Fget_obj_ids(id, types, max_objs, oid_list);
|
|
if( ret_value < 0 )
|
|
{
|
|
throw FileIException("H5File::getObjIDs", "H5Fget_obj_ids failed");
|
|
}
|
|
}
|
|
|
|
//--------------------------------------------------------------------------
|
|
// Function: H5File::getVFDHandle
|
|
///\brief Returns the pointer to the file handle of the low-level file
|
|
/// driver.
|
|
///\param fapl - File access property list
|
|
///\param file_handle - Pointer to the file handle being used by
|
|
/// the low-level virtual file driver
|
|
///\exception H5::FileIException
|
|
///\par Description
|
|
/// For the FAMILY or MULTI drivers, \a fapl should be
|
|
/// defined through the property list functions:
|
|
/// \c FileAccPropList::setFamilyOffset for the FAMILY driver
|
|
/// and \c FileAccPropList::setMultiType for the MULTI driver.
|
|
///
|
|
/// The obtained file handle is dynamic and is valid only while
|
|
/// the file remains open; it will be invalid if the file is
|
|
/// closed and reopened or opened during a subsequent session.
|
|
// Programmer Binh-Minh Ribler - May 2004
|
|
//--------------------------------------------------------------------------
|
|
void H5File::getVFDHandle(FileAccPropList& fapl, void **file_handle)
|
|
{
|
|
hid_t fapl_id = fapl.getId();
|
|
herr_t ret_value = H5Fget_vfd_handle(id, fapl_id, file_handle);
|
|
if( ret_value < 0 )
|
|
{
|
|
throw FileIException("H5File::getVFDHandle", "H5Fget_vfd_handle failed");
|
|
}
|
|
}
|
|
|
|
//--------------------------------------------------------------------------
|
|
// Function: H5File::getVFDHandle
|
|
///\brief This is an overloaded member function, provided for convenience.
|
|
/// It differs from the above function only in what arguments it
|
|
/// accepts.
|
|
///\param file_handle - Pointer to the file handle being used by
|
|
/// the low-level virtual file driver
|
|
///\exception H5::FileIException
|
|
// Programmer Binh-Minh Ribler - May 2004
|
|
//--------------------------------------------------------------------------
|
|
void H5File::getVFDHandle(void **file_handle)
|
|
{
|
|
herr_t ret_value = H5Fget_vfd_handle(id, H5P_DEFAULT, file_handle);
|
|
if( ret_value < 0 )
|
|
{
|
|
throw FileIException("H5File::getVFDHandle", "H5Fget_vfd_handle failed");
|
|
}
|
|
}
|
|
|
|
//--------------------------------------------------------------------------
|
|
// Function: H5File::p_close (private)
|
|
///\brief Closes this H5 file.
|
|
///\exception H5::FileIException
|
|
///\note
|
|
/// This function will be obsolete because its functionality
|
|
/// is recently handled by the C library layer.
|
|
// Programmer Binh-Minh Ribler - 2000
|
|
//--------------------------------------------------------------------------
|
|
void H5File::p_close() const
|
|
{
|
|
herr_t ret_value = H5Fclose( id );
|
|
if( ret_value < 0 )
|
|
{
|
|
throw FileIException(0, "H5Fclose failed");
|
|
}
|
|
}
|
|
|
|
//--------------------------------------------------------------------------
|
|
// Function: H5File::throwException
|
|
///\brief Throws file exception - initially implemented for CommonFG
|
|
///\param func_name - Name of the function where failure occurs
|
|
///\param msg - Message describing the failure
|
|
///\exception H5::FileIException
|
|
// Description
|
|
// This function is used in CommonFG implementation so that
|
|
// proper exception can be thrown for file or group. The
|
|
// argument func_name is a member of CommonFG and "H5File::"
|
|
// will be inserted to indicate the function called is an
|
|
// implementation of H5File.
|
|
// Programmer Binh-Minh Ribler - 2000
|
|
//--------------------------------------------------------------------------
|
|
void H5File::throwException(const string func_name, const string msg) const
|
|
{
|
|
string full_name = func_name;
|
|
full_name.insert(0, "H5File::");
|
|
throw FileIException(full_name, msg);
|
|
}
|
|
|
|
//--------------------------------------------------------------------------
|
|
// Function: H5File destructor
|
|
///\brief Properly terminates access to this file.
|
|
// Programmer Binh-Minh Ribler - 2000
|
|
//--------------------------------------------------------------------------
|
|
H5File::~H5File()
|
|
{
|
|
// The HDF5 file id will be closed properly
|
|
try {
|
|
resetIdComponent( this ); }
|
|
catch (Exception close_error) { // thrown by p_close
|
|
cerr << "H5File::~H5File - " << close_error.getDetailMsg() << endl;
|
|
}
|
|
}
|
|
|
|
#ifndef H5_NO_NAMESPACE
|
|
} // end namespace
|
|
#endif
|