HDF5 C++ API Reference Manual

 

 

 

H5::H5File Class Reference

#include <H5File.h>

Inheritance diagram for H5::H5File:

H5::IdComponent H5::CommonFG List of all members.

Public Member Functions

 H5File (const char *name, unsigned int flags, const FileCreatPropList &create_plist=FileCreatPropList::DEFAULT, const FileAccPropList &access_plist=FileAccPropList::DEFAULT)
 Creates or opens an HDF5 file depending on the parameter flags.
 H5File (const H5std_string &name, unsigned int flags, const FileCreatPropList &create_plist=FileCreatPropList::DEFAULT, const FileAccPropList &access_plist=FileAccPropList::DEFAULT)
 This is another overloaded constructor. It differs from the above constructor only in the type of the name argument.
void openFile (const H5std_string &name, unsigned int flags, const FileAccPropList &access_plist=FileAccPropList::DEFAULT)
 This is an overloaded member function, provided for convenience. It takes an H5std_string for name.
void openFile (const char *name, unsigned int flags, const FileAccPropList &access_plist=FileAccPropList::DEFAULT)
 Opens an HDF5 file.
virtual void close ()
 Closes this HDF5 file.
void flush (H5F_scope_t scope) const
 Flushes all buffers associated with a file to disk.
FileAccPropList getAccessPlist () const
 Returns the access property list of this file.
FileCreatPropList getCreatePlist () const
 Returns the creation property list of this file.
H5std_string getFileName () const
 Gets the name of this file.
hsize_t getFileSize () const
 Returns the file size of the HDF5 file.
hssize_t getFreeSpace () const
 Returns the amount of free space in the file.
ssize_t getObjCount (unsigned types) const
 Returns the number of opened object IDs (files, datasets, groups and datatypes) in the same file.
ssize_t getObjCount () const
 This is an overloaded member function, provided for convenience. It takes no parameter and returns the object count of all object types.
void getObjIDs (unsigned types, size_t max_objs, hid_t *oid_list) const
 Retrieves a list of opened object IDs (files, datasets, groups and datatypes) in the same file.
H5G_obj_t getRefObjType (void *ref, H5R_type_t ref_type=H5R_OBJECT) const
 Retrieves the type of object that an object reference points to.
H5G_obj_t getObjType (void *ref, H5R_type_t ref_type=H5R_OBJECT) const
 This function was misnamed and will be deprecated in favor of H5File::getRefObjType; please use getRefObjType instead.
DataSpace getRegion (void *ref, H5R_type_t ref_type=H5R_DATASET_REGION) const
 Retrieves a dataspace with the region pointed to selected.
void getVFDHandle (FileAccPropList &fapl, void **file_handle) const
 Returns the pointer to the file handle of the low-level file driver.
void getVFDHandle (void **file_handle) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.
void reOpen ()
 Reopens this file.
void reopen ()
 Reopens this file.
void reference (void *ref, const char *name, const DataSpace &dataspace, H5R_type_t ref_type=H5R_DATASET_REGION) const
 Creates a reference to an HDF5 object or a dataset region.
void reference (void *ref, const char *name) const
 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.
void reference (void *ref, const H5std_string &name) const
 This is an overloaded function, provided for your convenience. It differs from the above function in that it takes an H5std_string for the object's name.
virtual H5std_string fromClass () const
virtual void throwException (const H5std_string &func_name, const H5std_string &msg) const
 Throws file exception - initially implemented for CommonFG.
virtual hid_t getLocId () const
 H5File ()
 Default constructor: creates a stub H5File object.
 H5File (const H5File &original)
 Copy constructor: makes a copy of the original H5File object.
virtual hid_t getId () const
virtual ~H5File ()
 Properly terminates access to this file.

Static Public Member Functions

static bool isHdf5 (const char *name)
 Determines whether a file in HDF5 format.
static bool isHdf5 (const H5std_string &name)
 This is an overloaded member function, provided for convenience. It takes an H5std_string for name.

Protected Member Functions

virtual void p_setId (const hid_t new_id)
 Sets the identifier of this HDF5 file to a new value.

Detailed Description

Examples:

chunks.cpp, compound.cpp, create.cpp, extend_ds.cpp, h5group.cpp, readdata.cpp, and writedata.cpp.


Constructor & Destructor Documentation

H5::H5File::H5File ( const char *  name,
unsigned int  flags,
const FileCreatPropList create_plist = FileCreatPropList::DEFAULT,
const FileAccPropList access_plist = FileAccPropList::DEFAULT 
)

Creates or opens an HDF5 file depending on the parameter flags.

Parameters:
name - IN: Name of the file
flags - IN: File access flags
create_plist - IN: File creation property list, used when modifying default file meta-data. Default to FileCreatPropList::DEFAULT
access_plist - IN: File access property list. Default to FileCreatPropList::DEFAULT
Description
Valid values of flags include:
  • H5F_ACC_TRUNC - Truncate file, if it already exists, erasing all data previously stored in the file.
  • H5F_ACC_EXCL - Fail if file already exists. H5F_ACC_TRUNC and H5F_ACC_EXCL are mutually exclusive
  • 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.
For info on file creation in the case of an already-open file, please refer to the Special case section in the C layer Reference Manual at: ../RM_H5F.html::File-Create

H5::H5File::H5File ( const H5std_string &  name,
unsigned int  flags,
const FileCreatPropList create_plist = FileCreatPropList::DEFAULT,
const FileAccPropList access_plist = FileAccPropList::DEFAULT 
)

This is another overloaded constructor. It differs from the above constructor only in the type of the name argument.

Parameters:
name - IN: Name of the file - H5std_string
flags - IN: File access flags
create_plist - IN: File creation property list, used when modifying default file meta-data. Default to FileCreatPropList::DEFAULT
access_plist - IN: File access property list. Default to FileCreatPropList::DEFAULT

H5::H5File::H5File (  ) 

Default constructor: creates a stub H5File object.

H5::H5File::H5File ( const H5File original  ) 

Copy constructor: makes a copy of the original H5File object.

Parameters:
original - IN: H5File instance to copy

H5::H5File::~H5File (  )  [virtual]

Properly terminates access to this file.


Member Function Documentation

void H5::H5File::openFile ( const H5std_string &  name,
unsigned int  flags,
const FileAccPropList access_plist = FileAccPropList::DEFAULT 
)

This is an overloaded member function, provided for convenience. It takes an H5std_string for name.

Parameters:
name - IN: Name of the file - H5std_string
flags - IN: File access flags
access_plist - IN: File access property list. Default to FileAccPropList::DEFAULT

void H5::H5File::openFile ( const char *  name,
unsigned int  flags,
const FileAccPropList access_plist = FileAccPropList::DEFAULT 
)

Opens an HDF5 file.

Parameters:
name - IN: Name of the file
flags - IN: File access flags
access_plist - IN: File access property list. Default to FileCreatPropList::DEFAULT
Description
Valid values of flags include: H5F_ACC_RDWR: Open with read/write access. If the file is currently open for read-only access then it will be reopened. Absence of this flag implies read-only access.
H5F_ACC_RDONLY: Open with read only access. - default

void H5::H5File::close (  )  [virtual]

Closes this HDF5 file.

Exceptions:
H5::FileIException 

void H5::H5File::flush ( H5F_scope_t  scope  )  const

Flushes all buffers associated with a file to disk.

Parameters:
scope - IN: Specifies the scope of the flushing action, which can be either of these values:
  • H5F_SCOPE_GLOBAL - Flushes the entire virtual file
  • H5F_SCOPE_LOCAL - Flushes only the specified file
Exceptions:
H5::FileIException 

FileAccPropList H5::H5File::getAccessPlist (  )  const

Returns the access property list of this file.

Returns:
FileAccPropList object
Exceptions:
H5::FileIException 

FileCreatPropList H5::H5File::getCreatePlist (  )  const

Returns the creation property list of this file.

Returns:
FileCreatPropList object
Exceptions:
H5::FileIException 

H5std_string H5::H5File::getFileName (  )  const

Gets the name of this file.

Returns:
File name
Exceptions:
H5::FileIException 

hsize_t H5::H5File::getFileSize (  )  const

Returns the file size of the HDF5 file.

Returns:
File size
Exceptions:
H5::FileIException 
Description
This function is called after an existing file is opened in order to learn the true size of the underlying file.

hssize_t H5::H5File::getFreeSpace (  )  const

Returns the amount of free space in the file.

Returns:
Amount of free space
Exceptions:
H5::FileIException 

ssize_t H5::H5File::getObjCount ( unsigned  types  )  const

Returns the number of opened object IDs (files, datasets, groups and datatypes) in the same file.

Parameters:
types - Type of object to retrieve the count
Returns:
Number of opened object IDs
Exceptions:
H5::FileIException 
Description
The valid values for types include:
  • H5F_OBJ_FILE - Files only
  • H5F_OBJ_DATASET - Datasets only
  • H5F_OBJ_GROUP - Groups only
  • H5F_OBJ_DATATYPE - Named datatypes only
  • H5F_OBJ_ATTR - Attributes only
  • H5F_OBJ_ALL - All of the above, 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 (|).

ssize_t H5::H5File::getObjCount (  )  const

This is an overloaded member function, provided for convenience. It takes no parameter and returns the object count of all object types.

Returns:
Number of opened object IDs
Exceptions:
H5::FileIException 

void H5::H5File::getObjIDs ( unsigned  types,
size_t  max_objs,
hid_t *  oid_list 
) const

Retrieves a list of opened object IDs (files, datasets, groups and datatypes) in the same file.

Parameters:
types - Type of object to retrieve the count
max_objs - Maximum number of object identifiers to place into obj_id_list.
oid_list - List of open object identifiers
Exceptions:
H5::FileIException 
Description
The valid values for types include:
  • H5F_OBJ_FILE - Files only
  • H5F_OBJ_DATASET - Datasets only
  • H5F_OBJ_GROUP - Groups only
  • H5F_OBJ_DATATYPE - Named datatypes only
  • H5F_OBJ_ATTR - Attributes only
  • H5F_OBJ_ALL - All of the above, 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 (|).

H5G_obj_t H5::H5File::getRefObjType ( void *  ref,
H5R_type_t  ref_type = H5R_OBJECT 
) const

Retrieves the type of object that an object reference points to.

Parameters:
ref - IN: Reference to query
ref_type - IN: Type of reference, valid values are:
  • H5R_OBJECT is an object reference.
  • H5R_DATASET_REGION is a dataset region reference.
Returns:
Object type, which can be one of the following:
  • H5G_LINK - Object is a symbolic link.
  • H5G_GROUP - Object is a group.
  • H5G_DATASET - Object is a dataset.
  • H5G_TYPE - Object is a named datatype
Exceptions:
H5::FileIException 

H5G_obj_t H5::H5File::getObjType ( void *  ref,
H5R_type_t  ref_type = H5R_OBJECT 
) const

This function was misnamed and will be deprecated in favor of H5File::getRefObjType; please use getRefObjType instead.

DataSpace H5::H5File::getRegion ( void *  ref,
H5R_type_t  ref_type = H5R_DATASET_REGION 
) const

Retrieves a dataspace with the region pointed to selected.

Parameters:
ref - IN: Reference to get region of
ref_type - IN: Type of reference to get region of - default
Returns:
DataSpace instance
Exceptions:
H5::FileIException 

void H5::H5File::getVFDHandle ( FileAccPropList fapl,
void **  file_handle 
) const

Returns the pointer to the file handle of the low-level file driver.

Parameters:
fapl - File access property list
file_handle - Pointer to the file handle being used by the low-level virtual file driver
Exceptions:
H5::FileIException 
Description
For the FAMILY or MULTI drivers, fapl should be defined through the property list functions: FileAccPropList::setFamilyOffset for the FAMILY driver and 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.

void H5::H5File::getVFDHandle ( void **  file_handle  )  const

This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

Parameters:
file_handle - Pointer to the file handle being used by the low-level virtual file driver
Exceptions:
H5::FileIException 

bool H5::H5File::isHdf5 ( const char *  name  )  [static]

Determines whether a file in HDF5 format.

Parameters:
name - IN: Name of the file
Returns:
true if the file is in HDF5 format, and false, otherwise
Exceptions:
H5::FileIException 

bool H5::H5File::isHdf5 ( const H5std_string &  name  )  [static]

This is an overloaded member function, provided for convenience. It takes an H5std_string for name.

Parameters:
name - IN: Name of the file - H5std_string

void H5::H5File::reOpen (  ) 

Reopens this file.

Exceptions:
H5::FileIException 

void H5::H5File::reopen (  ) 

Reopens this file.

Exceptions:
H5::FileIException 
Description
This function will be replaced by the above function reOpen in future releases.

void H5::H5File::reference ( void *  ref,
const char *  name,
const DataSpace dataspace,
H5R_type_t  ref_type = H5R_DATASET_REGION 
) const

Creates a reference to an HDF5 object or a dataset region.

Parameters:
ref - IN: Reference pointer
name - IN: Name of the object to be referenced
dataspace - IN: Dataspace with selection
ref_type - IN: Type of reference to query, valid values are:
  • H5R_OBJECT is an object reference.
  • H5R_DATASET_REGION is a dataset region reference. - this is the default
Exceptions:
H5::IdComponentException 

void H5::H5File::reference ( void *  ref,
const char *  name 
) const

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.

Parameters:
ref - IN: Reference pointer
name - IN: Name of the object to be referenced - char pointer
Exceptions:
H5::IdComponentException 
Description

void H5::H5File::reference ( void *  ref,
const H5std_string &  name 
) const

This is an overloaded function, provided for your convenience. It differs from the above function in that it takes an H5std_string for the object's name.

Parameters:
ref - IN: Reference pointer
name - IN: Name of the object to be referenced - H5std_string

virtual H5std_string H5::H5File::fromClass (  )  const [inline, virtual]

void H5::H5File::throwException ( const H5std_string &  func_name,
const H5std_string &  msg 
) const [virtual]

Throws file exception - initially implemented for CommonFG.

Parameters:
func_name - Name of the function where failure occurs
msg - Message describing the failure
Exceptions:
H5::FileIException 

Implements H5::CommonFG.

hid_t H5::H5File::getLocId (  )  const [virtual]

hid_t H5::H5File::getId (  )  const [virtual]

Implements H5::IdComponent.

Examples:
h5group.cpp.

void H5::H5File::p_setId ( const hid_t  new_id  )  [protected, virtual]

Sets the identifier of this HDF5 file to a new value.

Exceptions:
H5::IdComponentException when the attempt to close the HDF5 object fails


Generated on Wed Nov 4 14:13:07 2009 by  doxygen 1.4.7