CreateMailslotW 函式 (winbase.h)
使用指定的名稱建立 mailslot,並傳回 mailslot 伺服器可用來在 mailslot 上執行作業的句柄。 mailslot 是建立郵件的本機計算機。 如果具有指定名稱的郵件圖已經存在,就會發生錯誤。
語法
HANDLE CreateMailslotW(
[in] LPCWSTR 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 的時間,以毫秒為單位。 下列值具有特殊意義。
值 | 意義 |
---|---|
|
如果沒有訊息存在,則會立即傳回 。 (系統不會將立即傳回視為 error.) |
|
永遠等候訊息。 |
這個逾時值適用於所有後續的讀取作業和所有繼承的郵件集句柄。
[in, optional] lpSecurityAttributes
SECURITY_ATTRIBUTES 結構的指標。 結構的 bInheritHandle 成員會判斷傳回的句柄是否可以由子進程繼承。 如果 lpSecurityAttributes 為 NULL,則無法繼承句柄。
傳回值
如果函式成功,則傳回值是mailslot的句柄,用於伺服器mailslot作業。 此函式傳回的句柄是異步或重疊的。
如果函式失敗,傳回值 會INVALID_HANDLE_VALUE。 若要取得擴充的錯誤資訊,請呼叫 GetLastError。
備註
mailslot 存在,直到下列其中一個條件成立為止:
- 最後一個 (可能繼承或複製) 句柄,會使用 CloseHandle 函式關閉。
- 擁有最後一個 (的程式可能繼承或重複) 句柄結束。
若要將郵件寫入 mailslot,程式會使用 CreateFile 函式,使用下列其中一種格式來指定 mailslot 名稱。
格式 | 使用方式 |
---|---|
\\.\mailslot\name | 擷取本機郵件集的用戶端句柄。 |
\\computername\mailslot\name | 擷取遠端郵件集的用戶端句柄。 |
\\domainname\mailslot\name | 擷取具有指定網域中指定名稱之所有mailslot的用戶端句柄。 |
\\*\mailslot\name | 擷取用戶端句柄,以在系統的主要網域中,擷取具有指定名稱的所有 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 專業版 [僅限傳統型應用程式] |
最低支援的伺服器 | Windows 2000 Server [僅限傳統型應用程式] |
目標平台 | Windows |
標頭 | winbase.h (包含 Windows.h) |
程式庫 | Kernel32.lib |
DLL | Kernel32.dll |