Other API Calls

Other API Calls

There are several additional named pipe functions that we haven't touched on yet. The first set of these API functions— CallNamedPipe and TransactNamedPipe— is designed to reduce coding complexity in an application. Both functions perform a write and read operation in one call. The CallNamedPipe function allows a client application to connect to a message-type pipe (and waits if an instance of the pipe is not available), writes to and reads from the pipe, and then closes the pipe. This is practically an entire client application written in one call. CallNamedPipe is defined as follows :

BOOL CallNamedPipe( LPCTSTR lpNamedPipeName, LPVOID lpInBuffer, DWORD nInBufferSize, LPVOID lpOutBuffer, DWORD nOutBufferSize, LPDWORD lpBytesRead, DWORD nTimeOut );

The lpNamedPipeName parameter is a string that represents the named pipe in UNC form. The lpInBuffer and nInBufferSize parameters represent the address and the size of the buffer that the application uses to write data to the server. The lpOutBuffer and nOutBufferSize parameters represent the address and the size of the buffer that the application uses to retrieve data from the server. The lpBytesRead parameter receives the number of bytes read from the pipe. The nTimeOut parameter specifies how many milliseconds to wait for the named pipe to be available.

The TransactNamedPipe function can be used in both a client and a server application. It is designed to combine read and write operations in one API call, thus optimizing network I/O by reducing send and receive transactions in the MSNP redirector. TransactNamedPipe is defined as follows:

BOOL TransactNamedPipe( HANDLE hNamedPipe, LPVOID lpInBuffer, DWORD nInBufferSize, LPVOID lpOutBuffer, DWORD nOutBufferSize, LPDWORD lpBytesRead, LPOVERLAPPED lpOverlapped );

The hNamedPipe parameter identifies the named pipe returned by the CreateNamedPipe or CreateFile API functions. The lpInBuffer and nInBufferSize parameters represent the address and the size of the buffer that the application uses to write data to the pipe. The lpOutBuffer and nOutBufferSize parameters represent the address and the size of the buffer that the application uses to retrieve data from the pipe. The lpBytesRead parameter receives the number of bytes read from the pipe. The lpOverlapped parameter allows this TransactNamedPipe to operate asynchronously using overlapped I/O.

The next set of functions— GetNamedPipeHandleState , SetNamedPipeHandleState , and GetNamedPipeInfo— are designed to make named pipe client and server communication more flexible at run time. For example, you can use these functions to change the operating mode of a pipe at run time from message mode to byte mode and vice versa. GetNamedPipeHandleState retrieves information such as the operating mode (message mode and byte mode), pipe instance count, and buffer caching information about a specified named pipe. The information that GetNamedPipeHandleState returns can vary during the lifetime of an instance of the named pipe. GetNamedPipeHandleState is defined as follows:

BOOL GetNamedPipeHandleState( HANDLE hNamedPipe, LPDWORD lpState, LPDWORD lpCurInstances, LPDWORD lpMaxCollectionCount, LPDWORD lpCollectDataTimeout, LPTSTR lpUserName, DWORD nMaxUserNameSize );

The hNamedPipe parameter identifies the named pipe returned by the CreateNamedPipe or CreateFile function. The lpState parameter is a pointer to a variable that receives the current operating mode of the pipe handle. The lpState parameter can return the value PIPE_NOWAIT or the value PIPE_READMODE_MESSAGE . The lpCurInstances parameter is a pointer to a variable that receives the number of current pipe instances. The lpMaxCollectionCount parameter receives the maximum number of bytes to be collected on the client's computer before transmission to the server. The lpCollectDataTimeout parameter receives the maximum time in milliseconds that can pass before a remote named pipe transfers information over a network. The lpUserName and nMaxUserNameSize parameters represent a buffer that receives a null- terminated string containing the user name string of the client application.

{% if main.adsdop %}{% include 'adsenceinline.tpl' %}{% endif %}

The SetNamedPipeHandleState function allows you to change the pipe characteristics retrieved with GetNamedPipeHandleState . SetNamedPipeHandleState is defined as follows:

BOOL SetNamedPipeHandleState( HANDLE hNamedPipe, LPDWORD lpMode, LPDWORD lpMaxCollectionCount, LPDWORD lpCollectDataTimeout );

The hNamedPipe parameter identifies the named pipe returned by CreateNamedPipe or CreateFile . The lpMode parameter sets the operating mode of a pipe. The lpMaxCollectionCount parameter specifies the maximum number of bytes collected on the client computer before data is transmitted to the server. The lpCollectDataTimeout parameter specifies the maximum time in milliseconds that can pass before a remote named pipe client transfers information over the network.

The GetNamedPipeInfo API function is used to retrieve buffer size and maximum pipe instance information. GetNamedPipeInfo is defined as follows:

BOOL GetNamedPipeInfo( HANDLE hNamedPipe, LPDWORD lpFlags, LPDWORD lpOutBufferSize, LPDWORD lpInBufferSize, LPDWORD lpMaxInstances );

The hNamedPipe parameter identifies the named pipe returned by Create-NamedPipe or CreateFile . The lpFlags parameter retrieves the type of the named pipe and determines whether it is a server or a client and whether the pipe is in byte mode or message mode. The lpOutBufferSize parameter determines the size in bytes of the internal buffer for outgoing data. The lpInBufferSize parameter receives the size of the internal buffer for incoming data. The lpMaxInstance parameter receives the maximum number of pipe instances that can be created.

The final API function, PeekNamedPipe , allows an application to look at the data in a named pipe without removing it from the pipe's internal buffer. This function is useful if an application wants to poll for incoming data to avoid blocking on the ReadFile API call. The function can also be useful for applications that need to examine data before they actually receive it. For example, an application might want to adjust its application buffers based on the size of incoming messages. PeekNamedPipe is defined as follows:

BOOL PeekNamedPipe( HANDLE hNamedPipe, LPVOID lpBuffer, DWORD nBufferSize, LPDWORD lpBytesRead, LPDWORD lpTotalBytesAvail, LPDWORD lpBytesLeftThisMessage );

The hNamedPipe parameter identifies the named pipe returned by Create-NamedPipe or CreateFile . The lpBuffer and nBufferSize parameters represent the receiving buffer along with the receiving buffer size to retrieve data from the pipe. The lpBytesRead parameter receives the number of bytes read from the pipe into the lpBuffer parameter. The lpTotalBytesAvail parameter receives the total number of bytes that are available to be read from the pipe. The lpBytesLeftThisMessage parameter receives the number of bytes remaining in a message if a pipe is opened in message mode. If a message cannot fit in the lpBuffer parameter, the remaining bytes in a message are returned. This parameter always returns 0 for byte-mode named pipes.