Loading & saving classes

The classes described in this section are used to load and store DICOM structures (represented by the class imebra::DataSet).

The easiest way to load and store an imebra::DataSet object is by using the static methods of the imebra::CodecFactory class.

BaseStreamInput

class BaseStreamInput

This class represents a generic input stream.

Specialized classes derived from this one can read data from files stored on the computer’s disks (FileStreamInput) or from memory (MemoryStreamInput).

The client application cannot read the data directly from a BaseStreamInput but must use a StreamReader. Several StreamReader objects can read data from the same BaseStreamInput object.

The StreamReader class is not thread-safe, but different StreamReader objects in different threads can access the same BaseStreamInput object.

Subclassed by imebra::FileStreamInput, imebra::MemoryStreamInput, imebra::Pipe, imebra::TCPStream

Public Functions

virtual ~BaseStreamInput()

Destructor.

BaseStreamOutput

class BaseStreamOutput

This class represents a generic output stream.

Specialized classes derived from this one can write into files on the computer’s disks (FileStreamOutput) or to memory (MemoryStreamOutput).

The application can write into the stream by using a StreamWriter object.

While this class can be used across several threads, a StreamWriter can be used only in one thread.

Several StreamWriter objects (also in different threads) can use the same BaseStreamOutput object.

Subclassed by imebra::FileStreamOutput, imebra::MemoryStreamOutput, imebra::Pipe, imebra::TCPStream

Public Functions

virtual ~BaseStreamOutput()

Destructor.

StreamTimeout

class StreamTimeout

Triggers a timeout on a selected stream if the class is not deallocated within the specified amount of time.

Public Functions

StreamTimeout(BaseStreamInput &stream, std::uint32_t timeoutSeconds)

Constructor. Starts a separate thread that closes the stream in the parameter if this class destructor is not called before the timeout expires.

Parameters
  • stream: stream that must be closed when the timeout expires
  • timeoutSeconds: timeout in milliseconds

~StreamTimeout()

Destructor. If the timeout has not yet expired then terminates the thread that closes the stream, preventing it from closing the stream.

CodecFactory

class CodecFactory

The CodecFactory class can load or save a DataSet or an Image object using one of the codecs supplied by the Imebra library.

Public Static Functions

static DataSet *load(StreamReader &reader, size_t maxSizeBufferLoad = std::numeric_limits<size_t>::max())

Parses the content of the input stream and returns a DataSet representing it.

If none of the codecs supplied by Imebra is able to decode the stream’s content then it throws a CodecWrongFormatError exception.

The read position of the StreamReader is undefined when this method returns.

Return
a DataSet object representing the input stream’s content
Parameters
  • reader: a StreamReader connected to the input stream
  • maxSizeBufferLoad: the maximum size of the tags that are loaded immediately. Tags larger than maxSizeBufferLoad are left on the input stream and loaded only when a ReadingDataHandler or a WritingDataHandler reference them.

static DataSet *load(const std::wstring &fileName, size_t maxSizeBufferLoad = std::numeric_limits<size_t>::max())

Parses the content of the input file and returns a DataSet representing it.

If none of the codecs supplied by Imebra is able to decode the file’s content then it throws a CodecWrongFormatError exception.

Return
a DataSet object representing the input file’s content
Parameters
  • fileName: the Unicode name of the input file to read
  • maxSizeBufferLoad: the maximum size of the tags that are loaded immediately. Tags larger than maxSizeBufferLoad are left on the input stream and loaded only when a ReadingDataHandler or a WritingDataHandler reference them.

static DataSet *load(const std::string &fileName, size_t maxSizeBufferLoad = std::numeric_limits<size_t>::max())

Parses the content of the input file and returns a DataSet representing it.

If none of the codecs supplied by Imebra is able to decode the file’s content then it throws a CodecWrongFormatError exception.

Return
a DataSet object representing the input file’s content
Parameters
  • fileName: the Utf8 name of the input file to read
  • maxSizeBufferLoad: the maximum size of the tags that are loaded immediately. Tags larger than maxSizeBufferLoad are left on the input stream and loaded only when a ReadingDataHandler or a WritingDataHandler reference them.

static void save(const DataSet &dataSet, StreamWriter &writer, codecType_t codecType)

Saves the content of a DataSet object to an output stream using the requested codec.

Parameters
  • dataSet: the DataSet object to save
  • writer: a StreamWriter connected to the output stream
  • codecType: the codec to use to save the DataSet

static void save(const DataSet &dataSet, const std::wstring &fileName, codecType_t codecType)

Saves the content of a DataSet object to an output file using the requested codec.

Parameters
  • dataSet: the DataSet object to save
  • fileName: the Unicode name of the output file to create
  • codecType: the codec to use to save the DataSet

static void save(const DataSet &dataSet, const std::string &fileName, codecType_t codecType)

Saves the content of a DataSet object to an output file using the requested codec.

Parameters
  • dataSet: the DataSet object to save
  • fileName: the Utf8 name of the output file to create
  • codecType: the codec to use to save the DataSet

static void setMaximumImageSize(const std::uint32_t maximumWidth, const std::uint32_t maximumHeight)

Set the maximum image’s width & height accepted by Imebra.

By default both the maximum width and height are set to 4096 pixels.

Parameters
  • maximumWidth: the maximum image’s width accepted by Imebra
  • maximumHeight: the maximum image’s height accepted by Imebra

FileStreamInput

class FileStreamInput : public imebra::BaseStreamInput

Represents an input file stream.

Public Functions

FileStreamInput(const std::wstring &name)

Constructor.

Parameters
  • name: the path to the file to open in read mode

FileStreamInput(const std::string &name)

Constructor.

Parameters
  • name: the path to the file to open in read mode, in encoded in UTF8

~FileStreamInput()

Destructor. Closes the file.

FileStreamOutput

class FileStreamOutput : public imebra::BaseStreamOutput

Represents an output file stream.

Public Functions

FileStreamOutput(const std::wstring &name)

Constructor.

Parameters
  • name: the path to the file to open in write mode

FileStreamOutput(const std::string &name)

Constructor.

Parameters
  • name: the path to the file to open in write mode

~FileStreamOutput()

Destructor. Closes the file.

MemoryStreamInput

class MemoryStreamInput : public imebra::BaseStreamInput

An input stream that reads data from a memory region.

Public Functions

MemoryStreamInput(const ReadMemory &memory)

Constructor.

Parameters
  • memory: the memory region from which the stream will read the data

MemoryStreamInput(const ReadWriteMemory &memory)

Constructor.

Parameters
  • memory: the memory region from which the stream will read the data

MemoryStreamOutput

class MemoryStreamOutput : public imebra::BaseStreamOutput

An output stream that writes data into a memory region.

When new data is written into the memory then it is resized as necessary.

Public Functions

MemoryStreamOutput(const ReadWriteMemory &memory)

Constructor.

Parameters
  • memory: the memory region into which the stream will write the data

StreamReader

class StreamReader

A StreamReader is used to read data from a BaseStreamInput object.

A StreamReader can be mapped to only a portion of the BaseStreamInput it manages: for instance this is used by the Imebra classes to read Jpeg streams embedded into a DICOM stream.

Warning
The StreamReader object IS NOT THREAD-SAFE: however, several StreamReader objects from different threads can be connected to the same BaseStreamInput object.

Public Functions

StreamReader(const BaseStreamInput &stream)

Constructor.

Parameters

StreamReader(const BaseStreamInput &stream, size_t virtualStart, size_t virtualLength)

Constructor.

This version of the constructor limits the portion of the stream that the StreamReader will see.

Parameters
  • stream: the BaseStreamInput object from which the StreamReader will read
  • virtualStart: the first visible byte of the managed stream
  • virtualLength: the number of visible bytes in the managed stream

StreamReader *getVirtualStream(size_t virtualStreamLength)

Returns a virtual stream that has a restricted view into the stream.

The reading position of this stream advances to the end of the virtual stream.

Return
a virtual stream that sees a limited number of bytes of this stream
Parameters
  • virtualStreamLength: the number of bytes that the virtual stream can read

void terminate()

Cause the controlled stream to throw StreamClosedError during the mext read operation.

This can be used to cause reading threads to terminate.

StreamWriter

class StreamWriter

A StreamWriter is used to write data into a BaseStreamOutput object.

A StreamWriter can be mapped to only a portion of the BaseStreamOutput it manages.

Warning
: The StreamWriter object IS NOT THREAD-SAFE: however, several StreamWriter objects from different threads can be connected to the same BaseStreamOutput object.

Public Functions

StreamWriter(const BaseStreamOutput &stream)

Constructor.

Parameters

StreamWriter(const BaseStreamOutput &stream, size_t virtualStart, size_t virtualLength)

Constructor.

This version of the constructor limits the portion of the stream that the StreamWriter will be able to use.

Parameters
  • stream: the BaseStreamOutput object on which the StreamWriter will write
  • virtualStart: the first visible byte of the managed stream
  • virtualLength: the number of visible bytes in the managed stream