summaryrefslogtreecommitdiffstats
path: root/c++/src
diff options
context:
space:
mode:
authorBinh-Minh Ribler <bmribler@hdfgroup.org>2004-05-14 17:53:33 (GMT)
committerBinh-Minh Ribler <bmribler@hdfgroup.org>2004-05-14 17:53:33 (GMT)
commit4e7a6b7b1d0bbb882a3ac3f3aeffe042ef187717 (patch)
tree284eb86b117675018ac31a7e90038ee3850fbfcc /c++/src
parent77a7fc4428f5ea1545cded5336ba715934507c4a (diff)
downloadhdf5-4e7a6b7b1d0bbb882a3ac3f3aeffe042ef187717.zip
hdf5-4e7a6b7b1d0bbb882a3ac3f3aeffe042ef187717.tar.gz
hdf5-4e7a6b7b1d0bbb882a3ac3f3aeffe042ef187717.tar.bz2
[svn-r8526] Purpose:
Add more C++ wrappers - incrementally check-in Description: Added more wrappers for C H5F functions and added Doxygen documentation to existing member functions of H5File. This is an incremental check-in to preserve the code, corresponding tests will follow in a few weeks. Newly added wrappers are for: H5Fget_freespace H5Fget_obj_count H5Fget_obj_ids H5Fget_vfd_handle Platforms: SunOS 5.7 (arabica) Linux 2.4 (eirene) Windows 2000
Diffstat (limited to 'c++/src')
-rw-r--r--c++/src/H5File.cpp314
-rw-r--r--c++/src/H5File.h19
2 files changed, 309 insertions, 24 deletions
diff --git a/c++/src/H5File.cpp b/c++/src/H5File.cpp
index e85700c..d46f628 100644
--- a/c++/src/H5File.cpp
+++ b/c++/src/H5File.cpp
@@ -42,15 +42,64 @@
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
+// Date 2000
+//--------------------------------------------------------------------------
H5File::H5File() : IdComponent() {}
-// Creates or opens an HDF5 file depending on the parameter flags.
+//--------------------------------------------------------------------------
+// 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
+// Date 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
+// Date 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 );
@@ -58,6 +107,8 @@ H5File::H5File( const char* name, unsigned int flags, const FileCreatPropList& c
// This function is private and contains common code between the
// constructors taking a string or a char*
+// Programmer Binh-Minh Ribler
+// Date 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,
@@ -85,14 +136,24 @@ 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
+// Programmer Binh-Minh Ribler
+// Date 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
+// Date 2000
+//--------------------------------------------------------------------------
bool H5File::isHdf5(const char* name )
{
// Calls C routine H5Fis_hdf5 to determine whether the file is in
@@ -107,15 +168,43 @@ bool H5File::isHdf5(const char* name )
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
+// Date 2000
+//--------------------------------------------------------------------------
+bool H5File::isHdf5(const string& name )
+{
+ return( isHdf5( name.c_str()) );
+}
-// Get id of the location, which id the file id here; used by CommonFG
-// member functions
+//--------------------------------------------------------------------------
+// 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
+// Date 2000
+//--------------------------------------------------------------------------
hid_t H5File::getLocId() const
{
return( getId() );
}
-// 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
+// Date 2000
+//--------------------------------------------------------------------------
void H5File::reopen()
{
// reset the identifier of this H5File - send 'this' in so that
@@ -135,7 +224,14 @@ 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
+// Date 2000
+//--------------------------------------------------------------------------
FileCreatPropList H5File::getCreatePlist() const
{
hid_t create_plist_id = H5Fget_create_plist( id );
@@ -153,7 +249,14 @@ 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
+// Date 2000
+//--------------------------------------------------------------------------
FileAccPropList H5File::getAccessPlist() const
{
hid_t access_plist_id = H5Fget_access_plist( id );
@@ -171,6 +274,158 @@ FileAccPropList H5File::getAccessPlist() 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
+// Date 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
+// Date 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
+// Date 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
+// Date 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
+// Date 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
+// Date 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");
+ }
+}
+
// Calls the C API H5Fclose to close this file. Used by IdComponent::reset
void H5File::p_close() const
{
@@ -181,10 +436,21 @@ 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
+// Date 2000
+//--------------------------------------------------------------------------
void H5File::throwException(const string func_name, const string msg) const
{
string full_name = func_name;
@@ -192,11 +458,15 @@ 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::getVFDHandle
+///\brief This is an overloaded member function, provided for convenience.
+/// It differs from the above function only in what arguments it
+/// accepts.
+///\exception H5::FileIException
+// Programmer Binh-Minh Ribler
+// Date 2000
+//--------------------------------------------------------------------------
H5File::~H5File()
{
// The HDF5 file id will be closed properly
diff --git a/c++/src/H5File.h b/c++/src/H5File.h
index 2e088ad..3edc6a3 100644
--- a/c++/src/H5File.h
+++ b/c++/src/H5File.h
@@ -39,9 +39,21 @@ 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();
+
+ // Returns the number of opened object IDs (files, datasets, groups
+ // and datatypes) in the same file.
+ int getObjCount(unsigned types);
+ int getObjCount();
+
+ // 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);
+ // Returns the pointer to the file handle of the low-level file driver.
+ void getVFDHandle(FileAccPropList& fapl, void **file_handle);
+ void getVFDHandle(void **file_handle);
// Determines if a file, specified by its name, is in HDF5 format
static bool isHdf5(const string& name );
@@ -56,6 +68,9 @@ class H5_DLLCPP H5File : public IdComponent, public CommonFG {
// Gets the access property list of this file
FileAccPropList getAccessPlist() const;
+ // 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;