Download source files - 29 Kb
Introduction
These 2 classes provide a clean C++ interface to the little known but quite
powerful WIn32 IPC mechanism called mailslots. They are very similar to the more common
Named Pipe IPC mechanism. Unlike named pipes, mailslots use datagrams. 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 mailslot handle and the client handle retrieved when the
mailslot is opened for a write operation, applications can easily implement a simple
message-passing facility within a domain.
Another advantage that mailslots have over named pipes is that the server mailslot
(the mailslot which can read) can be created on Windows 95. This is unlike
named pipes which can only be created server side on Windows NT.
The source zip file contains the source code for the 2 classes and also includes a VC 5
workspace file to build a demonstration program called WinNotify. People who have used
the WinPopup utility supplied with Windows 95 will notice the "Striking similarity"
between it and the demonstration program as show above.
- Simple and clean C++ interface.
- The classes are fully Unicode compliant and include Unicode built options in the
workspace file.
- To use the class in your code simply include mailslot.cpp in your project and
#include mailslot.h in which ever of your modules needs to make calls to the class.
- Your code will need to include MFC either statically or dynamically.
- To see the class in action, have a look at the module WinNotifyDoc.cpp/.h.
V1.1 (26 July 1998)
- Provision of Unicode build configurations.
- 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 a HTML file.
- Changed 2 functions which used a pointer parameter to now use a C++ reference instead.
V1.11 (10 August 1998)
- Fixed a bug in the
Close() function of both classes where the mailslot handle
was not being set back to INVALID_HANDLE_VALUE.
11 August 1998
- Inclusion of a VC 5 make file.
- Tidy up of the resources the program uses plus their names.
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::MessageWaiting
CServerMailslot::MessageCount
CServerMailslot::SizeOfWaitingMessage
CServerMailslot::MaximumMessageSize
CServerMailslot::SetReadTimeout
CServerMailslot::GetCreationTime
CServerMailslot::GetLastAccessTime
CServerMailslot::GetLastWriteTime
CServerMailslot::IsOpen
CServerMailslot::operator Handle
CServerMailslot::AssertValid
CServerMailslot::Dump
Client Side
CClientMailslot::CClientMailslot
CClientMailslot::~CClientMailslot
CClientMailslot::Open
CClientMailslot::Close
CClientMailslot::Write
CClientMailslot::IsOpen
CClientMailslot::operator Handle
CClientMailslot::AssertValid
CClientMailslot::Dump
- CServerMailslot::CServerMailslot
- CServerMailslot::CServerMailslot();
Remarks:
Standard constructor which initializes member variables to a default value.
See Also:
CServerMailslot::~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 = NULL);
Return Value:
TRUE if the mailslot was successfully created otherwise FALSE. If the call fails, you should
use GetLastError() to determine the reason.
Parameters:
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& dwNumberOfBytesRead);
Return Value:
TRUE if the mailslot was successfully read otherwise FALSE.
Parameters:
- lpBuffer -- Pointer to buffer that receives data.
- dwNumberOfBytesToRead -- Number of bytes to read.
- dwNumberOfBytesRead -- Pointer to number of bytes read.
Remarks:
Allows data to be read from the mailslot.
- CServerMailslot::MessageWaiting
- BOOL CServerMailslot::MessageWaiting();
Return Value:
TRUE if the mailslot was has a message waiting otherwise FALSE. If the call fails, you should use
GetLastError() to determine the reason.
Remarks:
Allows data to be read from the mailslot.
- CServerMailslot::MessageCount
- DWORD CServerMailslot::MessageCount();
Return Value:
The number of messages waiting in the mailslot.
Remarks:
Allows the number of messages waiting in the mailslot to be determined.
- CServerMailslot::SizeOfWaitingMessage
- DWORD CServerMailslot::SizeofWaitingMessage();
Return Value:
The size in bytes of the message waiting in the mailslot.
Remarks:
Allows the size of the next message in the mailslot to be determined.
- CServerMailslot::MaximumMessageSize
- DWORD CServerMailslot::MaximumMessageSize();
Return Value:
The maximum size of size in bytes of the message waiting in the mailslot.
Remarks:
Returns the maximum message size, in bytes, allowed for this mailslot. This value can be greater
than or equal to the value specified in the Open()
function that created the mailslot.
- 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:
| Value | Meaning |
| 0 | Returns immediately if no message is present. (The system does not treat an
immediate return as an error.) |
| MAILSLOT_WAIT_FOREVER | Waits forever for a message. |
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::GetCreationTime
- BOOL CServerMailslot::GetCreationTime(LPFILETIME lpCreationTime);
Return Value:
TRUE if the mailslot creation time was successfully retrieved otherwise FALSE. If the call fails,
you should use GetLastError() to determine the reason.
Parameters:
- lpCreationTime -- Pointer to a
FILETIME structure to receive the date
and time the file was created.
- CServerMailslot::GetLastAccessTime
- BOOL CServerMailslot::GetLastAccessTime(LPFILETIME lpLastAccessTime);
Return Value:
TRUE if the mailslot last access time was successfully retrieved otherwise FALSE. If the call fails,
you should use GetLastError() to determine the reason.
Parameters:
- lpLastAccessTime -- Pointer to a
FILETIME structure to receive the date
and time the mailslot was last accessed.
- CServerMailslot::GetLastWriteTime
- BOOL CServerMailslot::GetLastWriteTime(LPFILETIME lpLastWriteTime);
Return Value:
TRUE if the mailslot last write time was successfully retrieved otherwise FALSE. If the call fails,
you should use GetLastError() to determine the reason.
Parameters:
- lpLastWriteTime -- Pointer to a
FILETIME structure to receive the date
and time the mailslot was written to.
- 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.
- CServerMailslot::AssertValid
- virtual void CServerMailslot::AssertValid() const;
Remarks:
Standard MFC diagnostic override.
- CServerMailslot::Dump
- virtual void CServerMailslot::Dump(CDumpContext& dc) const;
Parameters:
- dc -- The diagnostic dump context for dumping, usually
afxDump.
Remarks:
Dumps the contents of your object to a CDumpContext object.
- CClientMailslot::CClientMailslot
- CClientMailslot::CClientMailslot();
Remarks:
Standard constructor which initializes member variables to a default value.
See Also:
CClientMailslot::~CClientMailslot
- CClientMailslot::~CClientMailslot
- CClientMailslot::~CClientMailslot();
Remarks:
Standard destructor which closes the mailslot if open.
See Also:
CClientMailslot::CClientMailslot
- CClientMailslot::Open
- BOOL CClientMailslot::Open(LPCTSTR lpszComputerOrDomainName, LPCTSTR lpszName, LPSECURITY_ATTRIBUTES lpSecurityAttributes = NULL);
Return Value:
TRUE if the mailslot was successfully opened otherwise FALSE. If the call fails, you should use
GetLastError() to determine the reason.
Parameters:
- lpszComputerOrDomainName -- Name of the machine or domain on which the server side of
the mailslot resides.
- 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.
- CClientMailslot::AssertValid
- virtual void CClientMailslot::AssertValid() const;
Remarks:
Standard MFC diagnostic override.
- CClientMailslot::Dump
- virtual void CClientMailslot::Dump(CDumpContext& dc) const;
Parameters:
- dc -- The diagnostic dump context for dumping, usually
afxDump.
Remarks:
Dumps the contents of your object to a CDumpContext object.
PJ Naughter
Email:
pjn@indigo.ie
Web:
http://www.naughter.com
26 July 1998
Submit an article or tip
General 
News 
Suggestion 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin