// 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:

// ip6_hook.h - hook interface for IPv6 extension header handlers

// This module defines the interface between the main IPv6 protocol

// handler (ip6.cpp) and header handlers. A hook need only the basic

// IPv6 header definitions (ip6_hdr.h), it does not need to be aware

// of IPv6 protocol specific classes: it should not include ip6.h!

// This describes a pure interface, there is no respective

// implementation module (ip6_hook.cpp does not exist).

//

/**

 @file ip6_hook.h

 @publishedPartner

 @released

*/

#ifndef __IP6_HOOK_H__

#define __IP6_HOOK_H__

#include <es_prot.h>

#include <nifmbuf.h>	// The interface uses RMBuf with Info

#include "inet6err.h"

#include "flow.h"

#include "ip6_iprt.h"	// ..for CProtocolBaseUnbind class.

#include "apibase.h"

/** @name IP v6 constants 

* @since v7.0

*/

//@{

/**

* A reference constant used to compute protocol ID values for the CProtocolBase::BindL() 

* method of the IP protocol.

*/

const TInt KIp6Hook_ANY = 256;

/**

* A special return value from MIp6Hook::ApplyL().

*

* This signals that the hook didn't handle the extension header,

* which will be passed to the next registered hook

*/

const TInt KIp6Hook_PASS = 0;

/**

* A special return value from MIp6Hook::ApplyL().

* 

* This signals that the hook processed the extension header and

* that the main loop should restart a new hook processing using

* the function's aInfo.iProtocol field.

*/

const TInt KIp6Hook_DONE = 1;

/**

* A flag that must be <b>cleared</b> by MIp6Hook::ApplyL() processing

* in the aInfo.iFlags parameter, if the hook changes the destination or

* source address in the aInfo.

* 

* It causes address and forwarding checks to be run by the main loop.

* 

* Note that this requires the hook to also signal that the extension

* header has been processed by returning KIp6Hook_DONE. 

*/

const TUint KIpAddressVerified	= 0x080000;

//

//	*NOTE*	This flag is added as a stopgap solution for

//			the IPSEC problem, which results if decrypted packet

//			is echoed pack due to some error condition (like

//			Port Unreachable). It may be removed when a final

//			solution for the problem is found (and if no other

//			uses exist). -- msa

/**

* Prevent sending of this packet as ICMP error report.

*

* A flag that if set causes an unconditional drop of a packet,

* if the packet is passed to the ICMP send functionality in

* the IP layer. (see MNetworkService::Icmp4Send or

* MNetworkService::Icmp6Send

*/

const TUint KIpNeverIcmpError	= 0x100000;

// *NOTE*

//	Reuse the same bit as KIpAddressVerified. This

//	is ok, because verified bit is used only for incoming

//	packets, and the keep up is used only for outgoing packets.

//

/**

* KIpKeepInterfaceUp is an internal flag which set or reset

* depending on the state of the KSoKeepInterfaceUp option.

*/

const TUint KIpKeepInterfaceUp	= 0x080000;

/**

* If this bit is set in RMBufPktInfo flags, the ECN ECT bits in

* IP packet should be zeroed.

*/

const TUint KIpNoEcnEct			= 0x200000;

//@}

//

//	RMBufRecvInfo

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

class RMBufRecvInfo : public RMBufPktInfo

/**

* Information for incoming packets.

* 

* This extends the packet information class to record progress of

* processing the received IPv4 or IPv6 packet.

*

* The RMBufChain contains a full IPv6 (or IPv4) packet

* starting from the beginning. The position of the current

* (upper layer or extension header) is indicated by the

* #iOffset field.

*

* @li #iProtocol

*	is always the internet protocol number 	corresponding

*	to the header incidated by iOffset.

*	

* @li #iLength

*	is the length of the FULL packet, starting from the

*	IP header. The upper layer length (that includes

*	the uppler layer header) is always: (iLength - iOffset) >= 0.

*	Note that this can be ZERO!

*

* @li #iIcmp == 0, for normal packet

*

* @li #iIcmp =! 0, for ICMP error report

*

* The source and destination address are loaded from the ip

* header associated with the indicated upper layer header. In

* case of ICMP error report, the addresses are loaded from the

* packet *inside* the ICMP report.

*

* The addresses are always in IPv6 format. If the packet

* was IPv4 packet, the addresses are presented in IPv4 mapped format.

*

* @warning

*	The fact that address is IPv4 mapped DOES NOT mean that

*	the packet is IPv4. It could as well be an IPv6

*	packet with mapped addresses!

*

* @warning

*	RMBufRecvInfo is assuming that it fits

*	into the single RMBuf block.

*

* @publishedPartner

* @released

* @since v7.0

*/

	{

public:

	TInt CheckL(TInt aLength) const

	/**

	* Tests that the specified length field does not exceed the

	* remaining space in the buffer.

	*

	* Verify that there is enough data after in the packet

	* after the #iOffset octets. This simply tests whether

	* (aLength > #iLength - #iOffset), and leaves

	* with #KErrInet6ShortPacket, if true.

	*

	* @param aLength				Length to test.

	* @return aLength				(for convenience)

	* @leave KErrInet6ShortPacket	Insufficient space.

	*/

		{

		if (aLength > iLength - iOffset)

			User::Leave(KErrInet6ShortPacket);

		return aLength;

		}

	/** Index of the logical source network interface. */

  	TUint32 iInterfaceIndex;

	/** Index of the physical original network interface. */

 	TUint32 iOriginalIndex;

	//

	// IP Information

	//

	/**

	* An offset that indicates the beginning of the current header

	* being processed.

	* 

	* Inbound hooks must update this if they consume a header

	* within the packet.

	* 	

	* It initially points to the first header after the IP header.

	* Offset to the header being processed.

	*/

	TInt iOffset;

	/**

	* Offset to the related IP header.

	* 

	* This is usually zero, but is non-zero for ICMP error reports, and could be 

	* non-zero for tunneled packets.

	*/

	TUint16 iOffsetIp;

	/** Offset of the previous Next Header field.

	* 

	* If a hook consumes an extension header and advances #iOffset to the

	* next header, it must also set this to point to the Next Header

	* field of the former header.

	*

	* This is initialized to refer the next header field of the IP header.

	*

	* This can be used by header handlers which remove the

	* header from the packet. For example, IPSEC does this for AH and

	* ESP headers. IPSEC must be able to correct the protocol/next header

	* field of the previous header.

	*/

	TUint16 iPrevNextHdr;

	/**

	* IP Version (4 or 6) of the related IP header.

	*/

	TUint8 iVersion;

	/**

	* ICMP packet flag.

	* 	

	* This determines the interpretation of the information fields:

	* iType, iCode, and iParameter.

	*

	* @li

	*	iIcmp == 0,	The buffer contains normal upper layer packet,

	*	the header starting from the indicated iOffset.

	*	The values of the iType, iCode and iParameter are undefined..

	*

	* @li

	*	iIcmp != 0,	The buffer contains an ICMP error report for

	*	the upper layer protocol, the returned upper layer header

	*	starting from the indicated iOffset. The #iOffsetIp indicates

	*	the start of the problem packet.

	*

	* Valid values are: 0, #KProtocolInetIcmp, or #KProtocolInet6Icmp.

	*/

	TUint8 iIcmp;

	/**

	* ICMP Type (0..255).

	* 

	* This applies to both ICMPv4 and ICMPv6.

	*

	* (only defined if the field iIcmp != 0)

	*/

	TUint8 iType;

	/**

	* ICMP Code (0..255).

	* 

	* This applies to both ICMPv4 and ICMPv6.

	*

	* (only defined if the field iIcmp != 0)

	*/

	TUint8 iCode;

	/**

	* The last 32 bits from the ICMP header.

	*

	* (only defined if the field iIcmp != 0)

	*/

	TUint32 iParameter;

	};

typedef class RMBufInfoPacketBase<RMBufRecvInfo> RMBufRecvPacket;

class MPacketContext : public MInetBase

/**

* Provides a packet context as a number of (key, value) pairs.

*

* The rules for construction of the key are:

* @li

*	The low eight bits of the key contain always the protocol number

*	(extension header) being implemented by the hook.

* @li

*	If the protocol is destination option or hop-by-hop option,

*	the implemented option types are communicated to the default

*	handler by adding a non-zero value to the packet context with

*	a key computed as "(option-type << 8) | protocol".

*

* @publishedPartner

* @released

* @since v7.0

*/

	{

public:

	/**

	* Sets a (key,value) pair.

	* 

	* If a setting already exists for the key, the value is just replaced.

	*

	* @param aId	Key

	* @param aValue	Value associated with the key

	* @return

	* @li	KErrNone, if value stored successfully.

	* @li	KErrNoMemory, if there was no room for the new value

	*/

	virtual TInt SetHookValue(const TUint32 aId, const TUint32 aValue) = 0;

	/**

	* Gets the value associated with the specified key.

	*

	* Return the current value associated with aId. If aId does not

	* exist, ZERO is returned [=> there is no way to differentiate

	* between non-existing value and a value that is explicitly set

	* to zero. Implementation may interpret setting value to ZERO

	* as request to delete the association, if it exists].

	*

	* @param aId	Key

	* @return	The value, or 0 if no value was found for the key..

	*/

	virtual TUint32 HookValue(const TUint32 aId) const = 0;

	};

class RMBufHookPacket : public RMBufRecvPacket

/**

* Extends the received packet buffer class for hook processing.

* 

* The extension provides a packet context (MPacketContext) for

* the duration of the hook processing. 

* 

* This extension has been created to solve the following problem:

*

*	-#	The default option header handlers need to return ICMP

*		error message on some unimplemented options,

*	-#	The basic design idea of the stack is that functionality

*		can be dynamically added. Thus, if a dynamically loaded

*		module adds support for some new option type, the default

*		handler should not report error for such options.

*

* The rules of the context use are:

*

*	-#	While the incoming packet is processed with hooks, the IP

*		layer maintains a packet specific context, which can store

*		values (32 bits) associated with a key (32 bits).

*	-#	The low 8 bits of the key is defined to be the protocol number

*		of the header, and interpretation of the rest of the key bits

*		is up to protocol/header specific definitions.

*	-#	For destination and hop by hop headers, to solve the problem,

*		the additional specification is used: the default handlers will

*		look a value from packet context with the following key:

*			- (optiontype << 8) | (protocol)

*			.

*		and if the returned value is non-ZERO, the default handler

*		will assume someone implemented the option in question and

*		does not generate an error.

*

* @note

*	The packet context is only available during "hook processing".

*	It is not available for upper layer prototocols!

*

* @publishedPartner

* @released

* @since v7.0

*/

	{

public:

	/**

	* Constructor

	* @param aContext Packet context

    */

	inline RMBufHookPacket(MPacketContext *const aContext) : iContext(aContext) {}

	inline TInt SetHookValue(const TUint32 aId, const TUint32 aValue)

	/**

	* Sets a (key,value) pair.

	* 

	* If a setting already exists for the key, the value is just replaced.

	*

	* @param aId Key

	* @param aValue  Value associated with the key

	* @return  KErrNone, if the value was stored,

	* @return  KErrNoMemory, if there was no room to store the value

	*/

		{ return iContext->SetHookValue(aId, aValue); }

	inline TInt HookValue(const TUint32 aId) const

	/**

	* Gets the value associated with the specified key. 

	* 

	* @param aId	Key

	* @return		The value, or 0 if no value was found for the key 

	*

	* Note: There is no way to distinquish between 'no stored value'

	* and 'stored value = 0'.

	*/

		{ return iContext->HookValue(aId); }

private:

	// The packet context handler. This is always defined while the

	// packet is being processed by the hooks.

	MPacketContext *const iContext;

	};

//

//	MIp6Hook

//

class MIp6Hook : public MInetBase

/** Abstract IP hook interface.

* 

* A protocol which binds to the stack as a hook

* must implement this interface.

*

* @warning

*	Even though this is a mixin class, all protocol hooks

*	<b>MUST</b> be derived from CIp6Hook, which includes MIp6Hook.

*	The stack assumes that all hooks use CIp6Hook derived

*	classes. This is only for hooks, an upper layer protocol

*	can be anything derived from CProtocolBase. However, the

*	recommended base class for the upper layer is CProtocolInet6Binder.

*	The recommended generic base class for any hook is CProtocolPosthook,

*	which inherits from CIp6Hook.

*

* An IPv6 packet can have several layers of extension headers

* to be peeled off, before the actual transport layer is reached.

* This process must be done by the installed hooks following this

* API. The stack includes default hooks for the obligatory extension

* headers (destination, hop-by-hop and routing headers). A hook which

* implements an extension header for the protocol number N, attaches

* itself to the stack by calling

@code

	NetworkService()->BindL(this, BindHookFor(N));

@endcode

* and starts receiving a call to the ApplyL() function for

* each protocol header N. It is possible that one packet contains

* multiple instances of the header N, and ApplyL is called

* for each of them. If multiple hooks register for the same

* protocol, they are called sequentially until any of them

* handles the header or rejects the packet.

*

* A hook can also register to be called just before the packet

* is going to be passed to the upper layer by calling:

@code

	NetworkService()->BindL(this, BindHookAll());

@endcode

* Any number of hooks can register this way and the ApplyL()

* is called sequentially until any of them rejects the packet.

* If all of them pass the packet, the packet goes to the

* upper layer protocol.

*

* A hook can also process outgoing packets. This type of hook

* should implement OpenL(), SetFlowOption() and GetFlowOption().

* The outbound processing is totally different from the inbound

* processing, and is based on the flow architecture and MFlowHook.

* Registerning for outbound flow processing is

@code

	NetworkService()->BindL(this, BindFlowHook());

@endcode

* If a hook is interested in packets which the stack would

* forward, if forwarding is enabled, there is a binding code

* for that too:

@code

	NetworkService()->BindL(this, BindForwardHook());

@endcode

* The ApplyL() of the forwarding hook is called for each received

* packet, which does not have a destination address of this node

* (either unicast or multicast group).

*

* Finally, a hook can be a post processing hook, which sees raw

* packets as they come from the network interfaces (inbound) or are

* going out to the interface (outbound).

* The base class for a post processing hook should be CProtocolPosthook.

* The registering for post processing hook is:

@code

	NetworkService()->BindL(this, BindPostHook()); // for outbound

	NetworkService()->BindL(this, BindPreHook());  // for inbound.

@endcode

*

* All hooks can monitor which interfaces are attached to the stack.

* This requires implementing InterfaceAttached() and InterfaceDetached(). 

*

* @publishedPartner

* @released

* @since v7.0

*

* @dontinclude mip6hook.cpp

* Example using a hook class

* @skip class CHookExample

* @until //-

* and registering hooks with the stack to handle extension header

* in all incoming and outgoing packets:

* @skip ::NetworkAttachedL

* @until //-

*/

	{

public:

	inline static TUint BindHookFor(TUint8 aProtocol)

		/**

		* Gets the ID value for binding as an inbound hook for the

		* specified protocol.

		* 

		* @param aProtocol Protocol number (0..255) for which to get ID

		* @return 		   The ID value

		*/

		{ return KIp6Hook_ANY + aProtocol; }

	inline static TUint BindHookAll()

		/**

		* Gets the ID value for binding as an inbound hook for all protocols.	

		* 

		* @return	The ID value

		*/

		{ return 2*KIp6Hook_ANY; }

	inline static TUint BindFlowHook(TUint8 aPriority = 1)

		/**

		* Gets the ID value for binding as an outbound flow hook

		* with the specified priority.

		* 

		* The priority determines the calling order for OpenL() sequence.

		* 

		* @param aPriority Priority value (allowed range [1..255])

		* @return 		   The ID value

		*/

		{ return 2*KIp6Hook_ANY + Max(Min(KIp6Hook_ANY-1, aPriority), 1); }

	inline static TUint BindPostHook()

		/**

		* Gets the ID value for binding as an outbound packet

		* post-processor (below the IP layer).

		*

		* See CProtocolPosthook.

		* 

		* @return	The ID value

		*/

		{ return 3*KIp6Hook_ANY; }