Fungsi ConnectNamedPipe (namedpipeapi.h)

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

Sintaksis

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

Parameter

[in] hNamedPipe

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

[in, out, optional] lpOverlapped

Penunjuk ke struktur TUMPANG TINDIH.

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

Jika hNamedPipe dibuat dengan FILE_FLAG_OVERLAPPED dan lpOverlapped tidak NULL , struktur 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 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, panggil GetLastError.

Jika operasi tidak sinkron, ConnectNamedPipe 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.

Komentar

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 tergantung 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 diberi sinyal, dan kemudian dapat menggunakan makro HasOverlappedIoCompleted untuk menentukan kapan operasi ConnectNamedPipe selesai.

Jika handel pipa yang ditentukan dalam mode nonblocking, ConnectNamedPipe selalu 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 berada 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 dan yang lebih baru: Pipes tidak dapat digunakan untuk berkomunikasi antara kontainer aplikasi; yaitu, dari satu proses UWP ke proses UWP lain yang bukan bagian dari aplikasi yang sama. Selain itu, pipa bernama dalam app-containers harus menggunakan sintaks '\\.\pipe\LOCAL\' untuk nama pipa.

Contoh

Misalnya, lihatMultithreaded Pipe Server .

Persyaratan

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

Lihat juga

CallNamedPipe

CreateEvent

CreateFile

CreateNamedPipe

DisconnectNamedPipe

GetOverlappedResult

TUMPANG TINDIH

Pipe Functions

Gambaran Umum Pipa

setNamedPipeHandleState

SleepEx

  • Last updated on