Click here to Skip to main content
Click here to Skip to main content

CServerMailslot & CClientMailslot

, 3 Mar 2000
Rate this:
Please Sign up or sign in to vote.
Freeware MFC wrapper classes for Win32 Mailslots.
  • Download source files - 29 Kb
  • Sample Image - Mailslot.gif

    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


    License

    This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

    A list of licenses authors might use can be found here

    Share

    About the Author

    PJ Naughter

    United States United States
    No Biography provided

    Comments and Discussions

     
    Questiondomain broadcast doesn't work for me? PinsussRon Whites21-Jul-00 13:46 

    General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

    Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

    | Advertise | Privacy | Terms of Use | Mobile
    Web04 | 2.8.141220.1 | Last Updated 4 Mar 2000
    Article Copyright 2000 by PJ Naughter
    Everything else Copyright © CodeProject, 1999-2014
    Layout: fixed | fluid