E57 Foundation API v1.1.312  Aug. 10, 2011
Public Member Functions
BlobNode Class Reference

An E57 element encoding an fixed-length sequence of bytes with an opaque format. More...

List of all members.

Public Member Functions

 BlobNode (ImageFile destImageFile, int64_t byteCount)
 Create an element for storing a sequence of bytes with an opaque format.
int64_t byteCount () const
 Get size of blob declared when it was created.
void read (uint8_t *buf, int64_t start, size_t byteCount)
 Read a buffer of bytes from a blob.
void write (uint8_t *buf, int64_t start, size_t byteCount)
 Write a buffer of bytes to a blob.
 operator Node () const
 Upcast a BlobNode handle to a generic Node handle.
 BlobNode (const Node &n)
 Downcast a generic Node handle to a BlobNode handle.
bool isRoot () const
 Is this a root node.
Node parent () const
 Return parent of node, or self if a root node.
ustring pathName () const
 Get absolute pathname of node.
ustring elementName () const
 Get elementName string, that identifies the node in its parent..
ImageFile destImageFile () const
 Get the ImageFile that was declared as the destination for the node when it was created.
bool isAttached () const
 Has node been attached into the tree of an ImageFile.
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.
void checkInvariant (bool doRecurse=true, bool doUpcast=true)
 Check whether BlobNode class invariant is true.

Detailed Description

An E57 element encoding an fixed-length sequence of bytes with an opaque format.

A BlobNode is a terminal node (i.e. having no children) that holds an opaque, fixed-length sequence of bytes. The number of bytes in the BlobNode is declared at creation time. The content of the blob is stored within the E57 file in an efficient binary format (but not compressed). The BlobNode cannot grow after it is created. There is no ordering constraints on how content of a BlobNode may be accessed (i.e. it is random access). BlobNodes in an ImageFile opened for reading are read-only.

There are two categories of BlobNodes, distinguished by their usage: private BlobNodes and public BlobNodes. In a private BlobNode, the format of its content bytes is not published. This is useful for storing proprietary data that a writer does not wish to share with all readers. Rather than put this information in a separate file, the writer can embed the file inside the E57 file so it cannot be lost.

In a public BlobNode, the format is published or follows some industry standard format (e.g. JPEG). Rather than reinvent the wheel in applications that are already well-served by an existing format standard, an E57 file writer can just embed an existing file as an "attachment" in a BlobNode. The internal format of a public BlobNode is not enforced by the Foundation API. It is recommended that there be some mechanism for a reader to know ahead of time which format the BlobNode content adheres to (either specified by a document, or encoded by some scheme in the E57 Element tree).

The BlobNode is the one node type where the set-once policy is not strictly enforced. It is possible to write the same byte location in a BlobNode several times. However it is not recommended.

See Node class discussion for discussion of the common functions that StructureNode supports.

Class Invariant

A class invariant is a list of statements about an object that are always true before and after any operation on the object. An invariant is useful for testing correct operation of an implementation. Statements in an invariant can involve only externally visible state, or, can refer to internal implementation-specific state that is not visible to the API user. The following C++ code checks externally visible state for consistency and throws an exception if the invariant is violated:

void BlobNode::checkInvariant(bool /*doRecurse*/, bool doUpcast) {
    // If destImageFile not open, can't test invariant (almost every call would throw)
    if (!destImageFile().isOpen())
        return;

    // If requested, call Node::checkInvariant
    if (doUpcast)
        static_cast<Node>(*this).checkInvariant(false, false);

    if (byteCount() < 0)
       throw E57_EXCEPTION1(E57_ERROR_INVARIANCE_VIOLATION);
} // end BlobNode::checkInvariant

See also:
Node
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Defines