Bagikan melalui

Fungsi DisableMediaSense (iphlpapi.h)

  • Artikel

Fungsi DisableMediaSense menonaktifkan kemampuan sensor media tumpukan TCP/IP pada komputer lokal.

Sintaks

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

Parameter

pHandle

Penunjuk ke variabel yang digunakan untuk menyimpan handel. Jika parameter pOverlapped bukan NULL, variabel ini akan digunakan secara internal untuk menyimpan handel yang diperlukan untuk memanggil driver IP dan menonaktifkan kemampuan sensor media.

Aplikasi tidak boleh menggunakan nilai yang diacu oleh variabel ini. Handel ini untuk penggunaan internal dan tidak boleh ditutup.

pOverLapped

Penunjuk ke struktur YANG TUMPANG TINDIH . Kecuali untuk anggota hEvent , semua anggota struktur ini harus diatur ke nol. Anggota hEvent memerlukan handel ke objek peristiwa yang valid. Gunakan fungsi CreateEvent untuk membuat objek kejadian ini.

Menampilkan nilai

Jika fungsi berhasil, nilai yang dikembalikan NO_ERROR.

Jika fungsi gagal, nilai yang dikembalikan adalah salah satu kode kesalahan berikut.

Menampilkan kode Deskripsi
ERROR_INVALID_PARAMETER
 Parameter yang tidak valid diteruskan ke fungsi. Kesalahan ini dikembalikan jika parameter pOverlapped adalah penunjuk yang buruk.
ERROR_IO_PENDING
 Operasi sedang berlangsung. Nilai ini dikembalikan oleh panggilan asinkron yang berhasil ke DisableMediaSense.
ERROR_OPEN_FAILED
 Handel yang diarahkan oleh parameter pHandle tidak valid.
ERROR_NOT_SUPPORTED
 Permintaan tidak didukung.
Lainnya
 Gunakan FormatMessage untuk mendapatkan string pesan untuk kesalahan yang dikembalikan.

Keterangan

Jika parameter pHandle atau pOverlappedNULL, fungsi DisableMediaSense dijalankan secara sinkron.

Jika parameter pHandle dan pOverlapped bukan NULL, fungsi DisableMediaSense dijalankan secara asinkron menggunakan struktur TUMPANG TINDIH yang diarahkan oleh parameter pOverlapped .

Fungsi DisableMediaSense tidak selesai sampai fungsi RestoreMediaSense dipanggil nanti untuk memulihkan kemampuan sensor media. Hingga saat itu, paket permintaan I/O (IRP) tetap mengantre. Atau, ketika proses yang disebut DisableMediaSense keluar, IRP dibatalkan dan rutinitas pembatalan disebut yang akan kembali memulihkan kemampuan sensor media.

Untuk memanggil DisableMediaSense secara sinkron, aplikasi perlu membuat utas terpisah untuk panggilan ini. Jika tidak, itu akan terus menunggu penyelesaian IRP dan fungsi akan memblokir.

Untuk memanggil DisableMediaSense secara asinkron, aplikasi perlu mengalokasikan struktur yang TUMPANG TINDIH . Kecuali untuk anggota hEvent , semua anggota struktur ini harus diatur ke nol. Anggota hEvent memerlukan handel ke objek peristiwa yang valid. Gunakan fungsi CreateEvent untuk membuat kejadian ini. Ketika dipanggil secara asinkron, DisableMediaSense selalu mengembalikan ERROR_IO_PENDING. IRP hanya akan diselesaikan ketika RestoreMediaSense dipanggil nanti. Gunakan fungsi CloseHandle untuk menutup handel ke objek peristiwa saat tidak lagi diperlukan. Sistem menutup handel secara otomatis ketika proses berakhir. Objek peristiwa dihancurkan ketika handel terakhirnya telah ditutup.

Pada Windows Server 2003dan Windows XP, tumpukan TCP/IP menerapkan kebijakan menghapus semua alamat IP pada antarmuka sebagai respons terhadap peristiwa pemutusan indera media dari antarmuka jaringan yang mendasar. Jika sakelar atau hub jaringan yang tersambung dengan komputer lokal dimatikan, atau kabel jaringan terputus, antarmuka jaringan akan memberikan peristiwa pemutusan sambungan. Informasi konfigurasi IP yang terkait dengan antarmuka jaringan hilang. Akibatnya, tumpukan TCP/IP menerapkan kebijakan menyembunyikan antarmuka yang terputus sehingga antarmuka ini dan alamat IP terkaitnya tidak muncul dalam informasi konfigurasi yang diambil melalui pembantu IP. Kebijakan ini mencegah beberapa aplikasi dengan mudah mendeteksi bahwa antarmuka jaringan hanya terputus, daripada dihapus dari sistem.

Perilaku ini biasanya tidak berdampak pada komputer klien lokal jika menggunakan permintaan DHCP ke server DHCP untuk informasi konfigurasi IP. Tetapi ini dapat berdampak serius pada komputer server, terutama komputer yang digunakan sebagai bagian dari kluster. Fungsi DisableMediaSense dapat digunakan untuk menonaktifkan sementara kemampuan sensor media untuk kasus ini. Di lain waktu, fungsi RestoreMediaSense akan dipanggil untuk memulihkan kemampuan sensor media.

Pengaturan registri berikut terkait dengan fungsi DisableMediaSense dan RestoreMediaSense :

Sistem\CurrentControlSet\Layanan\Tcpip\Parameter\DisableDHCPMediaSense

Ada bendera internal di Windows yang diatur jika kunci registri ini ada ketika komputer pertama kali boot up. Bendera internal yang sama juga akan diatur dan diatur ulang dengan memanggil DisableMediaSense dan RestoreMediaSense. Namun dengan pengaturan registri, Anda perlu me-reboot komputer agar perubahan terjadi.

Tumpukan TCP/IP pada Windows Vista dan kemudian diubah agar tidak menyembunyikan antarmuka yang terputus ketika terjadi peristiwa pemutusan sambungan. Jadi pada Windows Vista dan yang lebih baru, fungsi DisableMediaSense dan RestoreMediaSense tidak melakukan apa pun dan selalu mengembalikan NO_ERROR.

Contoh

Contoh berikut menunjukkan cara memanggil fungsi DisableMediaSense dan RestoreMediaSense secara asinkron. Sampel ini hanya berguna pada Windows Server 2003dan Windows XP di mana fungsi DisableMediaSense dan RestoreMediaSense melakukan sesuatu yang berguna.

Sampel pertama-tama memanggil fungsi DisableMediaSense , tidur selama 60 detik untuk memungkinkan pengguna memutuskan kabel jaringan, mengambil tabel alamat IP dan mencetak beberapa anggota entri alamat IP dalam tabel, memanggil fungsi RestoreMediaSense , mengambil tabel alamat IP lagi, dan mencetak beberapa anggota entri alamat IP dalam tabel. Dampak menonaktifkan kemampuan sensor media dapat dilihat dalam perbedaan entri tabel alamat IP.

Untuk contoh yang menunjukkan cara memanggil fungsi DisableMediaSense dan RestoreMediaSense secara sinkron, lihat referensi fungsi RestoreMediaSense .

#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);
}

Persyaratan

   
Klien minimum yang didukung Windows XP [hanya aplikasi desktop]
Server minimum yang didukung Windows Server 2003 [hanya aplikasi desktop]
Target Platform Windows
Header iphlpapi.h
Pustaka Iphlpapi.lib
DLL Iphlpapi.dll

Lihat juga

CloseHandle

CreateEvent

EnableRouter

Referensi Fungsi Pembantu IP

Halaman Mulai Pembantu IP

TUMPANG TINDIH

RestoreMediaSense

UnenableRouter