/**

* Copyright (c) 1997-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:

* Interface Manager Standard Variable Names

* 

*

*/

/**

 @file in6_dstcache_internal.h

 @internalTechnology

 @released

*/

#ifndef __DSTCACHE_INTERNAL_H__

#define __DSTCACHE_INTERNAL_H__

#include <in6_dstcache.h>

/**

* @file in6_dstcache_internal.h

* Destination cache. It will be used mostly by transport

* protocols (primarily TCP) only. The core functionality in iface.cpp does not need

* to care about it at all, except when doing Path MTU discovery, which is also

* stored in the cache.

*

* The cache implementation consists of a hashtable

* that uses destination IP addresses as key values and a struct of stored metrics

* as data. When a (TCP) connection is opened, the SAP checks whether there are

* stored values to be used as initial parameters in the cache. If a matching cache

* entry is found, the (TCP) sender uses those as initial values, otherwise it adopts

* the normal initial values conventionally. Correspondingly, when the connection is

* about to be closed, the current values in

* TCP SAP variables are stored in the cache to be used for future connections.

*

* The destination cache is meant to be protocol-independent so that also other

* transport protocols than TCP (such as a possible SCTP implementation) could

* use the variables in the cache.

*

* The cache entries have lifetime, and the cache entries can be removed

* after timer expires. Instead of actively removing cache entries,

* we implement a "lazy" method: The implementation remembers the time

* of last store event for each cache entry, and checks the validity of cache

* entries upon certain events, for example when accessing the cache item next time,

* and removes the entry if necessary. The cache has limited max size.

*

* @internalTechnology

* @released

*/

/** One node in THashTable.

@internalTechnology

@released

*/

template <class K, class V>

class TChain

	{

public:

	K			iKey;

	V			iValue;

	TChain<K,V>	*iNext;

	};

#ifdef NONSHARABLE_CLASS

	NONSHARABLE_CLASS(THashKeyIp6);

#endif

/**

* A hash key based on IPv6 addresses. There are three operation modes:

* @li	each IP address forms its own equivalence class.

* @li	IP addresses in the same network belong to the same equivalence class

*		Since we often do not

*		have the information about the network masks at the destination, we

*		have to do some kind of assumptions. Therefore, IPv6 addresses are considered

*		to have /64 prefix and IPv4 addresses have /24 prefix.

*		(Note that occasionally having slightly wrong network prefixes here is not

*		too bad a failure, if the general direction is correct).

* @li	Addresses delivered via a particular network interface belong to the same

*		equivalence class. Here we have unsolved implementation issues and

*		other considerations, so presently this remains a TODO item. Motivation of this

*		is the assumption that in the GPRS world the last-hop wireless link is

*		the bottleneck that determines the TCP connection characteristics.

*

* @internalTechnology

* @released

*/

class THashKeyIp6 : public MHashKey

	{

public:

	enum TKeyMode

		{

		EPerHost,		///< Each host has a dedicated entry in hash table.

		EPerNet,		///< Hosts with the same network prefix have a common entry

						///< in the table.

		EPerIface		///< All destinations with same network interface share an

						///< entry in the table (not yet implemeted).

		};

	THashKeyIp6() { };

	THashKeyIp6(TKeyMode aMode, const TInetAddr& aAddr);

	virtual TUint ToInt();

	virtual TBool IsEqual(const MHashKey& aKey);

	inline const TIp6Addr& Ip6Address() const { return iAddress; }

	inline TUint32 ScopeId() const { return iScopeId; }

private:

	TKeyMode	iKeyMode;	///< Key Mode of this key.

	TIp6Addr	iAddress;	///< IP address represented by this key.

	TUint32		iScopeId;	///< Scope ID of the destination entry.

	};

/**

* Generic hashtable for storing keys with associated values. K must

* be a subclass of class MHashKey.

*

* @internalTechnology

* @released

*/

template <class K, class V>

class THashTable

	{

public:

	THashTable(TUint aSize);

	~THashTable();

	void ConstructL();

	/**

	* Store key and the associated value to the hashtable. The cache operates in

	* overwrite mode: if key exists, the earlier value is overwritten with new one.

	* A future work item might be to implement the conventional mode, that would

	* raise an exception when the key already exists.

	*

	* @return	Number of bytes allocated from memory with this call. 0 indicates that

	*			there was already an equivalent entry in the cache that was overwritten.

	*			If an error occurred (e.g. out of memory) the call leaves with an

	*			appropriate error code.

	*/

	TUint StoreL(MHashKey& aKey, V& aValue);

	V* Find(MHashKey& aKey);

	/**

	* Deletes a data item from hash and releases the memory allocated.

	*

	* @return	Number of bytes freed from memory.

	*/

	TUint RemoveL(MHashKey& aKey);

	/// How many objects are stored in Hash table.

	TUint Length();

	/// How many bytes does the hash table take. This assumes all data objects are

	/// equally sized.

	inline TUint Size() { return Length() * sizeof(TChain<K,V>); }

	/**

	* Iterate through hashtable and exectue aRemoveCriteria function for all

	* entries. Delete entries for which the function returns ETrue.

	*

	* @param aRemoveCriteria	Function that returns ETrue if the data item given as

	*							the parameter for the function should be removed.

	*

	* @param aDataObject		Data pointer that is passed to the remove criteria

	*							function. The meaning of data pointer is determined

	*							by the criteria function.

	*							See CDestinationCache::Cleanup for example on how this

	*							function is used.

	*

	* @return Total number of bytes deleted

	*/

	TUint RemoveIf(TBool (*aRemoveCriteria)(const V&, void *), void *aDataObject);

	/**

	* Removes all data from the hashtable.

	*/

	void RemoveAll();

private:

	TChain<K,V>	*iTable;	///< Array of size specified in constructor.

	TUint		iSize;		///< Size of iTable array.

	};

const TUint KNumCacheMetrics = 16;

/** Information that is stored for each entry in destination cache.

This is the data part of THashTable entries.

@internalTechnology

@released

*/

class TCacheInfo

	{

public:

	TTime		iStoreTime;					///< When was this entry stored.

	TUint32		iMetrics[KNumCacheMetrics];	///< Data elements indexed by TCacheIndex.

	/// Fills all metrics with zeros.

	inline void ClearAll() { for (TUint i = 0; i < KNumCacheMetrics; i++) iMetrics[i] = 0; }

	enum TCacheIndex

		{

		EPathMTU	= 0,	///< Result of Path MTU discovery (Bytes).

		ESsThresh	= 1,	///< Slow start threshold (Bytes).

		ESRtt		= 2,	///< Smoothed RTT estimate (Ms).

		ERto		= 3		///< Retransmission timer estimate (Ms).

							//  (is this needed, since we have srtt?)							

		};

	};

const TUint KApiVer_MDestinationCache = 3;

typedef THashTable<THashKeyIp6, TCacheInfo> TCacheHash;

const TUint KCacheHashSize = 11;

const TUint KDstCacheLifetime 	= 600;	///< Default entry lifetime = 10 min.

const TUint KDstCacheMaxSize	= 2048;	///< Default cache max size = 2 KB.

#endif // __DSTCACHE_INTERNAL_H__