CreateMailslotA 関数 (winbase.h)
指定した名前の 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 に書き込むことができる 1 つのメッセージの最大サイズ (バイト単位)。 メッセージに任意のサイズを指定するには、この値を 0 に設定します。
[in] lReadTimeout
メッセージが mailslot に書き込まれるのを読み取り操作で待機できる時間 。タイムアウトが発生するまでの時間 (ミリ秒単位)。 次の値は特別な意味を持ちます。
| 値 | 意味 |
|---|---|
|
メッセージが存在しない場合は、すぐにを返します。 (システムは即時戻り値をエラーとして扱いません。 |
|
メッセージを無期限に待機します。 |
このタイムアウト値は、後続のすべての読み取り操作と、継承されたすべての mailslot ハンドルに適用されます。
[in, optional] lpSecurityAttributes
SECURITY_ATTRIBUTES構造体へのポインター。 構造体の bInheritHandle メンバーは、返されたハンドルを子プロセスによって継承できるかどうかを決定します。 lpSecurityAttributes が NULL の場合、ハンドルを継承できません。
戻り値
関数が成功した場合、戻り値は、サーバー mailslot 操作で使用する mailslot へのハンドルです。 この関数によって返されるハンドルが非同期であるか、重複しています。
失敗した場合の戻り値は、INVALID_HANDLE_VALUE です。 詳細なエラー情報を得るには、GetLastError を呼び出します。
解説
mailslot は、次のいずれかの条件が満たされるまで存在します。
- 最後のハンドル (継承または複製される可能性があります) は、 CloseHandle 関数を使用して閉じられます。
- 最後の (継承または重複している可能性がある) ハンドルを所有するプロセスは終了します。
mailslot にメッセージを書き込むには、次のいずれかの形式を使用して mailslot 名を指定する CreateFile 関数が使用されます。
| フォーマット | 使用 |
|---|---|
| \\.\mailslot\name | ローカル mailslot へのクライアント ハンドルを取得します。 |
| \\computername\mailslot\name | リモート mailslot へのクライアント ハンドルを取得します。 |
| \\domainname\mailslot\name | 指定したドメイン内の指定した名前を持つすべての mailslot に対するクライアント ハンドルを取得します。 |
| \\*\mailslot\name | システムのプライマリ ドメインで指定された名前を持つすべてのメールスロットに対するクライアント ハンドルを取得します。 |
CreateFile がドメインを指定するか、アスタリスク形式を使用してシステムのプライマリ ドメインを指定する場合、アプリケーションは一度に 424 バイトを超えるバイトを mailslot に書き込むことができません。 アプリケーションがそうしようとすると、WriteFile 関数は失敗し、GetLastError はERROR_BAD_NETPATHを返します。
CreateFile を使用してクライアント ハンドルを mailslot に取得する場合、アプリケーションは FILE_SHARE_READ フラグを指定する必要があります。
存在しない mailslot にアクセスするために CreateFile が呼び出されると、 ERROR_FILE_NOT_FOUND エラー コードが設定されます。
例
例については、「 Mailslot の作成」を参照してください。
注意
winbase.h ヘッダーは、CreateMailslot をエイリアスとして定義し、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 2000 Professional [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows 2000 Server [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | winbase.h (Windows.h を含む) |
| Library | Kernel32.lib |
| [DLL] | Kernel32.dll |