SetFileInformationByHandle 関数 (fileapi.h)
指定したファイルのファイル情報を設定します。
ファイル ハンドルを使用してファイル情報を取得するには、「 GetFileInformationByHandle 」または 「GetFileInformationByHandleEx」を参照してください。
構文
BOOL SetFileInformationByHandle(
[in] HANDLE hFile,
[in] FILE_INFO_BY_HANDLE_CLASS FileInformationClass,
[in] LPVOID lpFileInformation,
[in] DWORD dwBufferSize
);
パラメーター
[in] hFile
情報を変更するファイルのハンドル。
このハンドルは、要求された変更に対する適切なアクセス許可を使用して開く必要があります。 詳細については、「解説」および「コード例」セクションを参照してください。
このハンドルはパイプ ハンドルにしないでください。
[in] FileInformationClass
変更 する情報の 種類を指定するFILE_INFO_BY_HANDLE_CLASS列挙値。
有効な値の表については、「解説」セクションを参照してください。
[in] lpFileInformation
指定したファイル情報クラスに対して変更する情報を含むバッファーへのポインター。 このパラメーターが指す構造体は、 FileInformationClass で指定されたクラスに対応します。
有効な構造体型の表については、「解説」セクションを参照してください。
[in] dwBufferSize
lpFileInformation のサイズ (バイト単位)。
戻り値
成功した場合は 0 以外、それ以外の場合は 0 を返します。
詳細なエラー情報を得るには、GetLastError を呼び出します。
解説
オペレーティング システムのリリースによって、特定のファイル情報クラスの動作が若干異なります。 これらのクラスは基になるドライバーでサポートされており、返される情報はオペレーティング システムのリリース間で変更される可能性があります。
次の表は、有効なファイル情報クラスと、この関数で使用する対応するデータ構造の型を示しています。
| FileInformationClass 値 | lpFileInformation 型 |
|---|---|
|
FileBasicInfo
0 |
|
|
FileRenameInfo
3 |
|
|
FileDispositionInfo
4 |
|
|
FileAllocationInfo
5 |
|
|
FileEndOfFileInfo
6 |
|
|
FileIoPriorityHintInfo
12 |
SetFileInformationByHandle で使用するファイル ハンドルを作成するときは、適切なアクセス フラグを指定する必要があります。 たとえば、アプリケーションで DeleteFile メンバーが TRUE に設定されたFILE_DISPOSITION_INFOを使用している場合、ファイルは CreateFile 関数の呼び出しで DELETE アクセスを要求する必要があります。 この例については、「コード例」セクションを参照してください。 ファイルのアクセス許可の詳細については、「 ファイルのセキュリティとアクセス権」を参照してください。
ハンドルにバインドされたトランザクションがある場合、情報クラス FileBasicInfo、FileRenameInfo、FileAllocationInfo、FileEndOfFileInfo、FileDispositionInfo に関して行う変更はトランザクション処理対象です。 FileDispositionInfo を指定した場合、DeleteFile 操作が要求された場合、削除操作のみが処理されます。 この場合、ハンドルを閉じる前にトランザクションがコミットされていない場合、削除は行われません。 TxF の詳細については、「 トランザクション NTFS (TxF)」を参照してください。
Windows 8 と Windows Server 2012 では、この関数は、次のテクノロジによってサポートされています。
| テクノロジ | サポートされています |
|---|---|
| サーバー メッセージ ブロック (SMB) 3.0 プロトコル | はい |
| SMB 3.0 Transparent Failover (TFO) | コメントを表示する |
| スケールアウト ファイル共有 (SO) を使う SMB 3.0 | コメントを表示する |
| クラスターの共有ボリューム ファイル システム (CsvFS) | はい |
| Resilient File System (ReFS) | はい |
SMB 3.0 では、継続的な可用性機能を備えたファイル共有での代替データ ストリームの名前変更はサポートされていません。
例
次の C++ の例は、ファイルを作成し、ハンドルが閉じられたときに削除用にマークする方法を示しています。
//...
HANDLE hFile = CreateFile( TEXT("tempfile"),
GENERIC_READ | GENERIC_WRITE | DELETE,
0 /* exclusive access */,
NULL,
CREATE_ALWAYS,
0,
NULL);
if (hFile != INVALID_HANDLE_VALUE)
{
FILE_DISPOSITION_INFO fdi;
fdi.DeleteFile = TRUE; // marking for deletion
BOOL fResult = SetFileInformationByHandle( hFile,
FileDispositionInfo,
&fdi,
sizeof(FILE_DISPOSITION_INFO) );
if (fResult)
{
// File will be deleted upon CloseHandle.
_tprintf( TEXT("SetFileInformationByHandle marked tempfile for deletion\n") );
// ...
// Now use the file for whatever temp data storage you need,
// it will automatically be deleted upon CloseHandle or
// application termination.
// ...
}
else
{
_tprintf( TEXT("error %lu: SetFileInformationByHandle could not mark tempfile for deletion\n"),
GetLastError() );
}
CloseHandle(hFile);
// At this point, the file is closed and deleted by the system.
}
else
{
_tprintf( TEXT("error %lu: could not create tempfile\n"),
GetLastError() );
}
//...
要件
| サポートされている最小のクライアント | Windows Vista [デスクトップ アプリのみ | UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2008 [デスクトップ アプリ | UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | fileapi.h (Windows.h を含む) |
| Library | Kernel32.lib;Windows Server 2003 および Windows XP の FileExtd.lib |
| [DLL] | Kernel32.dll |
| 再頒布可能パッケージ | Windows Server 2003 および Windows XP 上の Windows SDK。 |