// Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies).

// All rights reserved.

// This component and the accompanying materials are made available

// under the terms of "Eclipse Public License v1.0"

// which accompanies this distribution, and is available

// at the URL "http://www.eclipse.org/legal/epl-v10.html".

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

// in_pkt.h - packet handling routines

// Generic packet handling utility for mapping packet handling to the RMBufChain.

//

/**

 @file in_pkt_partner.h

 @publishedPartner

 @released

*/

#ifndef __IN_PKTPARTNER_H__

#define __IN_PKTPARTNER_H__

#include <nifmbuf.h>

//	RMBufPacketPeek

//	***************

class RMBufPacketPeek : public RMBufChain

	/**

	Extends RMBufChain to add functions to read packet data as a descriptor 

	and as an IP header.

	The RMBufChain is assumed to contain the raw packet, without

	the info block prepended (e.g. if this class is used for RMBufPacketBase

	derived handle, it must be in "unpacked" state).

	@since v7.0

	@publishedAll

	@released

	*/

	{

public:

	IMPORT_C TPtr8 Access(TInt aSize, TUint aOffset = 0);

	IMPORT_C TIpHeader *GetIpHeader();

	};

//	TPacketHead

//	***********

class TPacketHead

	/**

	Storage for some precomputed information for an outbound packet flow.

	The outbound TPacketHead is part of the flow context (CFlowContext).

	The CFlowContext::Connect initializes the content from the parameters

	of the flow (TFlowInfo) and runs the connection process.. The connection

	process (MIp6Hook::OpenL and MFlowHook::ReadyL phases) completes the

	information. After this, as long as the flow is connected, the content

	is mostly frozen and <b>must not be modified by anyone</b>.

    When there is a need to change any flow information, the changes must

	be done to the flow parameters (and not to TPacketHead). The change of

	flow parameters also sets the CFlowContext::iChanged flag, and this

	eventually causes a new CFlowContext::Connect, which re-initializes

	the TPacketHead with the new information.

	For each field in the TPacketHead, the hook writer must follow the

	basic rule (only for fields that it intends to change):

	- if some field is changed in MIp6Hook::OpenL, then the previous

	value should be restored in the MFlowHook::ReadyL.

	- an exeception: the hook must omit the restore, if the

	previous value was unspecified value (for example, the source

	address).

	- the content of #iPacket (and #iOffset) are special: they cannot

	be modified in the MIp6Hook::OpenL phase. A hook can

	modify them only in the MFlowHook::ReadyL phase. And, if the hook

	is adding an IP header for tunneling, it must save the current content

	of these fields in the ReadyL function, and then clear out the fields

	(it must make the iPacket empty and zero iOffset). The hook must add

	the saved iPacket content below the added tunnel header in

	MFlowHook::ApplyL .

	@since v7.0

	@publishedAll

	@released

	*/

	{

public:

	IMPORT_C TBool ExtHdrGet(TInt aType, TInt& aOfs, TInt& aLen);

	IMPORT_C TBool ExtHdrGetOrPrependL(TInt aType, TInt& aOfs, TInt& aLen);

	IMPORT_C TBool ExtHdrGetOrAppendL(TInt aType, TInt& aOfs, TInt& aLen);

	IMPORT_C void AddDestinationOptionL(const TPtrC8& aOption, TUint8 aAlign=0, TUint8 aModulo=4);

	IMPORT_C void AddDestinationOptionL(const TUint8* aOption, TUint8 aLen, TUint8 aAlign=0, TUint8 aModulo=4);

public:

	/**

	"Virtual" IP header. The IPv6 header stucture is used, but the same

	format is <b>also</b> used for the IPv4 destinations (Version() == 4,

	even though the header format is still IPv6!)

	This header is initialized in the beginning of the OpenL phase

	as follows:

	@li	Version = 0

	@li	Traffic Class, copied from the flow iOptions.iTrafficClass

	@li	Flow Label = 0

	@li	Payload Length = 0 (dummy field, not used)

	@li	Next Header, copied from the flow iProtocol

	@li	Hop Limit, copied from the flow iOptions.iHopLimit

	@li	Src Address, copied from the flow Local Address (usually unspecified)

	@li	Dst Address, copied from the flow Remote Address

	At beginning of the ReadyL phase (= at end of OpenL), the destination

	address (and iDstId) are used to find a route on the interface. Depending

	on whether this address is IPv4 (mapped) or IPv6, the Version field is set

	accordingly to either 4 or 6.

	After succesfull completion of the ReadyL, this used for *each* packet

	which needs an IP header to be generated on send. The Version() determines

	whether IPv4 or IPv6 frame is to be generated (this is the initial

	header in the packet, *before* running outbound ApplyL hooks):

	@verbatim

	                   IPv6            IPv4

	   Version         == 6            ==4

	   Traffic Class   used as is      used as TOS

	   Flow Label      used as is      ignored

	   Payload Length  ignored         ignored

	   Next Header     used as is      used as Protocol

	   Hop Limit       used as is      used as TTL

	   Src Address     used as is      used as IPv4 mapped

	   Dst Address     used as is      used as IPv4 mapped

	@endverbatim

	*/

	TInet6HeaderIP ip6;

	/**

	Contains the scope id associated with the destination address

	which is stored in #ip6 Dst Address. This id and address must

	always be considered as a unit. Logically, any change changes

	both values.

	iDstId is initialized from the flow context TFlowInfo::iRemote.Scope() at

	beginning of the flow connect phase. If application does not define

	this scope id, then the system will attempt to choose a default value

	at beginning of the connect phase. If the default cannot be determined,

	the flow is put into pending state (and no connect happens).

	@par MIp6Hook::OpenL

	On entry to the OpenL, the iDstId is always non-zero and destination

	address is specified. If a hook changes the destination address in

	OpenL method, it must provide the correct id value

	which goes with the new destination. If it cannot do this, it

	must either abort the connect by leaving with an error state, or it

	can leave with PENDING (> 0) status to signal there is no route

	for the new destination.

	If the stack cannot find suitable interface for the destination, then

	it aborts the connect phase, and the flow is placed into holding state.

	@note

		Only a tunneling hook can safely change the destination

		address (a use of routing header can also be a kind of

		tunneling).

	@par MFlowHook::ReadyL

	If the hook changed the destination address (or id) in the OpenL,

	the ReadyL must restore the original values back.

	*/

	TUint32 iDstId;

	/**

	Contains the scope id associated with the source address

	which is stored in #ip6 Src address. This is defined when the source

	address is defined, and otherwise undefined.

	iSrcId is initialized from TFlowInfo::iLocal.Scope() at beginning of the

	flow connect phase. If application defines the source address,

	but does not specify this scope id, then the system chooses

	the id based on the interface defined by the source address.

	If scope and address are both specified, they must match the

	selected interface.

	@par MIp6Hook::OpenL

	On entry to the OpenL, the iSrcId (and source address) may be

	undefined (#iSourceSet = 0). If defined (iSourceSet = 1), then

	both address and iSrcId are defined (iSrcId != 0). A hook may

	force a reselection of the source just by zeroing the

	iSourceSet.

	@par MFlowHook::ReadyL

	If the hook changed the source address (or id) in the OpenL,

	the ReadyL must restore the original values back, but only

	if the original value was defined (#iSourceSet = 1 in OpenL).

	*/

	TUint32 iSrcId;

	/**

	The source address has been set.

	This bit indicates whether the value stored in #ip6 src field

	and #iSrcId is to be used as a source address as is.

	Initialized from TFlowInfo::iLocalSet, which tells whether user

	specified tbe source address or not (e.g used RSocket Bind method).

	The stack checks the value after each MIp6Hook::OpenL call, and

	if the flag is set, the source in ip6 is used as is. If the flag

	is zero, then the stack performs the normal source address selection

	based on the current destination address (#iSrcId and destination

	address).

	@par MIp6Hook::OpenL

	On entry, this flag is always set and source address is defined.

	A hook may clear this flag, if it wants the

	stack choose the source address based on current destination.

	The clearing operation is normally needed only by a tunneling

	hook.

	@note

		If the hook specifies the source address, it must be either

		a valid source address for the interface or unspecified

		address.

	@par MFlowHook::ReadyL

	Upon entry to the ReadyL, the source address is always fully

	known (the hook can assume that #iSrcId and the #ip6 source

	addresses are valid).

	If the source address was set before the OpenL, then this

	must restore the original value (along with the #iSrcId

	and source address).

	*/

	TUint iSourceSet:1;

#ifdef TPACKETHEAD_FRAGMENT

	/**

	The fragment processing alredy done.

	This bit is meaningful only in OpenL phase. If already set,

	then some ealier hook has requested that the packet must

	be fragmented to fit the mtu.

	A tunneling hook can set this bit in OpenL, if it needs

	the fragmenting to happen before the ApplyL is called (e.g.

	the fragments are tunneled instead of fragmenting the

	tunneling).

	This bit can only be set or left as is. It cannot be cleared

	once set.

	*/

	TUint iFragment:1;

#endif

	/**

	Selector info, the upper layer protocol.

	iProtocol has the same value as ip6.NextHeader() when iPacket is empty,

	and otherwise it is the same as NextHeader() of the last extension

	header in the iPacket.

	The values of the other selector fields: #iIcmpType, #iIcmpCode

	#iSrcPort and #iDstPort depend on iProtocol. Whenever iProtocol

	is changed, the other fields must be updated accordingly.

	@par MIp6Hook::OpenL

	Because iPacket cannot be modified during the OpenL phase, the

	content of this field and the Next Header (protocol) field in

	the #ip6 pseudoheader must always be the same. This field should

	be considered as <b>read-only</b>, unless the hook intends to

	apply IP-in-IP tunneling, in which case the hook <b>must</b>

	change the value to the appropriate tunneling protocol

	(#KProtocolInet6Ipip or #KProtocolInetIpip).

    @par MFlowHook::ReadyL

	Only a tunneling hook needs to restore the value here to match

	the original upper layer protocol. See #iPacket for

	more detailed information.

	*/

	TUint8 iProtocol;

	/**

	Selector field whose value depends on #iProtocol. 

	If this field does not have meaning with the protocol,

	the field content should be set to ZERO.

	*/

	TUint8 iIcmpType;

	/**

	Selector field whose value depends on #iProtocol. 

	If this field does not have meaning with the protocol,

	the field content should be set to ZERO.

	*/

	TUint8 iIcmpCode;

	/**

	Selector field whose value depends on #iProtocol. 

	If this field does not have meaning with the protocol,

	the field content should be set to ZERO.

	*/

	TUint16 iSrcPort;

	/**

	Selector field whose value depends on #iProtocol. 

	If this field does not have meaning with the protocol,

	the field content should be set to ZERO.

	*/

	TUint16 iDstPort;

	/**

	The amount of pre-computed IPv6 extension headers in iPacket which

	are copied to the beginning of each outgoing packet

	If iOffset > 0, then #iPacket includes that much of extension

	headers that are copied in front of each packet.

	*/

	TInt iOffset;

	/**

	Pre-computed extension headers for all packets in this flow.

	These can only be added in the ReadyL phase. If any of the

	ReadyL's adds extension headers into this, it must take care

	of maintaining the correct Next Header in the virtual IP header

	(and the original upper layer protocol must be placed in the

	next header of the last extension header added.

	Stack copies the content of this to each outgoing packet, just below

	the IP header, before running the ApplyL functions of the outbound

	flow hooks.

	@par MIp6Hook::OpenL

	The iPacket <b>must not</b> be modified during the OpenL phase.

	@par MFlowHook::ReadyL

	A non-tunneling hook may add extension headers into the current

	iPacket. A tunneling hook has more complex requirements:

	it must save the current iPacket and #iOffset and initialize

	iOffset = 0, and iPacket as empty.

    @par MFlowHook::ApplyL

	When a tunneling hook adds the tunneling IP header, it

	must also copy the saved iPacket below the added IP header.

	*/

	RMBufPacketPeek iPacket;

	/**

	The received packet which caused an ICMP error reply to be sent.

	This is only used for ICMP error repply flows, and should be

	ignored by others -- mainly for IPSEC hook. The packet, if

	present, is in unpacked state.

	*/

	RMBufPacketBase iIcmp;

	/**

	The current destination interface.

 	This is ONLY used during connect/OpenL phase.

	The value is maintained by the stack, and is intended as

	read-only information for the hooks that have a use for

	it (for example, IPSEC implementing VPN specific policies).

	A hook must not modify this value (the stack will recompute

	the value after each OpenL, based on the possibly changed

	address parameters in the TPacketHead)

	@par MIp6Hook::OpenL

	<b>read-only</b>

	@par MFlowHook::ReadyL

	<b>read-only</b>

	*/

 	TUint32 iInterfaceIndex;

	};

//	TPacketPoker

//	************

class TPacketPoker

	/**

	Provides a utility for linear scanning of a chain of RMBuf objects (an RMBufChain).

	An object of this type maintains a current point in the RMBufChain. This point 

	can only move forward, and a leave occurs if the point advances beyond the 

	end of the chain.

	Any pointers and aligns arranged before the current point, remain valid: for 

	example, you can save a reference and advance the pointer, and the reference 

	remains usable.

	If instead you need to go to a single specified offset, then use

	RMBufChain::Goto() or RMBufPacketPeek::Access().

	@post

	A Generic implementation assert: 

	after construct, iTail == 0 iff iCurrent == 0 (all scanned), or

	in other words: as long as there are bytes after current point,

	iTail will be non-zero (and More() returns ETrue).

	All methods maintain this invariant or leave, if impossible.

	Some other utility methods, not directly related to scanning, are also included. 

	@since v7.0

	@publishedAll

	@released

	*/

	{

public:

	IMPORT_C TPacketPoker(RMBufChain &aChain);

	inline void SkipL(TInt aSize)

		/**

		Moves the current point forward a specified number of bytes.

		@param aSize Number of bytes to move forward

		@leave KErrEof

			if the request cannot be satisfied.

		*/

		{ if (aSize < iTail) { iTail -= aSize; iOffset += aSize; } else OverL(aSize); }

	inline TUint8 *Ptr() const

		/**

		Raw pointer to the current point (can be invalid, if iTail = 0).

		@note Internal "unsafe" method

		*/

		{return iCurrent->Ptr() + iOffset; }

	inline TUint8 *ReferenceL(TInt aSize = 1)

		/**

		Gets a pointer to the current point, such that

		at least the specified minimum number of bytes can be read.

		@param aSize

			Specified minimum number of bytes to be read through

			the returned pointer.

		@return Raw data pointer

		@leave KErrEof

			if the request cannot be satisfied.

		*/

		{ if (iTail >= aSize) return Ptr(); else return AdjustL(aSize); }

	inline TUint8 *ReferenceAndSkipL(TInt aSize)

		/**

		Gets a pointer to the current point, such that at least the

		specified minimum number of bytes can be read,

		and moves the point the specified number of bytes forward.

		@param aSize

			Specified minimum number of bytes to be read through the returned 

			pointer, and the number of bytes to move forward

		@return

			Raw data pointer

		@leave KErrEof

			if the request cannot be satisfied.

		*/

		{ TUint8 *x = ReferenceL(aSize); SkipL(aSize); return x; }

	inline TInt Remainder() const

		/**

		Gets the length of the contiguous space after the current point.	

		@return Length after the current point

		*/

		{ return iTail; }

	inline TBool AtBegin() const

		/**

		Tests whether the current point is at the beginning of an RMBuf.

		@return ETrue if current point is at the beginning

		*/

		{ return iOffset == 0; }

	inline TBool More() const

		/**

		Tests whether there is more data to scan.

		@return ETrue if there is more data to scan

		*/

		{ return iTail > 0; }

	IMPORT_C static TBool IsExtensionHeader(TInt aProtocolId);

private:

	IMPORT_C void OverL(TInt aSize);

	IMPORT_C TUint8 *AdjustL(TInt aSize);

	/** The RMBuf of the current point. */

	RMBuf *iCurrent;

	/** The offset of the current point in the RMBuf. */

	TInt iOffset;

	/** Remaining bytes starting from the current point in the RMBuf. */

	TInt iTail;

	};

#endif