CreateMailslotA 函式（winbase.h）

發行項
11/20/2024

使用指定的名稱建立 mailslot，並傳回 mailslot 伺服器可用來在 mailslot 上執行作業的句柄。 mailslot 是建立郵件的本機計算機。如果具有指定名稱的郵件圖已經存在，就會發生錯誤。

語法

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

參數

[in] lpName

mailslot 的名稱。這個名稱必須具有下列格式：

\\.\mailslot\[路徑]名稱

名稱欄位必須是唯一的。此名稱可能包含多個以反斜杠分隔的虛擬目錄層級。例如，\.\mailslot\example_mailslot_name和 \\.\mailslot\abc\def\ghi 都是有效的名稱。

[in] nMaxMessageSize

可以寫入mailslot的單一訊息大小上限，以位元組為單位。若要指定訊息可以是任何大小，請將此值設定為零。

[in] lReadTimeout

讀取作業可以等候訊息在逾時發生前寫入 mailslot 的時間，以毫秒為單位。下列值具有特殊意義。

價值	意義
0	如果沒有訊息存在，則立即傳回。（系統不會將立即傳回視為錯誤。
MAILSLOT_WAIT_FOREVER （DWORD）-1）	永遠等候訊息。

這個逾時值適用於所有後續讀取作業和所有繼承的郵件集句柄。

[in, optional] lpSecurityAttributes

SECURITY_ATTRIBUTES 結構的指標。 bInheritHandle 結構的成員會決定子進程是否可以繼承傳回的句柄。如果 lpSecurityAttributesNULL，則無法繼承句柄。

傳回值

如果函式成功，傳回值是mailslot的句柄，用於伺服器mailslot作業。這個函式傳回的句柄是異步或重疊的。

如果函式失敗，傳回值會 INVALID_HANDLE_VALUE。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

言論

mailslot 存在，直到下列其中一個條件成立為止：

最後一個（可能繼承或重複的）句柄會使用 closeHandle 函式關閉。
擁有最後一個（可能繼承或重複）處理程式會結束。

系統會使用第二個方法來終結 mailslots。

若要將訊息寫入 mailslot，進程會使用 CreateFile 函式，使用下列其中一種格式來指定 mailslot 名稱。

格式	用法
\\.\mailslot\名稱	擷取本機 mailslot 的用戶端句柄。
\\computername\mailslot\name	擷取遠端mailslot的用戶端句柄。
\\domainname\mailslot\name	擷取具有指定網域中指定名稱之所有mailslot的用戶端句柄。
\\*\mailslot\名稱	擷取用戶端句柄，以系統的主要網域中指定名稱來擷取所有mailslot。

如果 CreateFile 指定網域或使用星號格式來指定系統的主要網域，則應用程式一次無法寫入 424 個字節以上的 mailslot。如果應用程式嘗試這樣做，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 [僅限傳統型應用程式]
目標平臺	窗戶
標頭	winbase.h （包括 Windows.h）
連結庫	Kernel32.lib
DLL	Kernel32.dll