Funzione DeleteIpForwardEntry (iphlpapi.h)
La funzione DeleteIpForwardEntry elimina una route esistente nella tabella di routing IPv4 del computer locale.
Sintassi
IPHLPAPI_DLL_LINKAGE DWORD DeleteIpForwardEntry(
[in] PMIB_IPFORWARDROW pRoute
);
Parametri
[in] pRoute
Puntatore a una struttura MIB_IPFORWARDROW . Questa struttura specifica informazioni che identificano la route da eliminare. Il chiamante deve specificare i valori per i membri dwForwardIfIndex, dwForwardDest, dwForwardMask, dwForwardNextHop e dwForwardProto della struttura.
Valore restituito
La funzione restituisce NO_ERROR (zero) se la routine ha esito positivo.
Se la funzione ha esito negativo, il valore restituito è uno dei codici di errore seguenti.
| Codice di errore | Significato |
|---|---|
|
Accesso negato. Questo errore viene restituito in Windows Vista e Windows Server 2008 in diverse condizioni che includono quanto segue: l'utente non dispone dei privilegi amministrativi necessari nel computer locale o l'applicazione non è in esecuzione in una shell avanzata come amministratore predefinito (amministratore RunAs). |
|
Un parametro di input non è valido, non è stata eseguita alcuna azione. Questo errore viene restituito se il parametro pRoute è NULL, il membro dwForwardMask della struttura PMIB_IPFORWARDROW non è una subnet mask IPv4 valida, il membro dwForwardIfIndex è NULL o uno degli altri membri della struttura MIB_IPFORWARDROW non è valido. |
|
Il parametro pRoute punta a una voce di route che non esiste. |
|
Il trasporto IPv4 non è configurato nel computer locale. |
|
La funzione può restituire altri codici di errore. |
Se la funzione ha esito negativo, usare FormatMessage per ottenere la stringa di messaggio per l'errore restituito.
Commenti
Il membro dwForwardProto del puntatore della struttura MIB_IPFORWARDROW su per il parametro di route deve essere impostato su MIB_IPPROTO_NETMGMT altrimenti DeleteIpForwardEntry avrà esito negativo. Gli identificatori del protocollo di routing vengono usati per identificare le informazioni di route per il protocollo di routing specificato. Ad esempio, MIB_IPPROTO_NETMGMT viene usato per identificare le informazioni di route per il routing IP impostato tramite la gestione di rete, ad esempio il protocollo DHCP (Dynamic Host Configuration Protocol), il Simple Network Management Protocol (SNMP) o le chiamate alle funzioni CreateIpForwardEntry, DeleteIpForwardEntry o SetIpForwardEntry.
In Windows Vista e Windows Server 2008, DeleteIpForwardEntry funziona solo su interfacce con una singola interfaccia secondaria (dove l'interfaccia LUID e il sottointerfaceNTE LUID sono gli stessi). Il membro dwForwardIfIndex della struttura MIB_IPFORWARDROW specifica l'interfaccia.
Un numero di membri della struttura MIB_IPFORWARDROW a cui punta il parametro di route non è attualmente usato da CreateIpForwardEntry. Questi membri includono dwForwardPolicy, dwForwardType, dwForwardAge, dwForwardNextHopAS, dwForwardMetric1, dwForwardMetric2, dwForwardMetric3, dwForwardMetric4 e dwForwardMetric5.
Per modificare una route esistente nella tabella di routing IPv4, usare la funzione SetIpForwardEntry . Per recuperare la tabella di routing IPv4, chiamare la funzione GetIpForwardTable .
In Windows Vista e versioni successive, la funzione DeleteIpForwardEntry può essere chiamata solo da un utente connesso come membro del gruppo Administrators. Se DeleteIpForwardEntry viene chiamato da un utente che non è membro del gruppo Administrators, la chiamata alla funzione avrà esito negativo e ERROR_ACCESS_DENIED viene restituita.
La funzione DeleteIpForwardEntry può anche non riuscire a causa del controllo dell'account utente in Windows Vista e versioni successive. Se un'applicazione contenente questa funzione viene eseguita da un utente connesso come membro del gruppo Administrators diverso dall'amministratore predefinito, questa chiamata avrà esito negativo a meno che l'applicazione non sia stata contrassegnata nel file manifesto con un set requestedExecutionLevel per richiedereAdministrator. Se l'applicazione manca di questo file manifesto, un utente ha eseguito l'accesso come membro del gruppo Administrators diverso dall'amministratore predefinito, deve quindi eseguire l'applicazione in una shell avanzata come amministratore predefinito (amministratore RunAs) per la riuscita di questa funzione.
Esempio
Nell'esempio di codice seguente viene illustrato come modificare il gateway predefinito in NewGateway. Chiamando GetIpForwardTable, modificando il gateway e chiamando SetIpForwardEntry non cambierà la route, ma aggiungerà una nuova. Se esistono più gateway predefiniti, questo codice li eliminerà. Tenere presente che il nuovo gateway deve essere valido; in caso contrario, TCP/IP ignora la modifica.
#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
#endif
#include <windows.h>
#include <winsock2.h>
#include <iphlpapi.h>
#include <stdio.h>
#include <stdlib.h>
#pragma comment(lib, "iphlpapi.lib")
int main()
{
// Declare and initialize variables
PMIB_IPFORWARDTABLE pIpForwardTable = NULL;
PMIB_IPFORWARDROW pRow = NULL;
DWORD dwSize = 0;
BOOL bOrder = FALSE;
DWORD dwStatus = 0;
DWORD NewGateway = 0xDDBBCCAA; // this is in host order Ip Address AA.BB.CC.DD is DDCCBBAA
unsigned int i;
// Identify the required size of the buffer.
dwStatus = GetIpForwardTable(pIpForwardTable, &dwSize, bOrder);
if (dwStatus == ERROR_INSUFFICIENT_BUFFER) {
// Allocate memory for the table.
if (!(pIpForwardTable = (PMIB_IPFORWARDTABLE) malloc(dwSize))) {
printf("Malloc failed. Out of memory.\n");
exit(1);
}
// Retrieve the table.
dwStatus = GetIpForwardTable(pIpForwardTable, &dwSize, bOrder);
}
if (dwStatus != ERROR_SUCCESS) {
printf("getIpForwardTable failed.\n");
if (pIpForwardTable)
free(pIpForwardTable);
exit(1);
}
// Search for the required row in the table. The default gateway has a destination
// of 0.0.0.0. Be aware the table continues to be searched, but only
// one row is copied. This is to ensure that, if multiple gateways exist, all of them are deleted.
//
for (i = 0; i < pIpForwardTable->dwNumEntries; i++) {
if (pIpForwardTable->table[i].dwForwardDest == 0) {
// The default gateway was found.
if (!pRow) {
// Allocate memory to store the row. This is easier than manually filling
// the row structure; only the gateway address is changed.
//
pRow = (PMIB_IPFORWARDROW) malloc(sizeof (MIB_IPFORWARDROW));
if (!pRow) {
printf("Malloc failed. Out of memory.\n");
exit(1);
}
// Copy the row.
memcpy(pRow, &(pIpForwardTable->table[i]),
sizeof (MIB_IPFORWARDROW));
}
// Delete the old default gateway entry.
dwStatus = DeleteIpForwardEntry(&(pIpForwardTable->table[i]));
if (dwStatus != ERROR_SUCCESS) {
printf("Could not delete old gateway\n");
exit(1);
}
}
}
// Set the nexthop field to our new gateway. All other properties of the route will
// remain the same.
pRow->dwForwardNextHop = NewGateway;
// Create a new route entry for the default gateway.
dwStatus = CreateIpForwardEntry(pRow);
if (dwStatus == NO_ERROR)
printf("Gateway changed successfully\n");
else if (dwStatus == ERROR_INVALID_PARAMETER)
printf("Invalid parameter.\n");
else
printf("Error: %d\n", dwStatus);
// Free the memory.
if (pIpForwardTable)
free(pIpForwardTable);
if (pRow)
free(pRow);
exit(0);
}
Requisiti
| Client minimo supportato | Windows 2000 Professional [solo app desktop] |
| Server minimo supportato | Windows 2000 Server [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | iphlpapi.h |
| Libreria | Iphlpapi.lib |
| DLL | Iphlpapi.dll |
Vedi anche
Informazioni di riferimento sulla funzione helper IP