CServerMailslot & CClientMailslot v1.24

These 2 freeware C++ classes provides a clean interface to the Win32 IPC mechanism called mailslots. They are very similar to the more common "Named Pipe" IPC mechanism. Unlike named pipes, mailslots use datagrams and do not offer any form of integrated security like Named Pipes do. A datagram is a small packet of information that the network sends along the wire. Like a radio or television broadcast, a datagram offers no confirmation of receipt; there is no way to guarantee that a datagram has been received.

Mailslots can broadcast messages within a domain. If several processes in a domain each create a mailslot using the same name, every message that is addressed to that mailslot and sent to the domain is received by the participating processes. Because one process can control both a server and client mailslot handle, applications can easily implement a simple message-passing facility within a domain.

The sample application contains a demonstration program called WinNotify. It is based on the old MS WinPopup utility.

Features

• Simple and clean C++ interface.
• The classes are fully Unicode compliant and include Unicode built options in the workspace file.

Usage

• To use the class in your code simply #include Mailslot.h in which ever of your modules needs to make calls to the classes.
• To see the class in action, have a look at the module "WinNotifyDoc.cpp/h".

Copyright

• You are allowed to include the source code in any product (commercial, shareware, freeware or otherwise) when your product is released in binary form.
• You are allowed to modify the source code in any way you want except you cannot modify the copyright details at the top of each module.
• If you want to distribute source code with your application, then you are only allowed to distribute versions released by the author. This is to maintain a single distribution point for the source code.

History

v1.24 (9 April 2022)

• Updated copyright details.
• Updated the code to use C++ uniform initialization for all variable declarations.

v1.23 (3 May 2020)

• Fixed more Clang-Tidy static code analysis warnings in the code.

v1.22 (26 December 2019)

• Fixed various Clang-Tidy static code analysis warnings in the code.
• Replaced BOOL with bool throughout the code.

v1.21 (21 September 2019)

• Fixed a number of compiler warnings when the code is compiled with VS 2019 Preview

v1.20 (3 June 2019)

• Updated copyright details
• Updated the code to clean compile on VC 2019

v1.19 (14 October 2018)

• Updated copyright details.
• Fixed a number of C++ core guidelines compiler warnings. These changes mean that the code will now only compile on VC 2017 or later.

v1.18 (30 April 2017)

• Updated copyright details.
• Updated the code to compile cleanly using /permissive-.

v1.17 (16 January 2016)

• Updated copyright details.
• Verified the code compiles cleanly in VC 2015

v1.16 (10 May 2015)

• Updated copyright details.
• Updated the project settings to more modern defaults
• Removed all unnecessary TRACE calls
• Made the classes into a header only implementation
• Updated the code to clean compile on VC 2013
• Reworked the CServerMailslot::Open and CClientMailslot::Open to provide the full mailslot name as its first parameter. This allows the class to avoid the use of CString
• Addition of a CServerMailslot::GetInfo method which encapsulates GetMailslotInfo.
• Removed the CServerMailslot::MessageWaiting, MessageCount, SizeOfWaitingMessage, MaximumMessageSize, GetCreationTime, GetLastAccessTime & GetLastWriteTime methods
• Added SAL annotations to all the code
• Reworked the CServerMailslot::Read method to use a pointer for returning the number of bytes read
• Reworked the CClientMailslot::Write method to use a pointer for returning the number of bytes write
• Replaced all ASSERT calls with ATLASSERT. This means that the class can now be used without the need to pull in MFC

v1.15 (7 September 2008)

• Updated copyright details.
• Code now compiles cleanly using Code Analysis (/analyze)
• Updated code to compile correctly using _ATL_CSTRING_EXPLICIT_CONSTRUCTORS define
• Updated sample app to clean compile on VC 2008
• The code has now been updated to support VC 2005 or later only.
• Removed VC 6 style AppWizard comments from the code.
• Updated the sample app to improve on the error reporting.

v1.14 (8 September 2007)

• Updated copyright details.
• Minor code tidy up.

v1.13 (23 December 2006)

• Code now uses CString instead of raw TCHAR buffers in various functions
• Classes now do not derive from CObject as it was not really required

v1.12 (22 December 2006)

• Updated copyright details
• Updated the documentation to use the same style as the web site
• Optimized CServerMailslot constructor code
• Addition of a CMAILSLOT_EXT_CLASS preprocessor macro to allow the classes to be more easily added to an extension dll
• Reviewed all TRACE statements for correctness
• Optimized CClientMailslot constructor code
• Updated the code to clean compile on VC 2005
• Code now uses newer C++ style casts instead of C style casts.
• Changed the default size of the FormView window in the sample ap to avoid scroll bars using default fonts.

v1.11 (26 July 2003)

• Updated copyright details.
• Fixed issue in CClientMailslot::Open which was causing it to only allow one instance of the mailslot to be opened. Thanks to GdP Software for reporting this problem.

v1.1 (26 July 1998)

• Provision of Unicode build configurations
• Updated make file to VC 5 format
• Fixed a bug in CClientMailslot destructor
• CServerMailslot::Close() & CClientMailslot::Close() now work correctly when the mailslot is already closed
• Fixed a level 4 warning in the CWinNotifyDoc in the demo program.
• Complete documentation for the classes is now provided in the form of this file
• Changed 2 functions which used a pointer parameter to now use a C++ reference instead.

API Reference

The API consists of the 2 classes CServerMailslot and CClientMailslot and their public members

Server Side

CServerMailslot::CServerMailslot
CServerMailslot::~CServerMailslot
CServerMailslot::Open
CServerMailslot::Close
CServerMailslot::Read
CServerMailslot::GetInfo
CServerMailslot::SetReadTimeout
CServerMailslot::IsOpen
CServerMailslot::operator Handle

Client Side

CClientMailslot::CClientMailslot
CClientMailslot::~CClientMailslot
CClientMailslot::Open
CClientMailslot::Close
CClientMailslot::Write
CClientMailslot::IsOpen
CClientMailslot::operator Handle

CServerMailslot::CServerMailslot

CServerMailslot();

Remarks

Standard constructor which initializes member variables to a default value

See Also

CServerMailslot::~CServerMailslot

CServerMailslot::~CServerMailslot

~CServerMailslot();

Remarks

Standard destructor which closes the mailslot if open

See Also

CServerMailslot::CServerMailslot

CServerMailslot::Open

bool CServerMailslot::Open(LPCTSTR lpszName, DWORD dwMaxMessageSize = 0, DWORD dwReadTimeout = 0, LPSECURITY_ATTRIBUTES lpSecurityAttributes = nullptr);

Return Value

true if the mailslot was successfully created otherwise false. If the call fails, you should use GetLastError to determine the reason.

Parameters

lpszName Pointer to a null-terminated string specifying the name of the mailslot.

dwMaxMessageSize Specifies the maximum size, in bytes, of a single message that can be written to the mailslots. To specify that the message can be of any size, set this value to zero.

dwReadTimeout Specifies the amount of time, in milliseconds, a read operation can wait for a message to be written to the mailslot before a time-out occurs. The following values have special meanings:

This time-out value applies to all subsequent read operations and all inherited mailslot handles.

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.

Remarks

Creates a server side mailslot

CServerMailslot::Close

bool CServerMailslot::Close();

Return Value

true if the mailslot was successfully closed otherwise false. If the call fails, you should use GetLastError to determine the reason.

CServerMailslot::Read

bool CServerMailslot::Read(LPVOID lpBuffer, DWORD dwNumberOfBytesToRead, DWORD* lpNumberOfBytesRead);

Parameters

lpBuffer pointer to buffer that receives data

dwNumberOfBytesToRead number of bytes to read

lpNumberOfBytesRead pointer to number of bytes read

Remarks

Allows data to be read from the mailslot

CServerMailslot::GetInfo

bool CServerMailslot::GetInfo(LPDWORD lpMaxMessageSize, LPDWORD lpNextSize, LPDWORD lpMessageCount, LPDWORD lpReadTimeout);

Return Value

true if the function succeeded otherwise false. If the call fails, you should use GetLastError to determine the reason.

Parameters

lpMaxMessageSize Pointer to the maximum size in bytes allowed for this mailslot which is returned on a successful call to this method.

lpNextSize Pointer to the size of the next message in bytes which is returned on a successful call to this method.

lpMessageCount Pointer to the total number of messages waiting to be read which is returned on a successful call to this method.

lpReadTimeout Pointer to the amount of time in milliseconds a read operation waits for a message to be written to the mailslot before a time-out occur which is returned on a successful call to this method.

Remarks

Simple wrapper for the GetMailslotInfo API

CServerMailslot::SetReadTimeout

bool CServerMailslot::SetReadTimeout(DWORD dwReadTimeout);

Return Value

true if the mailslot timeout was successfully changed otherwise false. If the call fails, you should use GetLastError to determine the reason.

Parameters

dwReadTimeout Specifies the amount of time, in milliseconds, a read operation can wait for a message to be written to the mailslot before a time-out occurs. The following values have special meanings:

This time-out value applies to all subsequent read operations and to all inherited mailslot handles.

Remarks

The initial time-out value used by a mailslot for a read operation is typically set by Open when the mailslot is created.

CServerMailslot::IsOpen

bool CServerMailslot::IsOpen();

Return Value

true if the mailslot is open otherwise false.

CServerMailslot::operator HANDLE()

HANDLE CServerMailslot::operator HANDLE();

Return Value

The underlying handle which the class encapsulates.

CClientMailslot::CClientMailslot

CClientMailslot();

Remarks

Standard constructor which initializes member variables to a default value

See Also

CClientMailslot::~CClientMailslot

CClientMailslot::~CClientMailslot

~CClientMailslot();

Remarks

Standard destructor which closes the mailslot if open

See Also

CClientMailslot::CClientMailslot

CClientMailslot::Open

bool CClientMailslot::Open(LPCTSTR lpszName, LPSECURITY_ATTRIBUTES lpSecurityAttributes = nullptr);

Return Value

true if the mailslot was successfully opened otherwise false. If the call fails, you should use GetLastError to determine the reason.

Parameters

lpszName Name of the mailslot to open.

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.

Remarks

Opens the client connection to a mailslot on a specified machine

CClientMailslot::Close

bool CClientMailslot::Close();

Return Value

true if the mailslot was successfully closed otherwise false. If the call fails, you should use GetLastError to determine the reason.

CClientMailslot::Write

bool CClientMailslot::Write(LPVOID lpBuffer, DWORD dwNumberOfBytesToWrite, DWORD& dwNumberOfBytesWrite);

Parameters

lpBuffer pointer to data that is to be written

dwNumberOfBytesToWrite number of bytes to write

dwNumberOfBytesRead pointer to number of bytes written

Remarks

Allows data to be written to the mailslot

CClientMailslot::IsOpen

bool CClientMailslot::IsOpen();

Return Value

true if the mailslot is open otherwise false.

CClientMailslot::operator HANDLE()

HANDLE CClientMailslot::operator HANDLE();

Return Value

The underlying handle which the class encapsulates.

Contacting the Author

PJ Naughter
Email: pjna@naughter.com
Web: http://www.naughter.com
9 April 2022