Funzione CreateIpForwardEntry (iphlpapi.h)
La funzione CreateIpForwardEntry crea una route nella tabella di routing IPv4 del computer locale.
Sintassi
IPHLPAPI_DLL_LINKAGE DWORD CreateIpForwardEntry(
[in] PMIB_IPFORWARDROW pRoute
);
Parametri
[in] pRoute
Puntatore a una struttura MIB_IPFORWARDROW che specifica le informazioni per la nuova route. Il chiamante deve specificare i valori per tutti i membri di questa struttura. Il chiamante deve specificare MIB_IPPROTO_NETMGMT per il membro dwForwardProto di MIB_IPFORWARDROW.
Valore restituito
La funzione restituisce NO_ERROR (zero) se la funzione ha esito positivo.
Se la funzione ha esito negativo, il valore restituito è uno dei codici di errore seguenti.
| Codice restituito | Descrizione |
|---|---|
|
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 dwForwardProto di MIB_IPFORWARDROW non è stato impostato su MIB_IPPROTO_NETMGMT, il membro dwForwardMaskdella struttura PMIB_IPFORWARDROW non è una subnet mask IPv4 valida o uno degli altri membri della struttura MIB_IPFORWARDROW non è valido. |
|
Il trasporto IPv4 non è configurato nel computer locale. |
|
Usare FormatMessage per ottenere la stringa di messaggio per l'errore restituito. |
Commenti
Il membro dwForwardProto della struttura MIB_IPFORWARDROW a cui punta il parametro di route deve essere impostato su MIB_IPPROTO_NETMGMT altrimenti CreateIpForwardEntry 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 la metrica di route specificata nel membro dwForwardMetric1 della struttura MIB_IPFORWARDROW puntata dal parametro pRoute rappresenta una combinazione della metrica di route aggiunta alla metrica di interfaccia specificata nel membro Metricadella struttura MIB_IPINTERFACE_ROW dell'interfaccia associata. Pertanto, il membro dwForwardMetric1 della struttura MIB_IPFORWARDROW deve essere uguale o maggiore del membro Metricadella struttura MIB_IPINTERFACE_ROW associata. Se un'applicazione vuole impostare la metrica di route su 0, il membro dwForwardMetric1della strutturaMIB_IPFORWARDROW deve essere impostato uguale al valore della metrica di interfaccia specificata nel membro Metrica della struttura MIB_IPINTERFACE_ROW associata. Un'applicazione può recuperare la metrica dell'interfaccia chiamando la funzione GetIpInterfaceEntry .
In Windows Vista e Windows Server 2008, CreateIpForwardEntry funziona solo su interfacce con una singola interfaccia secondaria (dove l'interfaccia LUID e il sottointerfaceNTE LUID sono uguali). 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, dwForwardMetric2, dwForwardMetric3, dwForwardMetric4 e dwForwardMetric5.
Una nuova route creata da CreateIpForwardEntry avrà automaticamente un valore predefinito per dwForwardAge di INFINITE.
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 CreateIpForwardEntry può essere chiamata solo da un utente connesso come membro del gruppo Administrators. Se CreateIpForwardEntry 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 CreateIpForwardEntry 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 seguente viene illustrato come modificare il gateway predefinito in NewGateway. È sufficiente chiamare GetIpForwardTable, modificare il gateway e quindi chiamare SetIpForwardEntry non cambierà la route, ma aggiungerà semplicemente uno nuovo. Se per qualche motivo sono presenti più gateway predefiniti, questo codice li eliminerà. Si noti 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 = 0xDDCCBBAA; // this is in host order Ip Address AA.BB.CC.DD is DDCCBBAA
unsigned int i;
// Find out how big our buffer needs to be.
dwStatus = GetIpForwardTable(pIpForwardTable, &dwSize, bOrder);
if (dwStatus == ERROR_INSUFFICIENT_BUFFER) {
// Allocate the memory for the table
if (!(pIpForwardTable = (PMIB_IPFORWARDTABLE) malloc(dwSize))) {
printf("Malloc failed. Out of memory.\n");
exit(1);
}
// Now get the table.
dwStatus = GetIpForwardTable(pIpForwardTable, &dwSize, bOrder);
}
if (dwStatus != ERROR_SUCCESS) {
printf("getIpForwardTable failed.\n");
if (pIpForwardTable)
free(pIpForwardTable);
exit(1);
}
// Search for the row in the table we want. The default gateway has a destination
// of 0.0.0.0. Notice that we continue looking through the table, but copy only
// one row. This is so that if there happen to be multiple default gateways, we can
// be sure to delete them all.
for (i = 0; i < pIpForwardTable->dwNumEntries; i++) {
if (pIpForwardTable->table[i].dwForwardDest == 0) {
// We have found the default gateway.
if (!pRow) {
// Allocate some memory to store the row in; this is easier than filling
// in the row structure ourselves, and we can be sure we change only the
// gateway address.
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 the other properties of the route will
// be the same as they were previously.
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 resources
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