// 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 the License "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
