Updates the existing Solution Header of FileToUpdate. Opens the file for exclusive access; the caller must have both read and write access to the file. NewHeader may be any (non-zero) size, including larger or smaller than the existing header.
void
FesfUtil2UpdateHeaderExclusiveWithExtension(
std::wstring_view FileToUpdate,
const FESF_UTIL2_SOLUTION_HEADER &NewHeader,
const std::wstring_view & BackupFileTag = L"");
DWORD
FesfUtil2UpdateHeaderExclusiveWithExtension_C(
[in] LPCWSTR FileToUpdate,
[in] PVOID HeaderBuffer,
[in] DWORD HeaderLength,
[inopt] LPCWSTR BackupFileTag);
FileToUpdate
Fully qualified path name of file to receive the new header.
NewHeader
Valid instance of a new header to be substituted for the existing one.
BackupFileTag
A tag to use in forming the backup file name. Defaults to an empty string. See remarks section for more information.
Throws an FEU2Exception if an error is encountered.
Requires the caller to have SeRestorePrivilege, SeTakeOwnershipPrivilege, and SeSecurityPrivilege on the system where the file is located. If these privileges are not already activated, they will be activated by the function and deactivated before return. Requires the caller to have both read and write access to the file.
This function allows a file to be updated with a Solution Header that is larger than that which will fit in the current file. To accomplish this, an entirely new file is created with the new header, the raw data from the original file is copied to the new file, the original file's characteristics are propagated to the new file using the Win32 function ReplaceFile, and the original file's security attributes (DACL and SACL) are propagated to the new file.
If a non-zero-length BackupFileTag is specified by the caller, the name of the backup file will incorporate that tag in the name. If a name is not specified, the tag "FESF_BACKUP" will be used. The backup file name is used by the Win32 ReplaceFile (which is called by this function). In addition, if the caller specifies a BackupFileTag, the backup file will be retained on return, even when this function is successful. If a BackupFileTag is not specified, and this function is successful, the backup file is deleted before returning to the caller.
The name of the backup file is formed by pre-pending the backup tag (either the one passed-in by the caller or the default value) to the filename portion of the fully qualified file path. The backup tag is separated from the original file name by a "_" character. For example:
FileToUpdate: C:\Fred\bob.txt
Default backup file name: C:\Fred\FESF_BACKUP_bob.txt
This scheme was devised to avoid clashing with the name of the original file and to make it more likely to preserve the original file's short name.
IFesfDs:: UpdateHeaderWithExtension