Fungsi panggilan balik VIRTUALCHANNELINIT (cchannel.h)

Artikel
03/08/2023

Menginisialisasi akses DLL klien ke saluran virtual Layanan Desktop Jarak Jauh. Klien memanggil VirtualChannelInit untuk mendaftarkan nama saluran virtualnya.

Layanan Desktop Jauh menyediakan penunjuk ke fungsi VirtualChannelInit dalam struktur CHANNEL_ENTRY_POINTS yang diteruskan ke titik masuk VirtualChannelEntry Anda.

Sintaks

VIRTUALCHANNELINIT Virtualchannelinit;

UINT VCAPITYPE Virtualchannelinit(
  [in]      LPVOID *ppInitHandle,
  [in, out] PCHANNEL_DEF pChannel,
  [in]      INT channelCount,
  [in]      ULONG versionRequested,
  [in]      PCHANNEL_INIT_EVENT_FN pChannelInitEventProc
)
{...}

Parameter

[in] ppInitHandle

Penunjuk ke variabel yang menerima handel yang mengidentifikasi koneksi klien. Gunakan handel ini untuk mengidentifikasi klien dalam panggilan berikutnya ke fungsi VirtualChannelOpen .

[in, out] pChannel

Penunjuk ke array struktur CHANNEL_DEF . Setiap struktur berisi opsi nama dan inisialisasi saluran virtual yang akan dibuka DLL klien. Perhatikan bahwa panggilan VirtualChannelInit tidak membuka saluran virtual ini; itu hanya mencadangkan nama untuk digunakan oleh aplikasi ini.

[in] channelCount

Menentukan jumlah entri dalam array pChannel .

[in] versionRequested

Menentukan tingkat dukungan saluran virtual. Atur parameter ini ke VIRTUAL_CHANNEL_VERSION_WIN2000.

[in] pChannelInitEventProc

Arahkan ke fungsi VirtualChannelInitEvent yang ditentukan aplikasi yang dipanggil Layanan Desktop Jauh untuk memberi tahu DLL klien tentang peristiwa saluran virtual.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan adalah CHANNEL_RC_OK.

Jika terjadi kesalahan, fungsi mengembalikan salah satu nilai berikut.

Keterangan

Anda dapat memanggil fungsi VirtualChannelInit hanya dari fungsi VirtualChannelEntry Anda. Panggilan ke VirtualChannelInit di lain waktu gagal.

Ketika VirtualChannelInit berhasil dikembalikan, Remote Desktop Services telah mendaftarkan saluran yang diminta. Namun, Layanan Desktop Jauh mungkin belum menyelesaikan inisialisasi lain. Ketika semua inisialisasi selesai, Layanan Desktop Jauh memanggil fungsi panggilan balik VirtualChannelInitEvent Anda dengan peristiwa CHANNEL_EVENT_INITIALIZED .

Anda tidak boleh membuat asumsi tentang jumlah saluran virtual yang tersedia sebelum memanggil fungsi ini, karena sistem dan plug-in lainnya mungkin telah memesan saluran virtual. Oleh karena itu, Anda harus selalu memeriksa kode pengembalian CHANNEL_RC_TOO_MANY_CHANNELS setelah memanggil fungsi ini.

Saat VirtualChannelInit kembali, anggota opsi dari setiap struktur CHANNEL_DEF menyertakan CHANNEL_OPTION_INITIALIZED jika saluran berhasil diinisialisasi.

Jumlah maksimum saluran per sesi klien adalah CHANNEL_MAX_COUNT.