#include <E57Format.h>

Public Member Functions
void	cancel ()
	Stop I/O operations and delete a partially written ImageFile on the disk. More...

void	checkInvariant (bool doRecurse=true) const
	Check whether ImageFile class invariant is true. More...

void	close ()
	Complete any write operations on an ImageFile, and close the file on the disk. More...

void	dump (int indent=0, std::ostream &os=std::cout) const
	Diagnostic function to print internal state of object to output stream in an indented format. More...

void	elementNameParse (const ustring &elementName, ustring &prefix, ustring &localPart) const
	Parse element name into prefix and localPart substrings. More...

void	extensionsAdd (const ustring &prefix, const ustring &uri)
	Declare the use of an E57 extension in an ImageFile being written. More...

size_t	extensionsCount () const
	Get number of E57 extensions declared in the ImageFile. More...

bool	extensionsLookupPrefix (const ustring &prefix, ustring &uri) const
	Get URI associated with an E57 extension prefix in the ImageFile. More...

bool	extensionsLookupUri (const ustring &uri, ustring &prefix) const
	Get an E57 extension prefix associated with a URI in the ImageFile. More...

ustring	extensionsPrefix (const size_t index) const
	Get an E57 extension prefix declared in an ImageFile by index. More...

ustring	extensionsUri (const size_t index) const
	Get an E57 extension URI declared in an ImageFile by index. More...

ustring	fileName () const
	Get the file name the ImageFile was created with. More...

	ImageFile ()=delete

	ImageFile (const char *input, const uint64_t size, ReadChecksumPolicy checksumPolicy=CHECKSUM_POLICY_ALL)

	ImageFile (const ustring &fname, const ustring &mode, ReadChecksumPolicy checksumPolicy=CHECKSUM_POLICY_ALL)
	Open an ASTM E57 imaging data file for reading/writing. More...

bool	isElementNameExtended (const ustring &elementName) const
	Test whether an E57 element name has an extension prefix. More...

bool	isOpen () const
	Test whether ImageFile is still open for accessing. More...

bool	isWritable () const
	Test whether ImageFile was opened in write mode. More...

bool	operator!= (ImageFile imf2) const
	Test if two ImageFile handles refer to different underlying ImageFile. More...

bool	operator== (ImageFile imf2) const
	Test if two ImageFile handles refer to the same underlying ImageFile. More...

int	readerCount () const
	Get current number of open CompressedVectorReader objects reading from ImageFile. More...

StructureNode	root () const
	Get the pre-established root StructureNode of the E57 ImageFile. More...

int	writerCount () const
	Get current number of open CompressedVectorWriter objects writing to ImageFile. More...

Constructor & Destructor Documentation

◆ ImageFile() [1/3]

e57::ImageFile::ImageFile ( )

delete

◆ ImageFile() [2/3]

ImageFile::ImageFile	(	const ustring &	fname,
		const ustring &	mode,
		ReadChecksumPolicy	checksumPolicy = `CHECKSUM_POLICY_ALL`
	)

Open an ASTM E57 imaging data file for reading/writing.

Parameters

[in]	fname	File name to open. Support of '\' as a directory separating character is system dependent. For maximum portability, it is recommended that '/' be used as a directory separator in file names. Special device file name support are implementation dependent (e.g. "\\.\PhysicalDrive3" or "/dev/hd3"). It is recommended that files that meet all of the requirements for a legal ASTM E57 file format use the extension `".e57"`. It is recommended that files that utilize the low-level E57 element data types, but do not have all the required element names required by ASTM E57 file format standard use the file extension `"._e57"`.
[in]	mode	Either "w" for writing or "r" for reading.
[in]	checksumPolicy	The percentage of checksums we compute and verify as an int. Clamped to 0-100.

Write Mode: In write mode, the file cannot be already open. A file with name given by fname is immediately created on the disk. This file may grow as a result of operations on the ImageFile. Which API functions write data to the file are implementation dependent. Thus any API operation that stores data may fail as a result of insufficient free disk space. Read API operations are legal for an ImageFile opened in write mode.

Read Mode: Read mode files may be shared. Write API operations are not legal for an ImageFile opened in read mode (i.e. the ImageFile is read-only). There is no API support for appending data onto an existing E57 data file.

Postcondition: Resulting ImageFile is in open state if constructor succeeds (no exception thrown).

Returns: A smart ImageFile handle referencing the underlying object.

Exceptions

E57_ERROR_BAD_API_ARGUMENT
E57_ERROR_OPEN_FAILED
E57_ERROR_LSEEK_FAILED
E57_ERROR_READ_FAILED
E57_ERROR_WRITE_FAILED
E57_ERROR_BAD_CHECKSUM
E57_ERROR_BAD_FILE_SIGNATURE
E57_ERROR_UNKNOWN_FILE_VERSION
E57_ERROR_BAD_FILE_LENGTH
E57_ERROR_XML_PARSER_INIT
E57_ERROR_XML_PARSER
E57_ERROR_BAD_XML_FORMAT
E57_ERROR_BAD_CONFIGURATION
E57_ERROR_INTERNAL	All objects in undocumented state

See also: IntegerNode, ScaledIntegerNode, FloatNode, StringNode, BlobNode, StructureNode, VectorNode, CompressedVectorNode, E57Exception, E57Utilities::E57Utilities

Do second phase of construction, now that ImageFile object is complete.

◆ ImageFile() [3/3]

ImageFile::ImageFile	(	const char *	input,
		const uint64_t	size,
		ReadChecksumPolicy	checksumPolicy = `CHECKSUM_POLICY_ALL`
	)

Member Function Documentation

◆ cancel()

void ImageFile::cancel ( )

Stop I/O operations and delete a partially written ImageFile on the disk.

If the ImageFile is write mode, the associated file on the disk is closed and deleted, and the ImageFile goes to the closed state. If the ImageFile is read mode, the behavior is same as calling ImageFile::close, but no exceptions are thrown. It is not an error if ImageFile is already closed.

Postcondition: ImageFile is in closed state.

Exceptions

No	E57Exceptions.

See also: ImageFile::ImageFile, ImageFile::close, ImageFile::isOpen

Referenced by DraftGui.DraftToolBar::finish(), DraftGui.DraftToolBar::offUi(), and DraftGui.DraftToolBar::pointUi().

◆ checkInvariant()

void ImageFile::checkInvariant ( bool doRecurse = true ) const

Check whether ImageFile class invariant is true.

Parameters

[in] doRecurse If true, also check invariants of all children or sub-objects recursively.

This function checks at least the assertions in the documented class invariant description (see class reference page for this object). Other internal invariants that are implementation-dependent may also be checked. If any invariant clause is violated, an E57Exception with errorCode of E57_ERROR_INVARIANCE_VIOLATION is thrown.

Checking the invariant recursively may be expensive if the tree is large, so should be used judiciously, in debug versions of the application.

Postcondition: No visible state is modified.

Exceptions

E57_ERROR_INVARIANCE_VIOLATION or any other E57 ErrorCode

See also: Node::checkInvariant

References e57::StructureNode::checkInvariant(), e57::E57_ERROR_INVARIANCE_VIOLATION, extensionsCount(), extensionsLookupPrefix(), extensionsLookupUri(), extensionsPrefix(), extensionsUri(), fileName(), isOpen(), isWritable(), readerCount(), root(), and writerCount().

◆ close()

void ImageFile::close ( )

Complete any write operations on an ImageFile, and close the file on the disk.

Completes the writing of the state of the ImageFile to the disk. Some API implementations may store significant portions of the state of the ImageFile in memory. This state is moved into the disk file before it is closed. Any errors in finishing the writing are reported by throwing an exception. If an exception is thrown, depending on the error code, the ImageFile may enter the closed state. If no exception is thrown, then the file on disk will be an accurate representation of the ImageFile.

Warning: if the ImageFile::close function is not called, and the ImageFile destructor is invoked with the ImageFile in the open state, the associated disk file will be deleted and the ImageFile will not be saved to the disk (the same outcome as calling ImageFile::cancel). The reason for this is that any error conditions can't be reported from a destructor, so the user can't be assured that the destruction/close completed successfully. It is strongly recommended that this close function be called before the ImageFile is destroyed.

It is not an error if ImageFile is already closed.

Postcondition: ImageFile is in closed state.

Exceptions

E57_ERROR_LSEEK_FAILED
E57_ERROR_READ_FAILED
E57_ERROR_WRITE_FAILED
E57_ERROR_CLOSE_FAILED
E57_ERROR_BAD_CHECKSUM
E57_ERROR_INTERNAL	All objects in undocumented state

See also: ImageFile::cancel, ImageFile::isOpen

Referenced by e57::ReaderImpl::Close(), e57::WriterImpl::Close(), and femexamples.examplesgui.FemExamples::reject().

◆ dump()

void ImageFile::dump	(	int	indent = `0`,
		std::ostream &	os = `std::cout`
	)		const

Diagnostic function to print internal state of object to output stream in an indented format.

Parameters

[in]	indent	Number of spaces to indent all the printed lines of this object.
[in]	os	Output stream to print on.

All objects in the E57 Foundation API (with exception of E57Exception) support a dump() function. These functions print out to the console a detailed listing of the internal state of objects. The content of these printouts is not documented, and is really of interest only to implementation developers/maintainers or the really adventurous users. In implementations of the API other than the Reference Implementation, the dump() functions may produce no output (although the functions should still be defined). The output format may change from version to version.

Postcondition: No visible object state is modified.

Exceptions

No	E57Exceptions

◆ elementNameParse()

void ImageFile::elementNameParse	(	const ustring &	elementName,
		ustring &	prefix,
		ustring &	localPart
	)		const

Parse element name into prefix and localPart substrings.

Parameters

[in]	elementName	The string element name to parse into prefix and local parts.
[out]	prefix	The prefix (if any) in the elementName.
[out]	localPart	The part of the element name after the prefix.

A legal element name may be in prefixed (ID:ID) or unprefixed (ID) form, where ID is a string whose first character is in {a-z,A-Z,_} followed by zero or more characters in {a-z,A-Z,_,0-9,-,.}. If in prefixed form, the prefix does not have to be declared in the ImageFile.

Postcondition: No visible state is modified.

Exceptions

E57_ERROR_BAD_PATH_NAME
E57_ERROR_INTERNAL	All objects in undocumented state

See also: ImageFile::isElementNameExtended

◆ extensionsAdd()

void ImageFile::extensionsAdd	(	const ustring &	prefix,
		const ustring &	uri
	)

Declare the use of an E57 extension in an ImageFile being written.

Parameters

[in]	prefix	The shorthand name of the extension to use in element names.
[in]	uri	The Uniform Resource Identifier string to associate with the prefix in the ImageFile.

The (prefix, uri) pair is registered in the known extensions of the ImageFile. Both prefix and uri must be unique in the ImageFile. It is not legal to declare a URI associated with the default namespace (prefix = ""). It is not an error to declare a namespace and not use it in an element name. It is an error to use a namespace prefix in an element name that is not declared beforehand.

A writer is free to "hard code" the prefix names in the element name strings that it uses (since it established the prefix declarations in the file). A reader cannot assume that any given prefix is always mapped to the same URI or vice versa. A reader might check an ImageFile, and if the prefixes aren't the way it likes, the reader could give up.

A better scheme would be to lookup the URI that the reader is familiar with, and store the prefix that the particular file uses in a variable. Then every time the reader needs to form a prefixed element name, it can assemble the full element name from the stored prefix variable and the constant documented base name string. This is less convenient than using a single "hard coded" string constant for an element name, but it is robust against any choice of prefix/URI combination.

See the class discussion at bottom of ImageFile page for more details about namespaces.

Precondition: This ImageFile must be open (i.e. isOpen()).; ImageFile must have been opened in write mode (i.e. isWritable()).; prefix != ""; uri != ""

Exceptions

E57_ERROR_BAD_API_ARGUMENT
E57_ERROR_IMAGEFILE_NOT_OPEN
E57_ERROR_FILE_IS_READ_ONLY
E57_ERROR_DUPLICATE_NAMESPACE_PREFIX
E57_ERROR_DUPLICATE_NAMESPACE_URI
E57_ERROR_INTERNAL	All objects in undocumented state

See also: ImageFile::extensionsCount, ImageFile::extensionsLookupPrefix, ImageFile::extensionsLookupUri

Referenced by e57::WriterImpl::WriterImpl().

◆ extensionsCount()

size_t ImageFile::extensionsCount ( ) const

Get number of E57 extensions declared in the ImageFile.

The default E57 namespace does not count as an extension.

Precondition: This ImageFile must be open (i.e. isOpen()).

Postcondition: No visible state is modified.

Returns: The number of E57 extensions defined in the ImageFile.

Exceptions

E57_ERROR_IMAGEFILE_NOT_OPEN
E57_ERROR_INTERNAL	All objects in undocumented state

See also: ImageFile::extensionsPrefix, ImageFile::extensionsUri

Referenced by checkInvariant().

◆ extensionsLookupPrefix()

bool ImageFile::extensionsLookupPrefix	(	const ustring &	prefix,
		ustring &	uri
	)		const

Get URI associated with an E57 extension prefix in the ImageFile.

Parameters

[in]	prefix	The shorthand name of the extension to look up.
[out]	uri	The URI that was associated with the given prefix.

If prefix = "", then uri is set to the default namespace URI, and the function returns true. if prefix is declared in the ImageFile, then uri is set the corresponding URI, and the function returns true. It is an error if prefix contains an illegal character combination for E57 namespace prefixes. It is not an error if prefix is well-formed, but not defined in the ImageFile (the function just returns false).

Precondition: This ImageFile must be open (i.e. isOpen()).

Postcondition: No visible state is modified.

Returns: true if prefix is declared in the ImageFile.

Exceptions

E57_ERROR_BAD_API_ARGUMENT
E57_ERROR_IMAGEFILE_NOT_OPEN
E57_ERROR_INTERNAL	All objects in undocumented state

See also: ImageFile::extensionsLookupUri

Referenced by checkInvariant(), e57::ReaderImpl::ReadData3D(), and e57::ReaderImpl::SetUpData3DPointsData().

◆ extensionsLookupUri()

bool ImageFile::extensionsLookupUri	(	const ustring &	uri,
		ustring &	prefix
	)		const

Get an E57 extension prefix associated with a URI in the ImageFile.

Parameters

[in]	uri	The URI of the extension to look up.
[out]	prefix	The shorthand prefix that was associated with the given uri.

If uri is declared in the ImageFile, then prefix is set the corresponding prefix, and the function returns true. It is an error if uri contains an illegal character combination for E57 namespace URIs. It is not an error if uri is well-formed, but not defined in the ImageFile (the function just returns false).

Precondition: This ImageFile must be open (i.e. isOpen()).; uri != ""

Postcondition: No visible state is modified.

Returns: true if URI is declared in the ImageFile.

Exceptions

E57_ERROR_BAD_API_ARGUMENT
E57_ERROR_IMAGEFILE_NOT_OPEN
E57_ERROR_INTERNAL	All objects in undocumented state

See also: ImageFile::extensionsLookupPrefix

Referenced by checkInvariant().

◆ extensionsPrefix()

ustring ImageFile::extensionsPrefix ( const size_t index ) const

Get an E57 extension prefix declared in an ImageFile by index.

Parameters

[in] index The index of the prefix to get, starting at 0.

The order that the prefixes are stored in is not necessarily the same as the order they were created. However the prefix order will correspond to the URI order. The default E57 namespace is not counted as an extension.

Precondition: This ImageFile must be open (i.e. isOpen()).; 0 <= index < extensionsCount()

Postcondition: No visible state is modified.

Returns: The E57 extension prefix at the given index.

Exceptions

E57_ERROR_BAD_API_ARGUMENT
E57_ERROR_IMAGEFILE_NOT_OPEN
E57_ERROR_INTERNAL	All objects in undocumented state

See also: ImageFile::extensionsCount, ImageFile::extensionsUri

Referenced by checkInvariant().

◆ extensionsUri()

ustring ImageFile::extensionsUri ( const size_t index ) const

Get an E57 extension URI declared in an ImageFile by index.

Parameters

[in] index The index of the URI to get, starting at 0.

The order that the URIs are stored is not necessarily the same as the order they were created. However the URI order will correspond to the prefix order. The default E57 namespace is not counted as an extension.

Precondition: This ImageFile must be open (i.e. isOpen()).; 0 <= index < extensionsCount()

Postcondition: No visible state is modified.

Returns: The E57 extension URI at the given index.

Exceptions

E57_ERROR_BAD_API_ARGUMENT
E57_ERROR_IMAGEFILE_NOT_OPEN
E57_ERROR_INTERNAL	All objects in undocumented state

See also: ImageFile::extensionsCount, ImageFile::extensionsPrefix

Referenced by checkInvariant().

◆ fileName()

ustring ImageFile::fileName ( ) const

Get the file name the ImageFile was created with.

Postcondition: No visible state is modified.

Returns: The file name the ImageFile was created with.

Exceptions

No	E57Exceptions.

See also: Cancel.cpp example, ImageFile::ImageFile

Referenced by checkInvariant().

◆ isElementNameExtended()

bool ImageFile::isElementNameExtended ( const ustring & elementName ) const

Test whether an E57 element name has an extension prefix.

The element name has a prefix if the function elementNameParse(elementName,prefix,dummy) would succeed, and returned prefix != "".

Parameters

[in] elementName The string element name to test.

Postcondition: No visible state is modified.

Returns: True if the E57 element name has an extension prefix.

Exceptions

No	E57Exceptions.

◆ isOpen()

bool ImageFile::isOpen ( ) const

Test whether ImageFile is still open for accessing.

Postcondition: No visible state is modified.

Returns: true if ImageFile is in open state.

Exceptions

No	E57Exceptions.

See also: ImageFile::ImageFile, ImageFile::close

Referenced by e57::CompressedVectorReader::checkInvariant(), e57::CompressedVectorWriter::checkInvariant(), checkInvariant(), e57::Node::checkInvariant(), e57::ReaderImpl::IsOpen(), and e57::WriterImpl::IsOpen().

◆ isWritable()

bool ImageFile::isWritable ( ) const

Test whether ImageFile was opened in write mode.

Postcondition: No visible state is modified.

Returns: true if ImageFile was opened in write mode.

Exceptions

No	E57Exceptions.

See also: ImageFile::ImageFile, ImageFile::isOpen

Referenced by e57::CompressedVectorWriter::checkInvariant(), and checkInvariant().

◆ operator!=()

bool ImageFile::operator!= ( ImageFile imf2 ) const

Test if two ImageFile handles refer to different underlying ImageFile.

Parameters

[in] imf2 The ImageFile to compare this ImageFile with

Postcondition: No visible object state is modified.

Returns: true if ImageFile handles refer to different underlying ImageFiles.

Exceptions

No	E57Exceptions

◆ operator==()

bool ImageFile::operator== ( ImageFile imf2 ) const

Test if two ImageFile handles refer to the same underlying ImageFile.

Parameters

[in] imf2 The ImageFile to compare this ImageFile with

Postcondition: No visible object state is modified.

Returns: true if ImageFile handles refer to the same underlying ImageFile.

Exceptions

No	E57Exceptions

◆ readerCount()

int ImageFile::readerCount ( ) const

Get current number of open CompressedVectorReader objects reading from ImageFile.

CompressedVectorReader objects that still exist, but are in the closed state aren't counted. CompressedVectorReader objects are created by the CompressedVectorNode::reader function.

Precondition: This ImageFile must be open (i.e. isOpen()).

Postcondition: No visible state is modified.

Returns: The current number of open CompressedVectorReader objects reading from ImageFile.

Exceptions

E57_ERROR_IMAGEFILE_NOT_OPEN
E57_ERROR_INTERNAL	All objects in undocumented state

See also: CompressedVectorNode::reader, CompressedVectorReader

Referenced by e57::CompressedVectorReader::checkInvariant(), e57::CompressedVectorWriter::checkInvariant(), and checkInvariant().

◆ root()

StructureNode ImageFile::root ( ) const

Get the pre-established root StructureNode of the E57 ImageFile.

The root node of an ImageFile always exists and is always type StructureNode. The root node is empty in a newly created write mode ImageFile.

Precondition: This ImageFile must be open (i.e. isOpen()).

Returns: A smart StructureNode handle referencing the underlying object.

Exceptions

E57_ERROR_IMAGEFILE_NOT_OPEN
E57_ERROR_INTERNAL	All objects in undocumented state

See also: StructureNode.

Referenced by checkInvariant(), e57::Node::checkInvariant(), Mod.Test.unittestgui.TkTestRunner::errorDialog(), Points::E57Reader::read(), Mod.Test.unittestgui.TkTestRunner::showAboutDialog(), Mod.Test.unittestgui.TkTestRunner::showHelpDialog(), and Mod.Test.unittestgui.TkTestRunner::showSelectedError().

◆ writerCount()

int ImageFile::writerCount ( ) const

Get current number of open CompressedVectorWriter objects writing to ImageFile.

CompressedVectorWriter objects that still exist, but are in the closed state aren't counted. CompressedVectorWriter objects are created by the CompressedVectorNode::writer function.

Precondition: This ImageFile must be open (i.e. isOpen()).

Postcondition: No visible state is modified.

Returns: The current number of open CompressedVectorWriter objects writing to ImageFile.

Exceptions

E57_ERROR_IMAGEFILE_NOT_OPEN
E57_ERROR_INTERNAL	All objects in undocumented state

See also: CompressedVectorNode::writer, CompressedVectorWriter

Referenced by e57::CompressedVectorReader::checkInvariant(), e57::CompressedVectorWriter::checkInvariant(), and checkInvariant().

The documentation for this class was generated from the following files:

FreeCAD/src/3rdParty/libE57Format/include/E57Format.h
FreeCAD/src/3rdParty/libE57Format/src/E57Format.cpp

Public Member Functions

Constructor & Destructor Documentation

◆ ImageFile() [1/3]

◆ ImageFile() [2/3]

◆ ImageFile() [3/3]

Member Function Documentation

◆ cancel()

◆ checkInvariant()

◆ close()

◆ dump()

◆ elementNameParse()

◆ extensionsAdd()

◆ extensionsCount()

◆ extensionsLookupPrefix()

◆ extensionsLookupUri()

◆ extensionsPrefix()

◆ extensionsUri()

◆ fileName()

◆ isElementNameExtended()

◆ isOpen()

◆ isWritable()

◆ operator!=()

◆ operator==()

◆ readerCount()

◆ root()

◆ writerCount()