GetNamedPipeHandleState

  BOOL GetNamedPipeHandleState(hNamedPipe, lpdwState, lpdwCurInstances, lpcbMaxCollect, lpdwCollectTimeout, lpszUser, cchMaxUser)    
  HANDLE hNamedPipe; /* named-pipe handle */
  LPDWORD lpdwState; /* gets flags indicating pipe state */
  LPDWORD lpdwCurInstances; /* gets number of current pipe instances */
  LPDWORD lpcbMaxCollect; /* gets max bytes before remote transmission */
  LPDWORD lpdwCollectTimeout; /* max time before remote transmission */
  LPTSTR lpszUser; /* gets username of client process */
  DWORD cchMaxUser; /* size in characters of username buffer */

The GetNamedPipeHandleState function retrieves information about a given named pipe handle. The information returned by this function can vary during the lifetime of an instance of a named pipe. The handle must be created with the GENERIC_READ access rights.

Parameters

hNamedPipe

Specifies a handle to the named pipe. The handle must have GENERIC_READ access to the named pipe.

lpdwState

Points to a DWORD which will be set with flags indicating the current state of the handle. May be NULL if the information is not needed. The following flags may be specified:

Value Meaning

PIPE_NOWAIT Nonblocking mode is to be used for this handle. If this flag is not set, blocking mode is used.
PIPE_READMODE_MESSAGE Read the pipe as a message stream. If this flag is not set, the pipe is read as a byte stream.

lpdwCurInstances

Points to a DWORD which will be set with the number of current pipe instances. May be NULL if the information is not needed.

lpcbMaxCollect

Points to a DWORD which will be set to the maximum number of bytes that will be collected on the client's machine before transmission to the server. This parameter must be NULL on a handle to the server end of a named pipe or when client and server applications are on the same machine. May be NULL if the information is not needed.

lpdwCollectTimeout

Points to a DWORD which will be set to 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 handle is for the server end of a named pipe or when client and server applications are on the same machine. May be NULL if the information is not needed.

lpszUser

Points to a buffer which will be filled-in with the null-terminated string containing the name of the username of the client application. This parameter must be NULL on a handle to a client end of a named pipe, and may be NULL on a server handle if the information is not needed.

cchMaxUser

Specifies the size in characters of the memory allocated at lpszUser. Ignored if lpszUser is NULL.

Return Value

The return value is TRUE if the function was successful, or FALSE if an error occurred. Use the GetLastError function to obtain extended error information.

Comments

The GetNamedPipeHandleState function may be used as either a wide-character function (where text arguments must use Unicode) or an ANSI function (where text arguments must use characters from the Windows 3.x character set installed).

It is not an error if all of the pointers passed to this function are null.

See Also

SetNamedPipeHandleState