1.1 --- a/epoc32/include/in6_if.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/in6_if.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,365 @@
1.4 -in6_if.h
1.5 +// Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +// All rights reserved.
1.7 +// This component and the accompanying materials are made available
1.8 +// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
1.9 +// which accompanies this distribution, and is available
1.10 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +//
1.12 +// Initial Contributors:
1.13 +// Nokia Corporation - initial contribution.
1.14 +//
1.15 +// Contributors:
1.16 +//
1.17 +// Description:
1.18 +// in6_if.h - control API between the stack and IPv6 interfaces
1.19 +// Specifies the IPv6 extensions for CNifIfBase::Control() API
1.20 +// defined in the standard EPOC header file in_iface.h.
1.21 +//
1.22 +
1.23 +
1.24 +
1.25 +/**
1.26 + @file in6_if.h
1.27 + @publishedAll
1.28 + @released
1.29 +*/
1.30 +
1.31 +#ifndef __IN6_IF_H__
1.32 +#define __IN6_IF_H__
1.33 +
1.34 +#include <e32std.h>
1.35 +#include "in_iface.h" // TSoIfInfo
1.36 +
1.37 +// CNifIfBase::Control(aLevel, aName, aOption, ..)
1.38 +// aLevel is KSOLInterface defined in in_iface.h in standard EPOC
1.39 +
1.40 +// IPv6 specific aName constants and aOption structures
1.41 +
1.42 +/**
1.43 +* Option to get the current network interface driver operation parameters to
1.44 +* the passed TSoIfInfo6 structure.
1.45 +* @since v7.0
1.46 +* @publishedAll
1.47 +* @released
1.48 +*/
1.49 +const TUint KSoIfInfo6 = 0x202;
1.50 +
1.51 +
1.52 +/**
1.53 +* Incoming RMBufPktInfo iFlag value for a loopback packet.
1.54 +*
1.55 +* The stack sets this flag for a packet, which is looped
1.56 +* back by a call to IP layer Process function. A NIF should
1.57 +* never set this flag.
1.58 +*
1.59 +* This flag is effective only when capabilities are enabled.
1.60 +* A packet with this flag set can be delivered to sockets
1.61 +* that do not posses NetworkServices cabability.
1.62 +*/
1.63 +const TUint KIpLoopbackPacket = 0x1;
1.64 +/**
1.65 +* Incoming and outgoing RMBufPktInfo iFlag value for broadcast packet.
1.66 +*
1.67 +* The packet uses link layer broadcast. The stack sets this bit for
1.68 +* outgoing packets that are not unicast (e.g. multicast and broadcast
1.69 +* destinations). A NIF can set this flag for incoming packet, if it
1.70 +* was sent to a link layer broadcast address. The presence of this
1.71 +* flag suppresses some error replies from the stack.
1.72 +*/
1.73 +const TUint KIpBroadcastOnLink = 0x2;
1.74 +
1.75 +
1.76 +/**
1.77 +* A TSoIfInfo::iFeatures flag to indicate that the interface requires Neighbour
1.78 +* Discovery.
1.79 +*
1.80 +* @note
1.81 +* For IPv4 this enables ARP for the interface. The NIF must
1.82 +* pass received ARP packets to the stack, and accept ARP
1.83 +* packets for sending from the stack.
1.84 +* @since v7.0
1.85 +* @publishedAll
1.86 +* @released
1.87 +*/
1.88 +const TUint KIfNeedsND = 0x00000100;
1.89 +
1.90 +class TSoIfInfo6 : public TSoIfInfo // aOption when aName == KSoIfInfo
1.91 + /**
1.92 + * Extends the TSoIfInfo for the receive MTU.
1.93 + *
1.94 + * The IPv6 capable interfaces must support this control option. The usage
1.95 + * template in the stack is:
1.96 +@code
1.97 + CNifIfBase *iNif;
1.98 + ...
1.99 + TPckgBuf<TSoIfInfo6> ifProp;
1.100 + TInt err = iNif->Control(KSOLInterface, KSoIfInfo6, ifProp);
1.101 +@endcode
1.102 + * For the IPv4 interfaces, only the plain TSoIfInfo is used.
1.103 +@code
1.104 + CNifIfBase *iNif;
1.105 + ...
1.106 + TPckgBuf<TSoIfInfo> ifProp;
1.107 + TInt err = iNif->Control(KSOLInterface, KSoIfInfo, ifProp);
1.108 +@endcode
1.109 + * @since v7.0
1.110 + * @publishedAll
1.111 + * @released
1.112 + */
1.113 + {
1.114 +public:
1.115 + /** Maximum transmission unit for receiving. */
1.116 + TInt iRMtu;
1.117 + };
1.118 +
1.119 +class TSoInet6IfConfig : public TSoIfConfigBase
1.120 + /**
1.121 + * IPv6 interface configuration.
1.122 + *
1.123 + * This is the option when stack queries the interface configuration
1.124 + * information using
1.125 +@code
1.126 + TPckgBuf<TSoInet6IfConfig> cfg;
1.127 + cfg().iFamily = KAfInet6; // Query about IPv6 capability
1.128 + TInt res = iNif->Control(KSOLInterface, KSoIfConfig, cfg);
1.129 +@endcode
1.130 + * The KErrNone return signifies that this NIF supports IPv6 on the
1.131 + * link layer. Note, similarly, the IPv4 support is detected by the
1.132 + * stack using:
1.133 +@code
1.134 + TPckgBuf<TSoInetIfConfig> cfg;
1.135 + cfg().iFamily = KAfInet; // Query about IPv4 capability.
1.136 + TInt res = iNif->Control(KSOLInterface, KSoIfConfig, cfg);
1.137 +@endcode
1.138 + * The same NIF can support both IPv4 and IPv6.
1.139 + *
1.140 + * @since v7.0
1.141 + * @publishedAll
1.142 + * @released
1.143 + */
1.144 + {
1.145 +public:
1.146 + /**
1.147 + * The local interface id.
1.148 + *
1.149 + * If the address family is not KAFUnspec, then this defines the id portion of
1.150 + * the IPv6 addresses for this host. The id portion is used in constructing the
1.151 + * link-local address (fe80::id) and combined with any other prefixes, which
1.152 + * are configured for this interface (prefix::id). Prefixes are configured via
1.153 + * Router Advertisement prefix option (TInet6OptionICMP_Prefix) with the A flag
1.154 + * set, or using interface control socket options (see TSoInet6InterfaceInfo).
1.155 + *
1.156 + * The length of the id is determined by the TSockAddr::GetUserLen. The normal
1.157 + * value is 8 (e.g. the standard id is always 64 bits). Other id lengths are
1.158 + * possibly activated by future RFC's for some special address formats.
1.159 + *
1.160 + * If the address family is KAFUnspec, then id is not configured (and for the
1.161 + * IPv6 interface to be functional, address(es), including the link-local address,
1.162 + * must be configured by some other means).
1.163 + */
1.164 + TSockAddr iLocalId;
1.165 + /**
1.166 + * The remote interface id (or KAFUnspec, if not applicaple).
1.167 + *
1.168 + * If the address family is not KAFUnspec, then this defines the id portion of
1.169 + * another host on the link. The stack constructs a link-local address
1.170 + * (fe80::remote-id) and installs a host route for it.
1.171 + *
1.172 + * This might be useful for PPP links, if other end is not acting as a router.
1.173 + * If the other end is a router, it's address will become automaticly known,
1.174 + * when it sends the Router Advertisement.
1.175 + */
1.176 + TSockAddr iRemoteId;
1.177 + /**
1.178 + * Unused highest significant bits in interface id (usually 0).
1.179 + *
1.180 + * This is reserved for future use, in case there is a need for id length
1.181 + * that is not multiple of 8.
1.182 + */
1.183 + TUint idPaddingBits;
1.184 + /** 1st DNS address (or Unspecified address, if none) */
1.185 + TInetAddr iNameSer1;
1.186 + /** 2nd DNS address (or Unspecified address, if none) */
1.187 + TInetAddr iNameSer2;
1.188 + };
1.189 +
1.190 +/**
1.191 +
1.192 +@page nif_interface The interface between a NIF and the TCP/IP stack.
1.193 +
1.194 + The network interfaces (NIF's) are registered with the stack using the
1.195 + MNifIfUser::IfUserNewInterfaceL function. Stack has an internal object that
1.196 + represents the interface and the given CNifIfBase object is attached to this.
1.197 +
1.198 + The stack communicates with the NIF using the public API defined by the CNifIfBase.
1.199 + The NIF sees the stack as an instance of CProtocolBase and can use a subset of
1.200 + public functions to communcite with the stack.
1.201 +
1.202 + The following CNifBase functions are used by the stack:
1.203 +
1.204 + - CNifIfBase::Open, (binding stack and NIF)
1.205 + - CNifIfBase::Close, (binding stack and NIF)
1.206 + - CNifIfBase::BindL, (binding stack and NIF)
1.207 + - CNifIfBase::Control, (for the configuration information)
1.208 + - CNifIfBase::Info, (retrieve the interface name)
1.209 + - CNifIfBase::Send, (send outbound packets to NIF)
1.210 + - CNifIfBase::Notify, (NIFMAN about packet activity)
1.211 +
1.212 + The following CProtocolBase functions are available for NIFs:
1.213 +
1.214 + - CProtocolBase::StartSending, (notify stack that NIF is ready)
1.215 + - CProtocolBase::Error, (notify stack about NIF error)
1.216 + - CProtocolBase::Process, (feed inbound packets to stack)
1.217 +
1.218 + The network interface is removed from the stack either by directly deleting it, or
1.219 + by NIFMAN using MNifIfUser::IfUserInterfaceDown.
1.220 +
1.221 + A pointer to the MNifIfUser object can be obtained from the network
1.222 + layer protocol.
1.223 +@code
1.224 + MNetworkService *iNetwork;
1.225 + TPckgBuf<MNifIfUser*> ifUser;
1.226 + TInt err = iNetwork->Protocol()->GetOption(KNifOptLevel, KNifOptGetNifIfUser, ifUser);
1.227 +@endcode
1.228 +
1.229 +
1.230 +@section nif_binding Binding the NIF and TCP/IP together
1.231 +
1.232 + MNifIfUser::IfUserNewInterfaceL introduces a new network interface (NIF) to the stack.
1.233 + The introduction consists of the following steps:
1.234 +
1.235 + -# retrieve interface info into TNifIfInfo by CNifIfBase::Info function. Stack uses
1.236 + only the interface name (iName) from this. The name cannot be an empty string.
1.237 + -# using the name, the stack searches for a matching internal interface object. If
1.238 + it does not exist, it is created. If there was an existing interface with the same
1.239 + name, the stack will disconnect that first.
1.240 + -# the stack gives itself to the new NIF by calling CNifIfBase::BindL.
1.241 + -# stack does not send any packets to the interface until the NIF has called
1.242 + CProtocolBase::StartSending at least once.
1.243 + -# stack executes the interface configuration when the first CProtocolBase::StartSending arrives
1.244 + after MNifIfUser::IfUserNewInterfaceL. The configuration uses the CNifIfBase::Control function
1.245 + with different options to retrieve additional information from the NIF.
1.246 +
1.247 + MNifIfUser::IfUserInterfaceDown disconnects the NIF from the stack. There is one
1.248 + exception: if the MNifIfUser::IfUserInterfaceDown aResult parameter has a special
1.249 + value #KErrLinkConfigChanged, then the internal interface state is only reset to the
1.250 + exact same state as if interface was just introduced by the
1.251 + MNifIfUser::IfUserNewInterfaceL, and a reconfiguration occurs when the NIF calls
1.252 + StartSending.
1.253 +
1.254 +@section nif_control_api The Control API
1.255 +
1.256 + The stack requires the NIF to implement a minimal set of #KSOLInterface level
1.257 + options via it's CNifIfBase::Control API.
1.258 +
1.259 + - at least one of the information options
1.260 + - TSoIfInfo6 with #KSoIfInfo6 (for IPv6)
1.261 + - TSoIfInfo with #KSoIfInfo (for IPv4)
1.262 + .
1.263 + - at least one of the configuration options
1.264 + - TSoInet6IfConfig (iFamily=#KAfInet6) with #KSoIfConfig
1.265 + - TSoInetIfConfig (iFamily=#KAfInet) with #KSoIfConfig
1.266 + .
1.267 + - TSoIfHardwareAddr with #KSoIfHardwareAddr if the link
1.268 + uses hardware addresses (only used #KIfNeedsND is also set.). The returned
1.269 + address is used in the neighbor discovery (ICMPv6 ND or ARP for IPv4), and
1.270 + in sending packets to NIF, the address family is used to indicate that the
1.271 + stack has chosen the destination link layer address (based on the neighbor
1.272 + cache).
1.273 + - TSoIfConnectionInfo with #KSoIfGetConnectionInfo (for IAP and NET numbers).
1.274 + If this is not supported, the stack will assign unique numbers for the
1.275 + IAP and NET. The scope vector (zone identifiers) is contructed as follows:
1.276 + -# [0] The unique interface index (node local scope id)
1.277 + -# [1] IAP number (link scope id)
1.278 + -# [2] IAP number (subnet scope id)
1.279 + -# [3] NET number
1.280 + -# [4] NET number (site local scope id)
1.281 + -# [5] NET number
1.282 + -# [6] NET number
1.283 + -# [7] NET number (organization scope id)
1.284 + -# [8] NET number
1.285 + -# [9] NET number
1.286 + -# [10] NET number
1.287 + -# [11] NET number
1.288 + -# [12] NET number
1.289 + -# [13] NET number (IPv6 global scope)
1.290 + -# [14] NET number
1.291 + -# [15] NET number (highest, NET id, IPv4 global)
1.292 +
1.293 + @note
1.294 + To build complete ARP packets in the stack, stack needs to know the hardware
1.295 + type value to be used in the packet (see TInet6HeaderArp). This 16 bit value
1.296 + is assumed to be in the Port() field of the returned hardware address
1.297 + (#KSoIfHardwareAddr). An IPv4 NIF that leaves the ARP to the stack,
1.298 + must provide this value (or sniff and fix the outgoing ARP packets).
1.299 +
1.300 +@section nif_inbound_packets Inbound packets from the NIF to stack.
1.301 +
1.302 + The NIF feeds the inbound packets to the stack through the CProtocolBase::Process
1.303 + function (see also MNetworkService::Process). The information block associated
1.304 + with the packet is RMBufPktInfo and the fields must have been set as follows:
1.305 +
1.306 + - RMBufPktInfo::iSrcAddr, the link layer source address (using the same
1.307 + address family as returned with the hardware address control option). If
1.308 + the link does not use addresses, then #KAFUnspec should be used.
1.309 + - RMBufPktInfo::iDstAddr, the link layer destination address (using the same
1.310 + address family as returned with the hardware address control option). If
1.311 + the link does not use addresses, then #KAFUnspec should be used.
1.312 + - RMBufPktInfo::iProtocol, the type of the packet:
1.313 + - #KProtocolInetIp, IPv4 packet
1.314 + - #KProtocolInet6Ip, IPv6 packet
1.315 + - #KProtocolArp, ARP packet
1.316 + .
1.317 + - RMBufPktInfo::iLength, the length of the packet in octets
1.318 + - RMBufPktInfo::iFlags, should be set to zero (reserved for future use).
1.319 +
1.320 +@note
1.321 + The stack is relaxed about the checking of iProtocol field, and anything
1.322 + else except #KProtocolArp is assumed to be an IP packet. This is potentially
1.323 + to changed in future, and NIFs should set the protocol field correctly.
1.324 +@note
1.325 + The link layer addresses in iSrcAddr and iDstAddr are informative. The
1.326 + values do not affect the processing of the packet within stack. They are
1.327 + made available for the inbound post hooks (CProtocolPosthook).
1.328 +
1.329 +@section nif_outbound_packets Outbound packets from the stack to NIF
1.330 +
1.331 + The stack feeds the outbound packets to the NIF through the CNifIfBase::Send
1.332 + function. The information block associated with the packet follows RMBufPktInfo
1.333 + and the fields need to be interpreted as follows:
1.334 +
1.335 + - RMBufPktInfo::iSrcAddr, undefined (must be ignored by the NIF).
1.336 + The NIF must choose the link layer source address.
1.337 + - RMBufPktInfo::iDstAddr, three variants, if link layer addresses are used
1.338 + - hardware address, using the same address family as NIF returned
1.339 + in harware address control option (TSoIfHardwareAddr ).
1.340 + The packet must be sent to this link layer destination.
1.341 + - #KAfInet, the address is IPv4 multicast address. and the NIF must
1.342 + select a suitable link layer broadcast address as a destination.
1.343 + - #KAfInet6, the address is IPv6 multicast address, and the NIF msut
1.344 + select a suitable link layer broadcast address as a destination.
1.345 + .
1.346 + If the NIF does not use link layer addresses, then iDstAddr is also
1.347 + undefined (must be ingnored byt the NIF). The link is a point-to-point
1.348 + interface.
1.349 + - RMBufPktInfo::iProtocol, defines the type of packet
1.350 + - #KProtocolInetIp, IPv4 packet
1.351 + - #KProtocolInet6Ip, IPv6 packet
1.352 + - #KProtocolArp, ARP packet
1.353 + .
1.354 + - RMBufPktInfo::iLength, the length of the packet in octets.
1.355 + - RMBufPktInfo::iFlags, undefined (must be igrnored by the NIF).
1.356 +
1.357 + The stack interprets the return value from the CNifIfBase::Send as follows:
1.358 +
1.359 + - return 1; the NIF is ready to receive more packets.
1.360 + - return 0; the NIF is blocked and cannot receive any more packets. The stack
1.361 + <b>does not send anything</b> to the NIF until it calls CProtocolBase::StartSending.
1.362 + - return < 0; unspecified, but currently, the error is passed on to
1.363 + all flows attached to this interface. The stack will continue sending
1.364 + packets to the interface (no StartSending is required).
1.365 + - return > 1; unspecified, but currently treated same as return 1.
1.366 +
1.367 +*/
1.368 +
1.369 +#endif