AbstractProtocol is the base abstract class which provides the interface for all protocols. More...

Public Types
enum	FieldFlag { FrameField = 0x1, MetaField = 0x2, CksumField = 0x4 }
	Properties of a field, can be OR'd. More...
enum	FieldAttrib { FieldName, FieldValue, FieldTextValue, FieldFrameValue, FieldBitSize }
	Various attributes of a field. More...
enum	ProtocolIdType { ProtocolIdNone, ProtocolIdLlc, ProtocolIdEth, ProtocolIdIp, ProtocolIdTcpUdp }
	Supported Protocol Id types. More...
enum	CksumType { CksumIp, CksumIpPseudo, CksumTcpUdp, CksumMax }
	Supported checksum types. More...
enum	CksumScope { CksumScopeAdjacentProtocol, CksumScopeAllProtocols }
	Supported checksum scopes. More...
Public Member Functions
	AbstractProtocol (StreamBase stream, AbstractProtocol parent=0)
	Constructs an abstract protocol for the given stream and parent.
virtual	~AbstractProtocol ()
	Destroys the abstract protocol.
virtual quint32	protocolNumber () const
	Returns the protocol's field number as defined in message 'Protocol', enum 'k' (file: protocol.proto)
void	commonProtoDataCopyInto (OstProto::Protocol &protocol) const
	Copies the common data (not specific to individual protocols) in the protocol member protobuf data into the passed in protocol parameter.
void	commonProtoDataCopyFrom (const OstProto::Protocol &protocol)
	Copies the common data (not specific to individual protocols) from the passed in param protocol protobuf into the member protobuf data.
virtual void	protoDataCopyInto (OstProto::Protocol &protocol) const =0
	Copy the protocol's protobuf as an extension into the passed in protocol.
virtual void	protoDataCopyFrom (const OstProto::Protocol &protocol)=0
	Copy and update the protocol's protobuf member data variable from the passed in protocol.
virtual QString	name () const
	Returns the full name of the protocol.
virtual QString	shortName () const
	Returns the short name or abbreviation of the protocol.
virtual ProtocolIdType	protocolIdType () const
	Returns the protocolIdType for the protocol.
virtual quint32	protocolId (ProtocolIdType type) const
	Returns the protocol id of the protocol for the given type.
quint32	payloadProtocolId (ProtocolIdType type) const
	Returns the protocol id of the payload protocol (the protocol that immediately follows the current one)
virtual int	fieldCount () const
	Returns the number of fields in the protocol (both Frame fields and Meta fields)
int	metaFieldCount () const
	Returns the number of meta fields.
virtual int	frameFieldCount () const
	Returns the number of frame fields.
virtual FieldFlags	fieldFlags (int index) const
	Returns the field flags for the passed in field index.
virtual QVariant	fieldData (int index, FieldAttrib attrib, int streamIndex=0) const
	Returns the requested field attribute data.
virtual bool	setFieldData (int index, const QVariant &value, FieldAttrib attrib=FieldValue)
	Sets the value of a field corresponding to index.
int	fieldFrameBitOffset (int index, int streamIndex=0) const
	Returns the bit offset where the specified field starts within the protocolFrameValue()
int	variableFieldCount () const
	Returns the count of variableFields in the protocol.
void	appendVariableField (const OstProto::VariableField &vf)
	Appends a variableField to the protocol.
void	removeVariableField (int index)
	Removes the variableField from the protocol at the specified index.
const OstProto::VariableField &	variableField (int index) const
	Returns the variableField at the specified index as a constant Reference i.e.
OstProto::VariableField *	mutableVariableField (int index)
	Returns the variableField at the specified index as a mutable pointer.
QByteArray	protocolFrameValue (int streamIndex=0, bool forCksum=false) const
	Returns a byte array encoding the protocol (and its fields) which can be inserted into the stream's frame.
virtual int	protocolFrameSize (int streamIndex=0) const
	Returns the protocol's size in bytes.
int	protocolFrameOffset (int streamIndex=0) const
	Returns the byte offset in the packet where the protocol starts.
int	protocolFramePayloadSize (int streamIndex=0) const
	Returns the size of the payload in bytes.
virtual bool	isProtocolFrameValueVariable () const
	Returns true if the protocol varies one or more of its fields at run-time, false otherwise.
virtual bool	isProtocolFrameSizeVariable () const
	Returns true if the protocol varies its size at run-time, false otherwise.
virtual int	protocolFrameVariableCount () const
	Returns the minimum number of frames required for the protocol to vary its fields.
bool	isProtocolFramePayloadValueVariable () const
	Returns true if the payload content for a protocol varies at run-time, false otherwise.
bool	isProtocolFramePayloadSizeVariable () const
	Returns true if the payload size for a protocol varies at run-time, false otherwise.
int	protocolFramePayloadVariableCount () const
	Returns true if the payload size for a protocol varies at run-time, false otherwise.
bool	protocolHasPayload () const
	Returns true if the protocol typically contains a payload or other protocols following it e.g.
virtual quint32	protocolFrameCksum (int streamIndex=0, CksumType cksumType=CksumIp) const
	Returns the checksum (of the requested type) of the protocol's contents.
quint32	protocolFrameHeaderCksum (int streamIndex=0, CksumType cksumType=CksumIp, CksumScope cksumScope=CksumScopeAdjacentProtocol) const
	Returns the checksum of the requested type for the protocol's header.
quint32	protocolFramePayloadCksum (int streamIndex=0, CksumType cksumType=CksumIp, CksumScope cksumScope=CksumScopeAllProtocols) const
	Returns the checksum of the requested type for the protocol's payload.
Static Public Member Functions
static AbstractProtocol *	createInstance (StreamBase stream, AbstractProtocol parent=0)
	Allocates and returns a new instance of the class.
static quint64	lcm (quint64 u, quint64 v)
static quint64	gcd (quint64 u, quint64 v)
Protected Types
enum	CacheFlag { FieldFrameBitOffsetCache = 0x1 }
	Caching Control Flags. More...
Protected Attributes
StreamBase *	mpStream
	Stream that this protocol belongs to.
AbstractProtocol *	parent
	Parent protocol, if any.
AbstractProtocol *	prev
	Protocol preceding this protocol.
AbstractProtocol *	next
	Protocol succeeding this protocol.
bool	_hasPayload
	Is protocol typically followed by payload or another protocol.
quint32	_cacheFlags
Friends
class	ComboProtocol
class	ProtocolListIterator

Detailed Description

AbstractProtocol is the base abstract class which provides the interface for all protocols.

All protocols supported by Ostinato are derived from AbstractProtocol. Apart from defining the interface for a protocol, it also provides sensible default implementations for methods so that the subclasses need not re-implement. It also provides convenience functions for subclasses to use such as methods to retrieve payload size, checksum etc.

A subclass typically needs to reimplement the following methods -

Depending on certain conditions, subclasses may need to reimplement the following additional methods -

See the description of the methods for more information.

Most of the above methods just need some standard boilerplate code - the SampleProtocol implementation includes the boilerplate

Member Enumeration Documentation

enum AbstractProtocol::CacheFlag [protected]

Caching Control Flags.

enum AbstractProtocol::CksumScope

Supported checksum scopes.

Enumerator:

CksumScopeAdjacentProtocol	Cksum only the adjacent protocol.
CksumScopeAllProtocols	Cksum over all the protocols.

enum AbstractProtocol::CksumType

Supported checksum types.

Enumerator:

CksumIp	Standard IP Checksum.
CksumIpPseudo	Standard checksum for Pseudo-IP header.
CksumTcpUdp	Standard TCP/UDP checksum including pseudo-IP.
CksumMax	Marker for number of cksum types.

enum AbstractProtocol::FieldAttrib

Various attributes of a field.

Enumerator:

FieldName	name
FieldValue	value in host byte order (user editable)
FieldTextValue	value as text
FieldFrameValue	frame encoded value in network byte order
FieldBitSize	size in bits

enum AbstractProtocol::FieldFlag

Properties of a field, can be OR'd.

Enumerator:

FrameField	field appears in frame content
MetaField	field does not appear in frame, is meta data
CksumField	field is a checksum and appears in frame content

enum AbstractProtocol::ProtocolIdType

Supported Protocol Id types.

Enumerator:

ProtocolIdNone	Marker representing non-existent protocol id.
ProtocolIdLlc	LLC (802.2)
ProtocolIdEth	Ethernet II.
ProtocolIdIp	IP.
ProtocolIdTcpUdp	TCP/UDP Port Number.

Constructor & Destructor Documentation

AbstractProtocol::AbstractProtocol	(	StreamBase *	stream,
		AbstractProtocol *	parent = `0`
	)

Constructs an abstract protocol for the given stream and parent.

parent is typically NULL except for protocols which are part of a ComboProtocol

AbstractProtocol::~AbstractProtocol ( ) [virtual]

Destroys the abstract protocol.

Member Function Documentation

void AbstractProtocol::appendVariableField ( const OstProto::VariableField & vf )

Appends a variableField to the protocol.

void AbstractProtocol::commonProtoDataCopyFrom ( const OstProto::Protocol & protocol )

Copies the common data (not specific to individual protocols) from the passed in param protocol protobuf into the member protobuf data.

The individual protocol specific protobuf data is copied using protoDataCopyFrom()

void AbstractProtocol::commonProtoDataCopyInto ( OstProto::Protocol & protocol ) const

Copies the common data (not specific to individual protocols) in the protocol member protobuf data into the passed in protocol parameter.

The individual protocol specific protobuf data is copied using protoDataCopyInto()

AbstractProtocol * AbstractProtocol::createInstance	(	StreamBase *	stream,
		AbstractProtocol *	parent = `0`
	)		`[static]`

Allocates and returns a new instance of the class.

Caller is responsible for freeing up after use. Subclasses MUST implement this function

int AbstractProtocol::fieldCount ( ) const [virtual]

Returns the number of fields in the protocol (both Frame fields and Meta fields)

The default implementation returns zero. Subclasses MUST implement this function.

QVariant AbstractProtocol::fieldData	(	int	index,
		FieldAttrib	attrib,
		int	streamIndex = `0`
	)		const `[virtual]`

Returns the requested field attribute data.

Protocols which have meta fields that vary a frame field across streams may use the streamIndex to return the appropriate field value
Some field attributes e.g. FieldName may be invariant across streams
The FieldTextValue attribute may include additional information about the field's value e.g. a checksum field may include "(correct)" or "(incorrect)" alongwith the actual checksum value.

The default implementation returns a empty string for FieldName and FieldTextValue; empty byte array of size 0 for FieldFrameValue; 0 for FieldValue; subclasses are expected to return meaning values for all these attributes. The only exception is the 'FieldBitSize' attribute - the default implementation takes the (byte) size of FieldFrameValue, multiplies it with 8 and returns the result - this can be used by subclasses for fields which are an integral multiple of bytes; for fields whose size are a non-integral multiple of bytes or smaller than a byte, subclasses should return the correct value. Also for fields which represent checksums, subclasses should return a value for FieldBitSize - even if it is an integral multiple of bytes.

Note:

If a subclass uses any of the below functions to derive FieldFrameValue, the subclass should handle and return a value for FieldBitSize to prevent endless recursion -

AbstractProtocol::FieldFlags AbstractProtocol::fieldFlags ( int index ) const [virtual]

Returns the field flags for the passed in field index.

The default implementation assumes all fields to be frame fields and returns 'FrameField'. Subclasses must reimplement this method if they have any meta fields or checksum fields. See the SampleProtocol for an example.

int AbstractProtocol::fieldFrameBitOffset	(	int	index,
		int	streamIndex = `0`
	)		const

Returns the bit offset where the specified field starts within the protocolFrameValue()

int AbstractProtocol::frameFieldCount ( ) const [virtual]

Returns the number of frame fields.

The default implementation counts and returns the number of fields for which the FrameField flag is set
The default implementation caches the count on its first invocation and subsequently returns the cached count

Subclasses which export different sets of fields based on a opcode/type (e.g. icmp) should re-implement this function

bool AbstractProtocol::isProtocolFramePayloadSizeVariable ( ) const

Returns true if the payload size for a protocol varies at run-time, false otherwise.

This is useful for subclasses which have fields dependent on payload size (e.g. UDP has a checksum field that varies if the payload varies)

bool AbstractProtocol::isProtocolFramePayloadValueVariable ( ) const

Returns true if the payload content for a protocol varies at run-time, false otherwise.

This is useful for subclasses which have fields dependent on payload content (e.g. UDP has a checksum field that varies if the payload varies)

bool AbstractProtocol::isProtocolFrameSizeVariable ( ) const [virtual]

Returns true if the protocol varies its size at run-time, false otherwise.

The default implmentation returns false. A subclass should reimplement if it varies its size at run-time e.g. a Payload protocol for a stream with incrementing/decrementing frame lengths

bool AbstractProtocol::isProtocolFrameValueVariable ( ) const [virtual]

Returns true if the protocol varies one or more of its fields at run-time, false otherwise.

int AbstractProtocol::metaFieldCount ( ) const

Returns the number of meta fields.

The default implementation counts and returns the number of fields for which the MetaField flag is set
The default implementation caches the count on its first invocation and subsequently returns the cached count

OstProto::VariableField * AbstractProtocol::mutableVariableField ( int index )

Returns the variableField at the specified index as a mutable pointer.

Changes made via the pointer will be reflected in the protocol

QString AbstractProtocol::name ( ) const [virtual]

Returns the full name of the protocol.

The default implementation returns a null string

quint32 AbstractProtocol::payloadProtocolId ( ProtocolIdType type ) const

Returns the protocol id of the payload protocol (the protocol that immediately follows the current one)

A subclass which has a protocol id field, can use this to retrieve the appropriate value

quint32 AbstractProtocol::protocolFrameCksum	(	int	streamIndex = `0`,
		CksumType	cksumType = `CksumIp`
	)		const `[virtual]`

Returns the checksum (of the requested type) of the protocol's contents.

Useful for protocols which have a checksum field

Note:: If a subclass uses protocolFrameCksum() from within fieldData() to derive a cksum field, it MUST handle and return the 'FieldBitSize' attribute also for that particular field instead of using the default AbstractProtocol implementation for 'FieldBitSize' - this is required to prevent infinite recursion

quint32 AbstractProtocol::protocolFrameHeaderCksum	(	int	streamIndex = `0`,
		CksumType	cksumType = `CksumIp`,
		CksumScope	cksumScope = `CksumScopeAdjacentProtocol`
	)		const

Returns the checksum of the requested type for the protocol's header.

This is useful for subclasses which needs the header's checksum e.g. TCP/UDP require a "Pseudo-IP" checksum. The checksum is limited to the specified scope.

Currently the default implementation supports only type CksumIpPseudo

Note:: The default value for cksumScope is different for protocolFrameHeaderCksum() and protocolFramePayloadCksum()

int AbstractProtocol::protocolFrameOffset ( int streamIndex = 0 ) const

Returns the byte offset in the packet where the protocol starts.

This method is useful only for "padding" protocols i.e. protocols which fill up the remaining space for the user defined packet size e.g. the PatternPayload protocol

quint32 AbstractProtocol::protocolFramePayloadCksum	(	int	streamIndex = `0`,
		CksumType	cksumType = `CksumIp`,
		CksumScope	cksumScope = `CksumScopeAllProtocols`
	)		const

Returns the checksum of the requested type for the protocol's payload.

This is useful for subclasses which needs the payload's checksum e.g. TCP/UDP require a IP checksum of the payload (to be combined with other checksums to derive the final checksum). The checksum is limited to the specified scope.

Currently the default implementation supports only type CksumIp

Note:: The default value for cksumScope is different for protocolFrameHeaderCksum() and protocolFramePayloadCksum()

int AbstractProtocol::protocolFramePayloadSize ( int streamIndex = 0 ) const

Returns the size of the payload in bytes.

The payload includes all protocols subsequent to the current

This method is useful for protocols which need to fill in a payload size field

int AbstractProtocol::protocolFramePayloadVariableCount ( ) const

Returns true if the payload size for a protocol varies at run-time, false otherwise.

This is useful for subclasses which have fields dependent on payload size (e.g. UDP has a checksum field that varies if the payload varies)

int AbstractProtocol::protocolFrameSize ( int streamIndex = 0 ) const [virtual]

Returns the protocol's size in bytes.

The default implementation sums up the individual field bit sizes and returns it. The default implementation calculates the caches the size on the first invocation and subsequently returns the cached size.

If the subclass protocol has a varying protocol size, it MUST reimplement this method, otherwise the default implementation is sufficient.

QByteArray AbstractProtocol::protocolFrameValue	(	int	streamIndex = `0`,
		bool	forCksum = `false`
	)		const

Returns a byte array encoding the protocol (and its fields) which can be inserted into the stream's frame.

The default implementation forms and returns an ordered concatenation of the FrameValue of all the 'frame' fields of the protocol also taking care of fields which are not an integral number of bytes

int AbstractProtocol::protocolFrameVariableCount ( ) const [virtual]

Returns the minimum number of frames required for the protocol to vary its fields.

This is the lowest common multiple (LCM) of the counts of all the varying fields in the protocol. Use the AbstractProtocol::lcm() static utility function to calculate the LCM.

The default implementation returns the LCM of all variableFields A subclass should reimplement if it has varying fields e.g. an IP protocol that increments/decrements the IP address with every packet.
Subclasses should call the base class method to retreive the count and do a LCM with the subclass' own varying fields

bool AbstractProtocol::protocolHasPayload ( ) const

Returns true if the protocol typically contains a payload or other protocols following it e.g.

TCP, UDP have payloads, while ARP, IGMP do not

The default implementation returns true. If a subclass does not have a payload, it should set the _hasPayload data member to false

quint32 AbstractProtocol::protocolId ( ProtocolIdType type ) const [virtual]

Returns the protocol id of the protocol for the given type.

The default implementation returns 0. If a subclass represents a protocol which has a particular protocol id, it should return the appropriate value. If a protocol does not have an id for the given type, it should defer to the base class. e.g. IGMP will return 2 for ProtocolIdIp, and defer to the base class for the remaining ProtocolIdTypes; IP will return 0x800 for ProtocolIdEth type, 0x060603 for ProtocolIdLlc and 0x04 for ProtocolIdIp etc.

AbstractProtocol::ProtocolIdType AbstractProtocol::protocolIdType ( ) const [virtual]

Returns the protocolIdType for the protocol.

The default implementation returns ProtocolIdNone. If a subclass has a protocolId field it should return the appropriate value e.g. IP protocol will return ProtocolIdIp, Ethernet will return ProtocolIdEth etc.

quint32 AbstractProtocol::protocolNumber ( ) const [virtual]

Returns the protocol's field number as defined in message 'Protocol', enum 'k' (file: protocol.proto)

Subclasses MUST implement this function

void AbstractProtocol::protoDataCopyFrom ( const OstProto::Protocol & protocol ) [pure virtual]

Copy and update the protocol's protobuf member data variable from the passed in protocol.

In the base class this is a pure virtual function. Subclasses MUST implement this function. See the SampleProtocol for an example

void AbstractProtocol::protoDataCopyInto ( OstProto::Protocol & protocol ) const [pure virtual]

Copy the protocol's protobuf as an extension into the passed in protocol.

In the base class this is a pure virtual function. Subclasses MUST implement this function. See the SampleProtocol for an example

void AbstractProtocol::removeVariableField ( int index )

Removes the variableField from the protocol at the specified index.

bool AbstractProtocol::setFieldData	(	int	index,
		const QVariant &	value,
		FieldAttrib	attrib = `FieldValue`
	)		`[virtual]`

Sets the value of a field corresponding to index.

This method is called by the GUI code to store a user specified value into the protocol's protoBuf. Currently this method is called with FieldAttrib = FieldValue only.

Returns true if field is successfully set, false otherwise. The default implementation always returns false. Subclasses should reimplement this method. See SampleProtocol for an example.

QString AbstractProtocol::shortName ( ) const [virtual]

Returns the short name or abbreviation of the protocol.

The default implementation forms and returns an abbreviation composed of all the upper case chars in name()
The default implementation caches the abbreviation on its first invocation and subsequently returns the cached abbreviation

const OstProto::VariableField & AbstractProtocol::variableField ( int index ) const

Returns the variableField at the specified index as a constant Reference i.e.

read-only

int AbstractProtocol::variableFieldCount ( ) const

Returns the count of variableFields in the protocol.