diff -r 000000000000 -r af10295192d8 networkprotocols/iphook/inhook6/include/posthook.h --- /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 +#include + +#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 + * binding to and binding from 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, bindto= ip6 is in the "hook" ESK file. + * #iNetwork has been set by CProtocolPosthook::DoBindToL. + * - if == 0, bindto= hook 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