Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]



Location: in_sock.h
Link against: insock.lib

Class TInetAddr

class TInetAddr : public TSockAddr;

Description

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:

The flow label and scope id fields exist only in KAfInet6 format. However, the access functions TInetAddr::FlowLabel and TInetAddr::Scope will also work for other address formats by always returning 0.

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.

Derivation

Members

Defined in TInetAddr:
Addr4Ptr(), AddrLen(), AddrPtr(), Address(), Cast(), Cast(), CmpAddr(), ConvertToV4(), ConvertToV4Compat(), ConvertToV4Mapped(), FlowLabel(), Init(), Input(), Ip6Address(), IsBroadcast(), IsClassA(), IsClassB(), IsClassC(), IsLinkLocal(), IsLoopback(), IsMulticast(), IsSiteLocal(), IsUnicast(), IsUnspecified(), IsV4Compat(), IsV4Mapped(), IsWildAddr(), IsWildPort(), Match(), Match(), Match(), Net(), NetBroadcast(), NetMask(), Output(), OutputWithScope(), Prefix(), PrefixMask(), Scope(), SetAddress(), SetAddress(), SetFlowLabel(), SetScope(), SetV4CompatAddress(), SetV4MappedAddress(), SubNet(), SubNetBroadcast(), TInetAddr(), TInetAddr(), TInetAddr(), TInetAddr(), TInetAddr()

Inherited from TSockAddr:
CmpPort(), Family(), GetUserLen(), Port(), SetFamily(), SetPort(), SetUserLen(), UserPtr()


Construction and destruction


TInetAddr()

IMPORT_C TInetAddr();

Description

Constructs a basic TInetAddr object.

The port is initialised to 0, and the IP address is unspecified. The resulting address family is KAFUnspec.


TInetAddr()

IMPORT_C TInetAddr(const TSockAddr &aAddr);

Description

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.

Parameters

const TSockAddr &aAddr

TSockAddr to be used as initial content.


TInetAddr()

IMPORT_C TInetAddr(TUint aPort);

Description

Constructs a TInetAddr and initialises the port to the specified value, and the IP address is unspecified.

The resulting address family is KAFUnspec.

Parameters

TUint aPort

Value to which to set the port.


TInetAddr()

IMPORT_C TInetAddr(const TIp6Addr &aAddr, TUint aPort);

Description

Constructs a TInetAddr and initialises the port to the specified value, and the IPv6 address to aAddr.

The resulting address family is KAfInet6.

Parameters

const TIp6Addr &aAddr

Value to which to set the IPv6 address.

TUint aPort

Value to which to set the port.


TInetAddr()

IMPORT_C TInetAddr(TUint32 aAddr, TUint aPort);

Description

Constructs a TInetAddr and initialise the specified port value to aPort and the IP address to aAddr.

The resulting address family is KAfInet

Parameters

TUint32 aAddr

Value to which to set the IP address.

TUint aPort

Value to which to set the port.

[Top]


Member functions


SetAddress()

IMPORT_C void SetAddress(TUint32 aAddr);

Description

Sets the IPv4 address value.

Note: An IP address in dotted-decimal form can be converted into a TUint32 by the INET_ADDR macro.

The resulting address family is KAfInet.

Parameters

TUint32 aAddr

Value to which to set the IPv4 address.


SetAddress()

IMPORT_C void SetAddress(const TIp6Addr &aAddr);

Description

Sets the IPv6 address value.

The resulting address family is KAfInet6. The scope id and flow label are zeroed.

Parameters

const TIp6Addr &aAddr

Value to which to set the IPv6 address.


SetV4CompatAddress()

IMPORT_C void SetV4CompatAddress(TUint32 aAddr);

Description

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.

Parameters

TUint32 aAddr

IPv4 address from which the IPv6 address is generated.


SetV4MappedAddress()

IMPORT_C void SetV4MappedAddress(TUint32 aAddr);

Description

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.

Parameters

TUint32 aAddr

IPv4 address from which the IPv6 address is generated.


SetFlowLabel()

IMPORT_C void SetFlowLabel(TInt aLabel);

Description

Sets the Flow Label.

Only for KAfInet6, undefined (ignored) for KAfInet.

Parameters

TInt aLabel

The flow label (only low 20 bits used)


FlowLabel()

IMPORT_C TInt FlowLabel() const;

Description

Gets the Flow Label.

Only for KAfInet6, return zero for KAfInet.

Return value

TInt

The flow label


Ip6Address()

IMPORT_C const TIp6Addr &Ip6Address() const;

Description

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).

Return value

const TIp6Addr &

The IPv6 address


ConvertToV4Compat()

IMPORT_C void ConvertToV4Compat();

Description

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.


ConvertToV4Mapped()

IMPORT_C void ConvertToV4Mapped();

Description

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.

The resulting address family is KAfInet6. The scope id and flow label are zeroed.


ConvertToV4()

IMPORT_C void ConvertToV4();

Description

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 .

The address family is set to KAfInet.


CmpAddr()

IMPORT_C TBool CmpAddr(const TInetAddr &aAddr) const;

Description

Compares IP address and port values with those in another TInetAddr.

Parameters

const TInetAddr &aAddr

TInetAddr with which to compare

Return value

TBool

ETrue if IP address and port values are the same; EFalse, otherwise.


Match()

IMPORT_C TBool Match(const TInetAddr &aHost) const;

Description

Tests the IP address value with that in another TInetAddr.

Note: The function matches IPv4 addresses even if they are stored in different formats (KAfInet or KAfInet6 using IPv4-mapped format) (since Symbian OS 7.0s).

Parameters

const TInetAddr &aHost

TInetAddr with which to compare

Return value

TBool

ETrue if IP address value is the same as this, EFalse, otherwise.


Match()

IMPORT_C TBool Match(const TInetAddr &aNet, const TInetAddr &aMask) const;

Description

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.

Note: The function matches IPv4 addresses even if they are stored in different formats (KAfInet or KAfInet6 using IPv4-mapped format). (since Symbian OS 7.0s).

Parameters

const TInetAddr &aNet

TInetAddr with which to compare.

const TInetAddr &aMask

TInetAddr object with the IP address set to the relevant subnet mask.

Return value

TBool

ETrue if both IP address values are the members of the same subnet; EFalse, otherwise.


Match()

IMPORT_C TBool Match(const TInetAddr &aNet, TInt aPrefixLen) const;

Description

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).

Parameters

const TInetAddr &aNet

TInetAddr with which to compare.

TInt aPrefixLen

Number of left-most bits to compare.

Return value

TBool

ETrue, if the bits match; EFalse, otherwise.


PrefixMask()

IMPORT_C void PrefixMask(TInt aPrefixLen);

Description

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.

Parameters

TInt aPrefixLen

Number of left-most bits to set to 1.


Prefix()

IMPORT_C void Prefix(const TInetAddr &aAddr, TInt aPrefixLen);

Description

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.

Parameters

const TInetAddr &aAddr

The address to copy the prefix from.

TInt aPrefixLen

Number of left-most bits to set to copy from aAddr.


Output()

IMPORT_C void Output(TDes &aBuf) const;

Description

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.

Parameters

TDes &aBuf


Input()

IMPORT_C TInt Input(const TDesC &aBuf);

Description

Sets the IP address from a string containing a representation of an IP address, such as might be entered in a dialog.

The string must contain an ASCII representation of the address. The format may be one of the following examples:

Use at most one ':: ' to denote consecutive zeroes (eg. 2001:618:400:6a::abc ), IPv4-compatible address (eg. ::192.168.40.4 ), and IPv4-mapped address (eg. ::ffff:192.168.40.4 )

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.

Parameters

const TDesC &aBuf

Descriptor containing a string representation of an IP address

Return value

TInt

KErrNone, if address syntax was correct and input succeeded; otherwise, one of the system-wide error codes.


Cast()

static inline TInetAddr &Cast(const TSockAddr &aAddr);

Description

Casts a TSockAddr to a TInetAddr reference.

The cast is only safe if the object being referenced is actually aTInetAddr.

Parameters

const TSockAddr &aAddr

TSockAddr to cast

Return value

TInetAddr &

Casted reference to a TInetAddr.


Cast()

static inline TInetAddr &Cast(const TSockAddr *aAddr);

Description

Casts a TSockAddr to a TInetAddr reference.

The cast is only safe if the object being referenced is actually aTInetAddr.

Parameters

const TSockAddr *aAddr

TSockAddr to cast

Return value

TInetAddr &

Casted pointer to a TInetAddr.


IsUnicast()

IMPORT_C TBool IsUnicast() const;

Description

Tests if address is unicast address.

This is just a "shorthand" notation for a test that none of the following is true

For exact semantics of IsUnicast, see the descriptions of the above functions.

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).

Return value

TBool

ETrue if the address is unicast: EFalse, otherwise


IsMulticast()

IMPORT_C TBool IsMulticast() const;

Description

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).

Return value

TBool

ETrue if the IP address value is multicast; EFalse, otherwise


IsLoopback()

IMPORT_C TBool IsLoopback() const;

Description

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 ).

Return value

TBool

ETrue, if the address is loopback; EFalse, otherwise


IsUnspecified()

IMPORT_C TBool IsUnspecified() const;

Description

Tests if the IP address is unspecified.

The address is unspecified if the

Return value

TBool

ETrue if the IP address is unspecified; EFalse, otherwise


IsLinkLocal()

IMPORT_C TBool IsLinkLocal() const;

Description

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:.. ).

Note: Does not return true for multicast addresses which are in the link-local scope.

Return value

TBool

ETrue, if this address is a link-local address; EFalse, otherwise


IsSiteLocal()

IMPORT_C TBool IsSiteLocal() const;

Description

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:... )

Note: Does not return true for multicast addresses which are in the site-local scope.

Return value

TBool

ETrue, if this is a site-local address; EFalse, otherwise


IsV4Compat()

IMPORT_C TBool IsV4Compat() const;

Description

Tests if this address is an IPv4-compatible address.

This is always false, if address is in KAfInet format.

Return value

TBool

ETrue, if this is a IPv4 compatible address; EFalse, otherwise.


IsV4Mapped()

IMPORT_C TBool IsV4Mapped() const;

Description

Tests if this address is an IPv4-mapped address.

This is always false, if address is in KAfInet format.

Return value

TBool

ETrue, if this address is an IPv4-mapped address; EFalse, otherwise.


Address()

IMPORT_C TUint32 Address() const;

Description

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).

Return value

TUint32

The IP address value.


NetMask()

IMPORT_C void NetMask(const TInetAddr &aAddr);

Description

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:

The resulting address family is KAfInet.

Parameters

const TInetAddr &aAddr

TInetAddr from which to obtain IP address


Net()

IMPORT_C void Net(const TInetAddr &aAddr);

Description

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

Parameters

const TInetAddr &aAddr

TInetAddr from which to obtain IP address for creating the network mask.


NetBroadcast()

IMPORT_C void NetBroadcast(const TInetAddr &aAddr);

Description

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

Parameters

const TInetAddr &aAddr

TInetAddr from which to obtain IP address for creating the network mask.


SubNet()

IMPORT_C void SubNet(const TInetAddr &aAddr, const TInetAddr &aMask);

Description

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.

Parameters

const TInetAddr &aAddr

TInetAddr from which to obtain IP address

const TInetAddr &aMask

TInetAddr object with the IP address set to the relevant subnet mask.


SubNetBroadcast()

IMPORT_C void SubNetBroadcast(const TInetAddr &aAddr, const TInetAddr &aMask);

Description

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.

Parameters

const TInetAddr &aAddr

TInetAddr from which to obtain IP address

const TInetAddr &aMask

TInetAddr object with the IP address set to the relevant subnet mask.


IsClassA()

inline TBool IsClassA() const;

Description

Tests if the IP address is Class A.

Return value

TBool

ETrue if the IPv4 address value is Class A; otherwise, EFalse


IsClassB()

inline TBool IsClassB() const;

Description

Tests if the IP address is Class B.

Return value

TBool

ETrue if the IPv4 address value is Class B; otherwise. EFalse


IsClassC()

inline TBool IsClassC() const;

Description

Tests if the IP address is Class C.

Return value

TBool

ETrue if the IPv4 address value is Class C; otherwise, EFalse


IsBroadcast()

inline TBool IsBroadcast() const;

Description

Tests if the IP address is a limited broadcast address (255.255.255.255).

Return value

TBool

ETrue if the IPv4 address value is a limited broadcast address; otherwise, EFalse


IsWildAddr()

inline TBool IsWildAddr() const;

Description

Tests if the IP address is unspecified.

This is same as IsUnspecified()

Return value

TBool

ETrue if the IP address value is unspecified; otherwise, EFalse.


IsWildPort()

inline TBool IsWildPort() const;

Description

Tests if the port is zero.

Return value

TBool

ETrue if the port is zero; otherwise, EFalse.


SetScope()

IMPORT_C void SetScope(TUint32 aScope);

Description

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).

Parameters

TUint32 aScope

The scope id of the address.


Scope()

IMPORT_C TUint32 Scope() const;

Description

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).

Return value

TUint32

The scope id of the address.


Init()

IMPORT_C void Init(TUint aFamily);

Description

Initialises the object properly according to the address family passed in.

Post-Condition

In all above cases, IsUnspecified() returns ETrue after this function.

Parameters

TUint aFamily

The address family. Valid values are


OutputWithScope()

IMPORT_C void OutputWithScope(TDes &aBuf) const;

Description

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.

Parameters

TDes &aBuf


Addr4Ptr()

protected: inline SInetAddr *Addr4Ptr() const;

Description

Returns a pointer to KAfInet content format

Return value

SInetAddr *


AddrPtr()

protected: inline SInet6Addr *AddrPtr() const;

Description

Returns a pointer to KAfInet6 content format.

Return value

SInet6Addr *


AddrLen()

protected: static inline TInt AddrLen();

Description

Returns the size of the KAfInet6 content format.

Return value

TInt