Kode Kontrol SIO_ADDRESS_LIST_QUERY

Artikel
06/12/2023

Deskripsi

Kode kontrol SIO_ADDRESS_LIST_QUERY mendapatkan daftar alamat transportasi lokal dari keluarga protokol soket tempat aplikasi dapat mengikat. Daftar alamat bervariasi berdasarkan keluarga alamat dan beberapa alamat dikecualikan dari daftar.

Untuk melakukan operasi ini, panggil fungsi WSAIoctl atau WSPIoctl dengan parameter berikut.

int WSAIoctl(
  (socket) s,            // descriptor identifying a socket
  SIO_ADDRESS_LIST_QUERY,            // dwIoControlCode
  NULL,                              // lpvInBuffer
  0,                                 // cbInBuffer
  (LPVOID) lpvOutBuffer,          // output buffer
  (DWORD) cbOutBuffer,            // size of output buffer  
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped, // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
);

int WSPIoctl(
  (socket) s,            // descriptor identifying a socket
  SIO_ADDRESS_LIST_QUERY,            // dwIoControlCode
  NULL,                              // lpvInBuffer
  0,                                 // cbInBuffer
  (LPVOID) lpvOutBuffer,          // output buffer
  (DWORD) cbOutBuffer,            // size of output buffer  
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped, // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
  (LPWSATHREADID) lpThreadId,   // a WSATHREADID structure
  (LPINT) lpErrno   // a pointer to the error code.
);

Parameter

s

Deskriptor yang mengidentifikasi soket.

dwIoControlCode

Kode kontrol untuk operasi. Gunakan SIO_ADDRESS_LIST_QUERY untuk operasi ini.

lpvInBuffer

Penunjuk ke buffer input. Parameter ini tidak digunakan untuk operasi ini.

cbInBuffer

Ukuran, dalam byte, dari buffer input. Parameter ini tidak digunakan untuk operasi ini.

lpvOutBuffer

Penunjuk ke buffer output.

cbOutBuffer

Ukuran, dalam byte, dari buffer output.

lpcbBytesReturned

Penunjuk ke variabel yang menerima ukuran, dalam byte, dari data yang disimpan dalam buffer output.

lpvOverlapped

Penunjuk ke struktur WSAOVERLAPPED .

Jika soket dibuat tanpa atribut yang tumpang tindih, parameter lpOverlapped diabaikan.

Jika s dibuka dengan atribut yang tumpang tindih dan parameter lpOverlapped bukan NULL, operasi dilakukan sebagai operasi yang tumpang tindih (asinkron). Dalam hal ini, parameter lpOverlapped harus menunjuk ke struktur WSAOVERLAPPED yang valid.

Untuk operasi yang tumpang tindih, fungsi WSAIoctl atau WSPIoctl segera kembali, dan metode penyelesaian yang sesuai disinyalir ketika operasi telah selesai. Jika tidak, fungsi tidak kembali sampai operasi selesai atau terjadi kesalahan.

lpCompletionRoutine

Jenis: LPWSAOVERLAPPED_COMPLETION_ROUTINE _In_opt_

Penunjuk ke rutinitas penyelesaian yang dipanggil ketika operasi telah selesai (diabaikan untuk soket yang tidak tumpang tindih).

lpThreadId

Penunjuk ke struktur WSATHREADID yang akan digunakan oleh penyedia dalam panggilan berikutnya ke WPUQueueApc. Penyedia harus menyimpan struktur WSATHREADID yang direferensikan (bukan penunjuk ke yang sama) sampai setelah fungsi WPUQueueApc kembali.

Catatan Parameter ini hanya berlaku untuk fungsi WSPIoctl .

lpErrno

Penunjuk ke kode kesalahan.

Catatan Parameter ini hanya berlaku untuk fungsi WSPIoctl .

Nilai kembali

Jika operasi berhasil diselesaikan, fungsi WSAIoctl atau WSPIoctl mengembalikan nol.

Jika operasi gagal atau tertunda, fungsi WSAIoctl atau WSPIoctl mengembalikan SOCKET_ERROR. Untuk mendapatkan informasi kesalahan yang diperluas, panggil WSAGetLastError.

Kode kesalahan	Makna
WSA_IO_PENDING	Operasi yang tumpang tindih berhasil dimulai dan penyelesaian akan ditunjukkan di lain waktu.
WSA_OPERATION_ABORTED	Operasi yang tumpang tindih dibatalkan karena penutupan soket atau eksekusi perintah SIO_FLUSH IOCTL.
WSAEFAULT	Parameter lpOverlapped atau lpCompletionRoutine tidak sepenuhnya terkandung dalam bagian ruang alamat pengguna yang valid.
WSAEINPROGRESS	Fungsi ini dipanggil ketika panggilan balik sedang berlangsung.
WSAEINTR	Operasi pemblokiran terganggu.
WSAEINVAL	Parameter dwIoControlCode bukan perintah yang valid, atau parameter input tertentu tidak dapat diterima, atau perintah tidak berlaku untuk jenis soket yang ditentukan. Kesalahan ini dikembalikan jika parameter cbInBuffer tidak diatur ke NULL.
WSAENETDOWN	Subsistem jaringan gagal.
WSAENOBUFS	Tidak tersedia ruang buffer.
WSAENOPROTOOPT	Opsi soket tidak didukung pada protokol yang ditentukan.
WSAENOTSOCK	Deskriptor bukan soket.
WSAEOPNOTSUPP	Perintah IOCTL yang ditentukan tidak didukung. Kesalahan ini dikembalikan jika SIO_ADDRESS_LIST_QUERY IOCTL tidak didukung oleh penyedia transportasi.

Keterangan

IOCTL SIO_ADDRESS_LIST_QUERY didukung pada Windows 2000 dan versi yang lebih baru dari sistem operasi.

Kode kontrol SIO_ADDRESS_LIST_QUERY mendapatkan daftar alamat transportasi lokal dari keluarga protokol soket tempat aplikasi dapat mengikat. Daftar alamat bervariasi berdasarkan keluarga alamat.

Untuk keluarga alamat AF_INET6, semua alamat dikembalikan kecuali untuk yang berikut ini:

Alamat IP apa pun tempat status deteksi alamat duplikat (DAD) bukan IpDadStatePreferred.
Alamat IP apa pun dengan tingkat cakupan yang lebih rendah dari ScopeLevelSubnet pada antarmuka tempat jenis antarmuka IF_TYPE_SOFTWARE_LOOPBACK. Ini berarti alamat link-local (fe80:*) dan loopback (::1) pada antarmuka jenis IF_TYPE_SOFTWARE_LOOPBACK dikecualikan, tetapi tidak jika alamat ini berada di antarmuka dengan jenis yang berbeda.

Untuk keluarga alamat AF_INET , semua alamat dikembalikan kecuali untuk yang berikut ini:

Alamat IP apa pun tempat status deteksi alamat duplikat (DAD) bukan IpDadStatePreferred.
Alamat IP apa pun pada antarmuka tempat jenis antarmuka IF_TYPE_SOFTWARE_LOOPBACK dan tautan bersifat lokal. Ini berarti alamat link-local (169.254.) dan loopback (127.) pada antarmuka jenis IF_TYPE_SOFTWARE_LOOPBACK dikecualikan, tetapi tidak jika alamat ini berada di antarmuka dengan jenis yang berbeda.

Untuk informasi selengkapnya tentang status DAD, lihat dokumentasi Pembantu IP tentang enumerasi IP_DAD_STATE dan struktur IP_ADAPTER_UNICAST_ADDRESS dan dokumentasi MIB tentang struktur MIB_UNICASTIPADDRESS_ROW . Untuk informasi selengkapnya tentang jenis antarmuka, lihat dokumentasi IP Helper tentang struktur IP_ADAPTER_ADDRESSES dan fungsi GetAdaptersAddresses dan dokumentasi MIB tentang struktur MIB_IF_ROW2 . Untuk informasi selengkapnya tentang tingkat cakupan, lihat dokumentasi Pembantu IP tentang struktur IP_ADAPTER_ADDRESSES dan enumerasi SCOPE_LEVEL .

Daftar yang dikembalikan dalam buffer output yang ditujukkan oleh parameter lpvOutBuffer dalam bentuk struktur SOCKET_ADDRESS_LIST .

Jika buffer output yang ditentukan dalam parameter lpvOutBuffer tidak cukup besar untuk berisi daftar alamat, SOCKET_ERROR dikembalikan sebagai hasil dari IOCTL ini dan WSAGetLastError mengembalikan WSAEFAULT. Ukuran yang diperlukan, dalam byte, untuk buffer output dikembalikan dalam parameter lpcbBytesReturned dalam kasus ini. Perhatikan kode kesalahan WSAEFAULT juga dikembalikan jika parameter lpvInBuffer, lpvOutBuffer, atau lpcbBytesReturned tidak sepenuhnya terkandung dalam bagian ruang alamat pengguna yang valid.

IOCTL SIO_ADDRESS_LIST_QUERY biasanya dipanggil secara sinkron dengan parameter lpvOverlapped yang diatur ke NULL, karena daftar alamat segera dikembalikan.

Catatan Di lingkungan Windows Plug-n-Play, alamat dapat ditambahkan dan dihapus secara dinamis. Oleh karena itu, aplikasi tidak dapat mengandalkan informasi yang dikembalikan oleh SIO_ADDRESS_LIST_QUERY untuk terus-menerus. Aplikasi dapat mendaftar untuk pemberitahuan perubahan alamat melalui SIO_ADDRESS_LIST_CHANGE IOCTL yang menyediakan pemberitahuan melalui I/O yang tumpang tindih atau peristiwa FD_ADDRESS_LIST_CHANGE . Urutan tindakan berikut dapat digunakan untuk menjamin bahwa aplikasi selalu memiliki informasi daftar alamat saat ini:

Menerbitkan IOCTL SIO_ADDRESS_LIST_CHANGE
Menerbitkan IOCTL SIO_ADDRESS_LIST_QUERY
Setiap kali panggilan IOCTL SIO_ADDRESS_LIST_CHANGE memberi tahu aplikasi perubahan daftar alamat (baik melalui I/O yang tumpang tindih atau dengan memberi sinyal peristiwa FD_ADDRESS_LIST_CHANGE ), seluruh urutan tindakan harus diulang.

Pada Microsoft Windows Software Development Kit (SDK) yang dirilis untuk Windows Vista dan yang lebih baru, organisasi file header telah berubah dan kode kontrol SIO_ADDRESS_LIST_QUERY ditentukan dalam file header Ws2def.h . Perhatikan bahwa file header Ws2def.h secara otomatis disertakan dalam Winsock2.h, dan tidak boleh digunakan secara langsung.