CreateMailslot
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 |
|
); |
|
Parameters
lpName
Points to a
null-terminated string specifying the name of the mailslot. This name must have
the following form:
\\.\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.
nMaxMessageSize
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.
lReadTimeout
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.
Windows 95:
The lpSecurityDescriptor member of the structure is ignored.
Return Values
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.
Remarks
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.
Both
Windows NT and Windows 95 use 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.
See Also