CNamedPipe v1.17CNamedPipe v1.17Welcome to CNamedPipe, A freeware C++ class to encapsulate the Named Pipe Inter Process Communication mechanism as provided in Win32.
| Copyright |
| Features |
| Usage |
| History |
| API Reference |
| Contacting the Author |
v1.17 (20 March 2022)
v1.16 (4 May 2020)
v1.15 (14 March 2020)
v1.14 (2 June 2019)
v1.13 (26 August 2018)
v1.12 (19 December 2017)
1 May 2017
V1.11 (1 June 2015)
v1.10 (12 July 2008)
v1.09 (30 November 2007)
v1.08 (29 November 2007)
v1.07 (15 July 2006)
v1.06 (19 November 2003)
v1.05 (12 November 2003)
v1.04 (5 March 2003)
v1.03 (9 November 2002)
v1.02 (28 July 2002)
v1.01 (21 February 2002)
v1.0 (2 August 1998)
The API consists of the class CNamedPipe and its public member functions:
CNamedPipe
~CNamedPipe
Create
Open
operator HANDLE
Close
Attach
Detach
Connect
Disconnect
Flush
Write
Read
Peek
Transact
IsOpen
CNamedPipe();
Remarks
Standard default constructor. Initialises the pipe handle to a default value.
See Also
~CNamedPipe();
Remarks
Standard default destructor. Will close any pipe handles which are still open
See Also
BOOL Create(LPCTSTR lpszName, DWORD dwOpenMode, DWORD dwPipeMode, DWORD dwMaxInstances, DWORD dwOutBufferSize, DWORD dwInBufferSize, DWORD dwDefaultTimeOut, LPSECURITY_ATTRIBUTES lpSecurityAttributes = NULL);
Return Value
Non zero if successful otherwise 0.
Parameters
lpszName Points to the null-terminated string that uniquely identifies the pipe. It can include any character other than a backslash, including numbers and special characters. The entire pipe name string can be up to 256 characters long. Pipe names are not case sensitive.
dwOpenMode Specifies the pipe access mode, the overlapped mode, the write-through mode, and the security access mode of the pipe handle. For more information on this parameter see the MSDN documentation for CreateFile.
dwPipeMode Specifies the type, read, and wait modes of the pipe handle. For more information on this parameter see the MSDN documentation for CreateFile.
nMaxInstances Specifies the maximum number of instances that can be created for this pipe. The same number must be specified for all instances. Acceptable values are in the range 1 through PIPE_UNLIMITED_INSTANCES. If this parameter is PIPE_UNLIMITED_INSTANCES, the number of pipe instances that can be created is limited only by the availability of system resources.
nOutBufferSize Specifies the number of bytes to reserve for the output buffer. For a discussion on sizing named pipe buffers, see the following Remarks section.
nInBufferSize Specifies the number of bytes to reserve for the input buffer. For a discussion on sizing named pipe buffers, see the following Remarks section.
nDefaultTimeOut Specifies the default time-out value, in milliseconds, if the WaitNamedPipe function specifies NMPWAIT_USE_DEFAULT_WAIT. Each instance of a named pipe must specify the same value.
lpSecurityAttributes Pointer to a SECURITY_ATTRIBUTES structure that specifies a security descriptor for the new named pipe and determines whether child processes can inherit the returned handle. If lpSecurityAttributes is NULL, the named pipe gets a default security descriptor and the handle cannot be inherited.
Remarks
Creates a server side named pipe. Please note that currently Microsoft only provide this functionality on Windows NT (workstation or Server) and not Windows 95 or Windows 98.
BOOL Open(LPCTSTR lpszServerName, LPCTSTR lpszPipeName, DWORD dwDesiredAccess, DWORD dwShareMode, LPSECURITY_ATTRIBUTES lpSecurityAttributes = NULL, DWORD dwFlagsAndAttributes = 0);
Return Value
Non zero if successful otherwise 0.
Parameters
lpszServerName Name of the machine where the server side of the named pipe resides. It can be "." to represent this machine.
lpszPipeName Name of the pipe to connect to
dwDesiredAccess Specifies the type of access to the pipe. An application can obtain read access, write access, read-write access, or device query access. For more information on this parameter see the MSDN documentation for CreateFile.
dwShareMode Set of bit flags that specifies how the object can be shared. If dwShareMode is 0, the object cannot be shared. Subsequent open operations on the object will fail, until the handle is closed. For more information on this parameter see the MSDN documentation for CreateFile.
lpSecurityAttributes Pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If lpSecurityAttributes is NULL, the handle cannot be inherited.
dwFlagsAndAttributes Specifies the file attributes and flags for the pipe. For more information on this parameter see the MSDN documentation for CreateFile.
Remarks
Opens a client side connection to a named pipe. Unlike the server side creation of a named pipe, this function does not have any Win32 OS considerations.
HANDLE operator HANDLE() const;
Return Value
Returns the underlying HANDLE which this instance encapsulates or INVALID_HANDLE_VALUE if this instance is not open.
void Close();
Remarks
Closes the pipe
void Attach(HANDLE hPipe, BOOL bAutoClose = TRUE);
Parameters
hPipe SDK handle of an existing pipe to attach to.
bAutoClose TRUE if the pipe handle should be closed when the pipe object goes out of scope or CNamedPipe::Close is called.
HANDLE Detach();
Return Value
The handle of the pipe which this instance was encapsulating.
Remarks
Detaches the C++ instance from the SDK pipe handle.
BOOL Connect(LPOVERLAPPED lpOverlapped = NULL);
Return Value
Non zero if successful otherwise 0.
Parameters
lpOverlapped pointer to an OVERLAPPED structure to use if this pipe was opened in a overlapped mode.
Remarks
Call by a server side pipe to connect a client connection. In the sockets world this corresponds very closely to an accept call.
BOOL Disconnect();
Return Value
Non zero if successful otherwise 0.
Parameters
This is the corollary function to ConnectClient and for each call to ConnectClient in your server side application there should be a corresponding call to DisconnectClient.
BOOL Flush();
Return Value
Non zero if successful otherwise 0
Remarks
Flushes any data which may be buffered in the pipe.
BOOL Write(LPCVOID lpBuffer, DWORD
nNumberOfBytesToWrite, LPOVERLAPPED lpOverlapped
= NULL, LPDWORD lpNumberOfBytesWritten =
NULL, LPOVERLAPPED lpOverlapped =
NULL);
BOOL WriteEx(LPCVOID lpBuffer, DWORD nNumberOfBytesToWrite,
LPOVERLAPPED lpOverlapped, LPOVERLAPPED_COMPLETION_ROUTINE
lpCompletionRoutine);
Return Value
Non zero if successful otherwise 0.
Parameters
lpBuffer Points to the buffer containing the data to be written to the pipe.
nNumberOfBytesToWrite Specifies the number of bytes to write to the pipe.
lpNumberOfBytesWritten Upon successful return will contain the number of bytes written.
lpOverlapped Points to an OVERLAPPED structure. This structure is required if the pipe was opened with FILE_FLAG_OVERLAPPED.
lpCompletionRoutine Points to a completion routine to be called when the write operation has been completed and the calling thread is in an alertable wait state.
Remarks
Performs a write to the named pipe. The first version can be used in a synchronous or asynchronous manner where as the second version can be used in an asynchronous manner only.
BOOL Read(LPVOID lpBuffer, DWORD dwNumberOfBytesToRead,
LPDWORD lpNumberOfBytesRead = NULL, LPOVERLAPPED lpOverlapped = NULL);
BOOL ReadEx(LPVOID lpBuffer, DWORD dwNumberOfBytesToRead,
LPOVERLAPPED lpOverlapped, LPOVERLAPPED_COMPLETION_ROUTINE
lpCompletionRoutine);
Return Value
Non zero if successful otherwise 0.
Parameters
lpBuffer Points to the buffer to receive the data to be read.
dwNumberOfBytesToWrite Specifies the number of bytes to read from the pipe.
lpNumberOfBytesRead Upon successful return will contain the number of bytes read.
lpOverlapped Points to an OVERLAPPED structure. This structure is required if the pipe was opened with FILE_FLAG_OVERLAPPED.
lpCompletionRoutine Points to a completion routine to be called when the read operation has been completed and the calling thread is in an alertable wait state.
Remarks
Performs a read from the named pipe. The first version can be used in a synchronous or asynchronous manner where as the second version can be used in an asynchronous manner only.
BOOL Peek(LPVOID lpBuffer, DWORD nBufferSize,
DWORD* lpBytesRead, DWORD* lpTotalBytesAvail, DWORD* lpBytesLeftThisMessage);
Return Value
Non zero if successful otherwise 0.
Parameters
lpBuffer Points to a buffer that receives data read from the pipe. This parameter can be NULL if no data is to be read.
nBufferSize Specifies the size, in bytes, of the buffer specified by the lpBuffer parameter. This parameter is ignored if lpBuffer is NULL.
lpBytesRead Upon successful return will contain the number of bytes read.
lpdwTotalBytesAvail Pointer to a 32-bit variable that receives the total number of bytes available to be read from the pipe.
lpdwBytesLeftThisMessage Pointer to a 32-bit variable that receives the number of bytes remaining in this message. This parameter will be zero for byte-type named pipes
Remarks
Copies data from the pipe into a buffer without removing it from the pipe. It also returns information about data in the pipe.
BOOL Transact(LPVOID lpInBuffer, DWORD nInBufferSize, LPVOID lpOutBuffer, DWORD nOutBufferSize, LPDWORD lpBytesRead, LPOVERLAPPED lpOverlapped = NULL);
Return Value
Non zero if successful otherwise 0.
Parameters
lpInBuffer Points to the buffer containing the data written to the pipe.
nInBufferSize Specifies the size, in bytes, of the write buffer.
lpOutBuffer Points to the buffer that receives the data read from the pipe.
nOutBufferSize Specifies the size, in bytes, of the read buffer.
lpBytesRead variable that receives the number of bytes read from the pipe.
lpOverlapped Points to an OVERLAPPED structure. This structure is required if the pipe was opened with FILE_FLAG_OVERLAPPED.
Remarks
Combines into a single network operation the functions that write a message to and read a message from the specified named pipe.
BOOL IsOpen() const;
Return Value
Non zero if the pipe is open otherwise FALSE.
PJ Naughter
Email: pjna@naughter.com
Web: http://www.naughter.com
20 March 2022