Poco::RemotingNG::TCP

class Connection

File Information

Library: RemotingNG/TCP
Package: TCP
Header: Poco/RemotingNG/TCP/Connection.h

Description

This class represents a TCP connection between a client and a server.

A Connection is used by multiple proxies simultaneously. It is also used to send event messages from a server to a client.

A Connection is split up into multiple channels, with each channel belonging to exactly one Proxy or EventSubscriber.

Messages sent between the client and the server are split up into frames, with each frame being transmitted on a specific channel.

Each connection is handled by a thread. Incoming requests or event messages will typically be handled by a separate thread obtained from a ThreadPool, but this is outside the scope of the Connection object.

Inheritance

Direct Base Classes: Poco::Runnable, Poco::RemotingNG::AttributedObject, Poco::RefCountedObject

All Base Classes: Poco::RefCountedObject, Poco::RemotingNG::AttributedObject, Poco::Runnable

Member Summary

Member Functions: abort, addCapability, allocChannel, close, getHandshakeTimeout, getIdleTimeout, hasCapability, id, localAddress, mode, peerHasCapability, popFrameHandler, processFrame, pushFrameHandler, receiveBYE, receiveFrame, receiveHELO, receiveNBytes, releaseChannel, remoteAddress, returnFrame, run, runImpl, secure, sendBYE, sendFrame, sendHELO, sendProtocolFrame, setHandshakeTimeout, setIdleTimeout, socket, state, waitReady

Inherited Functions: clearAttributes, countAttributes, duplicate, enumerateAttributes, getAttribute, hasAttribute, operator =, referenceCount, release, removeAttribute, run, setAttribute

Types Aliases

Ptr

using Ptr = Poco::AutoPtr < Connection >;

Enumerations

ConnectionMode

MODE_CLIENT

A connection created by a client.

MODE_SERVER

A connection created by a server.

ConnectionState

STATE_PRE_HANDSHAKE

The connection has been established, but no handshake (HELO) frames have been exchanged.

STATE_HANDSHAKE

The first handshake frame has been sent, and the connection is waiting for the peer's handshake frame.

STATE_ESTABLISHED

The connection is ready.

STATE_CLOSING_ACTIVE

The connection is being actively closed and a BYE frame has been sent to the peer. Waiting for the confirming BYE frame from the peer.

STATE_CLOSING_PASSIVE

A BYE frame has been received and a confirming BYE frame will be sent.

STATE_ABORTED

The connection has been forcefully closed, without a closing handshake, due to a protocol violation.

STATE_CLOSED

The connection has been orderly closed.

Constructors

Connection

Connection(
    const Poco::Net::StreamSocket & socket,
    ConnectionMode mode
);

Creates the Connection for the given socket and endpoint mode.

Destructor

~Connection virtual

~Connection();

Destroys the Connection.

Member Functions

abort

void abort();

Aborts the connection.

addCapability

void addCapability(
    Poco::UInt32 capability
);

Adds the given capability to the connection.

This must be done before the connection handshake takes place.

allocChannel

Poco::UInt32 allocChannel();

Allocates a channel number.

close

void close();

Orderly closes the connection.

getHandshakeTimeout inline

Poco::Timespan getHandshakeTimeout() const;

Returns the timeout for the HELO handshake.

getIdleTimeout inline

Poco::Timespan getIdleTimeout() const;

Returns the idle connection timeout.

hasCapability

bool hasCapability(
    Poco::UInt32 capability
);

Returns true if the connection has the given capability.

id inline

Poco::UInt32 id() const;

Returns the ID of the connection. This is unique within the server or client process among all connections.

localAddress

Poco::Net::SocketAddress localAddress() const;

Returns the socket's local address.

mode inline

ConnectionMode mode() const;

Returns the connection mode.

peerHasCapability

bool peerHasCapability(
    Poco::UInt32 capability
);

Returns true if the peer has the given capability.

Peer capabilities will be available after the connection handshake.

popFrameHandler

void popFrameHandler(
    Poco::AutoPtr < FrameHandler > pHandler
);

Removes the FrameHandler from the internal stack.

pushFrameHandler

void pushFrameHandler(
    Poco::AutoPtr < FrameHandler > pHandler
);

Pushes the FrameHandler to the internal stack.

releaseChannel

void releaseChannel(
    Poco::UInt32 channel
);

Releases the given channel number.

remoteAddress

Poco::Net::SocketAddress remoteAddress() const;

Returns the remote peer's socket address.

returnFrame inline

void returnFrame(
    Frame::Ptr pFrame
);

Returns the frame to the pool.

secure

bool secure() const;

Returns true if and only if the connection uses a secure socket.

sendFrame

void sendFrame(
    Frame::Ptr pFrame
);

Send a single frame. The connection must be in STATE_ESTABLISHED.

setHandshakeTimeout

void setHandshakeTimeout(
    Poco::Timespan timeout
);

Sets the timeout for the HELO handshake.

setIdleTimeout

void setIdleTimeout(
    Poco::Timespan timeout
);

Sets the timeout after an idle connection is closed.

socket

Poco::Net::StreamSocket socket() const;

Returns the underlying socket.

state inline

ConnectionState state() const;

Returns the connection state.

waitReady

bool waitReady(
    Poco::Timespan timeout = 2 * TIMEOUT_HELO
);

Waits until the connection is established, or the given timeout expires.

processFrame protected

void processFrame(
    Frame::Ptr pFrame
);

Process a single frame.

receiveBYE protected

void receiveBYE();

Waits for and receives the final BYE frame.

receiveFrame protected

Frame::Ptr receiveFrame();

Receives the next frame from the connection, or returns null if no frame has been received within a certain time.

receiveHELO protected

void receiveHELO();

Waits for and receives the initial HELO frame.

receiveNBytes protected

int receiveNBytes(
    char * buffer,
    int bytes
);

Receive exactly the given number of bytes.

run protected virtual

void run();

Handle incoming frames.

See also: Poco::Runnable::run()

runImpl protected

void runImpl();

Handle incoming frames.

sendBYE protected

void sendBYE();

Sends the final BYE frame.

sendHELO protected

void sendHELO();

Sends the initial HELO frame.

sendProtocolFrame protected

void sendProtocolFrame(
    Frame::Ptr pFrame
);

Send a single protocol frame.

Variables

connectionAborted

Poco::BasicEvent < Connection::Ptr > connectionAborted;

Fired after the connection has been aborted.

connectionClosed

Poco::BasicEvent < Connection::Ptr > connectionClosed;

Fired after the connection has been closed.

connectionClosing

Poco::BasicEvent < Connection::Ptr > connectionClosing;

Fired when the connection is about to be closed.

connectionEstablished

Poco::BasicEvent < Connection::Ptr > connectionEstablished;

Fired after the handshake is complete and the connection has been established.