GetAdaptersAddresses

GetAdaptersAddresses retrieves the addresses associated with the adapters on the local computer. When called within a RTSS application, only RTSS-controlled adapters on the local computer are returned.

Syntax

UNLONG GetAdaptersAddresses(
    ULONG Family,
    ULONG Flags,
    PVOID Reserved,
    PIP_ADAPTER_ADDRESSES AdapterAddresses,
    PULONG SizePointer

);

Parameters

Family

The address family of the addresses to retrieve. This parameter must be one of the following values.

Value	Meaning
AF_UNSPEC 0	Return both IPv4 and IPv6 addresses.
AF_INET 2	Return only IPv4 addresses.
AF_INET6 23	Return only IPv6 addresses associated.

Flags

The type of addresses to retrieve.

This parameter is a combination of the following supported values:

Value	Meaning
GAA_FLAG_SKIP_UNICAST 0x0001	Do not return unicast addresses.
GAA_FLAG_SKIP_FRIENDLY_NAME 0x0020	Do not return the adapter friendly name.
GAA_FLAG_INCLUDE_GATEWAYS 0x0080	Return the addresses of default gateways.
GAA_FLAG_INCLUDE_ALL_INTERFACES 0x0100	Return information about all configured and enabled RTX64 Network Interfaces, regardless of whether they have an IP address configured.

Reserved

This parameter is not currently used, but is reserved for future system use. The calling application should pass NULL for this parameter.

AdapterAddresses

A pointer to a buffer that contains a linked list of IP_ADAPTER_ADDRESSES structures on successful return.

SizePointer

A pointer to a variable that specifies the size of the buffer pointed to by AdapterAddresses, in bytes. If the function succeeds, the variable pointed to by this parameter is updated to contain the number of bytes in the buffer pointed to by AdapterAddresses. If the function fails with error ERROR_BUFFER_OVERFLOW, the variable pointed to by this parameter is updated to contain the required size of the buffer, in bytes.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is one of the following error codes.

Return Code	Description
ERROR_ADDRESS_NOT_ASSOCIATED	An address has not yet been associated with the network endpoint.
ERROR_BUFFER_OVERFLOW	The buffer size indicated by the SizePointer parameter is too small to hold the adapter information or the AdapterAddresses parameter is NULL. The SizePointer parameter returned points to the required size of the buffer to hold the adapter information.
ERROR_INVALID_PARAMETER	One of the parameters is invalid. This error is returned for any of the following conditions: the SizePointer parameter is NULL, the Address parameter is not AF_INET, AF_INET6, or AF_UNSPEC, or the address information for the parameters requested is greater than ULONG_MAX
ERROR_NOT_ENOUGH_MEMORY	Insufficient memory resources are available to complete the operation.
ERROR_NO_DATA	No addresses were found for the requested parameters or the TCP/IP stack was not running when the function was called.

To get extended error information, call GetLastError.

Remarks

Addresses are returned as a linked list of IP_ADAPTER_ADDRESSES structures in the buffer pointed to by the AdapterAddresses parameter. The application that calls the GetAdaptersAddresses function must allocate the amount of memory needed to return the IP_ADAPTER_ADDRESSES structures pointed to by the AdapterAddresses parameter. When these returned structures are no longer required, the application should free the memory allocated.

One method that can be used to determine the memory needed to return the IP_ADAPTER_ADDRESSES structures pointed to by the AdapterAddresses parameter is to pass too small a buffer size as indicated in the SizePointer parameter in the first call to the GetAdaptersAddresses function, so the function will fail with ERROR_BUFFER_OVERFLOW. SizePointer returns the required size of the buffer, if the return code is ERROR_BUFFER_OVERFLOW or the return code is 0. Note that it is possible for the buffer size required for the IP_ADAPTER_ADDRESSES structures pointed to by the AdapterAddresses parameter to change between subsequent calls to the GetAdaptersAddresses function if an adapter address is added or removed. However, this method of using the GetAdaptersAddresses function is strongly discouraged. This method requires calling the GetAdaptersAddresses function multiple times.

The recommended method of calling the GetAdaptersAddresses function is to pre-allocate a 15KB working buffer pointed to by the AdapterAddresses parameter. On typical computers, this dramatically reduces the chances that the GetAdaptersAddresses function returns ERROR_BUFFER_OVERFLOW, which would require calling GetAdaptersAddresses function multiple times. The example code illustrates this method of use.

When GAA_FLAG_INCLUDE_ALL_INTERFACES is not set, the adapters that don’t have IP addresses of the requested address family are not returned in the IP_ADAPTER_ADDRESSES list. When the flag is set, the adapter is included, but only IP addresses for the requested address family are included.

Requirements

Minimum Supported Version	RTX64 2014 with Service Pack 2
Header	ws2tcpip.h, iphlpapi.h
Library	Rtx_RtTcpip.lib