CServerMailslot & CClientMailslot





5.00/5 (3 votes)
Mar 4, 2000

51639

931
Freeware MFC wrapper classes for Win32 Mailslots.
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.
Features |
Usage |
History |
API Reference |
Contacting the Author |
- 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.
History
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 toINVALID_HANDLE_VALUE
.
11 August 1998
- Inclusion of a VC 5 make file.
- Tidy up of the resources the program uses plus their names.
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::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 useGetLastError()
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:
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 all inherited mailslot handles. - lpSecurityAttributes -- Pointer to a
SECURITY_ATTRIBUTES
structure that determines whether the returned handle can be inherited by child processes. IflpSecurityAttributes
is NULL, the handle cannot be inherited.Windows NT: The
lpSecurityDescriptor
member of the structure specifies a security descriptor for the new mailslot. IflpSecurityAttributes
is NULL, the mailslot gets a default security descriptor.
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 useGetLastError()
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 useGetLastError()
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 theOpen()
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 useGetLastError()
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 byOpen()
when the mailslot is created. - 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:
- 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 useGetLastError()
to determine the reason.Parameters:
- lpCreationTime -- Pointer to a
FILETIME
structure to receive the date and time the file was created.
- lpCreationTime -- Pointer to a
- 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 useGetLastError()
to determine the reason.Parameters:
- lpLastAccessTime -- Pointer to a
FILETIME
structure to receive the date and time the mailslot was last accessed.
- lpLastAccessTime -- Pointer to a
- 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 useGetLastError()
to determine the reason.Parameters:
- lpLastWriteTime -- Pointer to a
FILETIME
structure to receive the date and time the mailslot was written to.
- lpLastWriteTime -- Pointer to a
- 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. - dc -- The diagnostic dump context for dumping, usually
- 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 useGetLastError()
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. IflpSecurityAttributes
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 useGetLastError()
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. - dc -- The diagnostic dump context for dumping, usually
Contacting the Author
PJ Naughter
Email: pjn@indigo.ie
Web: http://www.naughter.com
26 July 1998