ReplaceFileW 関数 (winbase.h)
元のファイルのバックアップ コピーを作成するオプションを使って、あるファイルを別のファイルに置き換えます。 置換ファイルは、置き換えられたファイルの名前とその ID を前提としています。
構文
BOOL ReplaceFileW(
[in] LPCWSTR lpReplacedFileName,
[in] LPCWSTR lpReplacementFileName,
[in, optional] LPCWSTR 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の制限を削除するようにオプトインできます。 詳細については、「 ファイル、パス、および名前空間の名前付け 」の「最大パス長の制限」セクションを参照してください。
この関数は、SYNCHRONIZE、GENERIC_READ、GENERIC_WRITE、DELETE、および WRITE_DAC アクセス権を使用してこのファイルを開き、すべての属性と ACL を保持できるようにします。 これが失敗した場合、関数は SYNCHRONIZE、 GENERIC_READ、 DELETE、および WRITE_DAC アクセス権を使用してファイルを開こうとします。 共有モードは指定されません。
[in, optional] lpBackupFileName
lpReplacedFileName ファイルのバックアップ コピーとして機能するファイルの名前。 このパラメーターが NULL の場合、バックアップ ファイルは作成されません。 バックアップ ファイルの実装の詳細については、「解説」セクションを参照してください。
既定では、名前はMAX_PATH文字に制限されています。 この制限を 32,767 文字のワイド文字に拡張するには、パスの先頭に "\\?\" を付加します。 詳細については、「ファイル、パス、および名前空間の名前付け」を参照してください。
ヒント
Windows 10 バージョン 1607 以降では、"\\?\" を前に置かずに、MAX_PATHの制限を削除するようにオプトインできます。 詳細については、「 ファイル、パス、および名前空間の名前付け 」の「最大パス長の制限」セクションを参照してください。
[in] dwReplaceFlags
置換オプション。 このパラメーターには、次の 1 つ以上の値を指定できます。
lpExclude
将来使用するために予約されています。
lpReserved
将来使用するために予約されています。
戻り値
関数が成功すると、戻り値は 0 以外になります。
関数が失敗した場合は、0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。 この関数で発生する可能性のあるエラー コードを次に示します。
| リターン コード/値 | Description |
|---|---|
|
置換ファイルの名前を変更できませんでした。 lpBackupFileName を指定した場合、置き換えられたファイルと置換後のファイルは元のファイル名を保持します。 それ以外の場合、置き換えられたファイルは存在しなくなり、置換ファイルは元の名前の下に存在します。 |
|
置換ファイルを移動できませんでした。 置換ファイルは元の名前の下にまだ存在します。ただし、置き換えるファイルからファイル ストリームと属性を継承しています。 置き換えるファイルは、別の名前で引き続き存在します。 lpBackupFileName を指定すると、置き換えられたファイルの名前になります。 |
|
置き換えられたファイルを削除できませんでした。 置き換えられたファイルと置換されたファイルは、元のファイル名を保持します。 |
ERROR_INVALID_PARAMETERなどの他のエラーが返された場合、置換されたファイルと置換されたファイルは元のファイル名を保持します。 このシナリオでは、バックアップ ファイルが存在せず、置き換えられたファイルのすべての属性とストリームが置換ファイルによって継承されるとは限りません。
注釈
- 作成日時
- 短いファイル名
- オブジェクト識別子
- 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 によって保護されます。
バックアップ ファイル、置換されたファイル、および置換ファイルはすべて同じボリューム上に存在する必要があります。
ファイルを削除または名前変更するには、ファイルに対する削除アクセス許可を持っているか、親ディレクトリの子アクセス許可を削除する必要があります。 削除と削除の子を除くすべてのアクセス権を持つディレクトリを設定し、新しいファイルの 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 |