Fungsi ConnectNamedPipe (namedpipeapi.h)

Artikel
08/25/2023

Memungkinkan proses server pipa bernama menunggu proses klien tersambung ke instans pipa bernama. Proses klien tersambung dengan memanggil fungsi CreateFile atau CallNamedPipe .

Sintaks

BOOL ConnectNamedPipe(
  [in]                HANDLE       hNamedPipe,
  [in, out, optional] LPOVERLAPPED lpOverlapped
);

Parameter

[in] hNamedPipe

Handel ke akhir server dari instans pipa bernama. Handel ini dikembalikan oleh fungsi CreateNamedPipe .

[in, out, optional] lpOverlapped

Penunjuk ke struktur yang TUMPANG TINDIH .

Jika hNamedPipe dibuka dengan FILE_FLAG_OVERLAPPED, parameter lpOverlapped tidak boleh NULL. Ini harus menunjuk ke struktur TUMPANG TINDIH yang valid. Jika hNamedPipe dibuka dengan FILE_FLAG_OVERLAPPED dan lpOverlapped adalah NULL, fungsi dapat salah melaporkan bahwa operasi koneksi selesai.

Jika hNamedPipe dibuat dengan FILE_FLAG_OVERLAPPED dan lpOverlapped bukan NULL, struktur yang TUMPANG TINDIH harus berisi handel ke objek peristiwa reset manual (yang dapat dibuat server dengan menggunakan fungsi CreateEvent ).

Jika hNamedPipe tidak dibuka dengan FILE_FLAG_OVERLAPPED, fungsi tidak akan kembali hingga klien tersambung atau terjadi kesalahan. Operasi sinkron yang berhasil menghasilkan fungsi yang mengembalikan nilai bukan nol jika klien tersambung setelah fungsi dipanggil.

Mengembalikan nilai

Jika operasi sinkron, ConnectNamedPipe tidak akan kembali hingga operasi selesai. Jika fungsi berhasil, nilai yang dikembalikan bukan nol. Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Jika operasi tidak sinkron, ConnectNamedPipe akan segera kembali. Jika operasi masih tertunda, nilai yang dikembalikan adalah nol dan GetLastError mengembalikan ERROR_IO_PENDING. (Anda dapat menggunakan makro HasOverlappedIoCompleted untuk menentukan kapan operasi telah selesai.) Jika fungsi gagal, nilai yang dikembalikan adalah nol dan GetLastError mengembalikan nilai selain ERROR_IO_PENDING atau ERROR_PIPE_CONNECTED.

Jika klien tersambung sebelum fungsi dipanggil, fungsi mengembalikan nol dan GetLastError mengembalikan ERROR_PIPE_CONNECTED. Ini dapat terjadi jika klien terhubung dalam interval antara panggilan ke CreateNamedPipe dan panggilan ke ConnectNamedPipe. Dalam situasi ini, ada koneksi yang baik antara klien dan server, meskipun fungsi mengembalikan nol.

Keterangan

Proses server pipa bernama dapat menggunakan ConnectNamedPipe dengan instans pipa yang baru dibuat. Ini juga dapat digunakan dengan instans yang sebelumnya terhubung ke proses klien lain; dalam hal ini, proses server harus terlebih dahulu memanggil fungsi DisconnectNamedPipe untuk memutuskan pegangan dari klien sebelumnya sebelum handel dapat disambungkan kembali ke klien baru. Jika tidak, ConnectNamedPipe mengembalikan nol, dan GetLastError mengembalikan ERROR_NO_DATA jika klien sebelumnya telah menutup handel atau ERROR_PIPE_CONNECTED jika belum menutup handelnya.

Perilaku ConnectNamedPipe bergantung pada dua kondisi: apakah mode tunggu handel pipa diatur ke pemblokiran atau pemblokiran dan apakah fungsi diatur untuk dijalankan secara sinkron atau dalam mode tumpang tindih. Server awalnya menentukan mode tunggu handel pipa dalam fungsi CreateNamedPipe , dan dapat diubah dengan menggunakan fungsi SetNamedPipeHandleState .

Proses server dapat menggunakan salah satu fungsi tunggu atau SleepEx— untuk menentukan kapan status objek peristiwa disinyalkan, dan kemudian dapat menggunakan makro HasOverlappedIoCompleted untuk menentukan kapan operasi ConnectNamedPipe selesai.

Jika handel pipa yang ditentukan dalam mode nonblocking, ConnectNamedPipe akan segera kembali. Dalam mode nonblocking, ConnectNamedPipe mengembalikan nilai bukan nol saat pertama kali dipanggil untuk instans pipa yang terputus dari klien sebelumnya. Ini menunjukkan bahwa pipa sekarang tersedia untuk dihubungkan ke proses klien baru. Dalam semua situasi lain ketika handel pipa dalam mode nonblocking, ConnectNamedPipe mengembalikan nol. Dalam situasi ini, GetLastError mengembalikan ERROR_PIPE_LISTENING jika tidak ada klien yang terhubung, ERROR_PIPE_CONNECTED jika klien terhubung, dan ERROR_NO_DATA jika klien sebelumnya telah menutup handel pipanya tetapi server belum terputus. Perhatikan bahwa koneksi yang baik antara klien dan server hanya ada setelah kesalahan ERROR_PIPE_CONNECTED diterima.

Catatan Mode nonblocking didukung untuk kompatibilitas dengan Microsoft LAN Manager versi 2.0, dan tidak boleh digunakan untuk mencapai input dan output asinkron (I/O) dengan pipa bernama.

Windows 10, versi 1709: Pipa hanya didukung dalam kontainer aplikasi; yaitu, dari satu proses UWP ke proses UWP lain yang merupakan bagian dari aplikasi yang sama. Selain itu, pipa bernama harus menggunakan sintaks '\\.\pipe\LOCAL\' untuk nama pipa.

Contoh

Misalnya, lihat Multithreaded Pipe Server.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows 2000 Server [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	namedpipeapi.h
Pustaka	Kernel32.lib
DLL	Kernel32.dll