次の方法で共有


GetAdaptersAddresses (Compact 2013)

3/26/2014

This function retrieves the addresses associated with the adapters on the local device.

Syntax

ULONG WINAPI GetAdaptersAddresses(
  __in     ULONG Family,
  __in     ULONG Flags,
  __in     PVOID Reserved,
  __inout  PIP_ADAPTER_ADDRESSES AdapterAddresses,
  __inout  PULONG SizePointer
);

Parameters

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

    Value

    Meaning

    AF_INET

    Return only IPv4 addresses associated with adapters with IPv4 enabled.

    AF_INET6

    Return only IPv6 addresses associated with adapters with IPv6 enabled.

    AF_UNSPEC

    Return both IPv4 and IPv6 addresses associated with adapters with IPv4 or IPv6 enabled.

  • Flags
    The type of addresses to retrieve. The possible values are defined in the Iptypes.h header file. Notice that the Iptypes.h header file is automatically included in Iphlpapi.h, and should never be used directly.

    This parameter is a combination of the following values. If this parameter is zero, unicast, anycast, and multicast IP addresses will be returned.

    Value

    Meaning

    GAA_FLAG_INCLUDE_ALL_COMPARTMENTS

    Return addresses in all routing compartments. This flag is currently not supported and reserved for future use.

    GAA_FLAG_INCLUDE_ALL_INTERFACES

    Return addresses for all NDIS interfaces.

    GAA_FLAG_INCLUDE_GATEWAYS

    Return the addresses of default gateways.

    GAA_FLAG_INCLUDE_PREFIX

    Return a list of IP address prefixes on this adapter.

    GAA_FLAG_INCLUDE_TUNNEL_BINDINGORDER

    Return the adapter addresses sorted in tunnel binding order.

    GAA_FLAG_INCLUDE_WINS_INFO

    Return addresses of WINS servers.

    GAA_FLAG_SKIP_ANYCAST

    Do not return IPv6 anycast addresses.

    GAA_FLAG_SKIP_DNS_SERVER

    Do not return addresses of DNS servers.

    GAA_FLAG_SKIP_FRIENDLY_NAME

    Do not return the adapter friendly name.

    GAA_FLAG_SKIP_MULTICAST

    Do not return multicast addresses.

    GAA_FLAG_SKIP_UNICAST

    Do not return unicast addresses.

  • Reserved
    Reserved; set to NULL.
  • 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.

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

DHCP lease information was available.

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

Other

Use FormatMessage to obtain the message string for the returned error.

Remarks

The GetAdaptersAddresses function can retrieve information for IPv4 and IPv6 addresses.

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 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. This can be done by calling the HeapAlloc function to allocate memory and later calling the HeapFree function to free the allocated memory, as shown in the example code. Other memory allocation and free functions can be used as long as the same family of functions are used for both the allocation and the free function.

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. When the return value is ERROR_BUFFER_OVERFLOW, the SizePointer parameter returned points to the required size of the buffer to holder the adapter information. Notice that it is possible for the buffer size required for the IP_ADAPTER_ADDRESSES structures pointed to by the AdapterAddresses parameter to change between later calls to the GetAdaptersAddresses function if an adapter address is added or removed.

The order in which adapters appear in the list returned by this function can be controlled from the Network Connections folder: select the Advanced Settings menu item from the Advanced menu.

If the GAA_FLAG_INCLUDE_ALL_INTERFACES is set, all NDIS adapters will be retrieved even those addresses associated with adapters not bound to an address family specified in the Family parameter. When this flag is not set, only the addresses that are bound to an adapter enabled for the address family specified in the Family parameter are returned.

The SOCKET_ADDRESS structure is used in the IP_ADAPTER_ADDRESSES structure pointed to by the AdapterAddresses parameter. On the Windows Software Development Kit (SDK), the organization of header files has changed and the SOCKET_ADDRESS structure is defined in the Ws2def.h header file which is automatically included by the Winsock2.h header file.

Requirements

Header

iphlpapi.h,
winsock2.h

Library

Iphlpapi.lib

See Also

Reference

IP Helper Functions
IP_ADAPTER_ADDRESSES
SOCKET_ADDRESS
IP_ADAPTER_ADDRESSES

Other Resources

HeapAlloc
HeapFree
IP Helper