H5::H5File Class Reference

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 getObjType (void *ref, H5R_type_t ref_type=H5R_OBJECT) const

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

• 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

  Returns this class name.
  

• 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

  For subclasses, H5File and Group, to return the correct object id, i.e. file or group id.
  

• 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 object 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: http://www.hdfgroup.org/HDF5/doc/RM/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

(

const H5File &

original

)

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

Parameters:

original

- IN: H5File instance to copy

References H5::IdComponent::incRefCount().

---

Member Function Documentation

void H5::H5File::close

(

)

[virtual]

Closes this HDF5 file.

Exceptions:

H5::FileIException

Implements H5::IdComponent.

References H5::IdComponent::getCounter().

Referenced by p_setId(), reOpen(), and ~H5File().

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

References H5::Exception::getDetailMsg().

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

(

)

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

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 (|).

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::getObjType	(	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 - Reference is an object reference. H5R_DATASET_REGION - Reference 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

References H5::Exception::getDetailMsg().

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

References H5::Exception::getDetailMsg().

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

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.

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

References isHdf5().

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

Referenced by isHdf5().

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::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::p_setId

(

const hid_t

new_id

)

[protected, virtual]

Sets the identifier of this object to a new value.

Exceptions:

H5::IdComponentException

when the attempt to close the HDF5 object fails

Implements H5::IdComponent.

References close(), and H5::Exception::getDetailMsg().

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

References reference().

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

References H5::Exception::getDetailMsg().

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 - Reference is an object reference. H5R_DATASET_REGION - Reference is a dataset region reference. - this is the default

Exceptions:

H5::IdComponentException

References H5::Exception::getDetailMsg().

Referenced by reference().

void H5::H5File::reopen

(

)

Reopens this file.

Exceptions:

H5::FileIException

Description

This function will be replaced by the above function reOpen in future releases.

References reOpen().

void H5::H5File::reOpen

(

)

Reopens this file.

Exceptions:

H5::FileIException

References close(), and H5::Exception::getDetailMsg().

Referenced by reopen().

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.