SetNamedPipeHandleState
The SetNamedPipeHandleState
function sets the read mode and the blocking mode of the specified named pipe.
If the specified handle is to the client end of a named pipe and if the named
pipe server process is on a remote computer, the function can also be used to
control local buffering.
BOOL SetNamedPipeHandleState(
|
HANDLE hNamedPipe, |
// handle of named
pipe |
|
LPDWORD lpMode, |
// address of new
pipe mode |
|
LPDWORD lpMaxCollectionCount, |
// address of max.
bytes before remote transmission |
|
LPDWORD lpCollectDataTimeout |
// address of max.
time before remote transmission |
|
); |
|
Parameters
hNamedPipe
Identifies
the named pipe instance. This parameter can be a handle to the server end of
the pipe, as returned by the CreateNamedPipe21DZYT function, or to the client end of the
pipe, as returned by the CreateFile function. The handle must have GENERIC_WRITE
access to the named pipe.
lpMode
Points to a
32-bit variable that supplies the new mode. The mode is a combination of a
read-mode flag and a wait-mode flag. This parameter can be NULL if the mode is
not being set. One of the following read modes can be specified:
|
Mode |
Description |
|
PIPE_READMODE_BYTE |
Data is
read from the pipe as a stream of bytes. This mode is the default if no
read-mode flag is specified. |
|
PIPE_READMODE_MESSAGE |
Data is
read from the pipe as a stream of messages. The function fails if this flag
is specified for a byte-type pipe. |
One of the
following wait modes can be specified:
|
Mode |
Description |
|
PIPE_WAIT |
Blocking
mode is enabled. This mode is the default if no wait-mode flag is specified.
When a blocking mode pipe handle is specified in the ReadFile, WriteFile, or ConnectNamedPipe function, operations are
not finished until there is data to read, all data is written, or a client is
connected. Use of this mode can mean waiting indefinitely in some situations
for a client process to perform an action. |
|
PIPE_NOWAIT |
Nonblocking
mode is enabled. In this mode, ReadFile, WriteFile, and ConnectNamedPipe
always return immediately. Note that nonblocking mode is supported for compatibility
with Microsoft LAN Manager version 2.0 and should not be used to
achieve asynchronous input and output (I/O) with named pipes. |
lpMaxCollectionCount
Points to a 32-bit
variable that specifies the maximum number of bytes collected on the client
computer before transmission to the server. This parameter must be NULL if the
specified pipe handle is to the server end of a named pipe or if client and
server processes are on the same machine. This parameter is ignored if the
client process specifies the FILE_FLAG_WRITE_THROUGH flag in the CreateFile
function when the handle was created. This parameter can be NULL if the
collection count is not being set.
lpCollectDataTimeout
Points to a
32-bit variable that specifies the maximum time, in milliseconds, that can pass
before a remote named pipe transfers information over the network. This
parameter must be NULL if the specified pipe handle is to the server end of a
named pipe or if client and server processes are on the same computer. This
parameter is ignored if the client process specified the
FILE_FLAG_WRITE_THROUGH flag in the CreateFileXN35YD function when the handle was created. This
parameter can be NULL if the collection count is not being set.
Return Values
If the
function succeeds, the return value is nonzero.
If the
function fails, the return value is zero. To get extended error information,
call GetLastError.
See Also