C:/Projects32/e57-3d-imgfmt/trunk/include/E57Foundation.h

Go to the documentation of this file.

/*
 * E57Foundation.h - public header of E57 Foundation API for reading/writing .e57 files.
 *
 * Copyright 2009 - 2010 Kevin Ackley (kackley@gwi.net)
 *
 * Permission is hereby granted, free of charge, to any person or organization
 * obtaining a copy of the software and accompanying documentation covered by
 * this license (the "Software") to use, reproduce, display, distribute,
 * execute, and transmit the Software, and to prepare derivative works of the
 * Software, and to permit third-parties to whom the Software is furnished to
 * do so, all subject to the following:
 *
 * The copyright notices in the Software and this entire statement, including
 * the above license grant, this restriction and the following disclaimer,
 * must be included in all copies of the Software, in whole or in part, and
 * all derivative works of the Software, unless such copies or derivative
 * works are solely in the form of machine-executable object code generated by
 * a source language processor.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
 * SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
 * FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 * DEALINGS IN THE SOFTWARE.
 */
#ifndef E57FOUNDATION_H_INCLUDED
#define E57FOUNDATION_H_INCLUDED


// Define the following symbol to enable heap corruption and memory leakage debugging:
//#define E57_DEBUG_MEMORY 1
#if E57_DEBUG_MEMORY
#  define _CRTDBG_MAP_ALLOC
#  include <stdlib.h>
#  include <crtdbg.h>
#endif

#include <vector>
#include <string>
#include <iostream>
#include <float.h>
#include <boost/shared_ptr.hpp>
#include <boost/weak_ptr.hpp>
#include <boost/enable_shared_from_this.hpp>
#include <boost/cstdint.hpp>    // for int8_t, int16_t, int32_t, etc...


#ifndef DOXYGEN  // Doxygen is not handling namespaces well in @includelineno commands, so disable
namespace e57 {
#endif

// Use Boost type names for signed/unsigned integers in various witdths
using boost::int8_t;
using boost::uint8_t;
using boost::int16_t;
using boost::uint16_t;
using boost::int32_t;
using boost::uint32_t;
using boost::int64_t;
using boost::uint64_t;

// Shorthand for unicode string
typedef std::string ustring;

enum NodeType {
    E57_STRUCTURE         = 1,  
    E57_VECTOR            = 2,  
    E57_COMPRESSED_VECTOR = 3,  
    E57_INTEGER           = 4,  
    E57_SCALED_INTEGER    = 5,  
    E57_FLOAT             = 6,  
    E57_STRING            = 7,  
    E57_BLOB              = 8   
};

enum FloatPrecision {
    E57_SINGLE = 1,  
    E57_DOUBLE = 2   
};

enum MemoryRepresentation {
    E57_INT8     = 1,  
    E57_UINT8    = 2,  
    E57_INT16    = 3,  
    E57_UINT16   = 4,  
    E57_INT32    = 5,  
    E57_UINT32   = 6,  
    E57_INT64    = 7,  
    E57_BOOL     = 8,  
    E57_REAL32   = 9,  
    E57_REAL64   = 10, 
    E57_USTRING  = 11  
};

const int E57_FOUNDATION_API_MAJOR = 0;

const int E57_FOUNDATION_API_MINOR = 51;

// Used to identify the standard field names and the grammar that relates them.
// Will typically be associated with the default namespace in an E57 file.
#define E57_V1_0_URI "http://www.astm.org/COMMIT/E57/2010-e57-v1.0"

// Minimum and maximum values for integers
const int8_t   E57_INT8_MIN   = -128;
const int8_t   E57_INT8_MAX   = 127;
const int16_t  E57_INT16_MIN  = -32768;
const int16_t  E57_INT16_MAX  = 32767;
const int32_t  E57_INT32_MIN  = -2147483647 - 1;
const int32_t  E57_INT32_MAX  = 2147483647;
const int64_t  E57_INT64_MIN  = -9223372036854775807LL - 1;
const int64_t  E57_INT64_MAX  = 9223372036854775807LL;
const uint8_t  E57_UINT8_MIN  = 0U;
const uint8_t  E57_UINT8_MAX  = 0xffU; /* 255U */
const uint16_t E57_UINT16_MIN = 0U;
const uint16_t E57_UINT16_MAX = 0xffffU; /* 65535U */
const uint32_t E57_UINT32_MIN = 0U;
const uint32_t E57_UINT32_MAX = 0xffffffffU;  /* 4294967295U */
const uint64_t E57_UINT64_MIN = 0ULL;
const uint64_t E57_UINT64_MAX = 0xffffffffffffffffULL; /* 18446744073709551615ULL */

const float  E57_FLOAT_MIN  = -FLT_MAX;
const float  E57_FLOAT_MAX  = FLT_MAX;
const double E57_DOUBLE_MIN = -DBL_MAX;
const double E57_DOUBLE_MAX = DBL_MAX;

// Forward references to classes in this header
class Node;
class StructureNode;
class VectorNode;
class SourceDestBuffer;
class CompressedVectorReader;
class CompressedVectorWriter;
class CompressedVectorNode;
class IntegerNode;
class ScaledIntegerNode;
class FloatNode;
class StringNode;
class BlobNode;
class ImageFile;

//??? Can define operator-> that will make implementation more readable
// Internal implementation files should include e57FoundationImpl.h first which defines symbol E57_INTERNAL_IMPLEMENTATION_ENABLE.
// Normal API users should not define this symbol.
// Basically the internal version allows access to the pointer to the implementation (impl_)
#ifdef E57_INTERNAL_IMPLEMENTATION_ENABLE
#  define E57_OBJECT_IMPLEMENTATION(T)                              \
public:                                                             \
    boost::shared_ptr<T##Impl> impl() const {return(impl_);};       \
protected:                                                          \
    boost::shared_ptr<T##Impl> impl_;
#else
#  define E57_OBJECT_IMPLEMENTATION(T)                              \
protected:                                                          \
    boost::shared_ptr<T##Impl> impl_;
#endif


// Forward references to implementation in other headers (so don't have to include E57FoundationImpl.h)
class NodeImpl;
class StructureNodeImpl;
class VectorNodeImpl;
class SourceDestBufferImpl;
class CompressedVectorReaderImpl;
class CompressedVectorWriterImpl;
class CompressedVectorNodeImpl;
class IntegerNodeImpl;
class ScaledIntegerNodeImpl;
class FloatNodeImpl;
class BlobNodeImpl;
class ImageFileImpl;

class Node {
public:
    NodeType    type() const;
    bool        isRoot() const;
    Node        parent() const;
    ustring     pathName() const;
    ustring     elementName() const;
    ImageFile   destImageFile() const;
    bool        isAttached() const;
    void        dump(int indent = 0, std::ostream& os = std::cout) const;
    void        checkInvariant(bool doRecurse = true, bool doDowncast=true);
    bool        operator==(Node n2) const;
    bool        operator!=(Node n2) const;

#ifdef E57_INTERNAL_IMPLEMENTATION_ENABLE
    explicit    Node(boost::shared_ptr<NodeImpl>);  // internal use only
#endif
private:   //=================
                Node();                 // No default constructor is defined for Node
protected: //=================
    friend class NodeImpl;

    E57_OBJECT_IMPLEMENTATION(Node)  // Internal implementation details, not part of API, must be last in object
};

class StructureNode {
public:
                StructureNode(ImageFile destImageFile);

    int64_t     childCount() const;
    bool        isDefined(const ustring& pathName) const;
    Node        get(int64_t index) const;
    Node        get(const ustring& pathName) const;
    void        set(const ustring& pathName, Node n);

    // Up/Down cast conversion
                operator Node() const;
    explicit    StructureNode(const Node& n);

    // Common generic Node functions
    bool        isRoot() const;
    Node        parent() const;
    ustring     pathName() const;
    ustring     elementName() const;
    ImageFile   destImageFile() const;
    bool        isAttached() const;

    // Diagnostic functions:
    void        dump(int indent = 0, std::ostream& os = std::cout) const;
    void        checkInvariant(bool doRecurse = true, bool doUpcast=true);

private:   //=================
                StructureNode();                 // No default constructor is defined for StructureNode
protected: //=================
    friend class ImageFile;

                StructureNode(boost::shared_ptr<StructureNodeImpl> ni);    // internal use only
                StructureNode(boost::weak_ptr<ImageFileImpl> fileParent);  // internal use only

    E57_OBJECT_IMPLEMENTATION(StructureNode)  // Internal implementation details, not part of API, must be last in object
};


class VectorNode {
public:
    explicit    VectorNode(ImageFile destImageFile, bool allowHeteroChildren = false);

    bool        allowHeteroChildren() const;

    int64_t     childCount() const;
    bool        isDefined(const ustring& pathName) const;
    Node        get(int64_t index) const;
    Node        get(const ustring& pathName) const;
    void        append(Node n);

    // Up/Down cast conversion
                operator Node() const;
    explicit    VectorNode(const Node& n);

    // Common generic Node functions
    bool        isRoot() const;
    Node        parent() const;
    ustring     pathName() const;
    ustring     elementName() const;
    ImageFile   destImageFile() const;
    bool        isAttached() const;

    // Diagnostic functions:
    void        dump(int indent = 0, std::ostream& os = std::cout) const;
    void        checkInvariant(bool doRecurse = true, bool doUpcast=true);

private:   //=================
                VectorNode();                 // No default constructor is defined for VectorNode
protected: //=================
    friend class CompressedVectorNode;

                VectorNode(boost::shared_ptr<VectorNodeImpl> ni);  // internal use only

    E57_OBJECT_IMPLEMENTATION(VectorNode)  // Internal implementation details, not part of API, must be last in object
};

class SourceDestBuffer {
public:
    SourceDestBuffer(ImageFile destImageFile, const ustring pathName, int8_t* b,   const size_t capacity,
                     bool doConversion = false, bool doScaling = false, size_t stride = sizeof(int8_t));
    SourceDestBuffer(ImageFile destImageFile, const ustring pathName, uint8_t* b,  const size_t capacity,
                     bool doConversion = false, bool doScaling = false, size_t stride = sizeof(uint8_t));
    SourceDestBuffer(ImageFile destImageFile, const ustring pathName, int16_t* b,  const size_t capacity,
                     bool doConversion = false, bool doScaling = false, size_t stride = sizeof(int16_t));
    SourceDestBuffer(ImageFile destImageFile, const ustring pathName, uint16_t* b, const size_t capacity,
                     bool doConversion = false, bool doScaling = false, size_t stride = sizeof(uint16_t));
    SourceDestBuffer(ImageFile destImageFile, const ustring pathName, int32_t* b,  const size_t capacity,
                     bool doConversion = false, bool doScaling = false, size_t stride = sizeof(int32_t));
    SourceDestBuffer(ImageFile destImageFile, const ustring pathName, uint32_t* b, const size_t capacity,
                     bool doConversion = false, bool doScaling = false, size_t stride = sizeof(uint32_t));
    SourceDestBuffer(ImageFile destImageFile, const ustring pathName, int64_t* b,  const size_t capacity,
                     bool doConversion = false, bool doScaling = false, size_t stride = sizeof(int64_t));
    SourceDestBuffer(ImageFile destImageFile, const ustring pathName, bool* b,     const size_t capacity,
                     bool doConversion = false, bool doScaling = false, size_t stride = sizeof(bool));
    SourceDestBuffer(ImageFile destImageFile, const ustring pathName, float* b,    const size_t  capacity,
                     bool doConversion = false, bool doScaling = false, size_t stride = sizeof(float));
    SourceDestBuffer(ImageFile destImageFile, const ustring pathName, double* b,   const size_t capacity,
                     bool doConversion = false, bool doScaling = false, size_t stride = sizeof(double));
    SourceDestBuffer(ImageFile destImageFile, const ustring pathName, std::vector<ustring>* b);

    ustring         pathName() const;
    enum MemoryRepresentation  memoryRepresentation() const;
    size_t          capacity() const;
    bool            doConversion() const;
    bool            doScaling() const;
    size_t          stride() const;

    // Diagnostic functions:
    void            dump(int indent = 0, std::ostream& os = std::cout) const;
    void            checkInvariant(bool doRecurse = true);

private:   //=================
                    SourceDestBuffer();                 // No default constructor is defined for SourceDestBuffer

protected: //=================

    E57_OBJECT_IMPLEMENTATION(SourceDestBuffer)  // Internal implementation details, not part of API, must be last in object
};

class CompressedVectorReader {
public:
    unsigned    read();
    unsigned    read(std::vector<SourceDestBuffer>& dbufs);
    void        seek(int64_t recordNumber); // !!! not implemented yet
    void        close();
    bool        isOpen();
    CompressedVectorNode compressedVectorNode() const;

    void        dump(int indent = 0, std::ostream& os = std::cout) const;
    void        checkInvariant(bool doRecurse = true);

private:   //=================
                CompressedVectorReader();          // No default constructor is defined for CompressedVectorReader
protected: //=================
    friend class CompressedVectorNode;

                CompressedVectorReader(boost::shared_ptr<CompressedVectorReaderImpl> ni);

    E57_OBJECT_IMPLEMENTATION(CompressedVectorReader)  // Internal implementation details, not part of API, must be last in object
};

class CompressedVectorWriter {
public:
    void        write(const size_t requestedRecordCount);
    void        write(std::vector<SourceDestBuffer>& sbufs, const size_t requestedRecordCount);
    void        close();
    bool        isOpen();
    CompressedVectorNode compressedVectorNode() const;

    void        dump(int indent = 0, std::ostream& os = std::cout) const;
    void        checkInvariant(bool doRecurse = true);

private:   //=================
                CompressedVectorWriter();          // No default constructor is defined for CompressedVectorWriter
protected: //=================
    friend class CompressedVectorNode;

                CompressedVectorWriter(boost::shared_ptr<CompressedVectorWriterImpl> ni);

    E57_OBJECT_IMPLEMENTATION(CompressedVectorWriter)  // Internal implementation details, not part of API, must be last in object
};

class CompressedVectorNode {
public:
    explicit    CompressedVectorNode(ImageFile destImageFile, Node prototype, VectorNode codecs);

    int64_t     childCount() const;
    Node        prototype() const;
    VectorNode  codecs() const;

    // Iterators
    CompressedVectorWriter writer(std::vector<SourceDestBuffer>& sbufs);
    CompressedVectorReader reader(const std::vector<SourceDestBuffer>& dbufs);

    // Up/Down cast conversion
                operator Node() const;
    explicit    CompressedVectorNode(const Node& n);

    // Common generic Node functions
    bool        isRoot() const;
    Node        parent() const;
    ustring     pathName() const;
    ustring     elementName() const;
    ImageFile   destImageFile() const;
    bool        isAttached() const;

    // Diagnostic functions:
    void        dump(int indent = 0, std::ostream& os = std::cout) const;
    void        checkInvariant(bool doRecurse = true, bool doUpcast=true);

private:   //=================
                CompressedVectorNode();           // No default constructor is defined for CompressedVectorNode
protected: //=================
    friend class CompressedVectorReader;
    friend class CompressedVectorWriter;
    friend class E57XmlParser;

                CompressedVectorNode(boost::shared_ptr<CompressedVectorNodeImpl> ni);  // internal use only

    E57_OBJECT_IMPLEMENTATION(CompressedVectorNode)  // Internal implementation details, not part of API, must be last in object
};

class IntegerNode {
public:
    explicit    IntegerNode(ImageFile destImageFile, int64_t value = 0, int64_t minimum = E57_INT64_MIN, int64_t maximum = E57_INT64_MAX);

    int64_t     value() const;
    int64_t     minimum() const;
    int64_t     maximum() const;

    // Up/Down cast conversion
                operator Node() const;
    explicit    IntegerNode(const Node& n);

    // Common generic Node functions
    bool        isRoot() const;
    Node        parent() const;
    ustring     pathName() const;
    ustring     elementName() const;
    ImageFile   destImageFile() const;
    bool        isAttached() const;

    // Diagnostic functions:
    void        dump(int indent = 0, std::ostream& os = std::cout) const;
    void        checkInvariant(bool doRecurse = true, bool doUpcast=true);

private:   //=================
                IntegerNode();                 // No default constructor is defined for IntegerNode
protected: //=================

                IntegerNode(boost::shared_ptr<IntegerNodeImpl> ni);  // internal use only

    E57_OBJECT_IMPLEMENTATION(IntegerNode)  // Internal implementation details, not part of API, must be last in object
};

class ScaledIntegerNode {
public:
    explicit    ScaledIntegerNode(ImageFile destImageFile, int64_t value, int64_t minimum, int64_t maximum,
                                  double scale = 1.0, double offset = 0.0);
    explicit    ScaledIntegerNode(ImageFile destImageFile, int value, int64_t minimum, int64_t maximum,
                                  double scale = 1.0, double offset = 0.0);
    explicit    ScaledIntegerNode(ImageFile destImageFile, int value, int minimum, int maximum,
                                  double scale = 1.0, double offset = 0.0);
    explicit    ScaledIntegerNode(ImageFile destImageFile, double scaledValue, double scaledMinimum, double scaledMaximum,
                                  double scale = 1.0, double offset = 0.0);     //Added by SC

    int64_t     rawValue() const;
    double      scaledValue() const;
    int64_t     minimum() const;
    double      scaledMinimum() const;  //Added by SC
    int64_t     maximum() const;
    double      scaledMaximum() const;  //Added by SC
    double      scale() const;
    double      offset() const;

    // Up/Down cast conversion
                operator Node() const;
    explicit    ScaledIntegerNode(const Node& n);

    // Common generic Node functions
    bool        isRoot() const;
    Node        parent() const;
    ustring     pathName() const;
    ustring     elementName() const;
    ImageFile   destImageFile() const;
    bool        isAttached() const;

    // Diagnostic functions:
    void        dump(int indent = 0, std::ostream& os = std::cout) const;
    void        checkInvariant(bool doRecurse = true, bool doUpcast=true);

private:   //=================
                ScaledIntegerNode();                 // No default constructor is defined for ScaledIntegerNode
protected: //=================

                ScaledIntegerNode(boost::shared_ptr<ScaledIntegerNodeImpl> ni);  // internal use only

    E57_OBJECT_IMPLEMENTATION(ScaledIntegerNode)  // Internal implementation details, not part of API, must be last in object
};

class FloatNode {
public:
    explicit    FloatNode(ImageFile destImageFile, double value = 0.0, FloatPrecision precision = E57_DOUBLE,
                          double minimum = E57_DOUBLE_MIN, double  maximum = E57_DOUBLE_MAX);

    double      value() const;
    FloatPrecision precision() const;
    double      minimum() const;
    double      maximum() const;

    // Up/Down cast conversion
                operator Node() const;
    explicit    FloatNode(const Node& n);

    // Common generic Node functions
    bool        isRoot() const;
    Node        parent() const;
    ustring     pathName() const;
    ustring     elementName() const;
    ImageFile   destImageFile() const;
    bool        isAttached() const;

    // Diagnostic functions:
    void        dump(int indent = 0, std::ostream& os = std::cout) const;
    void        checkInvariant(bool doRecurse = true, bool doUpcast=true);

private:   //=================
                FloatNode();                 // No default constructor is defined for FloatNode
protected: //=================

                FloatNode(boost::shared_ptr<FloatNodeImpl> ni);  // internal use only

    E57_OBJECT_IMPLEMENTATION(FloatNode)  // Internal implementation details, not part of API, must be last in object
};

class StringNodeImpl;
class StringNode {
public:
    explicit    StringNode(ImageFile destImageFile, const ustring value = "");

    ustring     value() const;

    // Up/Down cast conversion
                operator Node() const;
    explicit    StringNode(const Node& n);

    // Common generic Node functions
    bool        isRoot() const;
    Node        parent() const;
    ustring     pathName() const;
    ustring     elementName() const;
    ImageFile   destImageFile() const;
    bool        isAttached() const;

    // Diagnostic functions:
    void        dump(int indent = 0, std::ostream& os = std::cout) const;
    void        checkInvariant(bool doRecurse = true, bool doUpcast=true);

private:   //=================
                StringNode();                 // No default constructor is defined for StringNode
protected: //=================
    friend class StringNodeImpl;
                StringNode(boost::shared_ptr<StringNodeImpl> ni);  // internal use only

    E57_OBJECT_IMPLEMENTATION(StringNode)  // Internal implementation details, not part of API, must be last in object
};

class BlobNode {
public:
    explicit    BlobNode(ImageFile destImageFile, int64_t byteCount);

    int64_t     byteCount() const;
    void        read(uint8_t* buf,  int64_t start, size_t byteCount);
    void        write(uint8_t* buf, int64_t start, size_t byteCount);

    // Up/Down cast conversion
                operator Node() const;
    explicit    BlobNode(const Node& n);

    // Common generic Node functions
    bool        isRoot() const;
    Node        parent() const;
    ustring     pathName() const;
    ustring     elementName() const;
    ImageFile   destImageFile() const;
    bool        isAttached() const;

    // Diagnostic functions:
    void        dump(int indent = 0, std::ostream& os = std::cout) const;
    void        checkInvariant(bool doRecurse = true, bool doUpcast=true);

private:   //=================
                BlobNode();                 // No default constructor is defined for BlobNode
protected: //=================
    friend class E57XmlParser;

                BlobNode(boost::shared_ptr<BlobNodeImpl> ni);       // internal use only

                // Internal use only, create blob already in a file
                BlobNode(ImageFile destImageFile, int64_t fileOffset, int64_t length);

    E57_OBJECT_IMPLEMENTATION(BlobNode)  // Internal implementation details, not part of API, must be last in object
};

class ImageFile {
public:
                    ImageFile(const ustring& fname, const ustring& mode, const ustring& configuration = "");
    StructureNode   root() const;
    void            close();
    void            cancel();
    bool            isOpen() const;
    bool            isWritable() const;
    ustring         fileName() const;
    int             writerCount() const;
    int             readerCount() const;

    // Manipulate registered extensions in the file
    void            extensionsAdd(const ustring& prefix, const ustring& uri);
    bool            extensionsLookupPrefix(const ustring& prefix, ustring& uri) const;
    bool            extensionsLookupUri(const ustring& uri, ustring& prefix) const;
    size_t          extensionsCount() const;
    ustring         extensionsPrefix(const size_t index) const;
    ustring         extensionsUri(const size_t index) const;

    // Field name functions:
    bool            isElementNameExtended(const ustring& elementName) const;
    void            elementNameParse(const ustring& elementName, ustring& prefix, ustring& localPart) const;

    // Diagnostic functions:
    void            dump(int indent = 0, std::ostream& os = std::cout) const;
    void            checkInvariant(bool doRecurse = true);
    bool            operator==(ImageFile imf2) const;
    bool            operator!=(ImageFile imf2) const;

private:   //=================
                    ImageFile();                 // No default constructor is defined for ImageFile
                    ImageFile(double);           // Give a second dummy constructor, better error msg for: ImageFile(0)
protected: //=================
    //??? workaround?
    friend class Node;
    friend class StructureNode;
    friend class VectorNode;
    friend class CompressedVectorNode;
    friend class IntegerNode;
    friend class ScaledIntegerNode;
    friend class FloatNode;
    friend class StringNode;
    friend class BlobNode;

                    ImageFile(boost::shared_ptr<ImageFileImpl> imfi);  // internal use only

    E57_OBJECT_IMPLEMENTATION(ImageFile)  // Internal implementation details, not part of API, must be last in object
};

enum ErrorCode {
    /*
     * N.B.  *** When changing error strings here, remember to update the error strings in E57Foundation.cpp ****
     */
    E57_SUCCESS                                 = 0,  
    E57_ERROR_BAD_CV_HEADER                     = 1,  
    E57_ERROR_BAD_CV_PACKET                     = 2,  
    E57_ERROR_CHILD_INDEX_OUT_OF_BOUNDS         = 3,  
    E57_ERROR_SET_TWICE                         = 4,  
    E57_ERROR_HOMOGENEOUS_VIOLATION             = 5,  
    E57_ERROR_VALUE_NOT_REPRESENTABLE           = 6,  
    E57_ERROR_SCALED_VALUE_NOT_REPRESENTABLE    = 7,  
    E57_ERROR_REAL64_TOO_LARGE                  = 8,  
    E57_ERROR_EXPECTING_NUMERIC                 = 9,  
    E57_ERROR_EXPECTING_USTRING                 = 10, 
    E57_ERROR_INTERNAL                          = 11, 
    E57_ERROR_BAD_XML_FORMAT                    = 12, 
    E57_ERROR_XML_PARSER                        = 13, 
    E57_ERROR_BAD_API_ARGUMENT                  = 14, 
    E57_ERROR_FILE_IS_READ_ONLY                 = 15, 
    E57_ERROR_BAD_CHECKSUM                      = 16, 
    E57_ERROR_OPEN_FAILED                       = 17, 
    E57_ERROR_CLOSE_FAILED                      = 18, 
    E57_ERROR_READ_FAILED                       = 19, 
    E57_ERROR_WRITE_FAILED                      = 20, 
    E57_ERROR_LSEEK_FAILED                      = 21, 
    E57_ERROR_PATH_UNDEFINED                    = 22, 
    E57_ERROR_BAD_BUFFER                        = 23, 
    E57_ERROR_NO_BUFFER_FOR_ELEMENT             = 24, 
    E57_ERROR_BUFFER_SIZE_MISMATCH              = 25, 
    E57_ERROR_BUFFER_DUPLICATE_PATHNAME         = 26, 
    E57_ERROR_BAD_FILE_SIGNATURE                = 27, 
    E57_ERROR_UNKNOWN_FILE_VERSION              = 28, 
    E57_ERROR_BAD_FILE_LENGTH                   = 29, 
    E57_ERROR_XML_PARSER_INIT                   = 30, 
    E57_ERROR_DUPLICATE_NAMESPACE_PREFIX        = 31, 
    E57_ERROR_DUPLICATE_NAMESPACE_URI           = 32, 
    E57_ERROR_BAD_PROTOTYPE                     = 33, 
    E57_ERROR_BAD_CODECS                        = 34, 
    E57_ERROR_VALUE_OUT_OF_BOUNDS               = 35, 
    E57_ERROR_CONVERSION_REQUIRED               = 36, 
    E57_ERROR_BAD_PATH_NAME                     = 37, 
    E57_ERROR_NOT_IMPLEMENTED                   = 38, 
    E57_ERROR_BAD_NODE_DOWNCAST                 = 39, 
    E57_ERROR_WRITER_NOT_OPEN                   = 40, 
    E57_ERROR_READER_NOT_OPEN                   = 41, 
    E57_ERROR_NODE_UNATTACHED                   = 42, 
    E57_ERROR_ALREADY_HAS_PARENT                = 43, 
    E57_ERROR_DIFFERENT_DEST_IMAGEFILE          = 44, 
    E57_ERROR_IMAGEFILE_NOT_OPEN                = 45, 
    E57_ERROR_BUFFERS_NOT_COMPATIBLE            = 46, 
    E57_ERROR_TOO_MANY_WRITERS                  = 47, 
    E57_ERROR_TOO_MANY_READERS                  = 48, 
    E57_ERROR_BAD_CONFIGURATION                 = 49, 
    E57_ERROR_INVARIANCE_VIOLATION              = 50  
    /*
     * N.B.  *** When changing error strings here, remember to update the error strings in E57Foundation.cpp ****
     */
};

class E57Exception : public std::exception {
public:
    virtual void        report(const char* reportingFileName=NULL, int reportingLineNumber=0, const char* reportingFunctionName=NULL, std::ostream& os = std::cout) const;
    virtual ErrorCode   errorCode() const;
    virtual ustring     context() const;
    virtual const char* what() const throw();

    // For debugging purposes:
    virtual const char* sourceFileName() const;
    virtual const char* sourceFunctionName() const;
    virtual int         sourceLineNumber() const;

    E57Exception(ErrorCode ecode, const ustring context,
                 const char* srcFileName = NULL, int srcLineNumber = 0, const char* srcFunctionName = NULL);
    ~E57Exception() throw() {};

private:   //=================
                E57Exception();                 // No default constructor is defined for E57Exception
protected: //=================
    ErrorCode   errorCode_;
    ustring     context_;
    const char* sourceFileName_;
    const char* sourceFunctionName_;
    int         sourceLineNumber_;
};

class E57Utilities {
public:
    // Constructor (does nothing for now)
                E57Utilities(const ustring& /*configuration*/ = "") {};

    // Get latest version of ASTM standard supported, and library id string
    void        getVersions(int& astmMajor, int& astmMinor, ustring& libraryId);

    // Error code translation
    ustring     errorCodeToString(ErrorCode ecode);

    // Direct read of XML representation in E57 file
    int64_t     rawXmlLength(const ustring& fname);
    void        rawXmlRead(const ustring& fname, uint8_t* buf, int64_t start, size_t byteCount);
};

#ifndef DOXYGEN
}  // end namespace e57
#endif

#endif // E57FOUNDATION_H_INCLUDED