epoc32/include/in6_opt.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000
branchSymbian2
changeset 2 2fe1408b6811
parent 0 061f57f2323e
child 4 837f303aceeb
permissions -rw-r--r--
Final list of Symbian^2 public API header files
williamr@2
     1
// Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2
     2
// All rights reserved.
williamr@2
     3
// This component and the accompanying materials are made available
williamr@2
     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
williamr@2
     5
// which accompanies this distribution, and is available
williamr@2
     6
// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2
     7
//
williamr@2
     8
// Initial Contributors:
williamr@2
     9
// Nokia Corporation - initial contribution.
williamr@2
    10
//
williamr@2
    11
// Contributors:
williamr@2
    12
//
williamr@2
    13
// Description:
williamr@2
    14
// in6_opt.h - new socket options and MEventService data e.g.
williamr@2
    15
// for accessing the network interface and route
williamr@2
    16
// information.
williamr@2
    17
// New socket options and MEventService data e.g. for accessing the network interface
williamr@2
    18
// and route information.
williamr@2
    19
//
williamr@2
    20
williamr@2
    21
williamr@2
    22
williamr@2
    23
/**
williamr@2
    24
 @file in6_opt.h
williamr@2
    25
 @publishedAll
williamr@2
    26
 @released
williamr@2
    27
*/
williamr@2
    28
williamr@2
    29
#ifndef __INSOCK_IN6_ROUTE_H__
williamr@2
    30
#define __INSOCK_IN6_ROUTE_H__
williamr@2
    31
williamr@2
    32
#include <in_sock.h>
williamr@2
    33
williamr@2
    34
williamr@2
    35
// PS: I'm declaring the following rule:
williamr@2
    36
// ** Use socket option names above 0x1000 for all options defined in this file **
williamr@2
    37
// (don't want to accidentally collide with in_sock.h, even though the probability is
williamr@2
    38
// small considering the number of different sockopt levels)
williamr@2
    39
williamr@2
    40
williamr@2
    41
// -- Socket option level: KSolInetIp --
williamr@2
    42
williamr@2
    43
/**
williamr@2
    44
Controls the use of Explicit Congestion Notification. Values:
williamr@2
    45
@li 0 = ECN disabled
williamr@2
    46
@li 1 = ECN enabled with ECT(1)
williamr@2
    47
@li 2 = ECN enabled with ECT(0) (recommended over ECT(1), because some implementations may
williamr@2
    48
not implement ECT(1))
williamr@2
    49
williamr@2
    50
See RFC 3168 for more information.
williamr@2
    51
@publishedAll
williamr@2
    52
@interim
williamr@2
    53
*/
williamr@2
    54
const TUint KSoIpEcn = 0x1010;
williamr@2
    55
williamr@2
    56
/**
williamr@2
    57
Next hop route selection.
williamr@2
    58
williamr@2
    59
Set forces the next hop route selection on the flow.
williamr@2
    60
The option parameter is not used in set.
williamr@2
    61
williamr@2
    62
Get returns information about the current next hop
williamr@2
    63
selection. The option parameter is TInetRouteInfo.
williamr@2
    64
williamr@2
    65
If the link layer is using addresses, the information
williamr@2
    66
refers to neighbor cache entry. If the interface is not
williamr@2
    67
using link layer addresses, the returned information just
williamr@2
    68
describes the currently attached route entry.
williamr@2
    69
williamr@2
    70
To be successful, the flow must be assigned to the
williamr@2
    71
interface and the source address must be set at the
williamr@2
    72
time of the call.
williamr@2
    73
williamr@2
    74
This option is provided for hook implementations, for
williamr@2
    75
example ISATAP tunneling hook can use this¨to force
williamr@2
    76
next hop selection on the virtual interface to find the
williamr@2
    77
actual link layer address (= outer IPv4 address).
williamr@2
    78
*/
williamr@2
    79
const TUint KSoNextHop = 0x1011;
williamr@2
    80
williamr@2
    81
williamr@2
    82
// -- Socket option level: KSolInetTcp --
williamr@2
    83
/**
williamr@2
    84
If set, only full-sized TCP segments are sent before closing the connection. This is like
williamr@2
    85
Nagle, but stricter.
williamr@2
    86
@publishedAll
williamr@2
    87
@interim
williamr@2
    88
*/
williamr@2
    89
const TUint KSoTcpCork = 0x1020;
williamr@2
    90
williamr@2
    91
/**
williamr@2
    92
Send only full-sized TCP segments. Separate option in addition to KSoTcpCork is needed for
williamr@2
    93
BSD compatibility.
williamr@2
    94
@publishedAll
williamr@2
    95
@interim
williamr@2
    96
*/
williamr@2
    97
const TUint KSoTcpNoPush = 0x1021;
williamr@2
    98
williamr@2
    99
/**
williamr@2
   100
Do not return from close immediately, but linger for given maximum time to wait that the
williamr@2
   101
send buffers are emptied. Socket option parameter is TSoTcpLingerOpt struct.
williamr@2
   102
@publishedAll
williamr@2
   103
@interim
williamr@2
   104
*/
williamr@2
   105
const TUint KSoTcpLinger = 0x1022;
williamr@2
   106
williamr@2
   107
williamr@2
   108
/**
williamr@2
   109
Parameter struct for KSoTcpLinger socket option. The following combinations are possible:
williamr@2
   110
williamr@2
   111
@li <b>iOnOff == 0</b>: Close() call returns immediately, but TCP still
williamr@2
   112
		tries to transmit the data remaining in its send buffers.
williamr@2
   113
@li <b>iOnOff == 1, iLinger == 0</b>: Close() returns immediately, and the TCP sender discards
williamr@2
   114
		all data in its send buffers. TCP RST is sent to the other end. Note: the TCP sender
williamr@2
   115
		avoids the TIME_WAIT state.
williamr@2
   116
@li <b>iOnOff == 1, iLinger > 0</b>: Close() call blocks until the data in TCP send buffers
williamr@2
   117
		is succesfully transmitted and the connection is graciously terminated.
williamr@2
   118
		If the sender cannot transmit all data before the linger time expires,
williamr@2
   119
		the Close() call wakes up, but the stack continues towards terminating the
williamr@2
   120
		connection as usual.
williamr@2
   121
		
williamr@2
   122
A similar structure is used in BSD Unix sockets, hence porting Unix apps using linger option
williamr@2
   123
should be straight forward.
williamr@2
   124
@publishedAll
williamr@2
   125
@interim
williamr@2
   126
*/
williamr@2
   127
class TSoTcpLingerOpt
williamr@2
   128
	{
williamr@2
   129
public:
williamr@2
   130
	TInt	iOnOff;		///< 0=Linger off; nonzero=Linger on.
williamr@2
   131
	TInt	iLinger;	///< Linger time in seconds.
williamr@2
   132
	};
williamr@2
   133
	
williamr@2
   134
williamr@2
   135
// -- Socket option level: KSolInetIfQuery --
williamr@2
   136
williamr@2
   137
// The options below are on KSolInetIfQuery level, although they use different option format
williamr@2
   138
// than the rest of the options.
williamr@2
   139
// There are no incoming parameters for these queries
williamr@2
   140
williamr@2
   141
/**
williamr@2
   142
Return array of TInetInterfaceInfo objects as the response of GetOptions call.
williamr@2
   143
@publishedAll
williamr@2
   144
@interim
williamr@2
   145
*/
williamr@2
   146
const TUint KSoInetInterfaceInfo = 0x1001;
williamr@2
   147
williamr@2
   148
/**
williamr@2
   149
Return array of TInetAddressInfo objects as the response of GetOptions call.
williamr@2
   150
@publishedAll
williamr@2
   151
@interim
williamr@2
   152
*/
williamr@2
   153
const TUint KSoInetAddressInfo = 0x1002;
williamr@2
   154
williamr@2
   155
/**
williamr@2
   156
Return array of TInetRouteInfo objects as the response of GetOptions call.
williamr@2
   157
@publishedAll
williamr@2
   158
@interim
williamr@2
   159
*/
williamr@2
   160
const TUint KSoInetRouteInfo = 0x1003;
williamr@2
   161
williamr@2
   162
/**
williamr@2
   163
Information of an address attached to interface.
williamr@2
   164
Used by the event service (EClassAddress events) and KSoInetAddressInfo socket option.
williamr@2
   165
@publishedAll
williamr@2
   166
@interim
williamr@2
   167
*/
williamr@2
   168
class TInetAddressInfo
williamr@2
   169
	{
williamr@2
   170
public:
williamr@2
   171
	TUint32	    iInterface;	    ///< Network interface index to which this address is bound.
williamr@2
   172
	TIp6Addr    iAddress;	    ///< Prefix or Id part of the address described.
williamr@2
   173
	TUint8	    iPrefixLen;	    ///< Length of the prefix part in bits.
williamr@2
   174
	TUint32	    iScopeId;	    ///< ScopeId of this address.
williamr@2
   175
	TUint32	    iPrefLifetime;  ///< Remaining Preferred lifetime of this address.
williamr@2
   176
	TUint32	    iValidLifetime; ///< Remaining Valid lifetime of this address.
williamr@2
   177
	TUint	    iFlags;	    ///< Is address entry for prefix or id, etc. See enum TFlags
williamr@2
   178
	TUint	    iState;	    ///< Address state, copied from TIp6AddressInfo, see enum TAddressState
williamr@2
   179
	TUint	    iType;	    ///< Address type copied from TIp6AddressInfo, see enum TAddressType
williamr@2
   180
	TUint	    iGenerations;   ///< Number of times the address Id is generated (or randomly re-generated)
williamr@2
   181
	TUint	    iNS;	    ///< Number of neighbour solicitations sent for DAD.
williamr@2
   182
williamr@2
   183
	/// Values used in iFlags field.
williamr@2
   184
	enum TFlags
williamr@2
   185
		{
williamr@2
   186
	    EF_Prefix = 0x1,	///< This address entry specifies prefix
williamr@2
   187
	    EF_Id = 0x2,    	///< This address entry specifies id part of the address
williamr@2
   188
	    EF_Deprecated = 0x4 ///< Address is deprecated
williamr@2
   189
		};
williamr@2
   190
williamr@2
   191
	/// Values used in iState field. The field is directly copied from iface.cpp.
williamr@2
   192
	enum TAddressState
williamr@2
   193
		{
williamr@2
   194
	    ENoAddress	= 0,	///< 0 0 - unassigned initial state (no address present)
williamr@2
   195
	    EDuplicate	= 1,	///< 0 1 - address is duplicate
williamr@2
   196
	    EAssigned	= 2,	///< 1 0 - address fully available
williamr@2
   197
	    ETentative	= 3	///< 1 1 - address is tentative (DAD in progress)
williamr@2
   198
		};
williamr@2
   199
williamr@2
   200
	/// Values used in iType field. The field is directly copied from iface.cpp.
williamr@2
   201
	enum TAddressType
williamr@2
   202
		{
williamr@2
   203
	    EProxy	= 2,	///< Do DAD, is not for me (forward)
williamr@2
   204
	    EAnycast	= 1,	///< Don't do DAD, is for me address
williamr@2
   205
	    ENormal	= 0	///< Do DAD, is for me
williamr@2
   206
		};
williamr@2
   207
	};
williamr@2
   208
williamr@2
   209
williamr@2
   210
/**
williamr@2
   211
Information of a network interface.
williamr@2
   212
Used by event service (EClassInterface events) and KSoInetInterfaceInfo socket option.
williamr@2
   213
@publishedAll
williamr@2
   214
@interim
williamr@2
   215
*/
williamr@2
   216
class TInetInterfaceInfo
williamr@2
   217
	{
williamr@2
   218
public:
williamr@2
   219
	TUint32	    iIndex;
williamr@2
   220
	TName	    iName;		///< Interface name
williamr@2
   221
	TInt	    iState;		///< State
williamr@2
   222
	TInt	    iSMtu;		///< Maximum transmit unit size
williamr@2
   223
	TInt	    iRMtu;		///< Maximum receive unit size
williamr@2
   224
	TInt	    iSpeedMetric;	///< Metric - bigger is better
williamr@2
   225
	TUint	    iFeatures;		///< Feature flags
williamr@2
   226
	TSockAddr   iHwAddr;		///< Hardware address
williamr@2
   227
williamr@2
   228
	/// Possible interface states.
williamr@2
   229
	/// Can also have negative values when on error state.
williamr@2
   230
	enum
williamr@2
   231
		{
williamr@2
   232
	    IfState_READY   = 0,  ///< Ready to receive data from protocol
williamr@2
   233
	    IfState_PENDING = 1,  ///< Not ready for data yet
williamr@2
   234
	    IfState_HOLD    = 2
williamr@2
   235
		};
williamr@2
   236
	};
williamr@2
   237
williamr@2
   238
williamr@2
   239
/**
williamr@2
   240
Information of a route entry in IP stack.
williamr@2
   241
Used by event service (EClassRoute events) and KSoInetRouteInfo socket option.
williamr@2
   242
@publishedAll
williamr@2
   243
@interim
williamr@2
   244
*/
williamr@2
   245
class TInetRouteInfo
williamr@2
   246
	{
williamr@2
   247
public:
williamr@2
   248
	TUint32	    iIndex;	///< Route index
williamr@2
   249
	TUint	    iType;	///< Type of route (kernel generated have 0 at the present)
williamr@2
   250
	TUint	    iState;	///< State of route (copied from iState in CIp6Route)
williamr@2
   251
	TInt	    iMetric;	///< Smaller is better (less hops and/or faster link)
williamr@2
   252
	TUint32	    iInterface; ///< Network interface index of the route
williamr@2
   253
	TIp6Addr    iGateway;	///< IP address of gateway (might be the interface)
williamr@2
   254
	TIp6Addr    iDstAddr;	///< Destination network or host
williamr@2
   255
	TUint8	    iPrefixLen;	///< Length of the route prefix in bits
williamr@2
   256
	TUint32	    iScopeId;	///< Scope Id of this route
williamr@2
   257
	TUint32	    iLifetime;  ///< Route lifetime in seconds
williamr@2
   258
williamr@2
   259
	enum
williamr@2
   260
		{ 
williamr@2
   261
		EDeprecated = 0x80000000	///< This bit is set in iType if the route is deprecated
williamr@2
   262
		};
williamr@2
   263
williamr@2
   264
	/// Values used in iState field
williamr@2
   265
	enum TState
williamr@2
   266
	  	{
williamr@2
   267
	    EIncomplete = 0,
williamr@2
   268
	    ELoopback = 1,
williamr@2
   269
	    EOnlink = 2,
williamr@2
   270
	    EGateway = 3,
williamr@2
   271
	    EAnycast = 5,
williamr@2
   272
	    ERedirect = 7,
williamr@2
   273
	    EReachable = 8,
williamr@2
   274
	    EStale = 16
williamr@2
   275
	 	 };
williamr@2
   276
	};
williamr@2
   277
	
williamr@2
   278
williamr@2
   279
/**
williamr@2
   280
Information on a neighbour cache entry in the IP stack.
williamr@2
   281
Used by event service (EClassNeighbour events).
williamr@2
   282
@released
williamr@2
   283
*/
williamr@2
   284
class TInetNeighbourInfo
williamr@2
   285
	{
williamr@2
   286
public:
williamr@2
   287
	TUint32	    iIndex;		///< Route index.
williamr@2
   288
	TIp6Addr    iDstAddr;	///< Neighbour's IP address.
williamr@2
   289
	TUint	    iState;		///< State of neigbour entry. @see TInetRouteInfo::TState.
williamr@2
   290
	TInt	    iMetric;	///< Smaller is better (less hops and/or faster link).
williamr@2
   291
	TUint32	    iInterface; ///< Network interface index of the route.
williamr@2
   292
	TUint32	    iScopeId;	///< Scope Id of this neighbour.
williamr@2
   293
	TUint32	    iLifetime;  ///< Cache entry lifetime in seconds.
williamr@2
   294
williamr@2
   295
	/// Hardware address (e.g. Ethernet MAC).
williamr@2
   296
	TBuf8<KMaxSockAddrSize>	iHwAddr;
williamr@2
   297
	};
williamr@2
   298
williamr@2
   299
williamr@2
   300
/**
williamr@2
   301
For building an array on top of TDes8. This is like casting a TDes8 data pointer to an array, but
williamr@2
   302
it provides protection against array boundary violations, and some small helpful utilities.
williamr@2
   303
The motivation of this class is to help in handling the information accessed by MNetworkInfo
williamr@2
   304
interface.
williamr@2
   305
@publishedAll
williamr@2
   306
@interim
williamr@2
   307
*/
williamr@2
   308
template<class T> class TOverlayArray
williamr@2
   309
	{
williamr@2
   310
public:
williamr@2
   311
	inline TOverlayArray(TDes8& aDes) : iDes(aDes)
williamr@2
   312
	{ }
williamr@2
   313
williamr@2
   314
	/**
williamr@2
   315
	* Returns pointer to the given element location in the array. If the index exceeds the
williamr@2
   316
	* maximum length of the array, NULL is returned.
williamr@2
   317
	*/
williamr@2
   318
	inline T* IndexPtr(TInt aIndex)
williamr@2
   319
	{ if (aIndex >= MaxLength()) return NULL; else return &((T*)iDes.Ptr())[aIndex]; }
williamr@2
   320
williamr@2
   321
	/**
williamr@2
   322
	* Return the given element of the array. No boundary checking.
williamr@2
   323
	*/
williamr@2
   324
	inline T& operator[](TInt aIndex)
williamr@2
   325
	{ return ((T*)iDes.Ptr())[aIndex]; }
williamr@2
   326
williamr@2
   327
	/**
williamr@2
   328
	* Returns the maximum length of the array in the number of array elements.
williamr@2
   329
	*/
williamr@2
   330
	inline TInt MaxLength()
williamr@2
   331
	{ return (iDes.MaxLength() / sizeof(T)); }
williamr@2
   332
williamr@2
   333
	/**
williamr@2
   334
	* Returns the current length of the array in the number of array elements.
williamr@2
   335
	* The length information is based
williamr@2
   336
	* on the current underlaying descriptor length, which may not always be the desired result.
williamr@2
   337
	*/
williamr@2
   338
	inline TInt Length()
williamr@2
   339
	{ return (iDes.Length() / sizeof(T)); }
williamr@2
   340
williamr@2
   341
	/**
williamr@2
   342
	* Set the length of the underlaying descriptor. The parameter is given in the number of array
williamr@2
   343
	* elements, which is then multiplied by a length of one element to determine the needed
williamr@2
   344
	* descriptor length.
williamr@2
   345
	*/
williamr@2
   346
	inline void SetLength(TInt aLength)
williamr@2
   347
	{ iDes.SetLength(aLength * sizeof(T)); }
williamr@2
   348
williamr@2
   349
private:
williamr@2
   350
	TDes8&	  iDes;
williamr@2
   351
	};
williamr@2
   352
williamr@2
   353
williamr@2
   354
/**
williamr@2
   355
Information of a multicast group joined by the IP stack. This class is not currently
williamr@2
   356
used by socket options, only EClassMulticast events.
williamr@2
   357
@publishedAll
williamr@2
   358
@interim
williamr@2
   359
*/
williamr@2
   360
class TInetMulticastInfo
williamr@2
   361
	{
williamr@2
   362
public:
williamr@2
   363
	TIp6Addr	iMulticastGroup;	///< IP address of the multicast group.
williamr@2
   364
	TUint32		iInterface;		///< Interface index of the group.
williamr@2
   365
	TUint32		iLifetime;		///< Lifetime of the group in seconds.
williamr@2
   366
	};
williamr@2
   367
williamr@2
   368
williamr@2
   369
// -- Socket option level: KSolInetIfCtrl --
williamr@2
   370
williamr@2
   371
/**
williamr@2
   372
Control the use of link-local addresses per interface.
williamr@2
   373
Argument: TSoInetIpv4LinkLocalInfo  (SetOpt only).
williamr@2
   374
@publishedAll
williamr@2
   375
@interim
williamr@2
   376
williamr@2
   377
@capability ECapabilityNetworkControl Configuring IPv4 Link-local addresses is restricted.
williamr@2
   378
@ref RSocket::SetOpt()
williamr@2
   379
*/
williamr@2
   380
const TUint KSoIpv4LinkLocal = 0x1001;
williamr@2
   381
williamr@2
   382
/**
williamr@2
   383
Used as a parameter in KSoIpv4LinkLocal.
williamr@2
   384
@publishedAll
williamr@2
   385
@interim
williamr@2
   386
*/
williamr@2
   387
class TSoInetIpv4LinkLocalInfo
williamr@2
   388
	{
williamr@2
   389
public:
williamr@2
   390
	TUint	iInterface;		///< Interface index to be affected.
williamr@2
   391
	TUint	iFlag;			///< Indicates whether IPv4 link locals are used  (0='no'; 1='yes').
williamr@2
   392
	};
williamr@2
   393
williamr@2
   394
#endif  // __INSOCK_IN6_ROUTE_H__