Platform SDK: Interprocess Communications
Multithreaded Pipe Server

The following example is a multithreaded pipe server. It has a main thread with a loop that creates a pipe instance and waits for a pipe client to connect. When a pipe client connects, the pipe server creates a thread to service that client and then continues to execute the loop. It is possible for a pipe client to connect successfully to the pipe instance in the interval between calls to the CreateNamedPipe and ConnectNamedPipe functions. If this happens, ConnectNamedPipe returns zero, and GetLastError returns ERROR_PIPE_CONNECTED.


The thread created to service each pipe instance reads requests from the pipe and writes replies to the pipe until the pipe client closes its handle. When this happens, the thread flushes the pipe, disconnects, closes its pipe handle, and terminates.

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <windows.h>

VOID InstanceThread(LPVOID);
VOID GetAnswerToRequest(LPTSTR, LPTSTR, LPDWORD);

int xx = 0;

DWORD main(VOID)
{
BOOL fConnected;
DWORD dwThreadId;
HANDLE hPipe, hThread;
LPTSTR lpszPipename = "\\\\.\\pipe\\mynamedpipe";

// The main loop creates an instance of the named pipe and
// then waits for a client to connect to it. When the client
// connects, a thread is created to handle communications
// with that client, and the loop is repeated.

for (;;)
{
hPipe = CreateNamedPipe(
lpszPipename, // pipe name
PIPE_ACCESS_DUPLEX, // read/write access
PIPE_TYPE_MESSAGE | // message type pipe
PIPE_READMODE_MESSAGE | // message-read mode
PIPE_WAIT, // blocking mode
PIPE_UNLIMITED_INSTANCES, // max. instances
BUFSIZE, // output buffer size
BUFSIZE, // input buffer size
PIPE_TIMEOUT, // client time-out
NULL); // no security attribute

if (hPipe == INVALID_HANDLE_VALUE)
MyErrExit("CreatePipe");

// Wait for the client to connect; if it succeeds,
// the function returns a nonzero value. If the function returns
// zero, GetLastError returns ERROR_PIPE_CONNECTED.

fConnected = ConnectNamedPipe(hPipe, NULL) ?
TRUE : (GetLastError() == ERROR_PIPE_CONNECTED);

if (fConnected)
{
// Create a thread for this client.
hThread = CreateThread(
NULL, // no security attribute
0, // default stack size
(LPTHREAD_START_ROUTINE) InstanceThread,
(LPVOID) hPipe, // thread parameter
0, // not suspended
&dwThreadId); // returns thread ID

if (hThread == NULL)
MyErrExit("CreateThread");
else
CloseHandle(hThread);

}
else
// The client could not connect, so close the pipe.
CloseHandle(hPipe);
}
return 1;
}

VOID InstanceThread(LPVOID lpvParam)
{
CHAR chRequest[BUFSIZE];
CHAR chReply[BUFSIZE];
DWORD cbBytesRead, cbReplyBytes, cbWritten;
BOOL fSuccess;
HANDLE hPipe;

// The thread's parameter is a handle to a pipe instance.

hPipe = (HANDLE) lpvParam;

while (1)
{
// Read client requests from the pipe.
fSuccess = ReadFile(
hPipe, // handle to pipe
chRequest, // buffer to receive data
BUFSIZE, // size of buffer
&cbBytesRead, // number of bytes read
NULL); // not overlapped I/O

if (! fSuccess || cbBytesRead == 0)
break;
GetAnswerToRequest(chRequest, chReply, &cbReplyBytes);

// Write the reply to the pipe.
fSuccess = WriteFile(
hPipe, // handle to pipe
chReply, // buffer to write from
cbReplyBytes, // number of bytes to write
&cbWritten, // number of bytes written
NULL); // not overlapped I/O

if (! fSuccess || cbReplyBytes != cbWritten) break;
}

// Flush the pipe to allow the client to read the pipe's contents
// before disconnecting. Then disconnect the pipe, and close the
// handle to this pipe instance.

FlushFileBuffers(hPipe);
DisconnectNamedPipe(hPipe);
CloseHandle(hPipe);
}

Platform SDK: Interprocess Communications
Named Pipe Client

A named pipe client uses the CreateFile function to open a handle to a named pipe. If the pipe exists but all of its instances are busy, CreateFile returns zero and the GetLastError function returns ERROR_PIPE_BUSY. When this happens, the named pipe client uses the WaitNamedPipe function to wait for an instance of the named pipe to become available.


The CreateFile function fails if the access specified is incompatible with the access specified (duplex, outbound, or inbound) when the server created the pipe. For a duplex pipe, the client can specify read, write, or read/write access; for an outbound pipe (write-only server), the client must specify read-only access; and for an inbound pipe (read-only server), the client must specify write-only access.

The handle returned by CreateFile defaults to byte-read mode, blocking-wait mode, overlapped mode disabled, and write-through mode disabled. The pipe client can use CreateFile to enable overlapped mode by specifying FILE_FLAG_OVERLAPPED or to enable write-through mode by specifying FILE_FLAG_WRITE_THROUGH. The client can use the SetNamedPipeHandleState function to enable nonblocking mode by specifying PIPE_WAIT or to enable message-read mode by specifying PIPE_READMODE_MESSAGE.

The following example shows a pipe client that opens a named pipe, sets the pipe handle to message-read mode, uses the WriteFile function to send a request to the server, and uses the ReadFile function to read the server's reply. This pipe client can be used with any of the message-type servers shown in the previous examples. With a byte-type server, however, this pipe client fails when it calls SetNamedPipeHandleState to change to message-read mode. Because the client is reading from the pipe in message-read mode, it is possible for the ReadFile operation to return zero after reading a partial message. This happens when the message is larger than the read buffer. In this situation, GetLastError returns ERROR_MORE_DATA, and the client can read the remainder of the message using additional calls to ReadFile.

#include <windows.h>

DWORD main(int argc, char *argv[])
{
HANDLE hPipe;
LPVOID lpvMessage;
CHAR chBuf[512];
BOOL fSuccess;
DWORD cbRead, cbWritten, dwMode;
LPTSTR lpszPipename = "\\\\.\\pipe\\mynamedpipe";

// Try to open a named pipe; wait for it, if necessary.

while (1)
{
hPipe = CreateFile(
lpszPipename, // pipe name
GENERIC_READ | // read and write access
GENERIC_WRITE,
0, // no sharing
NULL, // no security attributes
OPEN_EXISTING, // opens existing pipe
0, // default attributes
NULL); // no template file

// Break if the pipe handle is valid.

if (hPipe != INVALID_HANDLE_VALUE)
break;

// Exit if an error other than ERROR_PIPE_BUSY occurs.

if (GetLastError() != ERROR_PIPE_BUSY)
MyErrExit("Could not open pipe");

// All pipe instances are busy, so wait for 20 seconds.

if (! WaitNamedPipe(lpszPipename, 20000) )
MyErrExit("Could not open pipe");
}

// The pipe connected; change to message-read mode.

dwMode = PIPE_READMODE_MESSAGE;
fSuccess = SetNamedPipeHandleState(
hPipe, // pipe handle
&dwMode, // new pipe mode
NULL, // don't set maximum bytes
NULL); // don't set maximum time
if (!fSuccess)
MyErrExit("SetNamedPipeHandleState");

// Send a message to the pipe server.

lpvMessage = (argc > 1) ? argv[1] : "default message";

fSuccess = WriteFile(
hPipe, // pipe handle
lpvMessage, // message
strlen(lpvMessage) + 1, // message length
&cbWritten, // bytes written
NULL); // not overlapped
if (! fSuccess)
MyErrExit("WriteFile");

do
{
// Read from the pipe.

fSuccess = ReadFile(
hPipe, // pipe handle
chBuf, // buffer to receive reply
512, // size of buffer
&cbRead, // number of bytes read
NULL); // not overlapped

if (! fSuccess && GetLastError() != ERROR_MORE_DATA)
break;

// Reply from the pipe is written to STDOUT.

if (! WriteFile(GetStdHandle(STD_OUTPUT_HANDLE),
chBuf, cbRead, &cbWritten, NULL))
{
break;
}

} while (! fSuccess); // repeat loop if ERROR_MORE_DATA

CloseHandle(hPipe);

return 0;
}

Platform SDK: Interprocess Communications
Transactions on Named Pipes

A named pipe transaction is a client-server communication that combines a write operation and a read operation into a single network operation. A transaction can be used only on a duplex, message-type pipe. Transactions improve the performance of network communications between a client and a remote server. Processes can use the TransactNamedPipe and CallNamedPipe functions to perform named pipe transactions.


The TransactNamedPipe function is most commonly used by a pipe client to write a request message to the named pipe server and read the server's response message. The pipe client must specify GENERIC_READ | GENERIC_WRITE access when it opens its pipe handle by calling the CreateFile function. Then, the pipe client sets the pipe handle to message-read mode by calling the SetNamedPipeHandleState function. If the read buffer specified in the call to TransactNamedPipe is not large enough to hold the entire message written by the server, the function returns zero and GetLastError returns ERROR_MORE_DATA. The client can read the remainder of the message by calling either the ReadFile, ReadFileEx, or PeekNamedPipe function.

TransactNamedPipe is typically called by pipe clients, but can also be used by a pipe server.

The following example shows a pipe client using TransactNamedPipe. The example assumes that the pipe client has used CreateFile to connect to the pipe and SetNamedPipeHandleState to set the pipe handle's read mode, as shown in the pipe client example in the preceding topic.

fSuccess = TransactNamedPipe(
hPipe, // pipe handle
lpszWrite, // message to server
strlen(lpszWrite)+1, // message length
chReadBuf, // buffer to receive reply
512, // size of read buffer
&cbRead, // number of bytes read
NULL); // not overlapped

// Exit if an error occurs, unless the error indicates there is more
// data in the message.

if (!fSuccess && (GetLastError() != ERROR_MORE_DATA))
{
MyErrExit("TransactNamedPipe");
}

while(1)
{
// Data from the pipe is written to STDOUT.

if (! WriteFile(GetStdHandle(STD_OUTPUT_HANDLE),
chReadBuf, cbRead, &cbWritten, NULL) )
break;

// Break if TransactNamedPipe or ReadFile is successful.

if (fSuccess)
break;

// Read from the pipe if there is more data in the message.

fSuccess = ReadFile(
hPipe, // pipe handle
chReadBuf, // buffer to receive reply
512, // size of buffer
&cbRead, // number of bytes read
NULL); // not overlapped

// Exit if an error other than ERROR_MORE_DATA occurs.

if (! fSuccess && (GetLastError() != ERROR_MORE_DATA))
break;
}
A pipe client uses CallNamedPipe to combine the CreateFile, WaitNamedPipe (if necessary), TransactNamedPipe, and CloseHandle function calls into a single call. Because the pipe handle is closed before the function returns, any additional bytes in the message are lost if the message is larger than the specified size of the read buffer. The following example shows the use of CallNamedPipe.

// Combines connect, wait, write, read, and close operations.

fSuccess = CallNamedPipe(
lpszPipename, // pipe name
lpszWrite, // message to server
strlen(lpszWrite)+1, // message length
chReadBuf, // buffer to receive reply
512, // size of read buffer
&cbRead, // number of bytes read
20000); // waits for 20 seconds

if (fSuccess || GetLastError() == ERROR_MORE_DATA)
{

// Data from the pipe is written to STDOUT.

WriteFile(GetStdHandle(STD_OUTPUT_HANDLE),
chReadBuf, cbRead, &cbWritten, NULL);

// The pipe is closed, so no more bytes can be read from the
// message.

if (! fSuccess)
printf("\n...extra data in message was lost\n");
}