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

// in_bind.h - services provided by the IP layer of the stack

// services provided by the IP layer of the stack

//

/**

 @file in_bind.h

 @publishedPartner

 @released

*/

#ifndef __IN_BIND_H__

#define __IN_BIND_H__

#include <es_sock.h>

#include <es_prot.h>

#include "ip6_hook.h"

#include "apibase.h"

class CProtocolInet6Binder;

// MInterface

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

class MInterface : public MInetBase

	/**

	* Public services from the interface instance.

	*

	* @note

	* The MInterface reference must not be stored

	* into any member variables. The reference may become

	* invalid, if thread change occurs.

	* @since v7.0s

	* @publishedPartner

	* @released

	*/

	{

public:

	/**

	* @return the interface index of the interface. Always > 0.

	*/

	virtual TUint32 Index() const = 0;

	/**

	* @return a reference to the name of the interface.

	*/

	virtual const TDesC &Name() const = 0;

	/**

	* Query the value of the specied scope id.

	*

	* @param aType (0..15), select the scope id to be queried

	* @return The scope id value.

	*/

	virtual TUint32 Scope(const TScopeType aType) const = 0;

	};

/**

* @name AddRouteL flags

*

* The flags define the type of the "route" entry and some optional

* processing instructions for the MInterfaceManager::AddRouteL.

*

* The diagram represents 32 bit host order integer.

@verbatim

    |       |       |       |       |       |       |       |       |

    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

MSB |        Reserved                   |P|U|H|R|O|S| Type Ext  |Typ| LSB

    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Typ     Major type of the entry (type).

Type Ext

        For some route types, the stack uses additional qualifiers

        to track the route state. Should be zeroed.

S       Solicited bit from Neighbor discovery (only used when type = 0).

O       Override bit from Neighbor discovery (only used when type = 0).

R       Neighbor cache for router (only used when type = 0). Change to Router.

H       Neighbor cache for host (only used when type = 0). Change to Host.

U       Update Only (do not create entry, if it does not exist).

P       Probing only.

Reserved

        Must be zero.

@endverbatim

*/

//@{

/**

* type=0, Neighbor cache entry. The "prefix" length is always

* 128 bits. This type of entry stores the link layer address

* for a neighbor on the link.

*

* @note

*	This type is automaticly managaged by the IPv6 neighbor

*	discovery process, or by the IPv4 ARP protocol.

*/

const TUint KRouteAdd_NEIGHBOR	= 0;

/**

* type=1, My own prefix or address entry. This is also used for

* joined multicast groups. The prefix is always 128 bits for

* IPv4 addressess (entry contains the full IPv4 address in

* IPv4 mapped format), for configured specific IPv6 addresses,

* or when entry is used to represent joined multicast group.

*

* The prefix is shorter (usually 64) when

* the entry is used to present IPv6 address prefix that has

* been received via router advertisement (with address

* configuration bit A set).

*

* @note

*	This type is mostly handled automaticly via IPv6 or IPv4

*	configuration. Additionally, for example, joining a multicast

*	group on the interface, adds an entry of this type automaticly.

*/

const TUint KRouteAdd_MYPREFIX	= 1;

/**

* type=2, Onlink route.

*/

const TUint KRouteAdd_ONLINK	= 2;

/**

* type=3, Gateway route, destination offlink, behind the indicated gateway

*/

const TUint KRouteAdd_GATEWAY	= 3;

/**

* Mask (0x3), extracts the main type of the "route" entry (NEIGHBOR, MYPREFIX, ONLINK, GATEWAY)

*/

const TUint KRouteAdd_TYPEMASK	= 0x003;

/**

* Mask (0xff), extracts bits of the route state. System uses internally more states than the four main types.

*/

const TUint KRouteAdd_STATEMASK	= 0x0ff;

//

// - for a host route (= neighbor cache entry), four additional bits can be present

//   (these bits are ignored for the other route types). (Leave 8 bits room for

//   internal state, and start assigning flags from bit 8!)

//

/**

* Usually set from ND solicited bit (usually marks host as reachable).  NEIGHBOR only.

*/

const TUint KRouteAdd_SOLICITED	= 0x0100;

/**

* Update the link layer address. NEIGHBOR only.

*/

const TUint KRouteAdd_OVERRIDE	= 0x0200;

/**

* This host is now a router (not host). NEIGHBOR only.

*/

const TUint KRouteAdd_ISROUTER	= 0x0400;

/**

* This host is now a host (not router). NEIGHBOR only.

*/

const TUint KRouteAdd_ISHOST	= 0x0800;

//

//   When set, it also prevents the processing of ISROUTER/ISHOST, iff entry is

//   in incomplete state, link needs addresses and no link address is specifified

//   (see. CIp6Route::Update). [this subtly implements the NA dropping rule in

//   RFC 2461, 7.2.5 and still passes redirect target on-link route installs,

//   don't mess with this]

//

/**

* Do not create route entry, if it does not exist previously.

*

* By default, AddRouteL always creates a new route entry, if no matching

* route is found. Setting UPDATEONLY flag prevents this.

*/

const TUint KRouteAdd_UPDATEONLY= 0x1000;

/**

* If route is created, mark it as "probing only".

*

* When a route has "probing only" flag set, it is prevented from

* being selected bind "find route". Only useful for Neighbor Cache

* entries. The flag is automaticly cleared, if route state changes

* from Incomplete to some other state.

*/

const TUint KRouteAdd_PROBINGONLY = 0x2000;

//@}

//

// MInterfaceManager

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

// Public services from Interface Manager

class MInterfaceManager : public MInetBase

	/** Provides an interface to the IPv6 protocol module's interface manager.

	*

	* The functions of the MInterfaceManager define the externally visible

	* services of the interface manager.

	*

	* @publishedPartner

	* @released

	*/

	{

public:

	/**

	* Adds or modifies routes.

	*

	* AddRouteL adds the specified (aAddr/aPrefix) route pointing to the interface (aName).

	* If the interface with this name does not exist,

	* an empty interface instance is created for it.

	*

	* @note The route table can also be manipulated using socket options.

	*

	* AddRouteL succeeds always, and the leave condition is only invoked

	* when it fails to allocate the necessary objects to store the information.

	* 

	* The current route management is almost fully automatic,

	* based on information that is retrieved from the active interfaces

	* and from router advertisements.

	*

	* The current implementation uses the route table also for neighbor

	* cache, multicast group membership and stores IPv6 address generation

	* prefixes into route table.

	*

	* The aFlags arguments defines the type of the route entry and

	* some additional processing instructions. The type is one of the

	* following:

	* @li	#KRouteAdd_NEIGHBOR (neighbor cache entry)

	* @li	#KRouteAdd_MYPREFIX (own address/prefix/multicast entry)

	* @li	#KRouteAdd_ONLINK ("traditional" route entry)

	* @li	#KRouteAdd_GATEWAY ("traditional" route entry)

	*

	* Some modifiers can ored with the base type. The following

	* are effective <b>ONLY</b> with KRouteAdd_NEIGHBOR (and used

	* internally):

	* @li	#KRouteAdd_SOLICITED

	* @li	#KRouteAdd_OVERRIDE

	* @li	#KRouteAdd_ISROUTER

	* @li	#KRouteAdd_ISHOST

	*

	* #KRouteAdd_UPDATEONLY can be combined with any route type. It prevents

	* creation of the route entry, if it does not already exist.

	*

	* Type of KRouteAdd_NEIGHBOR routes are generated automaticly by the

	* neighbor discovery process. Careless use of this type

	* may disrupt the neighbor discovery processes.

	* 

	* @param aAddr Address part of the route prefix

	* @param aPrefix The number of bits in the prefix  (aAddr)

	* @param aName The interface name

	* @param aFlags Type of the route entry (KRouteAdd_MYPREFIX or KRouteAdd_ONLINK) and some other flags.

	* @param aGateway (ptr to) a gateway or link layer address depending on the type of route (GATEWAY/NEIGHBOR)

	* @param aLifetime (ptr to) the lifetime of the route in seconds (if zero, route is deleted) 

	*/

	virtual void AddRouteL(const TIp6Addr &aAddr, TInt aPrefix, const TDesC &aName,

		TUint aFlags = KRouteAdd_ONLINK, const TSockAddr *const aGateway = NULL, const TUint32 *const aLifetime = NULL) = 0;

	/** Tests if a route and source address exist for a given address.	

	* 

	* @param aAddr		Address to check

	* @param aScopeid	Address scope

	* @param aSrc		On return, the source address

	* @return 			KErrNone if the route exists, otherwise KErrNotFound

	*

	* @deprecated

	*/

	virtual TInt CheckRoute(const TIp6Addr &aAddr, const TUint32 aScopeid, TIp6Addr &aSrc) const = 0; 

	/**

	* Tests whether the address is usable as a source address within a

	* subset of interfaces limited by the <aLockType, aLock>.

	* 

	* @param aAddr The address (IPv6 or IPv4) to be tested in IPv6 format. IPv4

	* addresses are in IPv4 mapped format.

	* @param aLock The scope identifier for limiting the interfaces

	* @param aLockType The type of the scope identifier

	* @return NON-ZERO scope identifier which matches the tested address, if

	* address is a valid source address for the host. If address is not usable,

	* returns ZERO.

	*/

	virtual TUint32 LocalScope(const TIp6Addr &aAddr, const TUint32 aLock, const TScopeType aLockType) const = 0;

	/**

	* Finds the scope id for the remote address.

	*

	* Returns ZERO, if scope id cannot be determined.

	*

	* @param aAddr The address (IPv6 or IPv4) to be tested in IPv6 format. IPv4

	* addresses are in IPv4 mapped format.

	* @param aLock The scope identifier for limiting the interfaces

	* @param aLockType The type of the scope identifier

	* @return NON-ZERO scope identifier which matches the tested address, if

	* it can be determined (suitable route exists), and ZERO otherwise

	*/

	virtual TUint32 RemoteScope(const TIp6Addr &aAddr, const TUint32 aLock, const TScopeType aLockType) const = 0;

	/**

	* Tests whether a packet having a specified destination address should be processed 

	* by the current host.

	*

	* Suitable addresses include the source addresses covered by the IsMyAddress(), 

	* and also the applicable multicast and broadcast addresses.

	*

	* This method is mainly used by the IP layer.

	* 

	* @param aAddr The address (IPv6 or IPv4) to be tested (in network byte order)

	* @param aInterfaceIndex The source interface (the originating interface is

	* required for accurate determination of link local or multicast addresses)

	* @return NON-ZERO interface index, if destination applies to current node.

	*/

	virtual TUint32 IsForMeAddress(const TIp6Addr &aAddr, const TUint32 aInterfaceIndex) const = 0;

	/**

	* Finds MInterface by CNIfIfBase.

	*

	* Searches the internal inteface descriptions and looks for an interface

	* which is currently bound to the speficied NIF instance. The interface

	* manager does not prevent the situation where the same NIF is attached

	* to multiple internal interfaces. If such configuration is created, the

	* interface which is returned is always the first matching one.

	*

	* @param aIf	The NIF to be searched.

	* @return MInterface or NULL, if NIF not found.

	*/

	virtual const MInterface* Interface(const CNifIfBase *const aIf) const = 0;

	/**

	* Finds MInterface by name.

	*

	* Searches the internal interface descriptions and looks for an interface

	* with the specified name. The returned interface, if found, can be up

	* or down. There cannot be two interfaces with the same name, the name

	* is always a unique identifier of an interface.

	*

	* @param aName	The name to be searched.

	* @return MInterface or NULL, if NIF not found.

	*/

	virtual const MInterface* Interface(const TDesC &aName) const = 0;

	/**

	* Finds MInterface by interface index.

	*

	* Searches the internal interface descriptions and looks for an interface

	* with the specified index. The returned interface, if found, can be up

	* or down. Each interface is assigned a unique index, the index is always

	* a unique indentifier of an interface.

	*

	* @param aInterfaceIndex The index value to be searched.

	* @return MInterface or NULL, if NIF not found.

	*/

	virtual const MInterface* Interface(const TUint32 aInterfaceIndex) const = 0;

	/**

	* Enumerates interface information.

	*

	* This function gets information about the next interface after the interface 

	* identified by the input parameter aIndex.

	* 

	* To start, call first with aIndex=0, and after that always give the previously 

	* returned value as a parameter. When the return value is 0, all interfaces 

	* have been listed.

	* 

	* A single "real" interface has one index value for each possible source address. 

	* TSoInetInterfaceInfo::iName can be used to determine the "real" interface. 

	*

	* Note that TSoInetInterfaceInfo is the structure used by the Symbian OS v6.1 

	* IPv4 stack. The IPv6 interfaces do not provide automatic information about 

	* the name servers or gateways. Some of the information comes from the neighbor 

	* discovery or service location protocols.

	*

	* @param aIndex

	*	previous index value, use ZERO to restart scan from beginning. <b>Note</b>: This

	*	is not same as "interface index", which identifies a interface in the system.

	* @retval aInfo

	*	returns the information about the interface.

	* @return

	*	index of the current aInfo, or ZERO if there were no more entries to return.

	*/

	virtual TUint InterfaceInfo(TUint aIndex, TSoInetInterfaceInfo &aInfo) const = 0;

	/**

	* Enumerates route information.

	* 

	* This function returns information about the next route after the route identified 

	* by the input parameter aIndex. To start, call first with aIndex=0, and after 

	* that always give the previously returned value as a parameter. When the return 

	* is 0, all routes have been listed. 

	* 

	* The returned information is described by TSoInetRouteInfo,

	* which is the structure used by the Symbian OS v6.1 

	* IPv4 stack.

	* 

	* @param aIndex

	*	previous index, use ZERO to restart scan from beginning.

	* @retval aInfo

	*	returns the information about the route

	* @return

	*	index of the current aInfo, or ZERO if there were no more entries to return.

	*/

	virtual TUint RouteInfo(TUint aIndex, TSoInetRouteInfo &aInfo) const = 0;

	/**

	* Gets an option value.

	*

	* Implements some of the options at levels:

	* @li	KSOLInterface

	* @li	KSolInetIfQuery

	*

	* <b>note</b>: Does not necessarily implement all options on those

	* levels, just some.

	*

	* @param aLevel		Option level

	* @param aName		Option name

	* @retval aOption	On return, an option value

	* @return 			System-wide error code

	*/

	virtual TInt GetOption(TUint aLevel, TUint aName, TDes8 &aOption) const = 0;

	/**

	* Sets an option value.

	*

	* Implement some of the options at levels:

	* @li	KSolInetIfCtrl

	* @li	KSOLInterface

	* @li	KSolInetIfQuery

	* @li	KSolInetIp

	* @li	KSolInetRtCtrl

	*

	* <b>note</b>: Does not necessarily implement all options on those

	* levels, just some.

	*

	* @param aLevel 	Option level

	* @param aName 		Option name

	* @param aOption	An option value

	* @return 			System-wide error code

	*/

	virtual TInt SetOption(TUint aLevel, TUint aName, const TDesC8 &aOption) = 0;

	/**

	* Increments the "users" counter.

	*

	* The "users" count decides when the network/IP

	* has no users and the shutdown can be activated. It is

	* up to the upper layers to decide what exactly is counted as a

	* "user" in this sense. By default, any socket opened by an

	* application should count as one user.

	*

	* See also #KSoUserSocket socket option. The built-in protocols of the

	* TCPIP stack (UDP, TCP, ICMP, etc.) support this socket option. Other

	* protocols, which provide sockets to applications, should also support

	* this.

	*

	* When this count is non-ZERO, the "daemons" (as specified in tcpip.ini)

	* are running. When count becomes ZERO, the stack kills the daemon

	* processes.

	*/

	virtual void IncUsers() = 0;

	/**

	* Decrements the "users" counter.

	*

	* For details, see IncUsers().

	*/

	virtual void DecUsers() = 0;

	/**

	* Gets an string variable setting from the network configuration file (such 

	* as tcpip.ini).

	*

	* The function accesses tcpip.ini using the CESockIniData.

	*

	* @param aSection

	*	the section of INI file to be checked (the string inside

	*	the brackets in the INI file). Do not include brackets in

	*	call.

	* @param aVarName

	*	the variable within section. CEsockIniData is kludgy, it will

	*	search for "name=", so beware of using short variable names,

	*	which are part of the ending of another longer name!

	* @retval aResult

	*	returns the pointer to the buffer containing the requested value.

	*	The returned value must not be stored in any member or other long

	*	term variable.

	* @return

	* @li	TRUE, if value found (aResult has been initialized)

	* @li	FALSE, if value not found

	*/

	virtual TBool FindVar(const TDesC &aSection,const TDesC &aVarName,TPtrC &aResult) = 0;

	/**

	* Gets an integer variable setting from the network configuration file (such 

	* as tcpip.ini).

	*

	* The function accesses tcpip.ini using the CESockIniData.

	*

	* @param aSection

	*	the section of INI file to be checked (the string inside

	*	the brackets in the INI file). Do not include brackets in

	*	call.

	* @param aVarName

	*	the variable within section. CEsockIniData is kludgy, it will

	*	search for "name=", so beware of using short variable names,

	*	which are part of the ending of another longer name!

	* @retval aResult

	*	returns the value as an integer.

	* @return

	* @li	TRUE, if value found (aResult has been initialized)

	* @li	FALSE, if value not found

	*/

	virtual TBool FindVar(const TDesC &aSection,const TDesC &aVarName,TInt &aResult) = 0;

	/**

	* Reports a packet has been accepted by some upper layer service provider.

	*

	* An upper layer may call this function to ensure that the incoming interface

	* is not shut down due to lack of traffic. The intention is that only accepted

	* packet traffic can keep the interface up, and only the upper layer protocol

	* can know whether packet is accepted or not. The call is important, if the

	* protocol does not send any packets out to that interface (either because

	* it's a receive only application, or because outbound packets are routed via

	* another interface).

	*

	* @note

	*	The interface index should be the value from the RMBufRecvInfo::iOriginalIndex

	*	field, which represents the real incoming interface.

	*

	* @param aInterfaceIndex The index of the interface from which packet originated

	* @return KErrNotFound, if no such interface, and KErrNone otherwise.

	*/

	virtual TInt PacketAccepted(const TUint32 aInterfaceIndex) = 0;

	/**

	* Gets an option value.

	*