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

// flow.h - IPv6/IPv4 flow information

// IPv6/IPv4 flow information.

//

/**

 @file flow.h

 @publishedPartner

 @released

*/

#ifndef __FLOW_H__

#define __FLOW_H__

#define SYMBIAN_NETWORKING_UPS

#include <es_prot.h>

#include <nifmbuf.h>

#include "in_pkt.h"

#include "apibase.h"

//

//	TFlowStatus

//

/**

* Type of the flow status (some symbolic enum names).

* @since v7.0

* @publishedPartner

* @released

*/

enum TFlowStatus

	{

	/**

	* (< 0) Flow is in error state.

	*

	* All other system wide error codes also indicate a flow error state. 

	* To recover, the flow must be reconnected.

	*/

	EFlow_DOWN = KErrNotReady,

	/**

	* (= 0) Flow is ready to send data.

	*/

	EFlow_READY = 0,

	/**

	* (= 1) Flow is temporarily blocked.

	*

	* This is used when the flow is waiting for the connection setup. 

	* When there is a possibility that flow could change into EFLow_READY

	* state, the notifier is notified with MProviderNotify::CanSend().

	*/

	EFlow_PENDING = 1,

	/**

	* (= 2) Flow is temporarily blocked.

	*

	* This is used when the flow is blocked due to congestion (e.g. lower level 

	* buffers are full). When congestion clears and if there is a possibility

	* that flow could change into EFLow_READY state, the notifier is notified

	* with MProviderNotify::CanSend().

	*/

	EFlow_HOLD = 2

#ifdef SYMBIAN_TCPIPDHCP_UPDATE

	,

    EFlow_NOTCONFIGURE = 3

#endif //SYMBIAN_TCPIPDHCP_UPDATE    

	};

//	MProviderNotify

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

class MProviderNotify : public MInetBase

	/**

	* Receiver of the notifications of the status changes in the flow.

	*

	* Note that the two functions CanSend() and Error() are a subset of MSocketNotify. This allows 

	* a Service Access Point to implement the interface just by calling the equivalent 

	* MSocketNotify functions. 

	* @since v7.0

	* @publishedPartner

	* @released

	*/

	{

public:

	/**

	* Flags that the flow might be ready to change into the EFlow_READY status

	*

	* The flow is (or has been) in EFlow_PENDING or EFlow_HOLD state. The flow

	* owner can now check if flow really can be changed into EFlow_READY state.

	* The state is updated by calling RFlowContext::Status (or some other functions

	* that implicitly refresh the flow state by calling internally the

	* CFlowContext::RefreshFlow function).

	*

	* Even if this function is called, the flow can still be in error or blocked

	* state. This is because, for example, when congestion clears, all flows

	* waiting for that event are notified, but some earlier notified flow may

	* already have refilled all the buffers.

	*/

	virtual void CanSend() = 0;

	/**

	* The flow has entered an error state.

	*

	* Error state in a flow is permanent and requires a new connect (CFlowContext::Connect)

	* to be cleared. A new connect occurs implicitly at FlowContext::Status (or some

	* at some other functions), if flows connection parameters have been modified

	* since the last connect (CFlowContext::iChanged is 1).

	*

	* @param aError Flow error code

	* @param anOperationMask A bitmask of MSocketNotify::TOperationBitmasks values 

	* specifying which pending operations are affected by the error up-call.

	*/

	virtual void Error(TInt aError, TUint anOperationMask=MSocketNotify::EErrorAllOperations) = 0;

	virtual void NoBearer(const TDesC8& aConnectionParams) = 0;

	virtual void Bearer(const TDesC8 &aConnectionInfo) = 0;

	virtual TInt CheckPolicy(const TSecurityPolicy&, const char *) 

		{

		return KErrNone;

		};

	};

//

//	RFlowContext

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

//

class MFlowManager;

class CFlowContext;

class CNifIfBase;

//	*WARNING*:

//		Because RFlowContext is used as a member of RMBufSendInfo, which may

//		get moved around, the RFlowContext handle *MUST* not contain anything

//		that breaks if it is copied bit-by-bit from one memory area to another!

//		(for example don't even think of adding link fields and linking

//		RFlowContext's into a list!) -- msa

//

class RFlowContext

	/**

	* A handle to a flow context.

	*

	* The main purpose of this class is to provide automatic reference counting 

	* for flow context users.

	*

	* A typical use for a RFlowContext object is to:

	* @li	allocate a context to a handle through the flow manager (Open())

	* @li	set appropriate flow parameters (the upper layer protocol associated with 

	* 		the flow, destination and source addresses)

	* @li 	use the flow to send packets out

	* @li 	release the context (Close()) from the handle. 

	* @since v7.0

	* @publishedPartner

	* @released

	*/

	{

public:

	inline RFlowContext() : iFlow(0)

		/**

		* Default constructor.

		*

		* This creates a handle without any assigned flow context.

		*/

		{}

	IMPORT_C TInt Open(MFlowManager *aManager, const TSockAddr &aDst, const TSockAddr &aSrc, TUint aProtocol = 0, TUint aIcmpType = 0, TUint aIcmpCode = 0);

	IMPORT_C TInt Open(MFlowManager *aManager, TUint aProtocol = 0);

	IMPORT_C TInt Open(RFlowContext &aContext, RMBufPktInfo *aInfo = NULL);

	IMPORT_C TInt Clone(const RFlowContext &aFlow);

	IMPORT_C TInt ReOpen();

	IMPORT_C TInt Connect();

	inline TBool IsOpen()

		/**

		* Tests if context is attached

		*/

		{return iFlow != NULL;}

	IMPORT_C void SetRemoteAddr(const TSockAddr &aAddr);

	IMPORT_C void SetLocalAddr(const TSockAddr &aAddr);

	IMPORT_C void SetProtocol(TUint aProtocol);

	IMPORT_C void SetIcmpType(TUint aType, TUint aCode = 0);

	IMPORT_C MProviderNotify *SetNotify(MProviderNotify *aProvider);

	IMPORT_C TInt Status();

	IMPORT_C void Grab(RFlowContext &aContext);

	IMPORT_C void Copy(RFlowContext &aContext);

	IMPORT_C void Close();

	IMPORT_C CNifIfBase *Interface() const;

#ifdef SYMBIAN_TCPIPDHCP_UPDATE

	IMPORT_C TBool IsNdResolutionPending(); //RFC 4861 - Section 7.2.2

#endif //SYMBIAN_TCPIPDHCP_UPDATE

	inline CFlowContext *FlowContext() const

		/** Gets a pointer to the flow context object (CFlowContext)

		* attached to the handle.

		*

		* This can be used for more detailed control of the flow parameters.

		*

		* The returned pointer has limited validity,

		* and it should not be stored in any members of permanent objects.

		* In addition, care must be taken not to call any operation that could

		* destroy the flow context as a side effect.

		*

		* If there is a need for longer validity of the retrieved pointer,

		* the CFlowContext::Open and CFlowContext::Close methods can be used

		* to protect it.

		*

		* @return

		*		The flow context object.

		*/

		{ return iFlow; }

private:

	/** The flow context. */

	CFlowContext *iFlow;

	};

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

//	RMBufSendInfo, RMBufSendPacket

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

class RMBufSendInfo : public RMBufPktInfo

	/**

	* Information for outgoing packets.

	*

	* This extends the packet information class to record the flow context. 

	* @since v7.0

	* @publishedPartner

	* @released

	*/

	{

public:

	/** Flow context for the packet. */

	RFlowContext iFlow;	

	};

/** @since v5.0 */

typedef class RMBufInfoPacketBase<RMBufSendInfo> RMBufSendPacket;

// TFlowInfo

// *********

class TFlowInfo

	/**

	* Collects the information which defines a flow 

	* (The Upper Layer Flow Information). This is a

	* member of CFlowContext.

	*

	* @since v7.0s

	*/

	{

public:

	/**

	* Current remote addess as set by upper layer.

	*

	* Must always be specified before a flow can be connecte or

	* used for sending packets.

	*

	* See RFlowContext::SetRemoteAddr, CFlowContext::RemoteAddr

	*/

	TInetAddr iRemote;

	/**

	* Current local address (system or application selected).

	*

	* See RFlowContext::SetLocalAddr, CFlowContext::LocalAddr

	*/

	TInetAddr iLocal;

	/**

	* The protocol associated with the flow.

	*

	* See RFlowContext::SetProtocol, CFlowContext::Protocol

	*/

	TUint8 iProtocol;

	/**

	* ICMP type, when protocol is ICMP (or similar).

	*

	* See RFlowContext::SetIcmpType, CFlowContext::GetIcmpTypeCode

	*/

	TUint8 iIcmpType;

	/**

	* ICMP code, when protocol is ICMP (or similar).

	*

	* See RFlowContext::SetIcmpType, CFlowContext::GetIcmpTypeCode

	*/

	TUint8 iIcmpCode;

	/**

	* Set when upper layer set the local address.

	*

	* When set, the stack assumes the upper layer has specified

	* the source address of the flow. When not set, the stack

	* chooses the source address.

	*

	* This flag is cleared or set by the RFlowContext::SetLocalAddr().

	* The flag is cleared when address is unspecified and set otherwise.

	* Initial value is unset, if SetLocalAddr is never called.

	*

	* See also CFlowContext::IsLocalSet

	*/

	TUint iLocalSet:1;

	/**

	* Set when interface errors should not affect the flow.

	*

	* When an interface goes down (or reports an error), all flows

	* that are currently connected (routed) to this interface, are

	* also set into error error state (effectively, causing a

	* socket error to the applications).

	*

	* When this flag is set, flow is not set to the error state. However,

	* if interface is going down, the flow is put into hold/pending

	* state (until another or same interface becomes again available).

	*

	* See also the socket option: #KSoNoInterfaceError

	*/

	TUint iNoInterfaceError:1;

	/**

	* Set when this flow should not try to bring up the interface.

	*

	* When a connect is attempted on a flow and it fails due to

	* missing routes (no suitable interfaces up or configured yet), the

	* stack signals the NIFMAN (NoBearer notify function).

	*

	* When this flag is set, NIFMAN is not notified and the flow is

	* just placed into hold/pending state to wait for possible interface

	* or route to appear.

	*

	* @note

	*	NoBearer does not exisit in pre 7.0s systems. In such

	*	systems the stack itself activates the "netdial process" in

	*	this situation.

	*/

	TUint iNoInterfaceUp:1;

	/**

	* Set when flow is used for packet forwarding.

	*

	* This flag, when set, disables the source address checking.

	* Normally the stack works in "strong model" and requires that

	* a packet has a valid source address on the interface.

	* Forwarded packets have other than local source address and

	* the check must be disabled.

	*

	* This can only be set internally or from the hooks. There is no

	* application level socket option to set this.

	*/

	TUint iForwardingFlow:1;

	// Note! Cannot use TScopeType below, because it would make the

	// bitfield into signed and fail on tests like:

	//		x.iLockType == EScopeType_NET

	// even if x.iLockType has value EScopeType_NET!!! -- msa

	/**

	* Locked scope-1 (0..15) [TScopeType].

	*

	* This valid only when iLockId is non-zero.

	*/

	TUint iLockType:4;

	/**

	* Current Locking Id.

	*

	* Value ZERO is unlocked. Non-Zero value is a zone id in the scope

	* specified by iLockType.

	*/

	TUint32 iLockId;

	};

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

//	CFlowContext

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

//	A base class of the Flow Context, cannot be instantiated as is

//

class COptionValue;

class MFlowHook;

class MInterfaceManager;

class CFlowContext : public CBase

	/**

	* The flow context instance.

	*

	* The CFlowContext has several public methods, but not all of them are safe

	* (or even legal) to use in all situations.

	*

	* CFlowContext is a reference counted object. Whenever a pointer is

	* stored for long term duration, the Open() must be called, and when

	* pointer is no more used, a close must be called. This object is only

	* deleted indirectly via use of Close(). The delete operator is never

	* used explicitly from outside.

	*

	* Base class for a flow context.

	* @since v7.0

	* @publishedPartner

	* @released

	*/

	{

	friend class MFlowManager;

	friend class RFlowContext;

protected:

 	IMPORT_C CFlowContext(const void *aOwner, MFlowManager *aManager);

 	IMPORT_C CFlowContext(const void *aOwner, MFlowManager *aManager, CFlowContext &aFlow);

	// Destructor should not be exported, it should be private! -- msa

	IMPORT_C virtual ~CFlowContext();

#ifdef SYMBIAN_NETWORKING_UPS

	/**

	Indicate whether the flow has a provider above it.

	@return ETrue if it has, else EFalse.

	*/

	inline TBool HasProvider() const;

	inline void *GetProviderApiL(const TDesC8& aApiName, TUint* aVersion);

#endif //SYMBIAN_NETWORKING_UPS

public:

	IMPORT_C void Close();

	inline void Open()

		/**

		* Increments a reference count on the context

		*/

		{ iRefs++; }

	IMPORT_C TInt Status();

	IMPORT_C void SetStatus(TInt aStatus);

	IMPORT_C TInt StoreOption(TUint aLevel, TUint aName, const TDesC8 &aOption);

	IMPORT_C TInt RetrieveOption(TUint aLevel, TUint aName, TDes8 &aOption) const;

	inline TPacketHead &Head()

		/**

		* Gets access to precomputed information for the outbound packet flow.

		*

		* @return Precomputed information for the outbound packet flow

		*/

		{ return iHead; }

	/**

	* @defgroup	getselectors	Retrieve current selector fields

	*

	* @{

	*/

 	inline TUint LocalPort() const

		/**

		* Gets the flow's local port.

		* @return current local port

		*/

		{ return iInfo.iLocal.Port(); }

	inline TUint RemotePort() const

		/**

		* Gets the flow's remote port.

		* @return current remote port

		*/

		{ return iInfo.iRemote.Port(); }

	inline TUint Protocol() const

		/**

		* Gets the flow protocol.

		* @return current protocol

		*/

		{ return iInfo.iProtocol; }

	inline const TInetAddr &LocalAddr() const

		/**

		* Gets the flow's local address.

		*

		* The local address may have been selected by the system, if

		* the transport layer didn't set it (left it unspecified or

		* explicitly set unspecified address to it).

		*

		* @note

		*	All addresses in the flow context are kept in IPv6 format

		*	(using IPv4 mapped addresses for IPv4 flows).

		*

		* @return Local address.

		*/

		{ return iInfo.iLocal; }

	inline TBool IsLocalSet() const

		/**

		* Gets the flow's local address status.

		*

		* The local address can be selected by the stack, or application

		* can have set it into a specific value. When this address status

		* have value ETrue, the stack assumes that the local address has

		* been chosen by the application or upper layer protocol. When

		* status is EFalse, the stack selects the source

		* address for the flow when the flow is connected

		* (CFlowContext::Connect).

		*

		* The RFlowContext::SetLocalAddress will set this status to EFalse,

		* if the address is unspecified address, and to ETrue otherwise.

		*

		* @note

		*	If an application requires using the unspecified source address

		*	in packets (IPv4 <tt>0.0.0.0</tt> or IPv6 <tt>::</tt>), it must use

		*	the socket option #KSoNoSourceAddressSelect (level #KSolInetIp)

		*	<em>after</em> it has performed the RSocket::Bind() to uspecified

		*	address.

		*

		* Some upper layer protocols may also set this status, after the

		* connection is established (TCP).

		*

		* @return ETrue, if local addr is set

	 	*/

		{ return iInfo.iLocalSet != 0; }

	inline const TInetAddr &RemoteAddr() const

		/**

		* Gets the flow's remote address.

		*

		* @return Remote address.

		*/

		{ return iInfo.iRemote; }

	inline void GetIcmpTypeCode(TUint8 &aType, TUint8 &aCode) const

		/**

		* Gets the flow's ICMP type and code.

		*

		* @retval aType	Icmp (or other) type

		* @retval aCode	Icmp (or other) code

		*/

		{ aType = iInfo.iIcmpType; aCode = iInfo.iIcmpCode; }