Named Pipe Implementation Details

Named pipes are designed around the Windows file system using the Named Pipe File System (NPFS) interface. As a result, client and server applications use standard Win32 file system API functions such as ReadFile and WriteFile to send and receive data. Using these API functions allows applications to take advantage of Win32 file system naming conventions and Windows NT or Windows 2000 file system security. NPFS relies on the MSNP redirector to send and receive named pipe data over a network. This makes the interface protocol-independent: when developing an application that uses named pipes to form communications among processes across a network, a programmer does not have to worry about the details of underlying network transport protocols, such as TCP and IPX. Named pipes are identified to NPFS using the Universal Naming Convention (UNC). Chapter 2 describes the UNC, the Windows redirector, and security in greater detail.

Named Pipe Naming Conventions

Named pipes are identified using the following UNC format:

 \\server\Pipe\[path]name 

The string above is divided into three parts: \\server, \Pipe, and \[path]name. The first string part, \\server, represents the server name in which a named pipe is created and the server that listens for incoming connections. The second part, \Pipe, is a hardcoded mandatory string requirement for identifying that this filename belongs to NPFS. The third part, \[path]name, allows applications to uniquely define and identify a named pipe name, and it can have multiple levels of directories. For example, the following name types are legal for identifying a named pipe:

 \\myserver\PIPE\mypipe \\Testserver\pipe\cooldirectory\funtest\jim \\.\Pipe\Easynamedpipe 

The server string portion can be represented as a dot (.) or a server name.

Byte Mode and Message Mode

Named pipes offer two basic communication modes: byte mode and message mode. In byte mode, messages travel as a continuous stream of bytes between the client and the server. This means that a client application and a server application do not know precisely how many bytes are being read from or written to a pipe at any given moment. So a write on one side will not always result in a same-size read on the other. This allows a client and a server to transfer data without regard to the contents of the data. In message mode, the client and the server send and receive data in discrete units. Every time a message is sent on the pipe, it must be read as a complete message. Figure 4-1 compares the two pipe modes.

Figure 4-1. Byte mode and message mode

Compiling Applications

When you build a named pipe client or server application using Microsoft Visual C++, your application must include the Winbase.h file in your program files. But if your application includes Windows.h—as most do—you can omit Winbase.h. Your application is also responsible for linking with Kernel32.lib, which typically is configured with the Visual C++ linker flags.

Error Codes

All Win32 API functions (except CreateFile and CreateNamedPipe) that are used in developing named pipe client and server applications return the value 0 when they fail. CreateFile and CreateNamedPipe return INVALID_HANDLE_VALUE. When either of these functions fails, applications should call the GetLastError function to retrieve specific information about the failure. For a complete list of error codes, consult the header file Winerror.h or see Appendix C, "Winsock Error Codes."