Poco::RemotingNG::TCP

class Frame

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

Description

This class represents a network frame used by the TCP transport connection.

A frame consists of a header, followed by payload. Header format is as follows:

  • Frame Type: 32 bit unsigned integer.
  • Channel: 32 bit unsigned integer.
  • Flags: 16 bit unsigned integer.
  • Payload Size: 16 bit unsigned integer.

All integers are in network byte order. Payload sizes are 16 bit, although practically only payloads up to a size of 1012 bytes are used.

Inheritance

Direct Base Classes: Poco::RefCountedObject

All Base Classes: Poco::RefCountedObject

Member Summary

Member Functions: bufferBegin, bufferEnd, bufferSize, channel, flags, frameSize, getPayloadSize, maxPayloadSize, payloadBegin, payloadEnd, setPayloadSize, type, updateFlags

Inherited Functions: duplicate, referenceCount, release

Types

Ptr

typedef Poco::AutoPtr < Frame > Ptr;

Enumerations

Capabilities

CAPA_REMOTING_PROTOCOL_1_0 = 0x524D0100

The endpoint understands the Remoting NG binary protocol, version 1.0

CAPA_REMOTING_PROTOCOL_1_1 = 0x524D0101

The endpoint understands the Remoting NG binary protocol, version 1.1 (including authentication)

Flags

FRAME_FLAG_EOM = 0x0001

End Of Message - the last frame of a message.

FRAME_FLAG_CONT = 0x0002

Continuation frame - set on all frames except the first one in a multi-frame message.

FRAME_FLAG_ONEWAY = 0x0004

One Way Message - no reply expected.

FRAME_FLAG_DEFLATE = 0x0008

Frame/message payload is compressed using zlib deflate algorithm.

FRAME_FLAG_AUTH = 0x0010

Frame contains authentication token.

FRAME_FLAG_EXTHDR = 0x8000

Extended header - reserved for future use.

Sizes

FRAME_HEADER_SIZE = 12

Size of frame header.

FRAME_MAX_SIZE = 1024

Maximum frame size (header + payload) currently used by protocol.

FRAME_MAX_PAYLOAD_SIZE = FRAME_MAX_SIZE - FRAME_HEADER_SIZE

Maximum frame payload size currently used by protocol.

Types

FRAME_TYPE_HELO = 0x48454C4F

"HELO" - first frame to be sent over channel 0 after connection has been established. Sent by both parties. Payload is protocol major version (8 bit unsigned), followed by protocol minor version (8 bit unsigned), followed by flags (8 bit unsigned, currently unused), followed by number of capabilities (8 bit unsigned), followed by list of capabilities as 32 bit integers.

FRAME_TYPE_BYE = 0x42594521

"BYE!" - last frame to be sent over channel. The endpoint wishing to close the connection sends a BYE! frame, and the other side acknowledges by responding also with a BYE! frame. After acknowledgement, the underlying TCP connection is closed.

The frame has no payload.

FRAME_TYPE_AUTH = 0x41555448

"AUTH" - A Remoting NG authentication request message.

Payload:

  • mechanism: string
  • payload: serialized credentials (key-value pairs)

FRAME_TYPE_AUTC = 0x41555443

"AUTC" - A Remoting NG authentication continuation message.

Payload:

  • conversation ID: UInt32
  • payload: serialized credentials (key-value pairs)

FRAME_TYPE_AUTR = 0x41555452

"AUTR" - A Remoting NG authentication response message.

Payload is:

  • state: UInt8 (0x01 = Done, 0x02 = Continue, 0x80 = Failed)
  • conversation ID: UInt32
  • payload: serialized credentials (key-value pairs)
  • authToken (only if state = Done)

FRAME_TYPE_REQU = 0x52455155

"REQU" - A Remoting NG request message.

Payload is serialized request (see Poco::RemotingNG::BinarySerializer).

FRAME_TYPE_REPL = 0x5245504C

"RESP" - A Remoting NG reply message.

Payload is serialized reply (see Poco::RemotingNG::BinarySerializer).

FRAME_TYPE_EVNT = 0x45564E54

"EVNT" - A Remoting NG event message.

Payload is serialized event (see Poco::RemotingNG::BinarySerializer).

FRAME_TYPE_EVNR = 0x45564E52

"EVNR" - A Remoting NG event reply message.

Payload is serialized event reply (see Poco::RemotingNG::BinarySerializer).

FRAME_TYPE_EVSU = 0x45565355

"EVSU" - A Remoting NG event subscribe/renewal message.

FRAME_TYPE_EVUN = 0x4556554E

"EVUN" - A Remoting NG event unsubscribe message.

Version

PROTO_MAJOR_VERSION = 1

PROTO_MINOR_VERSION = 1

Constructors

Frame

Frame(
    Poco::UInt32 type,
    Poco::UInt32 channel,
    Poco::UInt16 flags,
    Poco::UInt16 bufferSize
);

Creates a frame with the given type, flags and buffer size.

Buffer size must be sufficient for both header and payload. Minimum buffer size is the size of the header, which is 12 bytes.

The initial payload size is 0.

Destructor

~Frame virtual

~Frame();

Destroys the frame.

Member Functions

bufferBegin inline

char * bufferBegin();

Returns a pointer to the begin of the buffer.

bufferBegin

const char * bufferBegin() const;

Returns a pointer to the begin of the buffer.

bufferEnd inline

char * bufferEnd();

Returns a pointer to the end (one past last byte) of the buffer.

bufferEnd

const char * bufferEnd() const;

Returns a pointer to the end (one past last byte) of the buffer.

bufferSize inline

Poco::UInt16 bufferSize() const;

Returns the buffer size.

channel inline

Poco::UInt32 channel() const;

Returns the channel.

flags inline

Poco::UInt16 flags() const;

Returns the flags.

frameSize inline

Poco::UInt16 frameSize() const;

Returns the frame size, which is header size plus payload size.

getPayloadSize inline

Poco::UInt16 getPayloadSize() const;

Returns the payload size.

maxPayloadSize inline

Poco::UInt16 maxPayloadSize() const;

Returns the maximum payload size, which is buffer size minus header size.

payloadBegin inline

char * payloadBegin();

Returns a pointer to the begin of the payload in the buffer.

payloadBegin

const char * payloadBegin() const;

Returns a pointer to the begin of the payload in the buffer.

payloadEnd inline

char * payloadEnd();

Returns a pointer to the end (one past last byte) of the payload in the buffer.

payloadEnd

const char * payloadEnd() const;

Returns a pointer to the end (one past last byte) of the payload in the buffer.

setPayloadSize inline

void setPayloadSize(
    Poco::UInt16 size
);

Sets the payload size, which must not exceed the buffer size minus header size.

type inline

Poco::UInt32 type() const;

Returns the frame type.

updateFlags inline

void updateFlags(
    Poco::UInt16 flags
);

Updates the flags.