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 つ以上を組み合わせて、オブジェクトを開くために要求できるアクセス モードを指定します。

説明
FILE_SHARE_DELETE
0x00000004
オブジェクトに対する後続のオープン操作を有効にして、削除アクセスを要求します。

それ以外の場合、削除アクセスを要求した場合、他のプロセスはオブジェクトを開くことができません。

このフラグが指定されていないが、オブジェクトが削除アクセス用に開かれている場合、関数は失敗します。

FILE_SHARE_READ
0x00000001
オブジェクトに対する後続のオープン操作を有効にして、読み取りアクセスを要求します。

それ以外の場合、他のプロセスは、読み取りアクセスを要求する場合、オブジェクトを開くことができません。

このフラグが指定されていないが、オブジェクトが読み取りアクセス用に開かれている場合、関数は失敗します。

FILE_SHARE_WRITE
0x00000002
オブジェクトに対する後続のオープン操作を有効にして、書き込みアクセスを要求します。

それ以外の場合、他のプロセスは、書き込みアクセスを要求する場合、オブジェクトを開くことができません。

このフラグが指定されていないが、オブジェクトが書き込みアクセス用に開かれているか、書き込みアクセス権を持つファイル マッピングを持っている場合、関数は失敗します。

[in, optional] lpSecurityAttributes

予約済み。

[in] dwFlagsAndAttributes

ファイル フラグ。

OpenFileById によってファイルが開かれると、ファイル フラグと既存のファイル属性が組み合わされ、指定されたファイル属性は無視されます。 このパラメーターには、次のフラグの任意の組み合わせを含めることができます。

説明
FILE_FLAG_BACKUP_SEMANTICS
0x02000000
バックアップまたは復元操作のためにファイルが開かれています。 システムは、プロセスに SE_BACKUP_NAMESE_RESTORE_NAME の特権がある場合に、呼び出し元のプロセスがファイル セキュリティ チェックをオーバーライドすることを保証します。 詳細については、「 トークンでの特権の変更」を参照してください。

ディレクトリへのハンドルを取得するには、このフラグを設定する必要があります。 ディレクトリ ハンドルは、ファイル ハンドルではなく一部の関数に渡すことができます。 詳細については、「 ディレクトリ ハンドル」を参照してください。

FILE_FLAG_NO_BUFFERING
0x20000000
システムは、システム キャッシュなしでファイルを開きます。 このフラグは、ハード ディスク キャッシュには影響しません。 FILE_FLAG_OVERLAPPEDと組み合わせると、I/O はメモリ マネージャーの同期操作に依存しないため、 フラグによって最大の非同期パフォーマンスが得られます。 ただし、データがキャッシュに保持されていないため、一部の I/O 操作には時間がかかります。 また、ファイル メタデータは引き続きキャッシュされる可能性があります。 メタデータをディスクにフラッシュするには、FlushFileBuffers 関数を使用します。

アプリケーションは、FILE_FLAG_NO_BUFFERINGで開かれたファイルを操作するときに、特定の要件 満たす必要があります。

  • ファイル アクセスは、ボリューム セクター サイズの整数倍数であるファイル内のバイト オフセットから開始する必要があります。
  • ファイル アクセスは、ボリューム セクター サイズの整数倍数であるバイト数に対してである必要があります。 たとえば、セクター サイズが 512 バイトの場合、アプリケーションは 512、1024、1536、または 2048 バイトの読み取りと書き込みを要求できますが、335、981、または 7171 バイトは要求できません。
  • 読み取りおよび書き込み操作のバッファー アドレスはセクターアラインする必要があります。つまり、ボリューム セクター サイズの整数倍数であるメモリ内のアドレスにアラインされます。 ディスクによっては、この要件が適用されない場合があります。
ボリューム セクター サイズの整数倍数にバッファーを配置する 1 つの方法は、 VirtualAlloc を使用してバッファーを割り当てることです。 オペレーティング システムのメモリ ページ サイズの整数の倍数であるアドレスにアラインされたメモリが割り当てられます。 メモリ ページ サイズとボリューム セクター サイズの両方が 2 の累乗であるため、このメモリは、ボリューム セクター サイズの整数倍数であるアドレスにも合わせて調整されます。 メモリ ページのサイズは 4 から 8 KB です。セクターは 512 バイト (ハード ディスク) または 2048 バイト (CD) であるため、ボリューム セクターをメモリ ページよりも大きくすることはできません。

アプリケーションは 、GetDiskFreeSpace 関数を呼び出すことによって、ボリューム セクターのサイズを決定できます。

FILE_FLAG_OPEN_NO_RECALL
0x00100000
ファイル データは要求されますが、引き続きリモート ストレージに配置する必要があります。 ローカル ストレージに転送しないでください。 このフラグは、リモート・ストレージ・システムで使用されます。
FILE_FLAG_OPEN_REPARSE_POINT
0x00200000
このフラグを使用すると、通常の 再解析ポイント 処理は行われず、 OpenFileById は再解析ポイントを開こうとします。 ファイルを開くと、再解析ポイントを制御するフィルターが動作可能かどうかに関係なく、ファイル ハンドルが返されます。 このフラグは 、CREATE_ALWAYS フラグでは使用できません。 ファイルが再解析ポイントでない場合、このフラグは無視されます。
FILE_FLAG_OVERLAPPED
0x40000000
非同期 I/O 用にファイルが開かれるか、または作成されます。 操作が完了すると、 OVERLAPPED 構造体の呼び出しに指定されたイベントがシグナル状態に設定されます。 処理にかなりの時間がかかる操作は 、ERROR_IO_PENDINGを返します。

このフラグを指定すると、読み取りと書き込みの同時操作にファイルを使用できます。 システムはファイル ポインターを維持しないため、 OVERLAPPED 構造体の読み取りおよび書き込み関数にファイル位置を渡すか、ファイル ポインターを更新する必要があります。

このフラグが指定されていない場合、読み取りおよび書き込み関数の呼び出しで OVERLAPPED 構造体が指定されている場合でも、I/O 操作はシリアル化されます。

FILE_FLAG_RANDOM_ACCESS
0x10000000
ファイルがランダムにアクセスされます。 システムはこれをヒントとしてファイルのキャッシュを最適化します。
FILE_FLAG_SEQUENTIAL_SCAN
0x08000000
ファイルが先頭から末尾まで順次アクセスされます。 システムはこれをヒントとしてファイルのキャッシュを最適化します。 アプリケーションがランダム アクセスのためにファイル ポインターを移動すると、最適なキャッシュが発生しない可能性があります。 ただし、正しい操作は引き続き保証されます。

このフラグを指定すると、シーケンシャル アクセスを使用して大きなファイルを読み取るアプリケーションのパフォーマンスが向上する可能性があります。 パフォーマンスの向上は、大きなファイルを主に順次読み取るアプリケーションではさらに顕著になる可能性がありますが、場合によっては小さなバイト範囲をスキップします。

FILE_FLAG_WRITE_THROUGH
0x80000000
システムは中間キャッシュを介して書き込みを行い、ディスクに直接移動します。

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。

関連項目

ACCESS_MASK

CloseHandle

CreateFile

DeleteFile

FILE_ID_DESCRIPTOR

File Management 関数

GetFileInformationByHandleEx

GetOverlappedResult

OVERLAPPED

OpenFile

ReadFile

WriteFile