createMailslotA 函式 (winbase.h)

發行項
03/13/2024

使用指定的名稱建立 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 函式關閉。
擁有最後一個 (可能繼承或重複的程式) 句柄結束。

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

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

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

如果 CreateFile 指定網域或使用星號格式指定系統的主要域，應用程式一次無法將超過 424 個字節寫入 mailslot。如果應用程式嘗試這樣做， WriteFile 函式會失敗，而且 GetLastError 會 傳回ERROR_BAD_NETPATH。

當使用 CreateFile 擷取 mailslot 的用戶端句柄時，應用程式必須指定FILE_SHARE_READ旗標。

如果呼叫 CreateFile 來存取不存在的 mailslot，則會設定 ERROR_FILE_NOT_FOUND 錯誤碼。

範例

如需範例，請參閱建立Mailslot。

注意

winbase.h 標頭會將 CreateMailslot 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求

需求	值
最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
目標平台	Windows
標頭	winbase.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll