#include <in_sock.h>
| class TInetAddr : public TSockAddr |
| Protected Member Functions | |
|---|---|
| SInetAddr * | Addr4Ptr() |
| TInt | AddrLen() |
| SInet6Addr * | AddrPtr() |
| Inherited Attributes | |
|---|---|
| TBuf8< KMaxSockAddrSize >::iBuf | |
| TDes8::__DECLARE_TEST | |
| TDes8::iMaxLength | |
This class specialises the generic socket server address class TSockAddr for the TCP/IP protocol family. It represents an IP address and stores either an IPv4 or an IPv6 address in its buffer after the generic data defined by TSockAddr. The protocol family field provided by the TSockAddr base class can be set to KAfInet, KAfInet6 or KAFUnspec.
The address family defines the format of the stored address:
KAfInet is for plain 32 bits IPv4 address presented as SInetAddr structure.
KAfInet6 is for both IPv4 and IPv6 addresses (IPv4 addresses are in IPv4 mapped format). The content is presented as SInet6Addr structure, which includes the scope id and flow label, in addition to the 128 address bits.
KAFUnspec does not contain any addresses and works in most contexts as unspecified address, This is better than placing explicit IPv4 "0.0.0.0" or IPv6 "::", which in certain situations may limit the connections to either IPv4 or IPv6, but not both.
Any function which sets or changes the address bits, will always reset the scope id and flow label to 0 (the TInetAddr::Init is always called internally). These are reasonable defaults, and normal application user does not normally need to worry about flow label or scope id.
When address is returned from the stack, it will often be in KAfInet6 format, and may contain non-zero values for flow label and scope id fields. When copying addresses, the full TInetAddr (or at least SInet6Addr) should be copied to preserve these fields.
| IMPORT_C | TInetAddr | ( | ) |
Constructs a basic TInetAddr object.
The port is initialised to 0, and the IP address is unspecified. The resulting address family is KAFUnspec.
| IMPORT_C | TInetAddr | ( | const TSockAddr & | aAddr | ) |
Constructs a TInetAddr from a TSockAddr.
The port and IP address values are copied from aAddr. The resulting address family is same as that of aAddr.
The function does a raw copy operation of the TSockAddr. No checks are made at this point.
| Parameter | Description |
|---|---|
| aAddr | TSockAddr to be used as initial content. |
| SInet6Addr * | AddrPtr | ( | ) | const [protected, inline] |
Returns a pointer to KAfInet6 content format.
| IMPORT_C TUint32 | Address | ( | ) | const |
Gets the IPv4 address value.
If the stored address is not an IPv4 address, the returned value is ZERO.
This works also for IPv4 addresses which are stored in IPv4-mapped or IPv4-compatible format. (since 7.0).
Returns: The IP address value.
| IMPORT_C void | ConvertToV4 | ( | ) |
Converts an IPv4-mapped or IPv4-comptatible address to IPv4.
The function assumes that the previous content is IPv4 address and accesses this using TInetAddr::Address() function. If the previous content was not IPv4 address (in any format), function acts as if the old content was 0.0.0.0.
| IMPORT_C void | ConvertToV4Compat | ( | ) |
Converts an IPv4 address to an IPv4-compatible IPv6 address.
The function assumes that the previous content is IPv4 address and accesses this using TInetAddr::Address() function. If the previous content was not IPv4 address (in any format), function acts as if the old content was 0.0.0.0.
The IPv4-compatible format is x.x.x.x.
The resulting address family is KAfInet6. The scope id and flow label are zeroed.
| IMPORT_C void | ConvertToV4Mapped | ( | ) |
Converts an IPv4 address to an IPv4-mapped IPv6 address.
The function assumes that the previous content is IPv4 address and accesses this using TInetAddr::Address() function. If the previous content was not IPv4 address (in any format), function acts as if the old content was "0.0.0.0".
The IPv4-mapped format is ffff:x.x.x.x. Internally, all IPv4 addresses are stored in this format.
| IMPORT_C void | Init | ( | TUint | aFamily | ) |
Initialises the object properly according to the address family passed in.
| Parameter | Description |
|---|---|
| aFamily | The address family. Valid values are KAfInet, plain IPv4 address format KAfInet6, combined IPv4 and IPv6 format, including fields for the scope id and flow label. anything else, initialized to KAFUnspec, with empty content. |
Sets the IP address from a string containing a representation of an IP address, such as might be entered in a dialog.
Four 8-bit decimal numbers separated by '.' (eg. 192.168.40.4)
Two 8-bit decimal numbers and a 16 bit decimal (eg. 192.168.10244)
One 8-bit decimal number and a 24-bit decimal (eg. 192.11020292)
One 32 decimal number (eg. 3232245764)
Eight 16-bit hex numbers separated by ':' (eg.2001:618:400:6a:0:0:0:abc)
Any of the address notations above can be followed by "%scope-id" and the scope id of the TInetAddress is also set accordingly. If a dotted IPv4 address is associated with scope id, the address is stored as IPv4-mapped. If scope is not specified, the value defaults to zero. The flow label is set to zero.
The hexadecimal numbers may be either upper or lower case.
| Parameter | Description |
|---|---|
| aBuf | Descriptor containing a string representation of an IP address |
Returns: KErrNone, if address syntax was correct and input succeeded; otherwise, one of the system-wide error codes.
| IMPORT_C const TIp6Addr & | Ip6Address | ( | ) | const |
Gets the IPv6 address
Only for KAfInet6, undefined for KAfInet.
This function returns a reference to a location where IPv6 address would be stored. No check on family is made, and using this function for any other address family except KAfInet6 does not cause an error, but returned reference does not point to valid IPv6 address (unless content is converted to KAfInet6).
Returns: The IPv6 address
| TBool | IsBroadcast | ( | ) | const [inline] |
Tests if the IP address is a limited broadcast address (255.255.255.255).
Returns: ETrue if the IPv4 address value is a limited broadcast address; otherwise, EFalse
| TBool | IsClassA | ( | ) | const [inline] |
Tests if the IP address is Class A.
DeprecatedWorks only for IPv4. It assumes the old IPv4 address classes (A, B, C). Applications using this function may not work properly in the current internet environment.
Returns: ETrue if the IPv4 address value is Class A; otherwise, EFalse
| TBool | IsClassB | ( | ) | const [inline] |
Tests if the IP address is Class B.
DeprecatedWorks only for IPv4. It assumes the old IPv4 address classes (A, B, C). Applications using this function may not work properly in the current internet environment.
Returns: ETrue if the IPv4 address value is Class B; otherwise. EFalse
| TBool | IsClassC | ( | ) | const [inline] |
Tests if the IP address is Class C.
DeprecatedWorks only for IPv4. It assumes the old IPv4 address classes (A, B, C). Applications using this function may not work properly in the current internet environment.
Returns: ETrue if the IPv4 address value is Class C; otherwise, EFalse
| IMPORT_C TBool | IsLinkLocal | ( | ) | const |
Tests if IP address is link-local address
For IPv4 this returns true, if the address belongs to the link-local net (169.254.x.x).
For IPv6 this returns true, if the address is IPv6 link-local address (fe80:..).
Does not return true for multicast addresses which are in the link-local scope.
Returns: ETrue, if this address is a link-local address; EFalse, otherwise
| IMPORT_C TBool | IsLoopback | ( | ) | const |
Tests if the IP address is a loopback address.
For IPv4 addresses this returns true, if address belongs to the loopback net (127.x.x.x). IPv4 address can be in KAfInet or in IPv4-mapped/compatible formats.
For IPv6 address this returns true for IPv6 loopback address (= ::1).
Returns: ETrue, if the address is loopback; EFalse, otherwise
| IMPORT_C TBool | IsMulticast | ( | ) | const |
Tests if the IP address is a multicast address.
For IPv4 addresses this returns true, if address is Class D (multicast). IPv4 address can be in KAfInet or KAfInet6 (IPv4-mapped or IPv4-compatible) formats.
For IPv6 addresses this returns true, if address is IPv6 multicast address (start with 0xff byte).
Returns: ETrue if the IP address value is multicast; EFalse, otherwise
| IMPORT_C TBool | IsSiteLocal | ( | ) | const |
Tests if IP address is site-local address.
Always false for IPv4 addressess.
For IPv6 this returns true, if the address is IPv6 site-local address (fec0:...)
Does not return true for multicast addresses which are in the site-local scope.
Returns: ETrue, if this is a site-local address; EFalse, otherwise
| IMPORT_C TBool | IsUnicast | ( | ) | const |
Tests if address is unicast address.
This is just a "shorthand" notation for a test that none of the following is true
Caution: the test is based purely on the address, and it should be kept in mind that this test has no way of detecting IPv4 net broadcast addresses (because the netmask is not known).
Returns: ETrue if the address is unicast: EFalse, otherwise
| IMPORT_C TBool | IsUnspecified | ( | ) | const |
Tests if the IP address is unspecified.
Returns: ETrue if the IP address is unspecified; EFalse, otherwise
| IMPORT_C TBool | IsV4Compat | ( | ) | const |
Tests if this address is an IPv4-compatible address.
This is always false, if address is in KAfInet format.
Returns: ETrue, if this is a IPv4 compatible address; EFalse, otherwise.
| TBool | IsWildAddr | ( | ) | const [inline] |
Tests if the IP address is unspecified.
This is same as IsUnspecified()
Returns: ETrue if the IP address value is unspecified; otherwise, EFalse.
| TBool | IsWildPort | ( | ) | const [inline] |
Tests if the port is zero.
Returns: ETrue if the port is zero; otherwise, EFalse.
Tests the IP address value with that in another TInetAddr.
| Parameter | Description |
|---|---|
| aHost | TInetAddr with which to compare |
Returns: ETrue if IP address value is the same as this, EFalse, otherwise.
Tests if another TInetAddr is in the same subnet.
The function applies the subnet mask passed through aMask to the IP address and to the IP address in aNet. If the resulting values are the same, this indicates that the addresses are part of the same subnet, and ETrue is returned.
| Parameter | Description |
|---|---|
| aNet | TInetAddr with which to compare. |
| aMask | TInetAddr object with the IP address set to the relevant subnet mask. |
Returns: ETrue if both IP address values are the members of the same subnet; EFalse, otherwise.
Tests if the specified number of left-most bits on addresses are same.
Return ETrue if leftmost aPrefixLen bits on addresses are same (both families must be the same).
| Parameter | Description |
|---|---|
| aNet | TInetAddr with which to compare. |
| aPrefixLen | Number of left-most bits to compare. |
Returns: ETrue, if the bits match; EFalse, otherwise.
| IMPORT_C void | Net | ( | const TInetAddr & | aAddr | ) |
Obtains a network mask corresponding to the class of the IP address, using the NetMask() function, and then applies this mask to the current IP address (deprecated).
The resulting address family is KAfInet
DeprecatedWorks only for IPv4. Prefix() should be used instead.
| Parameter | Description |
|---|---|
| aAddr | TInetAddr from which to obtain IP address for creating the network mask. |
| IMPORT_C void | NetBroadcast | ( | const TInetAddr & | aAddr | ) |
Sets the IP address to be suitable for a network-directed broadcast address (deprecated).
The function obtains a network mask corresponding to the class of the IP address in aAddr, using the NetMask() function. It then applies this mask to the current IP address to separate the network number part of the address. The mask is then used again to set all host number bits to 1 (which signifies, broadcast to all hosts on the network).
The resulting address family is KAfInet
DeprecatedWorks only for IPv4. This function works only for IPv4. It assumes the old IPv4 address classes (A, B, C). Applications using this function may not work properly in the current internet environment.
| Parameter | Description |
|---|---|
| aAddr | TInetAddr from which to obtain IP address for creating the network mask. |
| IMPORT_C void | NetMask | ( | const TInetAddr & | aAddr | ) |
Sets the IP address to a mask suitable for extracting the network number part of the IP address (deprecated).
This function assumes the IPv4 address classes (A, B, C). Applications using this function may not work properly in the current internet environment.
The function tests whether the IP address in aAddr is a Class A, B, C, or other address. It then sets the IP address to suitable mask values as follows:
Class A addresses: mask 255.0.0.0
Class B addresses: mask 255.255.0.0
Class C addresses: mask 255.255.255.0
other addresses: mask 255.255.255.255
DeprecatedWorks only for IPv4. The length of the network prefix needs to be aqcuired by other means. When prefix length is known, PrefixMask() function can be used.
| Parameter | Description |
|---|---|
| aAddr | TInetAddr from which to obtain IP address |
| IMPORT_C void | Output | ( | TDes & | aBuf | ) | const |
Writes the IP address into a string.
For an IPv4 address, the format is d.d.d.d, where "d" is an 8-bit decimal number. (An example IPv4 address: 127.0.0.1).
For an IPv6 address, the format is h:h:h:h:h:h:h:h, where "h" is a 16-bit hexadecimal number. (An example IPv6 address: 2001:618:40C:20:2C0:4FFF:FE24:AA79).
If address family is not KAfInet or KAfInet6, then empty string is returned (aBuf.Length() == 0).
If the family is KAfInet6, the output buffer must be at least 39 characters. If less, the buffer is filled with '*' characters.
| aBuf | contains a string representation of the IP address. |
| IMPORT_C void | OutputWithScope | ( | TDes & | aBuf | ) | const |
Writes the IP address into a string and appends the scope id.
The IP address is formatted with as with the standard Output.
If the scope id has non-zero value and if there is room in the output buffer, the scope id is appended to the address using the "%scope-id"-notation.
| aBuf | contains a string representation of the address. |
Creates an IPv6 address with the specified number of left-most bits copied from another address, and remaining bits set to 0.
The function does not check the family of the aAddr, and for anything else but KAfInet6 the resulting prefix value is undefined.
The resulting address family is KAfInet6. The scope id and flow label are zeroed.
| Parameter | Description |
|---|---|
| aAddr | The address to copy the prefix from. |
| aPrefixLen | Number of left-most bits to set to copy from aAddr. |
| IMPORT_C void | PrefixMask | ( | TInt | aPrefixLen | ) |
Creates an IPv6 address with the specified number of left-most bits set to 1, and the rest set to 0.
The previous content does not matter, and is overwritten.
| Parameter | Description |
|---|---|
| aPrefixLen | Number of left-most bits to set to 1. |
| IMPORT_C TUint32 | Scope | ( | ) | const |
Gets the scope id value
Only for KAfInet6, return zero for KAfInet.
When an IPv4 address is stored in IPv4-mapped format (KAfInet6), then non-zero scopes are also possible for IPv4 (and needed for proper handling of overlapping private address ranges or for IPv4 link local addresses).
Returns: The scope id of the address.
| IMPORT_C void | SetScope | ( | TUint32 | aScope | ) |
Sets the scope id value
Only for KAfInet6, undefined (ignored) for KAfInet.
When an IPv4 address is stored in IPv4-mapped format (KAfInet6), then non-zero scopes are also possible for IPv4 (and needed for proper handling of overlapping private address ranges or for IPv4 link local addresses).
| Parameter | Description |
|---|---|
| aScope | The scope id of the address. |
| IMPORT_C void | SetV4CompatAddress | ( | TUint32 | aAddr | ) |
Creates an IPv4-compatible IPv6 address.
The IPv4-compatible format is x.x.x.x.
The resulting address family is KAfInet6. The scope id and flow label are zeroed.
| Parameter | Description |
|---|---|
| aAddr | IPv4 address from which the IPv6 address is generated. |
| IMPORT_C void | SetV4MappedAddress | ( | TUint32 | aAddr | ) |
Creates an IPv4-mapped IPv6 address.
The IPv4-mapped format is ffff:x.x.x.x. Internally, all IPv4 addresses are stored in this format.
The resulting address family is KAfInet6. The scope id and flow label are zeroed.
| Parameter | Description |
|---|---|
| aAddr | IPv4 address from which the IPv6 address is generated. |
Sets the IP address to the network number and subnet parts of the IP address (that is, the original IP address with the host number part cleared).
This is obtained by applying the mask value in aMask to the IP address in aAddr. The result is undefined if address and mask have different address family.
| Parameter | Description |
|---|---|
| aAddr | TInetAddr from which to obtain IP address |
| aMask | TInetAddr object with the IP address set to the relevant subnet mask. |
Sets the IP address to be suitable for a subnet-directed broadcast address.
To achieve this, the subnet mask value in aMask is applied to the IP address in aAddr. The mask is then used again to set all host number bits to 1 (which signifies, broadcast to all hosts on the subnet).
Only for IPv4. The function does not have a sensible interpretation in IPv6. An application that uses this needs to code separate branches for IPv4 and IPv6 cases.
DeprecatedWorks only for IPv4. IPv6 has all-nodes link local multicast address (ff02::1) for this purpose.
| Parameter | Description |
|---|---|
| aAddr | TInetAddr from which to obtain IP address |
| aMask | TInetAddr object with the IP address set to the relevant subnet mask. |