Description
The TransactNamedPipe function performs a bidirectional synchronous I/O operation on the specified named pipe. This function is useful for sending a request to a named pipe server and receiving a response in a single operation.
It combines a write operation (sending the request) and a read operation (receiving the response) into one atomic transaction. The operation completes when either the specified timeout has expired or the entire transaction is complete.
Syntax
BOOL TransactNamedPipe(
HANDLE hNamedPipe,
LPINOUT_BUFFER lpvTransaction,
DWORD nTransactionSize,
LPBOOL pfPending,
LPOVERLAPPED lpOverlapped,
LPDWORD lpcbBytesTransferred
);Parameters
| Parameter | Description |
|---|---|
hNamedPipe |
A handle to the named pipe. This handle must have been created by the CreateNamedPipe function and opened with the FILE_FLAG_OVERLAPPED flag. |
lpvTransaction |
A pointer to a buffer that contains the data to be written to the pipe. The server writes its response to this same buffer. The buffer must be large enough to hold the data sent by the client and the data returned by the server. |
nTransactionSize |
The size of the buffer pointed to by lpvTransaction, in bytes. |
pfPending |
A pointer to a boolean value that receives TRUE if the I/O operation is pending, or FALSE otherwise. This parameter is only relevant if lpOverlapped is not NULL. |
lpOverlapped |
A pointer to an OVERLAPPED structure that is used for asynchronous operation. If this parameter is NULL, the function blocks until the operation is complete. |
lpcbBytesTransferred |
A pointer to a DWORD value that receives the number of bytes transferred, in bytes. This value is only valid if the operation is completed synchronously. If the operation is asynchronous, the value is valid when the OVERLAPPED operation completes. |
Return Value
| Value | Description |
|---|---|
TRUE |
If the function succeeds, the return value is TRUE. |
FALSE |
If the function fails, the return value is FALSE. To get extended error information, call GetLastError. |
Remarks
- The
TransactNamedPipefunction is a convenient way to perform a synchronous request-response communication pattern with a named pipe server. - If
lpOverlappedisNULL, the function is synchronous. It will block until the entire transaction is complete or an error occurs. - If
lpOverlappedis notNULL, the function is asynchronous. It will return immediately, and the completion of the operation is indicated by the status of theOVERLAPPEDstructure and the value ofpfPending. - The buffer pointed to by
lpvTransactionis used for both sending data to the server and receiving data from the server. The client first writes its request data to the beginning of the buffer, and thenTransactNamedPipesends this data. The server reads the request, processes it, and writes its response back into the same buffer. Finally,TransactNamedPipereads the server's response into the buffer. - The size of the data written by the server must not exceed the size of the data written by the client. If the server's response is larger than the client's request, the remaining data will be read in subsequent read operations.
- The
nTransactionSizeparameter should represent the maximum possible size of the data exchanged in the transaction, including both the client's request and the server's response. - If the operation is synchronous,
lpcbBytesTransferredwill contain the total number of bytes transferred for the transaction. - If the operation is asynchronous,
lpcbBytesTransferredwill be valid only after theOVERLAPPEDoperation has completed.
Important: For asynchronous operations, ensure that the
hNamedPipe handle was created with the FILE_FLAG_OVERLAPPED flag. The OVERLAPPED structure should be properly initialized, and the event object within it should be used to wait for completion.