1 in6_if.h |
1 // Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // 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 |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // in6_if.h - control API between the stack and IPv6 interfaces |
|
15 // Specifies the IPv6 extensions for CNifIfBase::Control() API |
|
16 // defined in the standard EPOC header file in_iface.h. |
|
17 // |
|
18 |
|
19 |
|
20 |
|
21 /** |
|
22 @file in6_if.h |
|
23 @publishedAll |
|
24 @released |
|
25 */ |
|
26 |
|
27 #ifndef __IN6_IF_H__ |
|
28 #define __IN6_IF_H__ |
|
29 |
|
30 #include <e32std.h> |
|
31 #include "in_iface.h" // TSoIfInfo |
|
32 |
|
33 // CNifIfBase::Control(aLevel, aName, aOption, ..) |
|
34 // aLevel is KSOLInterface defined in in_iface.h in standard EPOC |
|
35 |
|
36 // IPv6 specific aName constants and aOption structures |
|
37 |
|
38 /** |
|
39 * Option to get the current network interface driver operation parameters to |
|
40 * the passed TSoIfInfo6 structure. |
|
41 * @since v7.0 |
|
42 * @publishedAll |
|
43 * @released |
|
44 */ |
|
45 const TUint KSoIfInfo6 = 0x202; |
|
46 |
|
47 |
|
48 /** |
|
49 * Incoming RMBufPktInfo iFlag value for a loopback packet. |
|
50 * |
|
51 * The stack sets this flag for a packet, which is looped |
|
52 * back by a call to IP layer Process function. A NIF should |
|
53 * never set this flag. |
|
54 * |
|
55 * This flag is effective only when capabilities are enabled. |
|
56 * A packet with this flag set can be delivered to sockets |
|
57 * that do not posses NetworkServices cabability. |
|
58 */ |
|
59 const TUint KIpLoopbackPacket = 0x1; |
|
60 /** |
|
61 * Incoming and outgoing RMBufPktInfo iFlag value for broadcast packet. |
|
62 * |
|
63 * The packet uses link layer broadcast. The stack sets this bit for |
|
64 * outgoing packets that are not unicast (e.g. multicast and broadcast |
|
65 * destinations). A NIF can set this flag for incoming packet, if it |
|
66 * was sent to a link layer broadcast address. The presence of this |
|
67 * flag suppresses some error replies from the stack. |
|
68 */ |
|
69 const TUint KIpBroadcastOnLink = 0x2; |
|
70 |
|
71 |
|
72 /** |
|
73 * A TSoIfInfo::iFeatures flag to indicate that the interface requires Neighbour |
|
74 * Discovery. |
|
75 * |
|
76 * @note |
|
77 * For IPv4 this enables ARP for the interface. The NIF must |
|
78 * pass received ARP packets to the stack, and accept ARP |
|
79 * packets for sending from the stack. |
|
80 * @since v7.0 |
|
81 * @publishedAll |
|
82 * @released |
|
83 */ |
|
84 const TUint KIfNeedsND = 0x00000100; |
|
85 |
|
86 class TSoIfInfo6 : public TSoIfInfo // aOption when aName == KSoIfInfo |
|
87 /** |
|
88 * Extends the TSoIfInfo for the receive MTU. |
|
89 * |
|
90 * The IPv6 capable interfaces must support this control option. The usage |
|
91 * template in the stack is: |
|
92 @code |
|
93 CNifIfBase *iNif; |
|
94 ... |
|
95 TPckgBuf<TSoIfInfo6> ifProp; |
|
96 TInt err = iNif->Control(KSOLInterface, KSoIfInfo6, ifProp); |
|
97 @endcode |
|
98 * For the IPv4 interfaces, only the plain TSoIfInfo is used. |
|
99 @code |
|
100 CNifIfBase *iNif; |
|
101 ... |
|
102 TPckgBuf<TSoIfInfo> ifProp; |
|
103 TInt err = iNif->Control(KSOLInterface, KSoIfInfo, ifProp); |
|
104 @endcode |
|
105 * @since v7.0 |
|
106 * @publishedAll |
|
107 * @released |
|
108 */ |
|
109 { |
|
110 public: |
|
111 /** Maximum transmission unit for receiving. */ |
|
112 TInt iRMtu; |
|
113 }; |
|
114 |
|
115 class TSoInet6IfConfig : public TSoIfConfigBase |
|
116 /** |
|
117 * IPv6 interface configuration. |
|
118 * |
|
119 * This is the option when stack queries the interface configuration |
|
120 * information using |
|
121 @code |
|
122 TPckgBuf<TSoInet6IfConfig> cfg; |
|
123 cfg().iFamily = KAfInet6; // Query about IPv6 capability |
|
124 TInt res = iNif->Control(KSOLInterface, KSoIfConfig, cfg); |
|
125 @endcode |
|
126 * The KErrNone return signifies that this NIF supports IPv6 on the |
|
127 * link layer. Note, similarly, the IPv4 support is detected by the |
|
128 * stack using: |
|
129 @code |
|
130 TPckgBuf<TSoInetIfConfig> cfg; |
|
131 cfg().iFamily = KAfInet; // Query about IPv4 capability. |
|
132 TInt res = iNif->Control(KSOLInterface, KSoIfConfig, cfg); |
|
133 @endcode |
|
134 * The same NIF can support both IPv4 and IPv6. |
|
135 * |
|
136 * @since v7.0 |
|
137 * @publishedAll |
|
138 * @released |
|
139 */ |
|
140 { |
|
141 public: |
|
142 /** |
|
143 * The local interface id. |
|
144 * |
|
145 * If the address family is not KAFUnspec, then this defines the id portion of |
|
146 * the IPv6 addresses for this host. The id portion is used in constructing the |
|
147 * link-local address (fe80::id) and combined with any other prefixes, which |
|
148 * are configured for this interface (prefix::id). Prefixes are configured via |
|
149 * Router Advertisement prefix option (TInet6OptionICMP_Prefix) with the A flag |
|
150 * set, or using interface control socket options (see TSoInet6InterfaceInfo). |
|
151 * |
|
152 * The length of the id is determined by the TSockAddr::GetUserLen. The normal |
|
153 * value is 8 (e.g. the standard id is always 64 bits). Other id lengths are |
|
154 * possibly activated by future RFC's for some special address formats. |
|
155 * |
|
156 * If the address family is KAFUnspec, then id is not configured (and for the |
|
157 * IPv6 interface to be functional, address(es), including the link-local address, |
|
158 * must be configured by some other means). |
|
159 */ |
|
160 TSockAddr iLocalId; |
|
161 /** |
|
162 * The remote interface id (or KAFUnspec, if not applicaple). |
|
163 * |
|
164 * If the address family is not KAFUnspec, then this defines the id portion of |
|
165 * another host on the link. The stack constructs a link-local address |
|
166 * (fe80::remote-id) and installs a host route for it. |
|
167 * |
|
168 * This might be useful for PPP links, if other end is not acting as a router. |
|
169 * If the other end is a router, it's address will become automaticly known, |
|
170 * when it sends the Router Advertisement. |
|
171 */ |
|
172 TSockAddr iRemoteId; |
|
173 /** |
|
174 * Unused highest significant bits in interface id (usually 0). |
|
175 * |
|
176 * This is reserved for future use, in case there is a need for id length |
|
177 * that is not multiple of 8. |
|
178 */ |
|
179 TUint idPaddingBits; |
|
180 /** 1st DNS address (or Unspecified address, if none) */ |
|
181 TInetAddr iNameSer1; |
|
182 /** 2nd DNS address (or Unspecified address, if none) */ |
|
183 TInetAddr iNameSer2; |
|
184 }; |
|
185 |
|
186 /** |
|
187 |
|
188 @page nif_interface The interface between a NIF and the TCP/IP stack. |
|
189 |
|
190 The network interfaces (NIF's) are registered with the stack using the |
|
191 MNifIfUser::IfUserNewInterfaceL function. Stack has an internal object that |
|
192 represents the interface and the given CNifIfBase object is attached to this. |
|
193 |
|
194 The stack communicates with the NIF using the public API defined by the CNifIfBase. |
|
195 The NIF sees the stack as an instance of CProtocolBase and can use a subset of |
|
196 public functions to communcite with the stack. |
|
197 |
|
198 The following CNifBase functions are used by the stack: |
|
199 |
|
200 - CNifIfBase::Open, (binding stack and NIF) |
|
201 - CNifIfBase::Close, (binding stack and NIF) |
|
202 - CNifIfBase::BindL, (binding stack and NIF) |
|
203 - CNifIfBase::Control, (for the configuration information) |
|
204 - CNifIfBase::Info, (retrieve the interface name) |
|
205 - CNifIfBase::Send, (send outbound packets to NIF) |
|
206 - CNifIfBase::Notify, (NIFMAN about packet activity) |
|
207 |
|
208 The following CProtocolBase functions are available for NIFs: |
|
209 |
|
210 - CProtocolBase::StartSending, (notify stack that NIF is ready) |
|
211 - CProtocolBase::Error, (notify stack about NIF error) |
|
212 - CProtocolBase::Process, (feed inbound packets to stack) |
|
213 |
|
214 The network interface is removed from the stack either by directly deleting it, or |
|
215 by NIFMAN using MNifIfUser::IfUserInterfaceDown. |
|
216 |
|
217 A pointer to the MNifIfUser object can be obtained from the network |
|
218 layer protocol. |
|
219 @code |
|
220 MNetworkService *iNetwork; |
|
221 TPckgBuf<MNifIfUser*> ifUser; |
|
222 TInt err = iNetwork->Protocol()->GetOption(KNifOptLevel, KNifOptGetNifIfUser, ifUser); |
|
223 @endcode |
|
224 |
|
225 |
|
226 @section nif_binding Binding the NIF and TCP/IP together |
|
227 |
|
228 MNifIfUser::IfUserNewInterfaceL introduces a new network interface (NIF) to the stack. |
|
229 The introduction consists of the following steps: |
|
230 |
|
231 -# retrieve interface info into TNifIfInfo by CNifIfBase::Info function. Stack uses |
|
232 only the interface name (iName) from this. The name cannot be an empty string. |
|
233 -# using the name, the stack searches for a matching internal interface object. If |
|
234 it does not exist, it is created. If there was an existing interface with the same |
|
235 name, the stack will disconnect that first. |
|
236 -# the stack gives itself to the new NIF by calling CNifIfBase::BindL. |
|
237 -# stack does not send any packets to the interface until the NIF has called |
|
238 CProtocolBase::StartSending at least once. |
|
239 -# stack executes the interface configuration when the first CProtocolBase::StartSending arrives |
|
240 after MNifIfUser::IfUserNewInterfaceL. The configuration uses the CNifIfBase::Control function |
|
241 with different options to retrieve additional information from the NIF. |
|
242 |
|
243 MNifIfUser::IfUserInterfaceDown disconnects the NIF from the stack. There is one |
|
244 exception: if the MNifIfUser::IfUserInterfaceDown aResult parameter has a special |
|
245 value #KErrLinkConfigChanged, then the internal interface state is only reset to the |
|
246 exact same state as if interface was just introduced by the |
|
247 MNifIfUser::IfUserNewInterfaceL, and a reconfiguration occurs when the NIF calls |
|
248 StartSending. |
|
249 |
|
250 @section nif_control_api The Control API |
|
251 |
|
252 The stack requires the NIF to implement a minimal set of #KSOLInterface level |
|
253 options via it's CNifIfBase::Control API. |
|
254 |
|
255 - at least one of the information options |
|
256 - TSoIfInfo6 with #KSoIfInfo6 (for IPv6) |
|
257 - TSoIfInfo with #KSoIfInfo (for IPv4) |
|
258 . |
|
259 - at least one of the configuration options |
|
260 - TSoInet6IfConfig (iFamily=#KAfInet6) with #KSoIfConfig |
|
261 - TSoInetIfConfig (iFamily=#KAfInet) with #KSoIfConfig |
|
262 . |
|
263 - TSoIfHardwareAddr with #KSoIfHardwareAddr if the link |
|
264 uses hardware addresses (only used #KIfNeedsND is also set.). The returned |
|
265 address is used in the neighbor discovery (ICMPv6 ND or ARP for IPv4), and |
|
266 in sending packets to NIF, the address family is used to indicate that the |
|
267 stack has chosen the destination link layer address (based on the neighbor |
|
268 cache). |
|
269 - TSoIfConnectionInfo with #KSoIfGetConnectionInfo (for IAP and NET numbers). |
|
270 If this is not supported, the stack will assign unique numbers for the |
|
271 IAP and NET. The scope vector (zone identifiers) is contructed as follows: |
|
272 -# [0] The unique interface index (node local scope id) |
|
273 -# [1] IAP number (link scope id) |
|
274 -# [2] IAP number (subnet scope id) |
|
275 -# [3] NET number |
|
276 -# [4] NET number (site local scope id) |
|
277 -# [5] NET number |
|
278 -# [6] NET number |
|
279 -# [7] NET number (organization scope id) |
|
280 -# [8] NET number |
|
281 -# [9] NET number |
|
282 -# [10] NET number |
|
283 -# [11] NET number |
|
284 -# [12] NET number |
|
285 -# [13] NET number (IPv6 global scope) |
|
286 -# [14] NET number |
|
287 -# [15] NET number (highest, NET id, IPv4 global) |
|
288 |
|
289 @note |
|
290 To build complete ARP packets in the stack, stack needs to know the hardware |
|
291 type value to be used in the packet (see TInet6HeaderArp). This 16 bit value |
|
292 is assumed to be in the Port() field of the returned hardware address |
|
293 (#KSoIfHardwareAddr). An IPv4 NIF that leaves the ARP to the stack, |
|
294 must provide this value (or sniff and fix the outgoing ARP packets). |
|
295 |
|
296 @section nif_inbound_packets Inbound packets from the NIF to stack. |
|
297 |
|
298 The NIF feeds the inbound packets to the stack through the CProtocolBase::Process |
|
299 function (see also MNetworkService::Process). The information block associated |
|
300 with the packet is RMBufPktInfo and the fields must have been set as follows: |
|
301 |
|
302 - RMBufPktInfo::iSrcAddr, the link layer source address (using the same |
|
303 address family as returned with the hardware address control option). If |
|
304 the link does not use addresses, then #KAFUnspec should be used. |
|
305 - RMBufPktInfo::iDstAddr, the link layer destination address (using the same |
|
306 address family as returned with the hardware address control option). If |
|
307 the link does not use addresses, then #KAFUnspec should be used. |
|
308 - RMBufPktInfo::iProtocol, the type of the packet: |
|
309 - #KProtocolInetIp, IPv4 packet |
|
310 - #KProtocolInet6Ip, IPv6 packet |
|
311 - #KProtocolArp, ARP packet |
|
312 . |
|
313 - RMBufPktInfo::iLength, the length of the packet in octets |
|
314 - RMBufPktInfo::iFlags, should be set to zero (reserved for future use). |
|
315 |
|
316 @note |
|
317 The stack is relaxed about the checking of iProtocol field, and anything |
|
318 else except #KProtocolArp is assumed to be an IP packet. This is potentially |
|
319 to changed in future, and NIFs should set the protocol field correctly. |
|
320 @note |
|
321 The link layer addresses in iSrcAddr and iDstAddr are informative. The |
|
322 values do not affect the processing of the packet within stack. They are |
|
323 made available for the inbound post hooks (CProtocolPosthook). |
|
324 |
|
325 @section nif_outbound_packets Outbound packets from the stack to NIF |
|
326 |
|
327 The stack feeds the outbound packets to the NIF through the CNifIfBase::Send |
|
328 function. The information block associated with the packet follows RMBufPktInfo |
|
329 and the fields need to be interpreted as follows: |
|
330 |
|
331 - RMBufPktInfo::iSrcAddr, undefined (must be ignored by the NIF). |
|
332 The NIF must choose the link layer source address. |
|
333 - RMBufPktInfo::iDstAddr, three variants, if link layer addresses are used |
|
334 - hardware address, using the same address family as NIF returned |
|
335 in harware address control option (TSoIfHardwareAddr ). |
|
336 The packet must be sent to this link layer destination. |
|
337 - #KAfInet, the address is IPv4 multicast address. and the NIF must |
|
338 select a suitable link layer broadcast address as a destination. |
|
339 - #KAfInet6, the address is IPv6 multicast address, and the NIF msut |
|
340 select a suitable link layer broadcast address as a destination. |
|
341 . |
|
342 If the NIF does not use link layer addresses, then iDstAddr is also |
|
343 undefined (must be ingnored byt the NIF). The link is a point-to-point |
|
344 interface. |
|
345 - RMBufPktInfo::iProtocol, defines the type of packet |
|
346 - #KProtocolInetIp, IPv4 packet |
|
347 - #KProtocolInet6Ip, IPv6 packet |
|
348 - #KProtocolArp, ARP packet |
|
349 . |
|
350 - RMBufPktInfo::iLength, the length of the packet in octets. |
|
351 - RMBufPktInfo::iFlags, undefined (must be igrnored by the NIF). |
|
352 |
|
353 The stack interprets the return value from the CNifIfBase::Send as follows: |
|
354 |
|
355 - return 1; the NIF is ready to receive more packets. |
|
356 - return 0; the NIF is blocked and cannot receive any more packets. The stack |
|
357 <b>does not send anything</b> to the NIF until it calls CProtocolBase::StartSending. |
|
358 - return < 0; unspecified, but currently, the error is passed on to |
|
359 all flows attached to this interface. The stack will continue sending |
|
360 packets to the interface (no StartSending is required). |
|
361 - return > 1; unspecified, but currently treated same as return 1. |
|
362 |
|
363 */ |
|
364 |
|
365 #endif |