Bagikan melalui


Fungsi WSAAsyncGetServByName (winsock.h)

Fungsi WSAAsyncGetServByName secara asinkron mengambil informasi layanan yang sesuai dengan nama layanan dan port.

Sintaks

HANDLE WSAAsyncGetServByName(
  [in]  HWND       hWnd,
  [in]  u_int      wMsg,
  [in]  const char *name,
  [in]  const char *proto,
  [out] char       *buf,
  [in]  int        buflen
);

Parameter

[in] hWnd

Tangani jendela yang harus menerima pesan ketika permintaan asinkron selesai.

[in] wMsg

Pesan yang akan diterima ketika permintaan asinkron selesai.

[in] name

Penunjuk ke nama layanan yang dihentikan null.

[in] proto

Penunjuk ke nama protokol. Ini bisa NULL, dalam hal ini WSAAsyncGetServByName akan mencari entri layanan pertama yang s_name atau salah satu s_aliases cocok dengan nama yang diberikan. Jika tidak, WSAAsyncGetServByName cocok dengan nama dan proto.

[out] buf

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

[in] buflen

Ukuran area data untuk parameter buf , dalam byte.

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, WSAAsyncGetServByName mengembalikan nilai bukan nol dari jenis HANDLE yang merupakan handel tugas asinkron untuk permintaan (tidak akan dikacaukan dengan HTASK Windows). 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, WSAAsyncServByName 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 diekstrak dari lParam dalam pesan balasan menggunakan makro WSAGETASYNCERROR .

Kode kesalahan Makna
WSAENETDOWN
Subsistem jaringan gagal.
WSAENOBUFS
Ruang buffer tidak cukup tersedia.
WSAEFAULT
Parameter buf tidak berada di bagian ruang alamat proses yang valid.
WSAHOST_NOT_FOUND
Host jawaban otoritatif tidak ditemukan.
WSATRY_AGAIN
Layanan non-otoritatif tidak ditemukan, atau kegagalan server.
WSANO_RECOVERY
Kesalahan yang tidak dapat dipulihkan, database layanan tidak dapat diakses.
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 Pemblokiran panggilan Windows Sockets 1.1 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 WSAAsyncGetServByName adalah versi asinkron dari getservbyname dan digunakan untuk mengambil informasi layanan yang sesuai dengan nama layanan. 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 servent . Untuk mengakses anggota struktur ini, alamat buffer asli harus ditransmisikan ke penunjuk struktur servent 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 WSAAsyncGetServByName 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 servent bersama dengan konten area data yang dirujuk oleh anggota struktur servent yang sama. Untuk menghindari kesalahan WSAENOBUFS , aplikasi harus menyediakan buffer setidaknya byte MAXGETHOSTSTRUCT (seperti yang didefinisikan dalam Winsock2.h).

Kode kesalahan dan panjang buffer harus diekstrak 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)
Pustaka Ws2_32.lib
DLL Ws2_32.dll

Lihat juga

WSACancelAsyncRequest

Fungsi Winsock

Referensi Winsock

getservbyname