TCP classes

The TCP classes can be used with ImebraStreamWriter and ImebraStreamReader 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 ImebraTCPListener, while a TCP client (a socket that initiates a connection with a server) can be realized with the class ImebraTCPStream.

ImebraTCPListener creates a new ImebraTCPStream for each accepted incoming connection.

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

ImebraTCPAddress

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

ImebraTCPActiveAddress

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

ImebraTCPPassiveAddress

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

ImebraTCPStream

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.

ImebraTCPListener

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