The last (possibly inherited or duplicated) handle to it is closed using the CloseHandle function.| HANDLE CreateMailslot(lpszName, cbMaxMsg, dwReadTimeout, lpsa) | |||||
| LPTSTR lpszName; | /* string for mailslot name | */ | |||
| DWORD cbMaxMsg; | /* largest message allowed | */ | |||
| DWORD dwReadTimeout; | /* milliseconds before read timeout | */ | |||
| LPSECURITY_ATTRIBUTES lpsa; | /* SECURITY_ATTRIBUTES structure | */ | |||
The CreateMailslot function creates a mailslot with a given 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. It is an error if a mailslot with that name already exists.
lpszName
Points to a null-terminated string specifying the name of the mailslot. This name must have the following form:
\\.\mailslot\[path]name
The name portion must have the same format as a standard Win32 filename and must be unique. The name may include multiple levels of pseudo-directories separated by backslashes. For example, \\.\mailslot\example or \\.\mailslot\abc\def\ghi are valid names.
cbMaxMsg
Specifies the maximum size (in bytes) for a single message that can be written to the mailslots. This value can be zero, to specify that the message can be of any size.
dwReadTimeout
Specifies the amount of time (in milliseconds) to wait for a message to be written to the mailslot before timing out a read operation. The following values have special meanings:
| Value | Meaning |
| 0 | Return immediately if no message is present. (This is not treated as an error.) |
| MAILSLOT_WAIT_FOREVER | Wait forever for a message. |
lpsa
Points to a SECURITY_ATTRIBUTES structure for the mailslot. This structure includes a bInheritHandle member, which an application can use to allow a child process to inherit the mailslot handle. This parameter can be NULL. When this parameter is NULL, the bInheritHandle member is FALSE.
The SECURITY_ATTRIBUTES structure has the following format:
typedef struct _SECURITY_ATTRIBUTES { /* sa */
DWORD nLength;
LPVOID lpSecurityDescriptor;
BOOL bInheritHandle;
} SECURITY_ATTRIBUTES;
The return value is a handle to the mailslot, for use in server mailslot operations, if the function is successful. The return value is INVALID_HANDLE_VALUE if the function fails. Use the GetLastError function to obtain extended error information.
The mailslot exists until one of the following conditions is true:
The last (possibly inherited or duplicated) handle to it is closed using the CloseHandle function.
The process owning the last (possibly inherited or duplicated) handle exits.
Microsoft LAN Manager uses the second method to destroy mailslots.
To write a message to a mailslot, a process uses the CreateFile function, specifying the mailslot name in 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 given name in the specified domain. |
| \\*\mailslot\name | Retrieves a client handle to all mailslots with the given name in the system's primary domain. |
If the CreateFile function 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. When an application attempts to write more than 400 bytes, the WriteFile function fails and GetLastError returns ERROR_BAD_NETPATH.
An application must specify the FILE_SHARE_READ flag when it uses the CreateFile function to retrieve a client handle to a mailslot.
The CreateMailslot function can be used as either a wide-character function (in which text arguments use Unicode) or an ANSI function (in which text arguments use characters from the Windows 3.x character set).
CloseHandle, CreateFile, GetMailslotInfo, SetMailslotInfo