RestoreMediaSense

RestoreMediaSense 関数は、以前に DisableMediaSense 関数が呼び出されたローカルコンピューター上で、TCP/IP スタックのメディアセンシング機能を復元します。

関数が成功した場合、戻り値は NO_ERROR です。

関数が失敗した場合、戻り値は次のいずれかのエラーコードです。

pOverlapped パラメーターが NULL の場合、RestoreMediaSense 関数は同期的に実行されます。

pOverlapped パラメーターが NULL でない場合、RestoreMediaSense 関数は、pOverlapped パラメーターが指す OVERLAPPED 構造体を使用して非同期的に実行されます。

DisableMediaSense 関数は、後でメディアセンシング機能を復元するために RestoreMediaSense 関数が呼び出されるまで完了しません。それまでの間、I/O 要求パケット (IRP) はキューに残ったままになります。あるいは、DisableMediaSense を呼び出したプロセスが終了すると、IRP がキャンセルされ、キャンセルルーチンが呼び出されて、再びメディアセンシング機能が復元されます。

RestoreMediaSense を同期的に呼び出すには、アプリケーションは pOverlapped パラメーターに NULL ポインターを渡す必要があります。RestoreMediaSense を同期的に呼び出した場合、メディアセンスを復元するための I/O 要求パケット (IRP) が完了した時点で関数が戻ります。

RestoreMediaSense を非同期的に呼び出すには、アプリケーションは OVERLAPPED 構造体を割り当てる必要があります。hEvent メンバーを除き、この構造体のすべてのメンバーをゼロに設定する必要があります。hEvent メンバーには、有効なイベントオブジェクトへのハンドルが必要です。このイベントの作成には CreateEvent 関数を使用してください。非同期的に呼び出された場合、RestoreMediaSense は ERROR_IO_PENDING を返すことがあります。メディアセンシング機能が復元されると IRP が完了します。イベントオブジェクトへのハンドルが不要になったら、CloseHandle 関数を使用してハンドルを閉じてください。プロセスが終了すると、システムがハンドルを自動的に閉じます。イベントオブジェクトは、その最後のハンドルが閉じられた時点で破棄されます。

RestoreMediaSense を呼び出す前に DisableMediaSense が呼び出されていない場合、RestoreMediaSense は ERROR_INVALID_PARAMETER を返します。

Windows Server 2003 および Windows XP では、TCP/IP スタックは、基盤となるネットワークインターフェイスからのメディアセンス切断イベントに応答して、そのインターフェイス上のすべての IP アドレスを削除するというポリシーを実装しています。ローカルコンピューターが接続されているネットワークスイッチやハブの電源が切れたり、ネットワークケーブルが切断されたりすると、ネットワークインターフェイスは切断イベントを通知します。そのネットワークインターフェイスに関連付けられた IP 構成情報は失われます。その結果、TCP/IP スタックは切断されたインターフェイスを隠すポリシーを実装し、これらのインターフェイスおよびそれらに関連付けられた IP アドレスが、IP ヘルパー経由で取得される構成情報に表示されないようにします。このポリシーにより、一部のアプリケーションでは、ネットワークインターフェイスがシステムから削除されたのではなく単に切断されただけであることを容易に検出できなくなります。

この動作は、ローカルクライアントコンピューターが IP 構成情報のために DHCP サーバーへの DHCP 要求を使用している場合には、通常は影響しません。しかし、サーバーコンピューター、特にクラスターの一部として使用されるコンピューターには深刻な影響を及ぼす可能性があります。このような場合、DisableMediaSense 関数を使用して、メディアセンス機能を一時的に無効にできます。その後の任意の時点で、RestoreMediaSense 関数を呼び出してメディアセンシング機能を復元します。

次のレジストリ設定は、DisableMediaSense 関数および RestoreMediaSense 関数に関連しています。

System\CurrentControlSet\Services\Tcpip\Parameters\DisableDHCPMediaSense

Windows には内部フラグがあり、マシンが最初に起動したときにこのレジストリキーが存在すると、このフラグが設定されます。同じ内部フラグは、DisableMediaSense および RestoreMediaSense を呼び出すことによっても設定およびリセットされます。ただし、レジストリ設定の場合は、変更を反映させるためにマシンを再起動する必要があります。

Windows Vista 以降では、切断イベントが発生したときに切断されたインターフェイスを隠さないように TCP/IP スタックが変更されました。したがって、Windows Vista 以降では、DisableMediaSense 関数および RestoreMediaSense 関数は何も行わず、常に NO_ERROR を返します。

例

次の例は、DisableMediaSense 関数および RestoreMediaSense 関数を同期的に呼び出す方法を示しています。このサンプルは、DisableMediaSense 関数および RestoreMediaSense 関数が有用な動作を行う Windows Server 2003 および Windows XP でのみ役立ちます。

このサンプルでは、まず DisableMediaSense 関数を同期的に呼び出す別個のスレッドを作成します。メインスレッドは、ユーザーがネットワークケーブルを切断できるよう 60 秒間スリープし、IP アドレステーブルを取得してテーブル内の IP アドレスエントリのいくつかのメンバーを出力し、RestoreMediaSense 関数を同期的に呼び出し、再び IP アドレステーブルを取得して、テーブル内の IP アドレスエントリのいくつかのメンバーを出力します。メディアセンシング機能を無効にした影響は、IP アドレステーブルのエントリの違いに表れます。

DisableMediaSense 関数および RestoreMediaSense 関数を非同期的に呼び出す方法を示す例については、DisableMediaSense 関数のリファレンスを参照してください。

#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() */

// The thread proc to call DisableMediaSense
DWORD WINAPI ThreadProc(LPVOID lpParam)
{
    if (*((DWORD *) lpParam)) {
        DWORD dwRetVal;
        dwRetVal = DisableMediaSense(NULL, NULL);
        if (dwRetVal && dwRetVal != ERROR_IO_PENDING) {
            printf("DisableMediaSense failed with error %d\n", dwRetVal);
            return 0;
        } else {
            Sleep(1000);
            printf(" === DisableMediaSense Returned now. ===\n\n");
        }
    }
    return 0;
}

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;

    /* Variable to use with RestoreMediaSense */
    DWORD dwEnableCount = 0;

    // Variables used to create a separate thread to call
    // the DisableMediaSense function
    DWORD ThreadID;
    DWORD IsDisable = TRUE;
    HANDLE Disable_THandle;

    // Create the thread to call Disable MediaSense synchronously
    Disable_THandle =
        CreateThread(NULL, 0, ThreadProc, (LPVOID) & IsDisable, 0, &ThreadID);
    if (!Disable_THandle) {
        printf("CreateTread Failed:%d", GetLastError());
        exit(1);
    }

    printf(" === DisableMediaSense called on separate thread ===\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 synchronously to enable mediasense
    dwRetVal = RestoreMediaSense(NULL, &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);
}