DisableMediaSense-Funktion (iphlpapi.h)

Artikel
08/24/2023

Die DisableMediaSense-Funktion deaktiviert die Mediensensorfunktion des TCP/IP-Stapels auf einem lokalen Computer.

Syntax

IPHLPAPI_DLL_LINKAGE DWORD DisableMediaSense(
  HANDLE     *pHandle,
  OVERLAPPED *pOverLapped
);

Parameter

pHandle

Ein Zeiger auf eine Variable, die zum Speichern eines Handles verwendet wird. Wenn der pOverlapped-Parameter nicht NULL ist, wird diese Variable intern verwendet, um ein Handle zu speichern, das zum Aufrufen des IP-Treibers und zum Deaktivieren der Mediensensorfunktion erforderlich ist.

Eine Anwendung sollte nicht den Wert verwenden, auf den diese Variable verweist. Dieses Handle ist für die interne Verwendung vorgesehen und sollte nicht geschlossen werden.

pOverLapped

Ein Zeiger auf eine Struktur OVERLAPPED. Mit Ausnahme des hEvent-Elements müssen alle Member dieser Struktur auf 0 (null) festgelegt werden. Das hEvent-Element erfordert ein Handle für ein gültiges Ereignisobjekt. Verwenden Sie die CreateEvent-Funktion , um dieses Ereignisobjekt zu erstellen.

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
ERROR_INVALID_PARAMETER	Es wurde ein ungültiger Parameter an die Funktion übergeben. Dieser Fehler wird zurückgegeben, wenn ein pOverlapped-Parameter ein ungültiger Zeiger ist.
ERROR_IO_PENDING	Der Vorgang wird ausgeführt. Dieser Wert wird durch einen erfolgreichen asynchronen Aufruf von DisableMediaSense zurückgegeben.
ERROR_OPEN_FAILED	Das Handle, auf das der pHandle-Parameter verweist, war ungültig.
ERROR_NOT_SUPPORTED	Die Anforderung wird nicht unterstützt.
Andere	Verwenden Sie FormatMessage , um die Meldungszeichenfolge für den zurückgegebenen Fehler abzurufen.

Hinweise

Wenn die Parameter pHandle oder pOverlappedNULL sind, wird die DisableMediaSense-Funktion synchron ausgeführt.

Wenn sowohl der pHandle- als auch der pOverlapped-Parameter nicht NULL sind, wird die DisableMediaSense-Funktion asynchron mit der OVERLAPPED-Struktur ausgeführt, auf die der pOverlapped-Parameter verweist.

Die DisableMediaSense-Funktion wird erst abgeschlossen, wenn die RestoreMediaSense-Funktion später aufgerufen wird, um die Mediensensorfunktion wiederherzustellen. Bis dahin bleibt ein E/A-Anforderungspaket (IRP) in der Warteschlange. Wenn der Prozess mit dem Namen DisableMediaSense beendet wird, wird der IRP abgebrochen, und es wird eine Abbruchroutine aufgerufen, die die Mediensensorfunktion erneut wiederherstellen würde.

Um DisableMediaSense synchron aufzurufen, muss eine Anwendung einen separaten Thread für diesen Aufruf erstellen. Andernfalls wird weiterhin auf die IRP-Vervollständigung gewartet, und die Funktion wird blockiert.

Um DisableMediaSense asynchron aufzurufen, muss eine Anwendung eine OVERLAPPED-Struktur zuordnen. Mit Ausnahme des hEvent-Elements müssen alle Member dieser Struktur auf 0 (null) festgelegt werden. Das hEvent-Element erfordert ein Handle für ein gültiges Ereignisobjekt. Verwenden Sie die CreateEvent-Funktion , um dieses Ereignis zu erstellen. Bei asynchronem Aufruf gibt DisableMediaSense immer ERROR_IO_PENDING zurück. Die IRP wird nur abgeschlossen, wenn RestoreMediaSense später aufgerufen wird. Verwenden Sie die CloseHandle-Funktion , um das Handle für das Ereignisobjekt zu schließen, wenn es nicht mehr benötigt wird. Das System schließt das Handle automatisch, wenn der Prozess beendet wird. Das Ereignisobjekt wird zerstört, wenn sein letztes Handle geschlossen wurde.

Unter Windows Server 2003 und Windows XP implementiert der TCP/IP-Stapel eine Richtlinie zum Löschen aller IP-Adressen auf einer Schnittstelle als Reaktion auf ein Medienoptimierungstrennereignis von einer zugrunde liegenden Netzwerkschnittstelle. Wenn ein Netzwerkswitch oder Hub, mit dem der lokale Computer verbunden ist, ausgeschaltet ist oder ein Netzwerkkabel getrennt wird, übermittelt die Netzwerkschnittstelle Trennungsereignisse. Ip-Konfigurationsinformationen, die der Netzwerkschnittstelle zugeordnet sind, geht verloren. Daher implementiert der TCP/IP-Stapel eine Richtlinie zum Ausblenden getrennter Schnittstellen, sodass diese Schnittstellen und die zugehörigen IP-Adressen nicht in den Konfigurationsinformationen angezeigt werden, die über das IP-Hilfsprogramm abgerufen werden. Diese Richtlinie verhindert, dass einige Anwendungen leicht erkennen, dass eine Netzwerkschnittstelle nur getrennt und nicht aus dem System entfernt wird.

Dieses Verhalten wirkt sich normalerweise nicht auf einen lokalen Clientcomputer aus, wenn DHCP-Anforderungen für IP-Konfigurationsinformationen an einen DHCP-Server verwendet werden. Dies kann jedoch schwerwiegende Auswirkungen auf Servercomputer haben, insbesondere auf Computer, die als Teil von Clustern verwendet werden. Die Funktion DisableMediaSense kann verwendet werden, um die Mediensensorfunktion für diese Fälle vorübergehend zu deaktivieren. Zu einem späteren Zeitpunkt wird die RestoreMediaSense-Funktion aufgerufen, um die Medienerkennungsfunktion wiederherzustellen.

Die folgende Registrierungseinstellung bezieht sich auf die Funktionen DisableMediaSense und RestoreMediaSense :

System\Currentcontrolset\Dienstleistungen\Tcpip\Parameter\DisableDHCPMediaSense

Es gibt ein internes Flag in Windows, das festgelegt wird, wenn dieser Registrierungsschlüssel vorhanden ist, wenn der Computer zum ersten Mal gestartet wird. Dasselbe interne Flag wird auch festgelegt und zurückgesetzt, indem DisableMediaSense und RestoreMediaSense aufgerufen werden. Mit der Registrierungseinstellung müssen Sie den Computer jedoch neu starten, damit die Änderungen vorgenommen werden.

Der TCP/IP-Stapel unter Windows Vista und höher wurde so geändert, dass getrennte Schnittstellen nicht ausgeblendet werden, wenn ein Trennungsereignis auftritt. Unter Windows Vista und höher führen die Funktionen DisableMediaSense und RestoreMediaSense nichts aus und geben immer NO_ERROR zurück.

Beispiele

Das folgende Beispiel zeigt, wie die Funktionen DisableMediaSense und RestoreMediaSense asynchron aufgerufen werden. Dieses Beispiel ist nur unter Windows Server 2003und Windows XP nützlich, wo die Funktionen DisableMediaSense und RestoreMediaSense nützlich sind.

Im Beispiel wird zunächst die DisableMediaSense-Funktion aufgerufen, 60 Sekunden lang in den Ruhezustand versetzt, damit der Benutzer ein Netzwerkkabel trennen kann, ruft die IP-Adresstabelle ab und druckt einige Elemente der IP-Adresseinträge in der Tabelle, ruft die RestoreMediaSense-Funktion auf, ruft die IP-Adresstabelle erneut ab und gibt einige Elemente der IP-Adresseinträge in der Tabelle aus. Die Auswirkungen der Deaktivierung der Medienerkennungsfunktion können am Unterschied in den IP-Adresstabelleneinträgen gesehen werden.

Ein Beispiel zum synchronen Aufrufen der Funktionen DisableMediaSense und RestoreMediaSense finden Sie in der RestoreMediaSense-Funktionsreferenz .

#include <winsock2.h>
#include <ws2tcpip.h>
#include <iphlpapi.h>
#include <stdio.h>

#pragma comment(lib, "iphlpapi.lib")
#pragma comment(lib, "ws2_32.lib")

#define MALLOC(x) HeapAlloc(GetProcessHeap(), 0, (x))
#define FREE(x) HeapFree(GetProcessHeap(), 0, (x))

/* Note: could also use malloc() and free() */

int __cdecl main()
{

    int i;

    /* Variables used by GetIpAddrTable */
    PMIB_IPADDRTABLE pIPAddrTable;
    DWORD dwSize = 0;
    DWORD dwRetVal = 0;
    IN_ADDR IPAddr;

    /* Variables used to return error message */
    LPVOID lpMsgBuf;

    // Variables to call DisableMediaSense
    //  and RestoreMediaSense asynchronously
    HANDLE IpDriverHandle = INVALID_HANDLE_VALUE;
    OVERLAPPED Overlapped;
    HANDLE DriverHandle;
    DWORD dwEnableCount = 0;

    memset(&Overlapped, 0, sizeof (Overlapped));
    Overlapped.hEvent = CreateEvent(NULL, FALSE, FALSE, NULL);

    dwRetVal = DisableMediaSense(&DriverHandle, &Overlapped);
    if (dwRetVal != ERROR_IO_PENDING) {
        printf("DisableMediaSense failed with error %d\n", dwRetVal);
        exit(1);
    } else {
        printf(" === DisableMediaSense called ===\n\n");
        // Sleep for 60 seconds so we can disconnect a cable
        Sleep(60000);
    }

    // Before calling AddIPAddress we use GetIpAddrTable to get
    // an adapter to which we can add the IP.
    pIPAddrTable = (MIB_IPADDRTABLE *) MALLOC(sizeof (MIB_IPADDRTABLE));

    if (pIPAddrTable) {
        // Make an initial call to GetIpAddrTable to get the
        // necessary size into the dwSize variable
        if (GetIpAddrTable(pIPAddrTable, &dwSize, 0) ==
            ERROR_INSUFFICIENT_BUFFER) {
            FREE(pIPAddrTable);
            pIPAddrTable = (MIB_IPADDRTABLE *) MALLOC(dwSize);

        }
        if (pIPAddrTable == NULL) {
            printf("Memory allocation failed for GetIpAddrTable\n");
            exit(1);
        }
    }
    // Make a second call to GetIpAddrTable to get the
    // actual data we want
    if ((dwRetVal = GetIpAddrTable(pIPAddrTable, &dwSize, 0)) != NO_ERROR) {
        printf("GetIpAddrTable failed with error %d\n", dwRetVal);
        if (FormatMessage(FORMAT_MESSAGE_ALLOCATE_BUFFER |
                    FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS, 
                    NULL, 
                    dwRetVal, 
                    MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), // Default language
                    (LPTSTR) & lpMsgBuf, 0, NULL)) {
            printf("\tError: %s", lpMsgBuf);
            LocalFree(lpMsgBuf);
        }
        exit(1);
    }

    printf("\tNum Entries: %ld\n", pIPAddrTable->dwNumEntries);
    for (i = 0; i < (int) pIPAddrTable->dwNumEntries; i++) {
        printf("\n\tInterface Index[%d]:\t%ld\n", i,
               pIPAddrTable->table[i].dwIndex);
        IPAddr.S_un.S_addr = (u_long) pIPAddrTable->table[i].dwAddr;
        printf("\tIP Address[%d]:     \t%s\n", i, inet_ntoa(IPAddr));
        IPAddr.S_un.S_addr = (u_long) pIPAddrTable->table[i].dwMask;
        printf("\tSubnet Mask[%d]:    \t%s\n", i, inet_ntoa(IPAddr));
        IPAddr.S_un.S_addr = (u_long) pIPAddrTable->table[i].dwBCastAddr;
        printf("\tBroadCast[%d]:      \t%s (%ld%)\n", i, inet_ntoa(IPAddr),
               pIPAddrTable->table[i].dwBCastAddr);
        printf("\tReassembly size[%d]:\t%ld\n", i,
               pIPAddrTable->table[i].dwReasmSize);
        printf("\tType and State[%d]:", i);
        if (pIPAddrTable->table[i].wType & MIB_IPADDR_PRIMARY)
            printf("\tPrimary IP Address");
        if (pIPAddrTable->table[i].wType & MIB_IPADDR_DYNAMIC)
            printf("\tDynamic IP Address");
        if (pIPAddrTable->table[i].wType & MIB_IPADDR_DISCONNECTED)
            printf("\tAddress is on disconnected interface");
        if (pIPAddrTable->table[i].wType & MIB_IPADDR_DELETED)
            printf("\tAddress is being deleted");
        if (pIPAddrTable->table[i].wType & MIB_IPADDR_TRANSIENT)
            printf("\tTransient address");
        printf("\n");
    }

    // Call RestoreMediaSense asynchronously to enable mediasense
    dwRetVal = RestoreMediaSense(&Overlapped, &dwEnableCount);
    if (dwRetVal && dwRetVal != ERROR_IO_PENDING) {
        printf("RestoreMediaSense failed with error %d\n", dwRetVal);
        exit(1);
    } else {
        printf(" === RestoreMediaSense called ===\n");
        printf("  EnableCount returned was %ld\n\n", dwEnableCount);
    }

    if (pIPAddrTable) {
        // Make an initial call to GetIpAddrTable to get the
        // necessary size into the dwSize variable
        if (GetIpAddrTable(pIPAddrTable, &dwSize, 0) ==
            ERROR_INSUFFICIENT_BUFFER) {
            FREE(pIPAddrTable);
            pIPAddrTable = (MIB_IPADDRTABLE *) MALLOC(dwSize);

        }
        if (pIPAddrTable == NULL) {
            printf("Memory allocation failed for GetIpAddrTable\n");
            exit(1);
        }
    }
    // Make a second call to GetIpAddrTable to get the
    // actual data we want
    if ((dwRetVal = GetIpAddrTable(pIPAddrTable, &dwSize, 0)) != NO_ERROR) {
        printf("GetIpAddrTable failed with error %d\n", dwRetVal);
        if (FormatMessage(FORMAT_MESSAGE_ALLOCATE_BUFFER | 
                    FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS, 
                    NULL, dwRetVal, 
                    MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),  // Default language
                    (LPTSTR) & lpMsgBuf, 0, NULL)) {
            printf("\tError: %s", lpMsgBuf);
            LocalFree(lpMsgBuf);
        }
        exit(1);
    }

    printf("\tNum Entries: %ld\n", pIPAddrTable->dwNumEntries);
    for (i = 0; i < (int) pIPAddrTable->dwNumEntries; i++) {
        printf("\n\tInterface Index[%d]:\t%ld\n", i,
               pIPAddrTable->table[i].dwIndex);
        IPAddr.S_un.S_addr = (u_long) pIPAddrTable->table[i].dwAddr;
        printf("\tIP Address[%d]:     \t%s\n", i, inet_ntoa(IPAddr));
        IPAddr.S_un.S_addr = (u_long) pIPAddrTable->table[i].dwMask;
        printf("\tSubnet Mask[%d]:    \t%s\n", i, inet_ntoa(IPAddr));
        IPAddr.S_un.S_addr = (u_long) pIPAddrTable->table[i].dwBCastAddr;
        printf("\tBroadCast[%d]:      \t%s (%ld%)\n", i, inet_ntoa(IPAddr),
               pIPAddrTable->table[i].dwBCastAddr);
        printf("\tReassembly size[%d]:\t%ld\n", i,
               pIPAddrTable->table[i].dwReasmSize);
        printf("\tType and State[%d]:", i);
        if (pIPAddrTable->table[i].wType & MIB_IPADDR_PRIMARY)
            printf("\tPrimary IP Address");
        if (pIPAddrTable->table[i].wType & MIB_IPADDR_DYNAMIC)
            printf("\tDynamic IP Address");
        if (pIPAddrTable->table[i].wType & MIB_IPADDR_DISCONNECTED)
            printf("\tAddress is on disconnected interface");
        if (pIPAddrTable->table[i].wType & MIB_IPADDR_DELETED)
            printf("\tAddress is being deleted");
        if (pIPAddrTable->table[i].wType & MIB_IPADDR_TRANSIENT)
            printf("\tTransient address");
        printf("\n");
    }

    if (pIPAddrTable) {
        FREE(pIPAddrTable);
        pIPAddrTable = NULL;
    }

    exit(0);
}

Anforderungen


Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	iphlpapi.h
Bibliothek	Iphlpapi.lib
DLL	Iphlpapi.dll