--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/networkprotocols/iphook/inhook6/include/posthook.h Tue Jan 26 15:23:49 2010 +0200
@@ -0,0 +1,242 @@
+// 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