Platform SDK: Interprocess Communications |
The pipe server specifies the pipe access, overlap, and write-through modes in the dwOpenMode parameter of the CreateNamedPipe function. The pipe clients can specify these open modes for their pipe handles using the CreateFile function.
Setting the pipe access mode is equivalent to specifying read or write access associated with the pipe server's handles. The following table shows the CreateFile equivalent for each access mode you can specify with CreateNamedPipe.
CreateNamedPipe Access Mode | CreateFile Equivalent |
---|---|
PIPE_ACCESS_INBOUND | GENERIC_READ (server only reads and client only writes) |
PIPE_ACCESS_OUTBOUND | GENERIC_WRITE (server only writes and client only reads) |
PIPE_ACCESS_DUPLEX | GENERIC_READ | GENERIC_WRITE (server and client both read and write) |
Pipe clients using CreateFile to connect to a named pipe must specify an access mode in the dwDesiredAccess parameter that is compatible with the access mode specified by the pipe server. For example, a client must specify GENERIC_READ access for a pipe created with PIPE_ACCESS_OUTBOUND. The access modes must be the same for all instances of a pipe.
In overlapped mode, functions performing lengthy read, write, and connect operations can return immediately. This enables the thread to perform other operations while a time-consuming operation is executing in the background. To specify overlapped mode, use the FILE_FLAG_OVERLAPPED flag. For more information, see Synchronous and Overlapped Input and Output.
The CreateFile function allows the pipe client to set overlapped mode (FILE_FLAG_OVERLAPPED) for its pipe handles using the dwFlagsAndAttributes parameter.
Specify write-through mode with FILE_FLAG_WRITE_THROUGH. This mode affects only write operations to byte-type pipes between pipe clients and pipe servers on different computers. In write-through mode, the functions that write to a named pipe do not return until the data is transmitted across the network and into the pipe's buffer on the remote computer. Write-through mode is useful for applications that require synchronization for every write operation.
If write-through mode is not enabled, the system enhances the efficiency of network operations by buffering data until a minimum number of bytes have accumulated or until a maximum time period has elapsed. Buffering enables the system to combine multiple write operations into a single network transmission. This means that a write operation can be successfully completed after the system puts the data in the outbound buffer, but before the system transmits it across the network.
The CreateFile function allows the pipe client to set write-through mode (FILE_FLAG_WRITE_THROUGH) for its pipe handles using the dwFlagsAndAttributes parameter. The write-through mode of a pipe handle cannot be changed after the pipe handle has been created. The write-through mode can be different for server and client handles to the same pipe instance.
A pipe client can use the SetNamedPipeHandleState function to control the number of bytes and the time-out period before transmission for a pipe on which write-through mode is disabled.