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::PipeStream`	`ImebraPipeStream`	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)

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 const 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 const 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 const 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 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 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

Public Functions

BaseStreamInput(const BaseStreamInput &source)¶

Copy constructor.

Parameters

source: source base input stream

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 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

Public Functions

BaseStreamOutput(const BaseStreamOutput &source)¶

Copy constructor.

Parameters

source: source base output stream

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

stream: the BaseStreamInput object from which the StreamReader will read

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(const StreamReader &source)¶

Copy constructor.

Parameters

source: source StreamReader object

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 read(char *destination, size_t destinationSize)¶

Read data from the stream.

Parameters

destination: pointer to the destination buffer
destinationSize: number of bytes to read

size_t readSome(char *destination, size_t destinationSize)¶

Read data from the stream.

Return

the number of bytes that have been read

Parameters

destination: pointer to the destination buffer
destinationSize: maximum number of bytes to read

Memory read(size_t readSize)¶

Read data from the stream.

Return

memory block containing the read data

Parameters

readSize: number of bytes to read

Memory readSome(size_t readSize)¶

Read data from the stream.

Return

memory block containing the read data

Parameters

readSize: maximum number of bytes to 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

pInput: the ImebraBaseStreamInput object from which the ž ImebraStreamReader will read

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

stream: the BaseStreamOutput object on which the StreamWriter will write

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

StreamWriter(const StreamWriter &source)¶

Copy constructor.

Parameters

source: source StreamWriter object

void write(const char *data, size_t dataSize)¶

Write raw data into the stream.

Parameters

data: a pointer to the buffer which stores the data that must be written intothe stream
bufferLength: the number of bytes that must be written to the stream

void write(const Memory &memory)¶

Write raw data into the stream.

Parameters

memory: a Memory object containing the data to write

void flush()¶: Flush all the unwritten data into the controlled 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

pOutput: the ImebraBaseStreamOutput 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(const FileStreamInput &source)¶

Copy constructor.

Parameters

source: source FileStreamInput object

~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(const FileStreamOutput &source)¶

Copy constructor.

Parameters

source: source FileStreamOutput object

~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 Memory &memory)¶

Constructor.

Parameters

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

MemoryStreamInput(const MemoryStreamInput &source)¶

Copy constructor.

Parameters

source: source MemoryStreamInput object

Objective-C/Swift¶

class ImebraMemoryStreamInput : public ImebraBaseStreamInput ¶

An input stream that reads data from a memory region.

Public Functions

id ImebraMemoryStreamInput::initWithReadMemory:(ImebraMemory * 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 MutableMemory &memory)¶

Constructor.

Parameters

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

MemoryStreamOutput(const MemoryStreamOutput &source)¶

Copy constructor.

Parameters

source: source MemoryStreamOutput object

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::initWithMutableMemory:(ImebraMutableMemory * 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(const StreamTimeout &source)¶

Copy constructor.

Parameters

source: source stream timeout

~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 output pipe¶

Pipe¶

C++¶

class PipeStream¶

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 using a StreamWriter

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 feed to Pipe by using a StreamReader

Public Functions

PipeStream(size_t circularBufferSize)¶

Constructor.

Parameters

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

PipeStream(const PipeStream &source)¶

Copy constructor.

Parameters

source: source Pipe object

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) 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

BaseStreamInput getStreamInput()¶

Return a BaseStreamInput object able to read from the PipeStream.

Return: a BaseStreamInput object able to read from the PipeStream.

BaseStreamOutput getStreamOutput()¶

Return a BaseStreamOutput object able to write into the PipeStream.

Return: a BaseStreamOutput object able to write into the PipeStream

Objective-C/Swift¶

class ImebraPipeStream : public NSObject¶

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 using an ImebraStreamWriter

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 by using an ImebraStreamReader

Public Functions

id ImebraPipeStream::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 ImebraPipeStream::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

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¶

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.

TCPStream(const TCPStream &source)¶

Copy constructor.

Parameters

source: source TCPStream object

const TCPAddress getPeerAddress() const¶

Returns the address of the connected peer.

Return: the address of the connected peer

BaseStreamInput getStreamInput()¶

Return a BaseStreamInput object able to read from the TCPStream.

Return: a BaseStreamInput object able to read from the TCPStream.

BaseStreamOutput getStreamOutput()¶

Return a BaseStreamOutput object able to write into the TCPStream.

Return: a BaseStreamOutput object able to write into the TCPStream

Objective-C/Swift¶

class ImebraTCPStream : public NSObject¶

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

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

TCPListener(const TCPListener &source)¶

Copy constructor.

Parameters

source: source TCPListener object

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

TCPAddress(const TCPAddress &source)¶

Copy constructor.

Parameters

source: source TCPAddress object

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