Fungsi TransactNamedPipe (namedpipeapi.h)

Artikel
03/08/2023

Menggabungkan fungsi yang menulis pesan ke dan membaca pesan dari pipa bernama yang ditentukan ke dalam satu operasi.

Sintaks

BOOL TransactNamedPipe(
  [in]                HANDLE       hNamedPipe,
  [in]                LPVOID       lpInBuffer,
  [in]                DWORD        nInBufferSize,
  [out]               LPVOID       lpOutBuffer,
  [in]                DWORD        nOutBufferSize,
  [out]               LPDWORD      lpBytesRead,
  [in, out, optional] LPOVERLAPPED lpOverlapped
);

Parameter

[in] hNamedPipe

Handel ke pipa bernama yang dikembalikan oleh fungsi CreateNamedPipe atau CreateFile .

Parameter ini juga dapat menjadi handel ke pipa anonim, seperti yang dikembalikan oleh fungsi CreatePipe .

[in] lpInBuffer

Penunjuk ke buffer yang berisi data yang akan ditulis ke pipa.

[in] nInBufferSize

Ukuran buffer input, dalam byte.

[out] lpOutBuffer

Penunjuk ke buffer yang menerima data yang dibaca dari pipa.

[in] nOutBufferSize

Ukuran buffer output, dalam byte.

[out] lpBytesRead

Penunjuk ke variabel yang menerima jumlah byte yang dibaca dari pipa.

Jika lpOverlapped adalah NULL, lpBytesRead tidak boleh NULL.

Jika lpOverlapped bukan NULL, lpBytesRead bisa null. Jika ini adalah operasi baca yang tumpang tindih, Anda bisa mendapatkan jumlah byte yang dibaca dengan memanggil GetOverlappedResult. Jika hNamedPipe dikaitkan dengan port penyelesaian I/O, Anda bisa mendapatkan jumlah byte yang dibaca dengan memanggil GetQueuedCompletionStatus.

[in, out, optional] lpOverlapped

Penunjuk ke struktur yang TUMPANG TINDIH . Struktur ini diperlukan jika hNamedPipe dibuka dengan FILE_FLAG_OVERLAPPED.

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

Jika hNamedPipe dibuka dengan FILE_FLAG_OVERLAPPED dan lpOverlapped bukan NULL, TransactNamedPipe dijalankan sebagai operasi yang tumpang tindih. Struktur YANG TUMPANG TINDIH harus berisi objek peristiwa reset manual (yang dapat dibuat dengan menggunakan fungsi CreateEvent ). Jika operasi tidak dapat segera diselesaikan, TransactNamedPipe mengembalikan FALSE dan GetLastError mengembalikan ERROR_IO_PENDING. Dalam situasi ini, objek peristiwa diatur ke status nonsignaled sebelum TransactNamedPipe kembali, dan diatur ke status sinyal ketika transaksi telah selesai. Selain itu, Anda dapat diberi tahu ketika operasi yang tumpang tindih selesai dengan menggunakan fungsi GetQueuedCompletionStatus atau GetQueuedCompletionStatusEx . Dalam hal ini, Anda tidak perlu menetapkan peristiwa reset manual dalam struktur YANG TUMPANG TINDIH , dan penyelesaian terjadi terhadap hNamedPipe dengan cara yang sama seperti operasi baca atau tulis asinkron. Untuk informasi selengkapnya tentang operasi yang tumpang tindih, lihat Pipa.

Jika hNamedPipe tidak dibuka dengan FILE_FLAG_OVERLAPPED, TransactNamedPipe tidak akan kembali hingga operasi selesai.

Mengembalikan nilai

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 pesan yang akan dibaca lebih panjang dari buffer yang ditentukan oleh parameter nOutBufferSize , TransactNamedPipe mengembalikan FALSE dan fungsi GetLastError mengembalikan ERROR_MORE_DATA. Sisa pesan dapat dibaca dengan panggilan berikutnya ke ReadFile, ReadFileEx, atau PeekNamedPipe.

Keterangan

TransactNamedPipe gagal jika server tidak membuat pipa sebagai pipa jenis pesan atau jika handel pipa tidak dalam mode baca pesan. Misalnya, jika klien berjalan pada komputer yang sama dengan server dan menggunakan format \.\pipe\pipename untuk membuka pipa, pipa dibuka dalam mode byte oleh sistem file pipa (NPFS) bernama. Jika klien menggunakan formulir \\server\pipe\pipename, pengalih membuka pipa dalam mode pesan. Handel pipa mode byte dapat diubah ke mode baca pesan dengan fungsi SetNamedPipeHandleState .

Fungsi tidak dapat diselesaikan dengan sukses sampai data ditulis ke dalam buffer yang ditentukan oleh parameter lpOutBuffer . Parameter lpOverlapped tersedia untuk mengaktifkan utas panggilan untuk melakukan tugas lain saat operasi dijalankan di latar belakang.

Ukuran maksimum yang dijamin dari transaksi pipa bernama adalah 64 kilobyte. Dalam beberapa kasus terbatas, transaksi di luar 64 kilobyte dimungkinkan, tergantung pada versi OS yang berpartisipasi dalam transaksi dan kondisi jaringan dinamis. Namun, tidak ada jaminan bahwa transaksi di atas 64 kilobyte akan berhasil. Oleh karena itu disarankan agar transaksi pipa bernama dibatasi hingga 64 kilobyte data.

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 Transaksi pada Pipa Bernama.

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