e57::ImageFile Class Reference

#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]fnameFile 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]modeEither "w" for writing or "r" for reading.
[in]checksumPolicyThe 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_INTERNALAll 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
NoE57Exceptions.
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]doRecurseIf 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_VIOLATIONor 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_INTERNALAll 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]indentNumber of spaces to indent all the printed lines of this object.
[in]osOutput 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
NoE57Exceptions

◆ elementNameParse()

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

Parse element name into prefix and localPart substrings.

Parameters
[in]elementNameThe string element name to parse into prefix and local parts.
[out]prefixThe prefix (if any) in the elementName.
[out]localPartThe 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_INTERNALAll 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]prefixThe shorthand name of the extension to use in element names.
[in]uriThe 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_INTERNALAll 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_INTERNALAll 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]prefixThe shorthand name of the extension to look up.
[out]uriThe 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_INTERNALAll 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]uriThe URI of the extension to look up.
[out]prefixThe 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_INTERNALAll 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]indexThe 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_INTERNALAll 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]indexThe 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_INTERNALAll 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
NoE57Exceptions.
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]elementNameThe string element name to test.
Postcondition
No visible state is modified.
Returns
True if the E57 element name has an extension prefix.
Exceptions
NoE57Exceptions.

◆ 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
NoE57Exceptions.
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
NoE57Exceptions.
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]imf2The ImageFile to compare this ImageFile with
Postcondition
No visible object state is modified.
Returns
true if ImageFile handles refer to different underlying ImageFiles.
Exceptions
NoE57Exceptions

◆ operator==()

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

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

Parameters
[in]imf2The 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
NoE57Exceptions

◆ 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_INTERNALAll 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_INTERNALAll 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_INTERNALAll 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: