Stream classes

Introduction

The classes described in this chapter are used to load and store DICOM data structures (represented by a DataSet) and to send and receive DICOM messages.

The following classes are described in this chapter:

C++ class Objective-C/Swift class Description
imebra::CodecFactory ImebraCodecFactory Load/Save a DICOM structure
imebra::BaseStreamInput ImebraBaseStreamInput Base class for input streams
imebra::BaseStreamOutput ImebraBaseStreamOutput Base class for output streams
imebra::StreamReader ImebraStreamReader Read from an input stream
imebra::StreamWriter ImebraStreamWriter Write into an output stream
imebra::FileStreamInput ImebraFileStreamInput File input stream
imebra::FileStreamOutput ImebraFileStreamOutput File output stream
imebra::MemoryStreamInput ImebraMemoryStreamInput Memory input stream
imebra::MemoryStreamOutput ImebraMemoryStreamOutput Memory output stream
imebra::StreamTimeout ImebraStreamTimeout Causes a stream to fail after a timeout has expired
imebra::Pipe ImebraPipe Allow to implement custom input and output streams
imebra::TCPStream ImebraTCPStream Implement an input and output stream on a TCP connection
imebra::TCPListener ImebraTCPListener Listen for incoming TCP connections
imebra::TCPAddress ImebraTCPAddress Represents a TCP address
imebra::TCPPassiveAddress ImebraTCPPassiveAddress Represents a passive TCP address (used by the connection listener)
imebra::TCPActiveAddress ImebraTCPActiveAddress Represents an active TCP address (used to connect to a peer)
Stream related classes

Class diagram of the stream related classes

The easiest way to load or store a DataSet object is by using the static methods of the CodecFactory class.

All the Imebra Stream Classes (file, memory, tcp, pipe) derive from BaseStreamInput or/and BaseStreamOutput.

BaseStreamInput represents an input stream (you can read from it) while BaseStreamOutput represents an output stream (you can write into it). However, both classes don’t expose reading and writing methods: in order to read or write from/to a stream the client application must use the StreamReader or StreamWriter.

Several StreamReader or StreamWriter can share a single BaseStreamInput or BaseStreamOutput.

Stream classes

CodecFactory

C++

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

Objective-C/Swift

class ImebraCodecFactory : public NSObject

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

Public Static Functions

ImebraDataSet* ImebraCodecFactory::loadFromFile:error:(NSString * fileName, NSError ** pError)

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

If none of the codecs supplied by Imebra is able to decode the file’s content then sets the pError parameter and returns nil.

Return
a ImebraDataSet object representing the input file’s content
Parameters
  • fileName: the name of the input file
  • pError: pointer to a NSError pointer that will be set in case of error

ImebraDataSet* ImebraCodecFactory::loadFromFileMaxSize:maxBufferSize:error:(NSString * fileName, unsigned int maxBufferSize, NSError ** pError)

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

If none of the codecs supplied by Imebra is able to decode the file’s content then sets the pError parameter and returns nil.

Return
a ImebraDataSet object representing the input file’s content
Parameters
  • fileName: the name of the input file
  • 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 ImebraReadingDataHandler object or a ImebraWritingDataHandler object reference them.
  • pError: pointer to a NSError pointer that will be set in case of error

ImebraDataSet* ImebraCodecFactory::loadFromStream:error:(ImebraStreamReader * pReader, NSError ** pError)

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

If none of the codecs supplied by Imebra is able to decode the stream’s content then sets the pError parameter and returns nil.

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

Return
an ImebraDataSet object representing the input stream’s content
Parameters
  • pReader: a ImebraStreamReader object connected to the input stream
  • pError: pointer to a NSError pointer that will be set in case of error

ImebraDataSet* ImebraCodecFactory::loadFromStreamMaxSize:maxBufferSize:error:(ImebraStreamReader * pReader, unsigned int maxBufferSize, NSError ** pError)

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

If none of the codecs supplied by Imebra is able to decode the stream’s content then sets the pError parameter and returns nil.

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

Return
an ImebraDataSet object representing the input stream’s content
Parameters
  • pReader: a ImebraStreamReader object 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 an ImebraReadingDataHandler or an ImebraWritingDataHandler object reference sthem.
  • pError: pointer to a NSError pointer that will be set in case of error

void ImebraCodecFactory::saveToFile:dataSet:codecType:error:(NSString * fileName, ImebraDataSet * pDataSet, ImebraCodecType_t codecType, (swift_error(nonnull_error)) __attribute__)

Saves the content of a ImebraDataSet object to a file.

Parameters
  • fileName: the name of the output file
  • pDataSet: the ImebraDataSet object to save
  • codecType: the codec to use to save the ImebraDataSet
  • pError: pointer to a NSError pointer that will be set in case of error

void ImebraCodecFactory::saveToStream:dataSet:codecType:error:(ImebraStreamWriter * pWriter, ImebraDataSet * pDataSet, ImebraCodecType_t codecType, (swift_error(nonnull_error)) __attribute__)

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

Parameters
  • pWriter: an ImebraStreamWriter connected to the output stream
  • pDataSet: the ImebraDataSet object to save
  • codecType: the codec to use to save the ImebraDataSet
  • pError: pointer to a NSError pointer that will be set in case of error

void ImebraCodecFactory::setMaximumImageSize:maxHeight:(unsigned int maximumWidth, unsigned int 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

BaseStreamInput

C++

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.

Objective-C/Swift

class ImebraBaseStreamInput : public NSObject

This class represents a generic input stream.

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

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

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

Subclassed by ImebraBaseStreamInputOutput, ImebraFileStreamInput, ImebraMemoryStreamInput

BaseStreamOutput

C++

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.

Objective-C/Swift

class ImebraBaseStreamOutput : public NSObject

This class represents a generic output stream.

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

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

Subclassed by ImebraFileStreamOutput, ImebraMemoryStreamOutput

StreamReader

C++

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.

Objective-C/Swift

class ImebraStreamReader : public NSObject

ImebraStreamReader is used to read data from a ImebraBaseStreamInput object.

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

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

Public Functions

id ImebraStreamReader::initWithInputStream:(ImebraBaseStreamInput * pInput)

Initializer.

Parameters

id ImebraStreamReader::initWithInputStream:virtualStart:virtualEnd:(ImebraBaseStreamInput * pInput, unsigned int virtualStart, unsigned int virtualEnd)

Initializer.

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

Parameters
  • pInput: the ImebraBaseStreamInput object from which the ž ImebraStreamReader will read
  • virtualStart: the first visible byte of the managed stream
  • virtualLength: the number of visible bytes in the managed stream

ImebraStreamReader* ImebraStreamReader::getVirtualStream:error:(unsigned int virtualSize, NSError ** pError)

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
  • virtualSize: the number of bytes that the virtual stream can read
  • pError: set to a NSError derived class in case of error

void terminate()

Cause the controlled stream to set the ImebraStreamClosedError during the next read operation.

This can be used to cause reading threads to terminate.

StreamWriter

C++

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

Objective-C/Swift

class ImebraStreamWriter : public NSObject

A ImebraStreamWriter is used to write data into a ImebraBaseStreamOutput object.

Public Functions

id ImebraStreamWriter::initWithOutputStream:(ImebraBaseStreamOutput * pOutput)

Initializer.

Parameters

id ImebraStreamWriter::initWithInputOutputStream:(ImebraBaseStreamInputOutput * pInputOutput)

Initializer.

Parameters
  • pInputOutput: the ImebraBaseStreamInputOutput object on which the ImebraStreamWriter will write

FileStreamInput

C++

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.

Objective-C/Swift

class ImebraFileStreamInput : public ImebraBaseStreamInput

Represents an input file stream.

Public Functions

id ImebraFileStreamInput::initWithName:error:(NSString * fileName, NSError ** pError)

Initializer.

Parameters
  • fileName: the path to the file to open in read mode
  • pError: set to a NSError derived class in case of error

FileStreamOutput

C++

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.

Objective-C/Swift

class ImebraFileStreamOutput : public ImebraBaseStreamOutput

Represents an output file stream.

Public Functions

id ImebraFileStreamOutput::initWithName:error:(NSString * fileName, NSError ** pError)

Constructor.

Parameters
  • fileName: the path to the file to open in write mode
  • pError: set to a NSError derived class in case of error

MemoryStreamInput

C++

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

Objective-C/Swift

class ImebraMemoryStreamInput : public ImebraBaseStreamInput

An input stream that reads data from a memory region.

Public Functions

id ImebraMemoryStreamInput::initWithReadMemory:(ImebraReadMemory * pMemory)

Initializer.

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

MemoryStreamOutput

C++

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

Objective-C/Swift

class ImebraMemoryStreamOutput : public ImebraBaseStreamOutput

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

id ImebraMemoryStreamOutput::initWithReadWriteMemory:(ImebraReadWriteMemory * pMemory)

Initializer.

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

StreamTimeout

C++

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 seconds

~StreamTimeout()

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

Objective-C/Swift

class ImebraStreamTimeout : public NSObject

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

Public Functions

id ImebraStreamTimeout::initWithInputStream:timeoutSeconds:(ImebraBaseStreamInput * pStream, unsigned int timeoutSeconds)

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

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

Pipe classes

The Pipe class can be used to provide custom streams for the ACSE and DIMSE services or for any operation that takes a StreamReader or StreamWriter as parameter.

An example of custom stream could be:

  • a secure TCP connection
  • a connection through a dedicated custom network
  • etc.

A separate thread must be used to feed a Pipe (to supply a custom reading stream) or to sink data from a Pipe (to provide a custom writing stream).

Sequence diagram for the implementation of a custom write pipe

Sequence diagram for the implementation of a custom output pipe

Pipe

C++

class Pipe : public imebra::BaseStreamInput, public imebra::BaseStreamOutput

A Pipe can be used to push and pull data to/from an Imebra codec.

This is useful when an Imebra codec must be used with a data source or a data sink not supported by the library (e.g. a TLS stream).

In order to allow Imebra to read data from a custom data source:

  • allocate a Pipe class and use it as parameter for the StreamReader needed by the codec
  • from a secondary thread feed the data to the data source by calling feed()

In order to allow Imebra to write data to a custom data source:

  • allocate a Pipe class and use it as parameter for the StreamWriter needed by the codec
  • from a secondary thread read the data to feed to the data sink by calling sink()

Public Functions

Pipe(size_t circularBufferSize)

Constructor.

Parameters
  • circularBufferSize: the size of the buffer that stores the data fed to the Pipe until it is fetched

void feed(const ReadMemory &buffer)

Copy data into the Pipe so it can be retrieved by a codec via a StreamReader.

Parameters
  • buffer: the data to copy into the Pipe’s buffer

size_t sink(ReadWriteMemory &buffer)

Read data from the Pipe. The data can be pushed into the pipe via a StreamWriter.

Return
the number of bytes read from the pipe, which may be less than the buffer’s size
Parameters
  • buffer: a buffer that will contain the read data. The method will try to read as many bytes as the buffer size

void close(unsigned int timeoutMilliseconds)

Wait for the specified amount of time or until the internal buffer is empty (all the data fed has been retrieved by the StreamReader or by sink()), whichever comes first, then call terminate().

Subsequent read and write operations will fail by throwing the exception StreamClosedError.

Parameters
  • timeoutMilliseconds: the maximum time to wait until the internal buffer is empty, in milliseconds

void terminate()

Instruct any pending operation to terminate.

Current and subsequent read and write operations will fail by throwing the exception StreamClosedError.

Objective-C/Swift

class ImebraPipe : public ImebraBaseStreamInputOutput

A pipe can be used to push and pull data to/from an Imebra codec.

This is useful when an Imebra codec must be used with a data source or a data sink not supported by the library (e.g. a TLS stream).

In order to allow Imebra to read data from a custom data source:

  • allocate a ImebraPipe class and use it as parameter for the ImebraStreamReader needed by the codec
  • from a secondary thread feed the data to the data source by calling feed()

In order to allow Imebra to write data to a custom data source:

  • allocate a ImebraPipe class and use it as parameter for the ImebraStreamWriter needed by the codec
  • from a secondary thread read the data to feed to the data sink by calling sink()

Public Functions

id ImebraPipe::initWithBufferSize:(unsigned int circularBufferSize)

Initializer.

Parameters
  • circularBufferSize: the size of the buffer that stores the data fed to the Pipe until it is fetched

void ImebraPipe::feed:error:(ImebraReadMemory * buffer, (swift_error(nonnull_error)) __attribute__)

Copy data into the Pipe so it can be retrieved by a codec via a StreamReader.

Parameters
  • buffer: the data to copy into the Pipe’s buffer

unsigned int ImebraPipe::sink:error:(ImebraReadWriteMemory * buffer, (swift_error(nonnull_error)) __attribute__)

Read data from the Pipe. The data can be pushed into the pipe via a StreamWriter.

Return
the number of bytes read from the pipe, which may be less than the buffer’s size
Parameters
  • buffer: a buffer that will contain the read data. The method will try to read as many bytes as the buffer size

void ImebraPipe::close:error:(unsigned int timeoutMilliseconds, (swift_error(nonnull_error)) __attribute__)

Wait for the specified amount of time or until the internal buffer is empty (all the data fed has been retrieved by the StreamReader or by sink()), whichever comes first, then call terminate.

Subsequent read and write operations will fail by throwing the exception StreamClosedError.

Parameters
  • timeoutMilliseconds: the maximum time to wait until the internal buffer is empty, in milliseconds

void terminate()

Instruct any pending operation to terminate.

Current and subsequent read and write operations will fail by setting pError to ImebraStreamClosedError.

TCP classes

The TCP classes can be used with imebra::StreamWriter and imebra::StreamReader to send and receive data through a TCP stream.

A TCP server socket (a socket that listen for incoming connection) can be realized with the class imebra::TCPListener, while a TCP client (a socket that initiates a connection with a server) can be realized with the class imebra::TCPStream.

imebra::TCPListener creates a new imebra::TCPStream for each accepted incoming connection.

Both imebra::TCPListener and imebra::TCPStream expose blocking methods (except for the constructors which connect to the peer in non-blocking mode). You can exit a blocking method by closing the socket or by calling the terminate() method.

TCPStream

C++

class TCPStream : public imebra::BaseStreamInput, public imebra::BaseStreamOutput

Represents a TCP stream.

Public Functions

TCPStream(const TCPActiveAddress &address)

Construct a TCP socket and connects it to the destination address.

This is a non-blocking operation (the connection proceed after the constructor returns). Connection errors will be reported later while the communication happens.

Parameters
  • address: the address to which the socket has to be connected.

TCPAddress *getPeerAddress() const

Returns the address of the connected peer.

Return
the address of the connected peer

void terminate()

Instruct any pending operation to terminate.

Current and subsequent read and write operations will fail by throwing the exception StreamClosedError.

Objective-C/Swift

class ImebraTCPStream : public ImebraBaseStreamInputOutput

Represents a TCP stream.

Public Functions

id ImebraTCPStream::initWithAddress:error:(ImebraTCPActiveAddress * pAddress, NSError ** pError)

Construct a TCP socket and connects it to the destination address.

This is a non-blocking operation (the connection proceed after the constructor returns). Connection errors will be reported later while the communication happens.

Parameters
  • pAddress: the address to which the socket has to be connected.
  • pError: set to a StreamError derived class in case of error

ImebraTCPAddress* ImebraTCPStream::getPeerAddress:(NSError ** pError)

Returns the address of the connected peer.

Return
the address of the connected peer
Parameters
  • pError: set to a StreamError derived class in case of error

void terminate()

Instruct any pending operation to terminate.

Current and subsequent read and write operations will fail by setting pError to StreamClosedError.

TCPListener

C++

class TCPListener

Represents listening TCP socket.

Once allocated the socket starts listening at the address declared in the constructor.

A loop in the client application should call waitForConnection() in order to retrieve all the connections accepted by the socket.

Public Functions

TCPListener(const TCPPassiveAddress &address)

Constructor.

Constructs a listening socket and starts listening for incoming connections.

Parameters
  • address: the address to which the listening socket must be bound

TCPStream *waitForConnection()

Waits for an incoming connection on the listening socket.

The method blocks until a new connection is accepted or until the socket is closed, in which case it throws the exception StreamClosedError.

The socket is closed by the TCPStream’s destructor or by a call to terminate().

Return
a new TCPStream object bound to the new accepted connection. the returned TCPStream object will be owned by the caller

void terminate()

Instruct the listener to terminate any pending action.

If a thread is in the method waitForConnection() then it will receive the exception StreamClosedError. StreamClosedError will be also thrown for each subsequent call to waitForConnection().

Objective-C/Swift

class ImebraTCPListener : public NSObject

Represents listening TCP socket.

Once allocated the socket starts listening at the address declared in the constructor.

A loop in the client application should call waitForConnection() in order to retrieve all the connections accepted by the socket.

Public Functions

id ImebraTCPListener::initWithAddress:error:(ImebraTCPPassiveAddress * pAddress, NSError ** pError)

Initializer.

Constructs a listening socket and starts listening for incoming connections.

Parameters
  • address: the address to which the listening socket must be bound
  • pError: set to a NSError derived class in case of error

ImebraTCPStream* ImebraTCPListener::waitForConnection:(NSError ** pError)

Waits for an incoming connection on the listening socket.

The method blocks until a new connection is accepted or until the socket is closed, in which case pError is set to StreamClosedError.

The socket is closed by the ImebraTCPStream’s destructor or by a call to terminate.

Return
a new ImebraTCPStream object bound to the new accepted connection. The returned ImebraTCPStream object will be owned by the caller
Parameters
  • pError: set to a ImebraStreamError derived class in case of error

void terminate()

Instructs the listener to terminate any pending action.

If a thread is in the method waitForConnection() then it will receive the exception StreamClosedError. StreamClosedError will be also be set for each subsequent call to waitForConnection().

TCPAddress

C++

class TCPAddress

Represents a TCP address.

Use TCPActiveAddress to manage an address of an active socket (a socket that initiates the connection) and TCPPassiveAddress for a passive socket (a socket that listens for incoming connections).

Subclassed by imebra::TCPActiveAddress, imebra::TCPPassiveAddress

Public Functions

std::string getNode() const

Returns the node part of the TCP address.

The TCP address is composed by two parts:

  • the node which identifies the machine in the network
  • the service which identifies one of the ports (services) in the machine

Return
the node part of the TCP address

std::string getService() const

Returns the service part of the TCP address.

See getNode() for more information.

Return
the service part of the TCP address

Objective-C/Swift

class ImebraTCPAddress : public NSObject

Represents a TCP address.

Use ImebraTCPActiveAddress to manage an address of an active socket (a socket that initiates the connection) and ImebraTCPPassiveAddress for a passive socket (a socket that listens for incoming connections).

Subclassed by ImebraTCPActiveAddress, ImebraTCPPassiveAddress

Property

property ImebraTCPAddress::node

Returns the node part of the TCP address.

The TCP address is composed by two parts:

  • the node which identifies the machine in the network
  • the service which identifies one of the ports (services) in the machine

property ImebraTCPAddress::service

Returns the service part of the TCP address (the port number or name, eg. “80” or “HTTP”).

TCPPassiveAddress

C++

class TCPPassiveAddress : public imebra::TCPAddress

Represents an address of a passive socket (a socket that listens for connections initiated by the peers).

Public Functions

TCPPassiveAddress(const std::string &node, const std::string &service)

Constructor.

Constructs an active TCP address from a node and a service description.

The node may be a host name or address (both IPv4 and IPv6) while the service name may be a port number (in string format) or name (e.g. “FTP”).

Parameters
  • node: the host name or address (e.g. “192.168.10.20” or “example.com”). Use an empty string to refer to all the TCP devices on the local host.
  • service: the service port (in string format) or name (e.g. “140” or “ftp”).

Objective-C/Swift

class ImebraTCPPassiveAddress : public ImebraTCPAddress

Represents an address of a passive socket (a socket that listens for connections initiated by the peers).

Public Functions

id ImebraTCPPassiveAddress::initWithNode:service:error:(NSString * node, NSString * service, NSError ** pError)

Initializer.

Constructs a passive TCP address from a node and a service description.

The node may be a host name or address (both IPv4 and IPv6) while the service name may be a port number (in string format) or name (e.g. “FTP”).

Parameters
  • node: the host name or address (e.g. “192.168.10.20” or “example.com”). Use an empty string to refer to all the TCP devices on the local host.
  • service: the service port (in string format) or name (e.g. “140” or “ftp”).
  • pError: set to a NSError derived class in case of errors

TCPActiveAddress

C++

class TCPActiveAddress : public imebra::TCPAddress

Represents an address of an active socket (a socket that initiates the connection with the peer).

Public Functions

TCPActiveAddress(const std::string &node, const std::string &service)

Constructor.

Constructs an active TCP address from a node and a service description.

The node may be a host name or address (both IPv4 and IPv6) while the service name may be a port number (in string format) or name (e.g. “FTP”).

Parameters
  • node: the host name or address (e.g. “192.168.10.20” or “example.com”). Use an empty string to refer to the local host.
  • service: the service port (in string format) or name (e.g. “140” or “ftp”).

Objective-C/Swift

class ImebraTCPActiveAddress : public ImebraTCPAddress

Represents an address of an active socket (a socket that initiates the connection with the peer).

Public Functions

id ImebraTCPActiveAddress::initWithNode:service:error:(NSString * node, NSString * service, NSError ** pError)

Initializer.

Constructs an active TCP address from a node and a service description.

The node may be a host name or address (both IPv4 and IPv6) while the service name may be a port number (in string format) or name (e.g. “FTP”).

Parameters
  • node: the host name or address (e.g. “192.168.10.20” or “example.com”). Use an empty string to refer to the local host.
  • service: the service port (in string format) or name (e.g. “140” or “ftp”).
  • pError: set to a NSError derived class in case of errors