| BOOL ConnectNamedPipe(hNamedPipe, lpo) | |||||
| HANDLE hNamedPipe; | /* handle of named pipe to connect | */ | |||
| LPOVERLAPPED lpo; | /* address of overlapped structure | */ | |||
The ConnectNamedPipe function is used by the server side of a named pipe to wait for a client to connect to the named pipe (with the CreateFile function).
hNamedPipe
Specifies a handle to the server side of a named pipe. This handle is returned by the CreateNamedPipe function.
lpo
Points to an OVERLAPPED structure. May be NULL if overlapped operation is not desired. See the Comments section for a description of how the pipe mode and the OVERLAPPED structure interact to determine how the pipe behaves.
The OVERLAPPED structure has the following form:
typedef struct _OVERLAPPED { /* o */
DWORD Internal;
DWORD InternalHigh;
DWORD Offset;
DWORD OffsetHigh;
HANDLE hEvent;
} OVERLAPPED;
typedef OVERLAPPED *LPOVERLAPPED;
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.
The behavior of this function depends on the current state of the pipe instance which can be any of the following:
| State | Meaning |
| Listening | The pipe instance is waiting for a client process to connect. This is the initial state of a new instance. An instance in the Disconnected state can be changed to the Listening state by calling ConnectNamedPipe. An instance must be in the Listening state before a client can connect. |
| Connected | A client has connected to the pipe instance by calling CreateFile or CallNamedPipe. The state of a Connected instance changes to Closing when the client closes its handle, or to Disconnected when the server calls DisconnectNamedPipe. Only Connected pipes can be written to or read from. |
| Disconnected | The DisconnectNamedPipe function has been called for the pipe instance. |
| Closing | The client has closed its handle to the pipe instance, but the server has not disconnected. The server must call DisconnectNamedPipe before it can be reconnected to a new client. |
If the state of the pipe instance is Connected when ConnectNamedPipe is called, the function will return FALSE with GetLastError returning ERROR_PIPE_CONNECTED. This can occur when the instance was in a Listening state and a client connected before the call to ConnectNamedPipe. In this situation, there is a good connection between client and server even though the function returned FALSE.
If the state of the pipe instance is Closing when ConnectNamedPipe is called, the function will return FALSE with GetLastError returning ERROR_NO_DATA.
If the state of the pipe instance is Listening or Disconnected when ConnectNamedPipe is called, the function's behavior depends on the blocking and overlapped modes specified when the pipe was created.
ConnectNamedPipe will be executed synchronously if FILE_FLAG_OVERLAPPED was not specified when the pipe was created, or if the lpOverlapped parameter is NULL. Otherwise, the function is executed as an overlapped operation.
If blocking mode (PIPE_WAIT) was specified:
| Mode | Description |
| Synchronous | The function will block with the pipe instance in a Listening state, returning TRUE when a client connects (except in the cases noted above where the instance state was Connected or Closing). |
| Overlapped | The function will return immediately with a return value of FALSE and GetLastError will return ERROR_IO_PENDING (except in the cases noted above where the instance state was Connected or Closing). The OVERLAPPED structure should contain a handle to an event object. The event is set to the Not-Signalled state before ConnectNamedPipe returns, and is set to the Signalled state when a client connects to the named pipe. If the OVERLAPPED structure does not contain an event handle, the pipe handle is used to signal completion. Use of the pipe handle for this purpose is not recommended due to complications when simultaneous overlapped operations are performed on the same pipe instance. GetOverlappedResult is used to determine the function's result when GetLastError returns ERROR_IO_PENDING. |
If non-blocking mode (PIPE_NOWAIT) was specified, the ConnectNamedPipe function returns immediately. If the state of the instance was Disconnected, the function returns TRUE and the state is changed to Listening. Otherwise, FALSE is returned with the GetLastError return value depending on the instance state: ERROR_PIPE_LISTENING (Listening), ERROR_PIPE_CONNECTED (Connected), or ERROR_NO_DATA (Closing). Note that a good connection between client and server exists only after the ERROR_PIPE_CONNECTED error is received. Non-blocking mode is supported for compatibility with LanMan 2.0, and should not be used to achieve asynchronous (overlapped) I/O with named pipes.
CreateNamedPipe, DisconnectNamedPipe, GetOverlappedResult