The CreateMailslot function creates a mailslot with the specified name and returns a handle that a mailslot server can use to perform operations on the mailslot. The mailslot is local to the computer that creates it. An error occurs if a mailslot with the specified name already exists.
HANDLE CreateMailslot(
LPCTSTR lpName, // pointer to string for mailslot name
DWORD nMaxMessageSize, // maximum message size
DWORD lReadTimeout, // milliseconds before read time-out
LPSECURITY_ATTRIBUTES lpSecurityAttributes
// pointer to security structure
);
\\.\mailslot\[path]name
The name field must be unique. The name may include multiple levels of pseudodirectories separated by backslashes. For example, both \\.\mailslot\example_mailslot_name and \\.\mailslot\abc\def\ghi are valid names.
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.
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.
If the function succeeds, the return value is a handle to the mailslot, for use in server mailslot operations.
If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.
The mailslot exists until one of the following conditions is true:
The system uses the second method to destroy mailslots.
To write a message to a mailslot, a process uses the CreateFile function, specifying the mailslot name by using one of the following formats:
Format | Usage |
---|---|
\\.\mailslot\name | Retrieves a client handle to a local mailslot. |
\\computername\mailslot\name | Retrieves a client handle to a remote mailslot. |
\\domainname\mailslot\name | Retrieves a client handle to all mailslots with the specified name in the specified domain. |
\\*\mailslot\name | Retrieves a client handle to all mailslots with the specified name in the system's primary domain. |
If CreateFile specifies a domain or uses the asterisk format to specify the system's primary domain, the application cannot write more than 400 bytes at a time to the mailslot. If the application attempts to do so, the WriteFile function fails and GetLastError returns ERROR_BAD_NETPATH.
An application must specify the FILE_SHARE_READ flag when using CreateFile to retrieve a client handle to a mailslot.
Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in winbase.h.
Import Library: Use kernel32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.
Mailslots Overview, Mailslot Functions, CloseHandle, CreateFile, GetMailslotInfo, SECURITY_ATTRIBUTES, SetMailslotInfo, WriteFile