CServerMailslot & CClientMailslot

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.

Features

Usage

History

API Reference

Contacting the Author

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.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 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.

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 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:

  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. If lpSecurityAttributes is NULL, the handle cannot be inherited.

  Windows NT: The lpSecurityDescriptor member of the structure specifies a security descriptor for the new mailslot. If lpSecurityAttributes 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 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.

Contacting the Author

PJ Naughter
Email: pjn@indigo.ie
Web: http://www.naughter.com
26 July 1998