SetUnicastIpAddressEntry-Funktion (netioapi.h)
Die SetUnicastIpAddressEntry-Funktion legt die Eigenschaften eines vorhandenen Unicast-IP-Adresseintrags auf dem lokalen Computer fest.
Syntax
IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API SetUnicastIpAddressEntry(
[in] const MIB_UNICASTIPADDRESS_ROW *Row
);
Parameter
[in] Row
Ein Zeiger auf einen MIB_UNICASTIPADDRESS_ROW Struktureintrag für einen vorhandenen Unicast-IP-Adresseintrag.
Rückgabewert
Wenn die Funktion erfolgreich ist, wird der Rückgabewert NO_ERROR.
Wenn die Funktion fehlschlägt, ist der Rückgabewert einer der folgenden Fehlercodes.
| Rückgabecode | Beschreibung |
|---|---|
|
Zugriff verweigert.“ Dieser Fehler wird unter folgenden Bedingungen zurückgegeben: Dem Benutzer fehlen die erforderlichen Administratorrechte auf dem lokalen Computer, oder die Anwendung wird nicht in einer erweiterten Shell als integrierter Administrator (RunAs-Administrator) ausgeführt. |
|
Es wurde ein ungültiger Parameter an die Funktion übergeben. Dieser Fehler wird zurückgegeben, wenn ein NULL-Zeiger im Row-Parameter übergeben wird, das Address-Element des MIB_UNICASTIPADDRESS_ROW , auf das vom Row-Parameter verwiesen wird, nicht auf eine gültige Unicast-IPv4- oder IPv6-Adresse festgelegt wurde, oder die Elemente InterfaceLuid oder InterfaceIndex des MIB_UNICASTIPADDRESS_ROW vom Row-Parameter nicht angegeben wurden.
Dieser Fehler wird auch für andere Fehler in den Werten zurückgegeben, die für Member in der MIB_UNICASTIPADDRESS_ROW-Struktur festgelegt sind. Zu diesen Fehlern gehören folgendes: Wenn der ValidLifetime-Member kleiner als das PreferredLifetime-Element ist, wenn das PrefixOrigin-Element auf IpPrefixOriginUnchanged und das SuffixOrigin nicht auf IpSuffixOriginUnchanged festgelegt ist, wenn der PrefixOrigin-Member nicht auf IpPrefixOriginUnchanged festgelegt ist und das SuffixOrigin auf IpSuffixOriginUnchanged festgelegt ist, wenn das PrefixOrigin-Element nicht auf IpSuffixOriginUnchanged festgelegt ist, wenn das PrefixOrigin-Element nicht auf IpPrefixOriginUnchanged festgelegt ist. member is not set to a value from the NL_PREFIX_ORIGIN enumeration, if the SuffixOrigin member is not set to a value from the NL_SUFFIX_ORIGIN enumeration, or if the OnLinkPrefixLength member is set to a value than the IP address length, in bits (32 for an unicast IPv4 address or 128 for an unicast IPv6 address). |
|
Die angegebene Schnittstelle konnte nicht gefunden werden. Dieser Fehler wird zurückgegeben, wenn die Netzwerkschnittstelle, die vom InterfaceLuid - oder InterfaceIndex-Member des MIB_UNICASTIPADDRESS_ROW angegeben wurde, auf die der Row-Parameter verweist, nicht gefunden werden konnte. |
|
Die Anforderung wird nicht unterstützt. Dieser Fehler wird zurückgegeben, wenn sich auf dem lokalen Computer kein IPv4-Stapel befindet und eine IPv4-Adresse im Adresselement angegeben wurde, auf das der Row-Parameter verweist MIB_UNICASTIPADDRESS_ROW oder sich auf dem lokalen Computer kein IPv6-Stapel befindet und im Adresselement eine IPv6-Adresse angegeben wurde. |
|
Verwenden Sie FormatMessage , um die Nachrichtenzeichenfolge für den zurückgegebenen Fehler abzurufen. |
Hinweise
Die SetUnicastIpAddressEntry-Funktion ist unter Windows Vista und höher definiert.
Die GetUnicastIpAddressEntry-Funktion wird normalerweise verwendet, um einen vorhandenen MIB_UNICASTIPADDRESS_ROW zu ändernden Struktureintrag abzurufen. Eine Anwendung kann dann die Member im MIB_UNICASTIPADDRESS_ROW Eintrag ändern, den sie ändern möchte, und dann die SetUnicastIpAddressEntry-Funktion aufrufen.
Eine Anwendung kann die InitializeUnicastIpAddressEntry-Funktion aufrufen, um die Member eines MIB_UNICASTIPADDRESS_ROW Struktureintrags mit Standardwerten zu initialisieren, bevor Änderungen vorgenommen werden. Normalerweise speichert die Anwendung jedoch entweder den Member InterfaceLuid oder InterfaceIndex , bevor InitializeUnicastIpAddressEntry aufgerufen wird, und stellt eines dieser Member nach dem Aufruf wieder her.
Das Adresselement in der MIB_UNICASTIPADDRESS_ROW Struktur, auf die der Row-Parameter verweist, muss für eine gültige Unicast-IPv4- oder IPv6-Adresse und -Familie initialisiert werden. Darüber hinaus muss mindestens eines der folgenden Member in der MIB_UNICASTIPADDRESS_ROW Struktur initialisiert werden, die auf den Row-Parameter verweist: InterfaceLuid oder InterfaceIndex.
Die Felder werden in der oben aufgeführten Reihenfolge verwendet. Wenn also interfaceLuid angegeben wird, wird dieses Element verwendet, um die Schnittstelle zu bestimmen. Wenn kein Wert für das InterfaceLuid-Element festgelegt wurde (die Werte dieses Members wurden auf Null festgelegt), wird das InterfaceIndex-Element als nächstes verwendet, um die Schnittstelle zu bestimmen.
Wenn das OnLinkPrefixLength-Element des MIB_UNICASTIPADDRESS_ROW , auf das vom Row-Parameter verwiesen wird, auf 255 festgelegt ist, legt SetUnicastIpAddressEntry die Unicast-IP-Adresseigenschaften so fest, dass das OnLinkPrefixLength-Element der Länge der IP-Adresse entspricht. Für eine Unicast-IPv4-Adresse ist onLinkPrefixLength also auf 32 und OnLinkPrefixLength auf 128 für eine Unicast-IPv6-Adresse festgelegt. Wenn dies zu einer falschen Subnetzmaske für eine IPv4-Adresse oder dem falschen Linkpräfix für eine IPv6-Adresse führen würde, sollte die Anwendung diesen Member auf den richtigen Wert festlegen, bevor SetUnicastIpAddressEntry aufgerufen wird.
Die Elemente DadState, ScopeId und CreationTimeStamp der MIB_UNICASTIPADDRESS_ROW Struktur, auf die die Zeile verweist, werden ignoriert, wenn die SetUnicastIpAddressEntry-Funktion aufgerufen wird. Diese Elemente werden vom Netzwerkstapel festgelegt und können nicht mithilfe der Funktion SetUnicastIpAddressEntry geändert werden. Das ScopeId-Element wird automatisch von der Schnittstelle bestimmt, der die Adresse hinzugefügt wurde.
Die SetUnicastIpAddressEntry-Funktion kann nur von einem Benutzer aufgerufen werden, der als Mitglied der Gruppe Administratoren angemeldet ist. Wenn SetUnicastIpAddressEntry von einem Benutzer aufgerufen wird, der kein Mitglied der Gruppe Administratoren ist, schlägt der Funktionsaufruf fehl, und ERROR_ACCESS_DENIED wird zurückgegeben.
Die SetUnicastIpAddressEntry-Funktion kann auch aufgrund der Benutzerkontensteuerung (User Account Control, UAC) unter Windows Vista und höher fehlschlagen. Wenn eine Anwendung, die diese Funktion enthält, von einem Benutzer ausgeführt wird, der nicht als mitglied der Gruppe Administratoren als der integrierte Administrator angemeldet ist, schlägt dieser Aufruf fehl, es sei denn, die Anwendung wurde in der Manifestdatei mit einem requestedExecutionLevel-Wert gekennzeichnet, der auf requireAdministrator festgelegt ist. Wenn der Anwendung diese Manifestdatei fehlt, muss ein Benutzer, der sich als anderes Mitglied der Administratorgruppe als der integrierte Administrator angemeldet hat, die Anwendung dann in einer erweiterten Shell als integrierter Administrator (RunAs-Administrator) ausführen, damit diese Funktion erfolgreich ist.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows Vista [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2008 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | netioapi.h (include Iphlpapi.h) |
| Bibliothek | Iphlpapi.lib |
| DLL | Iphlpapi.dll |