Fungsi WSAAsyncGetHostByAddr (winsock.h)

Artikel
03/04/2024

Fungsi WSAAsyncGetHostByAddr secara asinkron mengambil informasi host yang sesuai dengan alamat.

Catatan Fungsi WSAAsyncGetHostByAddr tidak dirancang untuk memberikan resolusi paralel dari beberapa alamat. Oleh karena itu, aplikasi yang mengeluarkan beberapa permintaan seharusnya tidak mengharapkannya dijalankan secara bersamaan. Atau, aplikasi dapat memulai utas lain dan menggunakan fungsi getnameinfo untuk menyelesaikan alamat dengan cara agnostik versi IP. Pengembang yang membuat aplikasi Windows Sockets 2 didesak untuk menggunakan fungsi getnameinfo untuk memungkinkan transisi yang lancar ke kompatibilitas IPv6.

Sintaks

HANDLE WSAAsyncGetHostByAddr(
  HWND       hWnd,
  u_int      wMsg,
  const char *addr,
  int        len,
  int        type,
  char       *buf,
  int        buflen
);

Parameter

hWnd

TBD

wMsg

TBD

addr

TBD

len

TBD

type

TBD

buf

TBD

buflen

TBD

Mengembalikan nilai

Nilai yang dikembalikan menentukan apakah operasi asinkron berhasil dimulai atau tidak. Ini tidak menyiratkan keberhasilan atau kegagalan operasi itu sendiri.

Jika tidak ada kesalahan yang terjadi, WSAAsyncGetHostByAddr mengembalikan nilai bukan nol dari jenis HANDLE yang merupakan handel tugas asinkron (tidak dikacaukan dengan HTASK Windows) untuk permintaan tersebut. Nilai ini dapat digunakan dengan dua cara. Ini dapat digunakan untuk membatalkan operasi menggunakan WSACancelAsyncRequest, atau dapat digunakan untuk mencocokkan operasi asinkron dan pesan penyelesaian dengan memeriksa parameter pesan wParam .

Jika operasi asinkron tidak dapat dimulai, WSAAsyncGetHostByAddr mengembalikan nilai nol, dan nomor kesalahan tertentu dapat diambil dengan memanggil WSAGetLastError.

Kode kesalahan berikut dapat diatur saat jendela aplikasi menerima pesan. Seperti yang dijelaskan di atas, mereka dapat diekstraksi dari lParam dalam pesan balasan menggunakan makro WSAGETASYNCERROR .

Kode kesalahan	Makna
WSAENETDOWN	Subsistem jaringan gagal.
WSAENOBUFS	Ruang buffer tidak cukup tersedia.
WSAEFAULT	Parameter addr atau buf tidak berada di bagian ruang alamat proses yang valid.
WSAHOST_NOT_FOUND	Host jawaban otoritatif tidak ditemukan.
WSATRY_AGAIN	Host non-otoritatif tidak ditemukan, atau SERVERFAIL.
WSANO_RECOVERY	Kesalahan yang tidak dapat dipulihkan: FORMERR, REFUSED, NOTIMP.
WSANO_DATA	Nama yang valid, tidak ada catatan data dari jenis yang diminta.

Kesalahan berikut dapat terjadi pada saat panggilan fungsi, dan menunjukkan bahwa operasi asinkron tidak dapat dimulai.

Kode Kesalahan	Makna
WSANOTINITIALISED	Panggilan WSAStartup yang berhasil harus terjadi sebelum menggunakan fungsi ini.
WSAENETDOWN	Subsistem jaringan gagal.
WSAEINPROGRESS	Panggilan Windows Sockets 1.1 yang diblokir sedang berlangsung, atau penyedia layanan masih memproses fungsi panggilan balik.
WSAEWOULDBLOCK	Operasi asinkron tidak dapat dijadwalkan saat ini karena sumber daya atau batasan lain dalam implementasi Windows Sockets.

Keterangan

Fungsi WSAAsyncGetHostByAddr adalah versi asinkron dari gethostbyaddr. Ini digunakan untuk mengambil nama host dan informasi alamat yang sesuai dengan alamat jaringan. Windows Sockets memulai operasi dan segera kembali ke pemanggil, meneruskan kembali handel tugas buram dan asinkron yang dapat digunakan aplikasi untuk mengidentifikasi operasi. Ketika operasi selesai, hasilnya (jika ada) disalin ke dalam buffer yang disediakan oleh pemanggil dan pesan dikirim ke jendela aplikasi.

Ketika operasi asinkron telah selesai, jendela aplikasi yang ditunjukkan oleh parameter hWnd menerima pesan dalam parameter wMsg . Parameter wParam berisi handel tugas asinkron seperti yang dikembalikan oleh panggilan fungsi asli. LParam 16 bit tinggi berisi kode kesalahan apa pun. Kode kesalahan dapat berupa kesalahan apa pun seperti yang didefinisikan dalam Winsock2.h. Kode kesalahan nol menunjukkan keberhasilan penyelesaian operasi asinkron.

Setelah berhasil diselesaikan, buffer yang ditentukan ke panggilan fungsi asli berisi struktur hostent . Untuk mengakses anggota struktur ini, alamat buffer asli ditransmisikan ke penunjuk struktur hosten dan diakses sebagaimana mestinya.

Jika kode kesalahan adalah WSAENOBUFS, ukuran buffer yang ditentukan oleh buflen dalam panggilan asli terlalu kecil untuk berisi semua informasi yang dihasilkan. Dalam hal ini, lParam 16 bit rendah berisi ukuran buffer yang diperlukan untuk menyediakan semua informasi yang diperlukan. Jika aplikasi memutuskan bahwa data parsial tidak memadai, aplikasi dapat mengeluarkan kembali panggilan fungsi WSAAsyncGetHostByAddr dengan buffer yang cukup besar untuk menerima semua informasi yang diinginkan (yaitu, tidak lebih kecil dari 16 bit lParam yang rendah).

Buffer yang ditentukan untuk fungsi ini digunakan oleh Windows Sockets untuk membangun struktur bersama dengan konten area data yang dirujuk oleh anggota struktur hosten yang sama. Untuk menghindari kesalahan WSAENOBUFS , aplikasi harus menyediakan buffer setidaknya MAXGETHOSTSTRUCT byte (seperti yang didefinisikan dalam Winsock2.h).

Kode kesalahan dan panjang buffer harus diekstraksi dari lParam menggunakan makro WSAGETASYNCERROR dan WSAGETASYNCBUFLEN, didefinisikan dalam Winsock2.h sebagai:

#include <windows.h>

#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)
#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)

Penggunaan makro ini akan memaksimalkan portabilitas kode sumber untuk aplikasi.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	winsock.h (termasuk Winsock2.h, Winsock.h)
Pustaka	Ws2_32.lib
DLL	Ws2_32.dll