// 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:
// posthook.h - Base class for post hooks
// Base class for post hooks.
//



/**
 @file posthook.h
 @publishedPartner
 @released
*/

#ifndef __POSTHOOK_H
#define __POSTHOOK_H

#include <e32std.h>
#include <es_sock.h>

#include "in_bind.h"

// *****************
// CProtocolPostHook
// *****************

class CProtocolPosthook : public CIp6Hook
	/**
	* Base class for the hooks between IP and NIF.
	*
	* This is the base class for hooks that live between the IP and
	* NIF layer (post-processing and pre-processing hooks). However,
	* this is also suitable for the base class of any hook. The class
	* provides automatic "network service detection", and supports both
	* <b>binding to</b> and <b>binding from</b> IP6.
	*
	* The implementations of CProtocolPosthook::BindL and
	* CProtocolPosthook::Unbind handle the "chaining" feature of the
	* post processing hooks. The stack uses a sequence of BindL and
	* Unbind calls when inserting or removing a protocol.
	*
	* Outbound (MIp6Hook::BindPostHook()):
@verbatim
 U ---> IP6          F ---> NIF
 ..Send.. \         /
           \   ....P ->
            \                      |
             H1 --> H2 --> ... --> T
             ...Send...Send...Send
@endverbatim
	* The MNetworkService::Send passes the packet (P) to the CProtocolBase::Send
	* of the first post processing hook (H1). It is the responsibility of
	* H1 to pass the packet to the next post-processing hook (H2). The stack
	* maintains an internal chain terminator (T), which will pass the packet
	* to the NIF using the flow context (F) attached to the packet. The
	* Send does the packet forwarding to the next linked hook automaticly.
	* 
	* The information block associated with the packet is defined
	* by RMBufSendPacket , which always includes a reference to the
	* flow context (F). If a hook before the terminator (T) does
	* not pass the packet forward in chain, then it must also
	* take care of releasing the flow context
	* (RMBufSendInfo::iFlow.Close()).
	*
	* The flow context is the only way for the terminator (T) to
	* know the target NIF. If the packet has not flow context, the
	* terminator drops the packet. The flow context is detached
	* from the packet before it is passed to the NIF.
	*
	* Inbound (MIp6Hook::BindPreHook()):
@verbatim
   NIF --> IP6                     IP6 ---> U
  ..Process..\                      |
              \   ......P ->        |
               \     src=NIF        |
               H1 --> H2 --> .. --> T
            ..Process..Process..Process
@endverbatim
	* The MNetworkService::Process passes the incoming packet
	* to the CProtocolBase::Process of the first pre-processing hook
	* (H1). It is the responsibility of the H1 to pass the packet
	* to the next pre-processing hook (H2). The stack maintains
	* an internal terminator (T), which will pass the packet
	* upwards in the protocol stack. The CProtocolPosthook::Process
	* does the packet forwarding to the next linked hook automaticly.
	*
	* In the Process chain, the source (CProtocolBase *) is actually
	* a pointer to the NIF object (CNifIfBase). Upon arriving to the
	* terminator (T), the source must still be a valid and known to
	* stack as a NIF (successfully introduced as documented in
	* @ref nif_binding
	* at some earlier point). Otherwise packet is not accepted.
	* The information block is defined by the RMBufPktInfo class.
	* The information block "changes into" RMBufRecvInfo after the
	* terminator (T).
	*
	* CProtocolPosthook can also be used as a generic base for any hook.
	* Then the following protocol ids for the BindL will become reserved:
	*
	* - MIp6Hook::BindPostHook()  (for outbound posthook chaining)
	* - MIp6Hook::BindPreHook() (for inbound posthook chaining)
	* - #KProtocolInet6Ip (for the network intance)
	* - #KProtocolInetIp (for network instance, deprecated)
	*
	* ::BindToL implementation handles #KProtocolInet6Ip
	* and #KProtocolInetIp targets. This does not do automatic CProtcolBase::BindL
	* to the target (see ::DoBindToL). The hook binds, if needed, should be done
	* in the ::NetworkAttachedL function.
	*
	* @publishedPartner
	* @released
	*/
	{
protected:
	IMPORT_C virtual ~CProtocolPosthook();
public:
	IMPORT_C virtual void BindToL(CProtocolBase* aProtocol);
	IMPORT_C virtual void BindL(CProtocolBase* aProtocol, TUint aId);
	IMPORT_C virtual void Unbind(CProtocolBase* aProtocol, TUint aId);
	IMPORT_C virtual TInt Send(RMBufChain &aPacket, CProtocolBase* aSrc);
	IMPORT_C virtual void Process(RMBufChain &aPacket, CProtocolBase* aSrc);
	TInt ApplyL(RMBufHookPacket & /*aPacket*/, RMBufRecvInfo & /*aInfo*/) 
		/** Default ApplyL.
		* The default ApplyL does nothing to the packets.
		* @note
		*	If the only hook binding is post or pre-preprocessing, the ApplyL
		*	is never called.
		*
		* @return #KIp6Hook_PASS
		*/
		{ return KIp6Hook_PASS; }
	/**
	* Network layer has been attached.
	*
	* This function is called when the network layer is detected and
	* attached to this protocol object (::NetworkService() returns non-null).
	* The implementation in the derived class can now
	* do the hook specific binds and unbinds using:
@code
	// request inbound packets to my Process()
	NetworkService()->BindL(this, MIp6Hook::BindPreHook());
	// request outbound packets to my Send().
	NetworkService()->BindL(this, MIp6Hook::BindPostHook());
	...
	// stop getting inbound packets to my Process()
	NetworkService()->Unbind(this, MIp6Hook::BindPreHook());
	// stop getting outbound packets to my Send()
	NetworkService()->Unbind(this, MIp6Hook::BindPostHook());
	// ..or, to rip off all my hooks
	NetworkService()->Unbind(this);
@endcode
	*/
	virtual void NetworkAttachedL() = 0;
	/**
	* Network layer is being detached.
	*
	* This function is called when the hook is losing
	* the connection to the network instance (the network
	* instance has issued Unbind request, because it is
	* shutting down).
	*
	* Derived class does not need to implement this, unless it
	* caches network layer dependent data internally. Otherwise,
	* it must implement the function and cleanup all such data.
	*
	* During the call ::NetworkService returns the
	* service instance that is going away. However, it should not
	* be used for any binding or unbinding. the detach process does
	* the unbindings automaticly.
	*
	* @note
	*	The desctuctor can be called while network is attached.
	*	CProtocolPosthook destructor will unbind this object
	*	automaticly from the network (cancel all binds), and
	*	then detaches withouth calling NetworkDetached. Thus,
	*	the destructor of the derived class must do the cleanup
	*	of cached data, but it does not need to worry about the
	*	binds to the network.
	*/
	virtual void NetworkDetached() {};
	/**
	* Gets the network service.
	*
	* This returns the network service, if any is currently attached.
	* The network is attached after ::NetworkAttachedL call until
	* the next ::NetworkDetached or destruction. Otherwise, network
	* is not attached and return is always NULL.
	*
	* @return The network service or NULL.
	*/
	inline MNetworkService *NetworkService() const { return iNetwork; }
protected:
	IMPORT_C TInt DoBindToL(CProtocolBase *aProtocol);
private:
	/** The attached network layer (IP layer).
	* The CProtocolPosthook::DoBindToL, CProtocolPosthook::BindL
	* and CProtocolPosthook::Unbind implementations maintain this
	* pointer.
	*/
	MNetworkService *iNetwork;
	/** Outbound posthook chain.
	* The next protocol in list. The CProtocolPosthook::BindL and
	* CProtocolPosthook::Unbind implementions maintain this chain
	* based on the calls coming from the network layer. The id
	* reference in the chaining calls is MIp6Hook::BindPostHook().
	*/
	CProtocolBase *iPostHook;
	/** Inbound posthook chain.
	* The next protocol in list. The CProtocolPosthook::BindL and
	* CProtocolPosthook::Unbind implementions maintain this chain
	* based on the calls coming from the network layer. The id
	* reference in the chaining calls is MIp6Hook::BindPreHook().
	*/
	CProtocolBase *iInboundHook;
	/**
	* The network attachment type.
	* This base class supports both "bind" and "bindto" attachments
	* to the network layer.
	*
	* - if == 1, <tt>bindto= ip6</tt> is in the "hook" ESK file.
	*	#iNetwork has been set by CProtocolPosthook::DoBindToL.
	* - if == 0, <tt>bindto= hook</tt> is in the [ip6] section of
	*	the TCPIP6.ESK. #iNetwork has been set by the
	*	CProtocolPosthook::BindL.
	*
	* The value is significant only if #iNetwork is non-NULL.
	*/
	TUint iBindToNet:1;
	};

#endif