Fungsi WPUQueueApc (ws2spi.h)

  • Artikel

Fungsi WPUQueueApc mengantrekan panggilan prosedur mode-asinkron pengguna (APC) ke utas yang ditentukan untuk memfasilitasi pemanggilan rutinitas penyelesaian I/O yang tumpang tindih.

Sintaks

int WPUQueueApc(
  [in]  LPWSATHREADID lpThreadId,
  [in]  LPWSAUSERAPC  lpfnUserApc,
  [in]  DWORD_PTR     dwContext,
  [out] LPINT         lpErrno
);

Parameter

[in] lpThreadId

Penunjuk ke struktur WSATHREADID yang mengidentifikasi konteks utas. Pointer ke struktur ini diberikan ke penyedia layanan oleh Ws2_32.dll sebagai parameter input ke operasi yang tumpang tindih. Penyedia harus menyimpan struktur WSATHREADID secara lokal dan menyediakan pointer ke penyimpanan lokal ini. Salinan lokal WSATHREADID tidak lagi diperlukan setelah WPUQueueApc kembali.

[in] lpfnUserApc

Arahkan ke fungsi APC yang akan dipanggil.

[in] dwContext

Nilai konteks 32-bit yang kemudian disediakan sebagai parameter input ke fungsi APC.

[out] lpErrno

Arahkan ke kode kesalahan.

Mengembalikan nilai

Jika tidak ada kesalahan yang terjadi, WPUQueueApc mengembalikan nol dan mengantrekan rutinitas penyelesaian untuk utas yang ditentukan. Jika tidak, kode mengembalikan SOCKET_ERROR, dan kode kesalahan tertentu tersedia di lpErrno.

Kode kesalahan Makna
WSAEFAULT
 Parameter dwThreadId tidak menentukan utas yang valid.
 
 

Keterangan

Fungsi ini mengantrekan fungsi APC terhadap utas yang ditentukan. Di bawah Windows, ini akan dilakukan menggunakan panggilan prosedur mode pengguna-asinkron (APC). APC hanya akan dijalankan ketika utas yang ditentukan diblokir dalam tunggu yang dapat diperingatkan dan panggilan balik akan dilakukan secara langsung. Panggilan ini aman untuk digunakan dalam konteks interupsi.

LPWSAUSERAPC didefinisikan sebagai berikut:

typedef void ( CALLBACK FAR * LPWSAUSERAPC )( DWORD dwContext );

Karena mekanisme APC hanya mendukung satu nilai konteks, lpfnUserApc sendiri tidak dapat menjadi rutinitas yang ditentukan klien–penyelesaian, yang melibatkan lebih banyak parameter. Penyedia layanan harus menyediakan penunjuk ke fungsi APC sendiri yang menggunakan nilai dwContext yang disediakan untuk mengakses informasi hasil yang diperlukan untuk operasi yang tumpang tindih, lalu memanggil rutinitas penyelesaian yang ditentukan klien.

Untuk penyedia layanan di mana komponen mode pengguna menerapkan I/O yang tumpang tindih, penggunaan umum mekanisme APC adalah sebagai berikut.

    - Ketika operasi I/O selesai, penyedia mengalokasikan buffer kecil dan mengemasnya dengan pointer ke prosedur penyelesaian yang disediakan klien dan nilai parameter untuk diteruskan ke prosedur. - Ini mengantre APC, menentukan pointer ke buffer sebagai nilai dwContext dan prosedur perantaranya sendiri sebagai prosedur target lpfnUserApc. - Ketika utas target akhirnya memasuki status tunggu yang dapat diperingatkan, prosedur perantara penyedia layanan dipanggil dalam konteks utas yang tepat. - Prosedur perantara hanya membongkar parameter, membatalkan alokasi buffer, dan memanggil prosedur penyelesaian yang disediakan klien.

Persyaratan

   
Klien minimum yang didukung Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung Windows 2000 Server [hanya aplikasi desktop]
Target Platform Windows
Header ws2spi.h

Lihat juga

WSATHREADID

LPWSPIoctl

LPWSPRecv

LPWSPRecvFrom

LPWSPSend

LPWSPSendTo