createMailslotA 函数 (winbase.h)

项目
08/27/2023

使用指定名称创建 mailslot，并返回 mailslot 服务器可用于对 mailslot 执行操作的句柄。 mailslot 是创建它的计算机的本地位置。如果已存在具有指定名称的 mailslot，则会发生错误。

语法

HANDLE CreateMailslotA(
  [in]           LPCSTR                lpName,
  [in]           DWORD                 nMaxMessageSize,
  [in]           DWORD                 lReadTimeout,
  [in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes
);

参数

[in] lpName

mailslot 的名称。此名称必须具有以下格式：

\\.\mailslot\[path]name

名称字段必须是唯一的。该名称可能包含由反斜杠分隔的多个伪目录级别。例如，\\.\mailslot\example_mailslot_name 和 \\.\mailslot\abc\def\ghi 都是有效名称。

[in] nMaxMessageSize

可写入 mailslot 的单个邮件的最大大小（以字节为单位）。若要指定消息可以是任意大小，请将此值设置为零。

[in] lReadTimeout

读取操作在发生超时之前可以等待将邮件写入 mailslot 的时间（以毫秒为单位）。以下值具有特殊含义。

值	含义
0	如果没有消息，则立即返回。 (系统不会将立即返回视为 error。)
MAILSLOT_WAIT_FOREVER ( (DWORD) -1)	永远等待消息。

此超时值适用于所有后续读取操作和所有继承的 mailslot 句柄。

[in, optional] lpSecurityAttributes

指向 SECURITY_ATTRIBUTES 结构的指针。结构的 bInheritHandle 成员确定返回的句柄是否可以由子进程继承。如果 lpSecurityAttributes 为 NULL，则不能继承句柄。

返回值

如果函数成功，则返回值是 mailslot 的句柄，用于服务器 mailslot 操作。此函数返回的句柄是异步的或重叠的。

如果函数失败，则返回值为 INVALID_HANDLE_VALUE。要获得更多的错误信息，请调用 GetLastError。

注解

在满足以下条件之一之前，mailslot 一直存在：

最后一个 (可能继承或复制) 句柄使用 CloseHandle 函数关闭。
拥有最后一个 (的进程可能继承或重复) 句柄退出。

系统使用第二种方法销毁 mailslot。

若要将邮件写入 mailslot，进程使用 CreateFile 函数，并使用以下格式之一指定 mailslot 名称。

格式	使用情况
\\.\mailslot\name	检索本地 mailslot 的客户端句柄。
\\computername\mailslot\name	检索远程 mailslot 的客户端句柄。
\\domainname\mailslot\name	检索指定域中具有指定名称的所有 mailslot 的客户端句柄。
\\\mailslot\name*	检索系统主域中具有指定名称的所有 mailslot 的客户端句柄。

如果 CreateFile 指定域或使用星号格式指定系统的主域，则应用程序一次无法向 mailslot 写入超过 424 个字节。如果应用程序尝试这样做， WriteFile 函数将失败， GetLastError 将返回 ERROR_BAD_NETPATH。

使用 CreateFile 检索 mailslot 的客户端句柄时，应用程序必须指定FILE_SHARE_READ标志。

如果调用 CreateFile 来访问不存在的邮件图，则将设置 ERROR_FILE_NOT_FOUND 错误代码。

示例

有关示例，请参阅创建 Mailslot。

注意

winbase.h 标头将 CreateMailslot 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。有关详细信息，请参阅函数原型的约定。

要求

要求	值
最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	winbase.h (包括 Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll