Makro WSAAsyncGetHostByName (wsipv6ok.h)

Artikel
03/15/2023

Fungsi WSAAsyncGetHostByName secara asinkron mengambil informasi host yang sesuai dengan nama host.

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

Sintaks

void WSAAsyncGetHostByName(
  [in]   a,
  [in]   b,
  [in]   c,
  [out]  d,
  [in]   e
);

Parameter

[in] a

Menangani jendela yang akan menerima pesan ketika permintaan asinkron selesai.

[in] b

Pesan yang akan diterima ketika permintaan asinkron selesai.

[in] c

Penunjuk ke nama host yang dihentikan null.

[out] d

Arahkan ke area data untuk menerima data yang dihosting . Area data harus lebih besar dari ukuran struktur hosten karena area data yang ditentukan digunakan oleh Windows Sockets untuk berisi struktur hosten dan semua data yang dirujuk oleh anggota struktur hosten . Buffer byte MAXGETHOSTSTRUCT disarankan.

[in] e

Ukuran area data untuk parameter buf , dalam byte.

Mengembalikan nilai

Tidak ada

Keterangan

Fungsi WSAAsyncGetHostByName adalah versi asinkron dari gethostbyname, dan digunakan untuk mengambil informasi nama host dan alamat yang sesuai dengan nama host. Windows Sockets memulai operasi dan segera kembali ke pemanggil, meneruskan kembali handel tugas asinkron buram 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 elemen struktur ini, alamat buffer asli harus 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 WSAAsyncGetHostByName 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 hostent 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.

WSAAsyncGetHostByName dijamin untuk menyelesaikan string yang dikembalikan oleh panggilan yang berhasil ke gethostname.

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	wsipv6ok.h (termasuk Winsock2.h, Winsock.h)
Pustaka	Ws2_32.lib
DLL	Ws2_32.dll