Export (0) Print
Expand All
4 out of 9 rated this helpful - Rate this topic

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.

Syntax


HANDLE WINAPI CreateMailslot(
  _In_      LPCTSTR lpName,
  _In_      DWORD nMaxMessageSize,
  _In_      DWORD lReadTimeout,
  _In_opt_  LPSECURITY_ATTRIBUTES lpSecurityAttributes
);

Parameters

lpName [in]

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 pseudo directories separated by backslashes. For example, both \\.\mailslot\example_mailslot_name and \\.\mailslot\abc\def\ghi are valid names.

nMaxMessageSize [in]

The maximum size of a single message that can be written to the mailslot, in bytes. To specify that the message can be of any size, set this value to zero.

lReadTimeout [in]

The time a read operation can wait for a message to be written to the mailslot before a time-out occurs, in milliseconds. The following values have special meanings.

ValueMeaning
0

Returns immediately if no message is present. (The system does not treat an immediate return as an error.)

MAILSLOT_WAIT_FOREVER
((DWORD)-1)

Waits forever for a message.

 

This time-out value applies to all subsequent read operations and all inherited mailslot handles.

lpSecurityAttributes [in, optional]

A pointer to a SECURITY_ATTRIBUTES structure. The bInheritHandle member of the structure determines whether the returned handle can be inherited by child processes. If lpSecurityAttributes is NULL, the handle cannot be inherited.

Return value

If the function succeeds, the return value is a handle to the mailslot, for use in server mailslot operations. The handle returned by this function is asynchronous, or overlapped.

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.

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.

FormatUsage
\\.\mailslot\nameRetrieves a client handle to a local mailslot.
\\computername\mailslot\nameRetrieves a client handle to a remote mailslot.
\\domainname\mailslot\nameRetrieves a client handle to all mailslots with the specified name in the specified domain.
\\*\mailslot\nameRetrieves 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 424 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.

If CreateFile is called to access a non-existent mailslot, the ERROR_FILE_NOT_FOUND error code will be set.

Examples

For an example, see Creating a Mailslot.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Winbase.h (include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

Unicode and ANSI names

CreateMailslotW (Unicode) and CreateMailslotA (ANSI)

See also

CloseHandle
CreateFile
GetMailslotInfo
Mailslot Functions
Mailslots Overview
SECURITY_ATTRIBUTES
SetMailslotInfo
WriteFile

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.