AddIPAddress (Compact 2013)

  • Article

3/26/2014

This function adds the specified IP address to the specified adapter.

Syntax

DWORD AddIPAddress(
  IPAddr Address,
  IPMask IpMask,
  DWORD IfIndex,
  PULONG NTEContext,
  PULONG NTEInstance 
);

Parameters

  • Address
    [in] The IP address to add to the adapter.
  • IpMask
    [in] The subnet mask for the IP address.
  • IfIndex
    [in] The adapter to which to add the address.
  • NTEContext
    [out] Pointer to the Net Table Entry (NTE) context for this IP address. The caller can later use this context in a call to DeleteIPAddress.
  • NTEInstance
    [out] Pointer to the NTE instance for this IP address.

Return Value

Return code

Description

NO_ERROR

The function succeeds.

ERROR_DEV_NOT_EXIST

The adapter specified by the IfIndex parameter does not exist.

ERROR_DUP_DOMAINNAME

The IPv4 address to add that is specified in the Address parameter already exists.

ERROR_GEN_FAILURE

A general failure. This error is returned for some values specified in the Address parameter, such as an IPv4 address usually considered a broadcast addresses.

ERROR_INVALID_HANDLE

The user trying to make the function call is not an administrator.

ERROR_INVALID_PARAMETER

One or more of the parameters is invalid. This error is returned if the NTEContext or NTEInstance parameters are NULL. This error is also returned when the IP address specified in the Address parameter is inconsistent with the interface index specified in the IfIndex parameter (for example, a loopback address on a non-loopback interface).

ERROR_NOT_SUPPORTED

The function call is not supported on the version of Windows on which it was run.

Other

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

Remarks

The AddIPAddress function is used to add a new IPv4 address entry on a local device. The IPv4 address added by the AddIPAddress function is not persistent. The IPv4 address exists only as long as the adapter object exists. The IPv4 address can be destroyed by the following actions:

  • Restarting the device
  • Manually resetting the network adapter
  • Certain PnP events

To create an IPv4 address that persists, the EnableStatic method of the Win32_NetworkAdapterConfiguration Class in the Windows Management Instrumentation (WMI) controls can be used. The netsh commands can also be used to create a persistent IPv4 address. For more information, see the documentation on Netsh.exe in the Windows Sockets documentation.

An IPv4 address that is added by using the AddIPAddress function can later be deleted by calling the DeleteIPAddress function passing the NTEContext parameter returned by the AddIPAddress function.

For information about the IPAddr and IPMask data types, see Window Data Types. To convert an IPv4 address between dotted decimal notation and IPAddr format, use the inet_addr and inet_ntoa functions.

Requirements

Header

iphlpapi.h

Library

Iphlpapi.lib

See Also

Reference

IP Helper Functions
CreateUnicastIpAddressEntry
GetIpAddrTable
IPAddr
DeleteIPAddress
GetAdapterIndex

Other Resources

IP Helper