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 を呼び出します。

解説

オペレーティング システムのリリースによって、特定のファイル情報クラスの動作が若干異なります。 これらのクラスは基になるドライバーでサポートされており、返される情報はオペレーティング システムのリリース間で変更される可能性があります。

次の表は、有効なファイル情報クラスと、この関数で使用する対応するデータ構造の型を示しています。

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 では、継続的な可用性機能を備えたファイル共有での代替データ ストリームの名前変更はサポートされていません。

例

次の 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() );
 }
//...

要件

関連項目

CreateFile

File Management 関数

ファイルのセキュリティとアクセス権

汎用アクセス権

GetFileInformationByHandle

GetFileInformationByHandleEx