ReplaceFileA 関数 (winbase.h)

  • [アーティクル]

1 つのファイルを別のファイルに置き換え、元のファイルのバックアップ コピーを作成するオプションで置き換えます。 置換ファイルは、置換されたファイルの名前とその ID を前提としています。

構文

BOOL ReplaceFileA(
  [in]           LPCSTR lpReplacedFileName,
  [in]           LPCSTR lpReplacementFileName,
  [in, optional] LPCSTR lpBackupFileName,
  [in]           DWORD  dwReplaceFlags,
                 LPVOID lpExclude,
                 LPVOID lpReserved
);

パラメーター

[in] lpReplacedFileName

置き換えるファイルの名前。

既定では、名前はMAX_PATH文字に制限されています。 この制限を 32,767 文字のワイド文字に拡張するには、パスの先頭に "\\?\" を付加します。 詳細については、「ファイル、パス、および名前空間の名前付け」を参照してください。

ヒント

Windows 10 バージョン 1607 以降では、"\\?\" を前もって指定しなくても、MAX_PATHの制限を削除するようにオプトインできます。 詳細については、「 名前付けファイル、パス、および名前空間 」の「パスの最大長制限」セクションを参照してください。

このファイルは、 GENERIC_READ、 DELETE、 SYNCHRONIZE アクセス権で開かれます。 共有モードは 、FILE_SHARE_DELETE | FILE_SHARE_WRITE | FILE_SHARE_READ。

呼び出し元は、置き換えるファイルへの書き込みアクセス権を持っている必要があります。 詳細については、「 ファイル のセキュリティとアクセス権」を参照してください。

[in] lpReplacementFileName

lpReplacedFileName ファイルを置き換えるファイルの名前。

既定では、名前はMAX_PATH文字に制限されています。 この制限を 32,767 文字のワイド文字に拡張するには、パスの先頭に "\\?\" を付加します。 詳細については、「ファイル、パス、および名前空間の名前付け」を参照してください。

ヒント

Windows 10 バージョン 1607 以降では、"\\?\" を前もって指定しなくても、MAX_PATHの制限を削除するようにオプトインできます。 詳細については、「 名前付けファイル、パス、および名前空間 」の「パスの最大長制限」セクションを参照してください。

関数は、すべての属性と ACL を保持できるように、 SYNCHRONIZE、 GENERIC_READ、 GENERIC_WRITE、 DELETE、 WRITE_DAC アクセス権を使用してこのファイルを開こうとします。 これが失敗した場合、関数は SYNCHRONIZE、GENERIC_READ、DELETE、WRITE_DAC アクセス権を使用してファイルを開こうとします。 共有モードは指定されません。

[in, optional] lpBackupFileName

lpReplacedFileName ファイルのバックアップ コピーとして機能するファイルの名前。 このパラメーターが NULL の場合、バックアップ ファイルは作成されません。 バックアップ ファイルの実装の詳細については、「解説」セクションを参照してください。

既定では、名前はMAX_PATH文字に制限されています。 この制限を 32,767 文字のワイド文字に拡張するには、パスの先頭に "\\?\" を付加します。 詳細については、「ファイル、パス、および名前空間の名前付け」を参照してください。

ヒント

Windows 10 バージョン 1607 以降では、"\\?\" を前もって指定しなくても、MAX_PATHの制限を削除するようにオプトインできます。 詳細については、「 名前付けファイル、パス、および名前空間 」の「パスの最大長制限」セクションを参照してください。

[in] dwReplaceFlags

置換オプション。 このパラメーターには、次の 1 つ以上の値を指定できます。

値 説明
REPLACEFILE_WRITE_THROUGH
0x00000001
 この値はサポートされていません。
REPLACEFILE_IGNORE_MERGE_ERRORS
0x00000002
 置換されたファイルから置換ファイルに情報 (属性や ACL など) をマージするときに発生するエラーを無視します。 したがって、このフラグを指定し、 WRITE_DAC アクセス権を持たない場合、関数は成功しますが、ACL は保持されません。
REPLACEFILE_IGNORE_ACL_ERRORS
0x00000004
 置き換えられたファイルから置換ファイルに ACL 情報をマージするときに発生するエラーを無視します。 したがって、このフラグを指定し、 WRITE_DAC アクセス権を持たない場合、関数は成功しますが、ACL は保持されません。 この値を使用するアプリケーションをコンパイルするには、 _WIN32_WINNT マクロを 0x0600 以降として定義します。

Windows Server 2003 および Windows XP: この値はサポートされていません。

lpExclude

将来使用するために予約されています。

lpReserved

将来使用するために予約されています。

戻り値

関数が成功すると、戻り値は 0 以外になります。

関数が失敗した場合は、0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。 この関数で発生する可能性のあるエラー コードを次に示します。

リターン コード/値 説明
ERROR_UNABLE_TO_MOVE_REPLACEMENT
1176 (0x498)
 置換ファイルの名前を変更できませんでした。 lpBackupFileName を指定した場合、置換されたファイルと置換されたファイルは元のファイル名を保持します。 それ以外の場合、置換されたファイルは存在せず、置換ファイルは元の名前の下に存在します。
ERROR_UNABLE_TO_MOVE_REPLACEMENT_2
1177 (0x499)
 置換ファイルを移動できませんでした。 置換ファイルは元の名前の下に存在します。ただし、置き換えるファイルからファイル ストリームと属性が継承されています。 置き換えるファイルは、まだ別の名前で存在します。 lpBackupFileName が指定されている場合は、置き換えられたファイルの名前になります。
ERROR_UNABLE_TO_REMOVE_REPLACED
1175 (0x497)
 置換されたファイルを削除できませんでした。 置換されたファイルと置換されたファイルは、元のファイル名を保持します。
 

ERROR_INVALID_PARAMETERなどの他のエラーが返された場合、置換されたファイルと置換されたファイルは元のファイル名を保持します。 このシナリオでは、バックアップ ファイルは存在せず、置き換えられたファイルのすべての属性とストリームが置換ファイルによって継承されるとは限りません。

Remarks

ヒントWindows 10 バージョン 1607 以降では、この関数の Unicode バージョン (ReplaceFileW) に対して、オプトインしてMAX_PATH制限を削除できます。 詳細については、「 名前付けファイル、パス、および名前空間 」の「パスの最大長制限」セクションを参照してください。
 
ReplaceFile 関数は、1 つの関数内で複数のステップを組み合わせます。 アプリケーションでは、別の関数を呼び出す代わりに ReplaceFile を呼び出して、データを新しいファイルに保存したり、一時名前を使用して元のファイルの名前を変更したり、新しいファイルの名前を元のファイルと同じ名前に変更したり、元のファイルを削除したりできます。 もう 1 つの利点は 、ReplaceFile が新しいファイル データをコピーするだけでなく、元のファイルの次の属性も保持することです。
  • 作成日時
  • 短いファイル名
  • オブジェクト識別子
  • DACL
  • セキュリティ リソース属性
  • 暗号化
  • 圧縮
  • 置換ファイルに名前付きストリームがまだ存在しない
たとえば、置換ファイルが暗号化されていても、置換されたファイルが暗号化されていない場合、結果のファイルは暗号化されません。

Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista、Windows Server 2003、Windows XP: 元のファイルのセキュリティ リソース属性 (ATTRIBUTE_SECURITY_INFORMATION) は、Windows 8してWindows Server 2012するまで保持されません。

注:  

選択的 ワイプを使用して置換ファイルが保護されている場合、置き換えられたファイルは置換ファイルのエンタープライズ ID によって保護されます。

 
結果のファイルのファイル ID は、置換ファイルと同じです。

バックアップ ファイル、置換されたファイル、および置換ファイルはすべて同じボリューム上に存在する必要があります。

ファイルを削除または名前変更するには、ファイルに対する削除アクセス許可を持っているか、親ディレクトリの子アクセス許可を削除する必要があります。 削除と削除の子を除くすべてのアクセス権を持つディレクトリを設定し、新しいファイルの DAC が継承される場合は、ファイルを削除しなくても作成できます。 ただし、ファイルを作成すると、ファイルの作成時に返されたハンドルに対して要求したすべてのアクセス権を取得できます。 ファイルの作成時に削除アクセス許可を要求した場合は、そのハンドルを使用してファイルを削除または名前変更できますが、他のハンドルでは削除できません。

注意

winbase.h ヘッダーは、Unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして ReplaceFile を定義します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

   
サポートされている最小のクライアント Windows XP [デスクトップ アプリ |UWP アプリ]
サポートされている最小のサーバー Windows Server 2003 [デスクトップ アプリ |UWP アプリ]
対象プラットフォーム Windows
ヘッダー winbase.h (Windows.h を含む)
Library Kernel32.lib
[DLL] Kernel32.dll

関連項目

CopyFile

CopyFileEx

ファイル管理機能

MoveFile

MoveFileEx

MoveFileWithProgress