diff options
Diffstat (limited to 'c++/src')
-rw-r--r-- | c++/src/H5File.cpp | 418 | ||||
-rw-r--r-- | c++/src/H5File.h | 47 |
2 files changed, 416 insertions, 49 deletions
diff --git a/c++/src/H5File.cpp b/c++/src/H5File.cpp index f44d6f0..e3c98ff 100644 --- a/c++/src/H5File.cpp +++ b/c++/src/H5File.cpp @@ -42,23 +42,72 @@ namespace H5 { #endif -// Default constructor +//-------------------------------------------------------------------------- +// 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() {} -// Creates or opens an HDF5 file depending on the parameter flags. -H5File::H5File( const string& name, unsigned int flags, const FileCreatPropList& create_plist, const FileAccPropList& access_plist ) : 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 char* name, unsigned int flags, const FileCreatPropList& create_plist, const FileAccPropList& access_plist ) : IdComponent() { - getFile( name.c_str(), flags, create_plist, access_plist ); + p_get_file(name, flags, create_plist, access_plist); } -H5File::H5File( const char* name, unsigned int flags, const FileCreatPropList& create_plist, const FileAccPropList& access_plist ) : IdComponent() +//-------------------------------------------------------------------------- +// 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 string& name, unsigned int flags, const FileCreatPropList& create_plist, const FileAccPropList& access_plist ) : IdComponent() { - getFile( name, flags, create_plist, access_plist ); + p_get_file(name.c_str(), flags, create_plist, access_plist); } +//-------------------------------------------------------------------------- // This function is private and contains common code between the // constructors taking a string or a char* -void H5File::getFile( const char* name, unsigned int flags, const FileCreatPropList& create_plist, const FileAccPropList& access_plist ) +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +void H5File::p_get_file(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. @@ -85,14 +134,23 @@ void H5File::getFile( const char* name, unsigned int flags, const FileCreatPropL } } -// Copy constructor: makes a copy of the original H5File object. +//-------------------------------------------------------------------------- +// 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 ) {} -// Determines whether a file specified by its name in HDF5 format -bool H5File::isHdf5(const string& name ) -{ - return( isHdf5( name.c_str()) ); -} +//-------------------------------------------------------------------------- +// 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 @@ -108,14 +166,27 @@ bool H5File::isHdf5(const char* name ) } } -// Get id of the location, which id the file id here; used by CommonFG -// member functions -hid_t H5File::getLocId() const +//-------------------------------------------------------------------------- +// 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 - \c std::string +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +bool H5File::isHdf5(const string& name ) { - return( getId() ); + return( isHdf5( name.c_str()) ); } -// Reopens this file +//-------------------------------------------------------------------------- +// 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 @@ -135,7 +206,13 @@ void H5File::reopen() } } -// Returns the creation property list of this file +//-------------------------------------------------------------------------- +// 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 ); @@ -153,7 +230,13 @@ FileCreatPropList H5File::getCreatePlist() const } } -// Returns the access property list of this file +//-------------------------------------------------------------------------- +// 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 ); @@ -171,23 +254,268 @@ FileAccPropList H5File::getAccessPlist() const } } -// Retrieves the file size of the HDF5 file. This function -// is called after an existing file is opened in order -// to learn the true size of the underlying file. -// (Raymond Lu) -herr_t H5File::getFileSize(hsize_t *size) const +//-------------------------------------------------------------------------- +// 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() const +{ + 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) const +{ + 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() const +{ + 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) const { - herr_t ret; - - ret = H5Fget_filesize(id, size); - if( ret < 0 ) + 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) const +{ + 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) const +{ + 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::Reference +///\brief Creates a reference to an Hdf5 object or a dataset region. +///\param name - IN: Name of the object to be referenced +///\param dataspace - IN: Dataspace with selection +///\param ref_type - IN: Type of reference; default to \c H5R_DATASET_REGION +///\return A reference +///\exception H5::ReferenceIException +///\par Description +/// Note that, for H5File, name must be an absolute path to the +/// object in the file. +// Programmer Binh-Minh Ribler - May, 2004 +//-------------------------------------------------------------------------- +void* H5File::Reference(const char* name, DataSpace& dataspace, H5R_type_t ref_type) const +{ + return(p_reference(name, dataspace.getId(), ref_type)); +} + +//-------------------------------------------------------------------------- +// Function: H5File::Reference +///\brief This is an overloaded function, provided for your convenience. +/// It differs from the above function in that it only creates +/// a reference to an HDF5 object, not to a dataset region. +///\param name - IN: Name of the object to be referenced +///\return A reference +///\exception H5::ReferenceIException +///\par Description +// This function passes H5R_OBJECT and -1 to the protected +// function for it to pass to the C API H5Rcreate +// to create a reference to the named object. +///\par +/// Note that, for H5File, name must be an absolute path to the +/// object in the file. +// Programmer Binh-Minh Ribler - May, 2004 +//-------------------------------------------------------------------------- +void* H5File::Reference(const char* name) const +{ + return(p_reference(name, -1, H5R_OBJECT)); +} + +//-------------------------------------------------------------------------- +// Function: H5File::getObjType +///\brief Retrieves the type of object that an object reference points to. +///\param ref - IN: Reference to query +///\param ref_type - IN: Type of reference to query +///\return Object type, which can be one of the following: +/// \li \c H5G_LINK Object is a symbolic link. +/// \li \c H5G_GROUP Object is a group. +/// \li \c H5G_DATASET Object is a dataset. +/// \li \c H5G_TYPE Object is a named datatype +///\exception H5::ReferenceIException +// Programmer Binh-Minh Ribler - May, 2004 +//-------------------------------------------------------------------------- +H5G_obj_t H5File::getObjType(void *ref, H5R_type_t ref_type) const +{ + return(p_get_obj_type(ref, ref_type)); +} + +//-------------------------------------------------------------------------- +// Function: H5File::getRegion +///\brief Retrieves a dataspace with the region pointed to selected. +///\param ref - IN: Reference to get region of +///\param ref_type - IN: Type of reference to get region of - default +///\return DataSpace instance +///\exception H5::ReferenceIException +// Programmer Binh-Minh Ribler - May, 2004 +//-------------------------------------------------------------------------- +DataSpace H5File::getRegion(void *ref, H5R_type_t ref_type) const +{ + DataSpace dataspace(p_get_region(ref, ref_type)); + return(dataspace); +} + +//-------------------------------------------------------------------------- +// Function: H5File::getFileSize +///\brief Returns the file size of the HDF5 file. +///\return File size +///\exception H5::FileIException +///\par Description +/// This function is called after an existing file is opened in +/// order to learn the true size of the underlying file. +// Programmer Raymond Lu - June 24, 2004 +//-------------------------------------------------------------------------- +hsize_t H5File::getFileSize() const +{ + hsize_t file_size; + herr_t ret_value = H5Fget_filesize(id, &file_size); + if (ret_value < 0) { throw FileIException("H5File::getFileSize", "H5Fget_filesize failed"); } - return ret; + return (file_size); +} + +//-------------------------------------------------------------------------- +// 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() ); } -// Calls the C API H5Fclose to close this file. Used by IdComponent::reset +//-------------------------------------------------------------------------- +// 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 ); @@ -197,10 +525,20 @@ void H5File::p_close() const } } -// Throw file exception; used in CommonFG implementation so that proper -// exception can be thrown for file or group. The func_name is a member -// function of CommonFG and "H5File::" will be inserted to indicate the -// function called is an implementation of H5File +//-------------------------------------------------------------------------- +// 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; @@ -208,11 +546,11 @@ void H5File::throwException(const string func_name, const string msg) const throw FileIException(full_name, msg); } -// The destructor of this instance calls IdComponent::reset to -// reset its identifier - no longer true -// Older compilers (baldric) don't support template member functions -// and IdComponent::reset is one; so at this time, the resetId is not -// a member function so it can be template to work around that problem. +//-------------------------------------------------------------------------- +// 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 diff --git a/c++/src/H5File.h b/c++/src/H5File.h index d1fe153..900681e 100644 --- a/c++/src/H5File.h +++ b/c++/src/H5File.h @@ -39,35 +39,64 @@ class H5_DLLCPP H5File : public IdComponent, public CommonFG { // Gets the file id virtual hid_t getLocId() const; - // Throw file exception - virtual void throwException(const string func_name, const string msg) const; + // Returns the amount of free space in the file. + hssize_t getFreeSpace() const; + + // Returns the number of opened object IDs (files, datasets, groups + // and datatypes) in the same file. + int getObjCount(unsigned types) const; + int getObjCount() const; + + // Retrieves a list of opened object IDs (files, datasets, groups + // and datatypes) in the same file. + void getObjIDs(unsigned types, int max_objs, hid_t *oid_list) const; + // Returns the pointer to the file handle of the low-level file driver. + void getVFDHandle(FileAccPropList& fapl, void **file_handle) const; + void getVFDHandle(void **file_handle) 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(); + // Creates a reference to a named Hdf5 object in this object. + void* Reference(const char* name) const; + + // Creates a reference to a named Hdf5 object or to a dataset region + // in this object. + void* Reference(const char* name, DataSpace& dataspace, H5R_type_t ref_type = H5R_DATASET_REGION) const; + + // Retrieves the type of object that an object reference points to. + H5G_obj_t getObjType(void *ref, H5R_type_t ref_type) const; + + // Retrieves a dataspace with the region pointed to selected. + DataSpace getRegion(void *ref, H5R_type_t ref_type = H5R_DATASET_REGION) const; // Retrieves the file size of an opened file. - herr_t getFileSize(hsize_t *size) const; + hsize_t getFileSize() const; + + // Reopens this file. + void reopen(); - // Gets the creation property list of this file + // Gets the creation property list of this file. FileCreatPropList getCreatePlist() const; - // Gets the access property list of this file + // Gets the access property list of this file. FileAccPropList getAccessPlist() const; - // Used by the API to appropriately close a file + // Throw file exception. + virtual void throwException(const string func_name, const string msg) const; + + // Used by the API to appropriately close a file. void p_close() const; + // H5File destructor. virtual ~H5File(); private: // This function is private and contains common code between the // constructors taking a string or a char* - void getFile( const char* name, unsigned int flags, const FileCreatPropList& create_plist, const FileAccPropList& access_plist ); + void p_get_file( const char* name, unsigned int flags, const FileCreatPropList& create_plist, const FileAccPropList& access_plist ); }; #ifndef H5_NO_NAMESPACE |