SetUnicastIpAddressEntry function (netioapi.h)

The SetUnicastIpAddressEntry function sets the properties of an existing unicast IP address entry on the local computer.

Syntax

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API SetUnicastIpAddressEntry(
  [in] const MIB_UNICASTIPADDRESS_ROW *Row
);

Parameters

[in] Row

A pointer to a MIB_UNICASTIPADDRESS_ROW structure entry for an existing unicast IP address entry.

Return value

If the function succeeds, the return value is NO_ERROR.

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

Remarks

The SetUnicastIpAddressEntry function is defined on Windows Vista and later.

The GetUnicastIpAddressEntry function is normally used to retrieve an existing MIB_UNICASTIPADDRESS_ROW structure entry to be modified. An application can then change the members in the MIB_UNICASTIPADDRESS_ROW entry it wishes to modify, and then call the SetUnicastIpAddressEntry function.

An application may call the InitializeUnicastIpAddressEntry function to initialize the members of a MIB_UNICASTIPADDRESS_ROW structure entry with default values before making changes. However, the application would normally save either the InterfaceLuid or InterfaceIndex member before calling InitializeUnicastIpAddressEntry and restore one of these members after the call.

The Address member in the MIB_UNICASTIPADDRESS_ROW structure pointed to by the Row parameter must be initialized to a valid unicast IPv4 or IPv6 address and family. In addition, at least one of the following members in the MIB_UNICASTIPADDRESS_ROW structure pointed to the Row parameter must be initialized: the InterfaceLuid or InterfaceIndex.

The fields are used in the order listed above. So if the InterfaceLuid is specified, then this member is used to determine the interface. If no value was set for the InterfaceLuid member (the values of this member was set to zero), then the InterfaceIndex member is next used to determine the interface.

If the OnLinkPrefixLength member of the MIB_UNICASTIPADDRESS_ROW pointed to by the Row parameter is set to 255, then SetUnicastIpAddressEntry will set the unicast IP address properties so that the OnLinkPrefixLength member is equal to the length of the IP address. So for a unicast IPv4 address, the OnLinkPrefixLength is set to 32 and the OnLinkPrefixLength is set to 128 for a unicast IPv6 address. If this would result in the incorrect subnet mask for an IPv4 address or the incorrect link prefix for an IPv6 address, then the application should set this member to the correct value before calling SetUnicastIpAddressEntry.

The DadState, ScopeId, and CreationTimeStamp members of the MIB_UNICASTIPADDRESS_ROW structure pointed to by the Row are ignored when the SetUnicastIpAddressEntry function is called. These members are set by the network stack and cannot be changed using the SetUnicastIpAddressEntry function. The ScopeId member is automatically determined by the interface on which the address was added.

The SetUnicastIpAddressEntry function can only be called by a user logged on as a member of the Administrators group. If SetUnicastIpAddressEntry is called by a user that is not a member of the Administrators group, the function call will fail and ERROR_ACCESS_DENIED is returned.

The SetUnicastIpAddressEntry function can also fail because of user account control (UAC) on Windows Vista and later. If an application that contains this function is executed by a user logged on as a member of the Administrators group other than the built-in Administrator, this call will fail unless the application has been marked in the manifest file with a requestedExecutionLevel set to requireAdministrator. If the application lacks this manifest file, a user logged on as a member of the Administrators group other than the built-in Administrator must then be executing the application in an enhanced shell as the built-in Administrator (RunAs administrator) for this function to succeed.

Requirements

See also

CreateUnicastIpAddressEntry

DeleteUnicastIpAddressEntry

GetUnicastIpAddressEntry

GetUnicastIpAddressTable

IP Helper Function Reference

InitializeUnicastIpAddressEntry

MIB_UNICASTIPADDRESS_ROW

MIB_UNICASTIPADDRESS_TABLE

NotifyUnicastIpAddressChange