OpenFileById 関数 (winbase.h)
指定された識別子と一致するファイルを開きます。
構文
HANDLE OpenFileById(
[in] HANDLE hVolumeHint,
[in] LPFILE_ID_DESCRIPTOR lpFileId,
[in] DWORD dwDesiredAccess,
[in] DWORD dwShareMode,
[in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
[in] DWORD dwFlagsAndAttributes
);
パラメーター
[in] hVolumeHint
開くファイルが格納されているボリュームまたは共有上の任意のファイルへのハンドル。
[in] lpFileId
開くファイルを識別する FILE_ID_DESCRIPTOR へのポインター。
[in] dwDesiredAccess
オブジェクトへのアクセス。 Access には、読み取り、書き込み、またはその両方を使用できます。
詳細については、「 ファイル のセキュリティとアクセス権」を参照してください。 開いているハンドルを持つオープン要求で指定された共有モードと競合するアクセス・モードを要求することはできません。
このパラメーターがゼロ (0) の場合、アプリケーションはデバイスにアクセスせずにファイル属性とデバイス属性を照会できます。 これは、フロッピー ディスク ドライブのサイズと、それがサポートする形式を、ドライブにフロッピーを必要とせずに決定するアプリケーションに役立ちます。 また、読み取りまたは書き込みアクセス用にファイルまたはディレクトリを開かずに、ファイルまたはディレクトリの存在をテストするために使用することもできます。
[in] dwShareMode
オブジェクトの共有モード。読み取り、書き込み、両方、またはなしを指定できます。
開いているハンドルを持つオープン要求で指定されたアクセス モードと競合する共有モードを要求することはできません。これは、共有違反 (ERROR_SHARING_VIOLATION) が発生するためです。 詳細については、「ファイルの作成とオープン」を参照してください。
このパラメーターが 0 (0) で OpenFileById が 成功した場合、オブジェクトは共有できず、ハンドルが閉じられるまでもう一度開くことはできません。 詳細については、このトピックの「解説」セクションを参照してください。
共有オプションは、オブジェクトへのハンドルを閉じるまで有効です。
別のプロセスがオブジェクトを開いている間にプロセスがオブジェクトを共有できるようにするには、次の値の 1 つ以上を組み合わせて、オブジェクトを開くために要求できるアクセス モードを指定します。
[in, optional] lpSecurityAttributes
予約済み。
[in] dwFlagsAndAttributes
ファイル フラグ。
OpenFileById によってファイルが開かれると、ファイル フラグと既存のファイル属性が組み合わされ、指定されたファイル属性は無視されます。 このパラメーターには、次のフラグの任意の組み合わせを含めることができます。
| 値 | 説明 |
|---|---|
|
バックアップまたは復元操作のためにファイルが開かれています。 システムは、プロセスに SE_BACKUP_NAME と SE_RESTORE_NAME の特権がある場合に、呼び出し元のプロセスがファイル セキュリティ チェックをオーバーライドすることを保証します。 詳細については、「 トークンでの特権の変更」を参照してください。
ディレクトリへのハンドルを取得するには、このフラグを設定する必要があります。 ディレクトリ ハンドルは、ファイル ハンドルではなく一部の関数に渡すことができます。 詳細については、「 ディレクトリ ハンドル」を参照してください。 |
|
システムは、システム キャッシュなしでファイルを開きます。 このフラグは、ハード ディスク キャッシュには影響しません。 FILE_FLAG_OVERLAPPEDと組み合わせると、I/O はメモリ マネージャーの同期操作に依存しないため、 フラグによって最大の非同期パフォーマンスが得られます。 ただし、データがキャッシュに保持されていないため、一部の I/O 操作には時間がかかります。 また、ファイル メタデータは引き続きキャッシュされる可能性があります。 メタデータをディスクにフラッシュするには、FlushFileBuffers 関数を使用します。
アプリケーションは、FILE_FLAG_NO_BUFFERINGで開かれたファイルを操作するときに、特定の要件 を満たす必要があります。
アプリケーションは 、GetDiskFreeSpace 関数を呼び出すことによって、ボリューム セクターのサイズを決定できます。 |
|
ファイル データは要求されますが、引き続きリモート ストレージに配置する必要があります。 ローカル ストレージに転送しないでください。 このフラグは、リモート・ストレージ・システムで使用されます。 |
|
このフラグを使用すると、通常の 再解析ポイント 処理は行われず、 OpenFileById は再解析ポイントを開こうとします。 ファイルを開くと、再解析ポイントを制御するフィルターが動作可能かどうかに関係なく、ファイル ハンドルが返されます。 このフラグは 、CREATE_ALWAYS フラグでは使用できません。 ファイルが再解析ポイントでない場合、このフラグは無視されます。 |
|
非同期 I/O 用にファイルが開かれるか、または作成されます。 操作が完了すると、 OVERLAPPED 構造体の呼び出しに指定されたイベントがシグナル状態に設定されます。 処理にかなりの時間がかかる操作は 、ERROR_IO_PENDINGを返します。
このフラグを指定すると、読み取りと書き込みの同時操作にファイルを使用できます。 システムはファイル ポインターを維持しないため、 OVERLAPPED 構造体の読み取りおよび書き込み関数にファイル位置を渡すか、ファイル ポインターを更新する必要があります。 このフラグが指定されていない場合、読み取りおよび書き込み関数の呼び出しで OVERLAPPED 構造体が指定されている場合でも、I/O 操作はシリアル化されます。 |
|
ファイルがランダムにアクセスされます。 システムはこれをヒントとしてファイルのキャッシュを最適化します。 |
|
ファイルが先頭から末尾まで順次アクセスされます。 システムはこれをヒントとしてファイルのキャッシュを最適化します。 アプリケーションがランダム アクセスのためにファイル ポインターを移動すると、最適なキャッシュが発生しない可能性があります。 ただし、正しい操作は引き続き保証されます。
このフラグを指定すると、シーケンシャル アクセスを使用して大きなファイルを読み取るアプリケーションのパフォーマンスが向上する可能性があります。 パフォーマンスの向上は、大きなファイルを主に順次読み取るアプリケーションではさらに顕著になる可能性がありますが、場合によっては小さなバイト範囲をスキップします。 |
|
システムは中間キャッシュを介して書き込みを行い、ディスクに直接移動します。
FILE_FLAG_NO_BUFFERINGも指定されていないので、システム キャッシュが有効になっている場合、データはシステム キャッシュに書き込まれますが、ディスクに遅延なくフラッシュされます。 FILE_FLAG_NO_BUFFERINGも指定されているため、システム キャッシュが有効にならない場合、データはシステム キャッシュを経由せずにすぐにディスクにフラッシュされます。 オペレーティング システムは、ハード ディスク キャッシュを通じて永続メディアへの書き込みも要求します。 ただし、すべてのハードウェアがこのライトスルー機能をサポートしているわけではありません。 |
戻り値
この関数の実行が成功した場合の戻り値は、指定したファイルへのオープン ハンドルです。
失敗した場合の戻り値は、INVALID_HANDLE_VALUE です。 詳細なエラー情報を得るには、GetLastError を呼び出します。
解説
OpenFileById から返されるオブジェクト ハンドルを閉じるには、CloseHandle 関数を使用します。
DeleteFile の以前の呼び出しの結果として削除が保留中のファイルで OpenFileById を呼び出すと、関数は失敗します。 オペレーティング システムは、ファイルに対するすべてのハンドルが閉じられるまでファイルの削除を遅延します。 GetLastError はERROR_ACCESS_DENIEDを返します。
Windows 8 と Windows Server 2012 では、この関数は、次のテクノロジによってサポートされています。
| テクノロジ | サポートされています |
|---|---|
| サーバー メッセージ ブロック (SMB) 3.0 プロトコル | いいえ |
| SMB 3.0 Transparent Failover (TFO) | いいえ |
| スケールアウト ファイル共有 (SO) を使う SMB 3.0 | いいえ |
| クラスターの共有ボリューム ファイル システム (CsvFS) | はい |
| Resilient File System (ReFS) | はい |
要件
| サポートされている最小のクライアント | Windows Vista [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows Server 2008 [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | winbase.h (Windows.h を含む) |
| Library | Kernel32.lib;Windows Server 2003 および Windows XP の FileExtd.lib |
| [DLL] | Kernel32.dll |
| 再頒布可能パッケージ | Windows Server 2003 および Windows XP 上の Windows SDK。 |