Copies an existing file to a new file. Notifies the application of its progress through a callback function. If the source file has verification data, the contents of the file are verified during the copy operation.

BOOL
WINAPI
WIMCopyFile(
	 PWSTR			pszExistingFileName,
	 PWSTR			pszNewFileName,
	 LPPROGRESS_ROUTINE  pProgressRoutine,
		 PVOID			pvData,
	 PBOOL			pbCancel,
	 DWORD			 dwCopyFlags
	);

Parameters

pszExistingFileName

[in] A pointer to a null-terminated string that specifies the name of an existing .wim file.

pszNewFileName

[in] A pointer to a null-terminated string that specifies the name of the new file.

pProgressRouting

[in] The address of a callback function of type LPPROGRESS_ROUTINE that is called each time another portion of the file has been copied. This parameter can be NULL. For more information about the progress callback function, see the CopyProgressRoutine function in the MSDN Library.

pData

[in] An argument to be passed to the callback function. This parameter can be NULL.

pbCancel

[in] If this flag is set to TRUE during the copy operation, the operation is canceled. Otherwise, the copy operation continues to completion.

dwCopyFlags

[in] A flag that specifies how the file is to be copied. This parameter can be a combination of the following values:

Value	Description
COPY_FILE_FAIL_IF_EXISTS	The copy operation fails immediately if the target file already exists.
WIM_COPY_FILE_RETRY	Automatically retries copy operations in event of failures.

Return Value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To obtain extended error information, call the GetLastError function.

If pProgressRoutine returns PROGRESS_CANCEL because the user cancels the operation, the WIMCopyFile function will return zero and set the LastError to ERROR_REQUEST_ABORTED. In this case, the partially copied destination file is deleted.

If pProgressRoutine returns PROGRESS_STOP because the user stops the operation, WIMCopyFile will return zero and set the LastError to ERROR_REQUEST_ABORTED. In this case, the partially copied destination file is left intact.

If the source file contains verification information, an integrity check is performed on each block as it is copied. If the integrity check fails, the WIMCopyFile function will return zero and set the LastError to ERROR_FILE_CORRUPT.

Remarks

This function does not preserve extended attributes, security attributes, OLE-structured storage, NTFS file system alternate data streams, or file attributes.

The WIMCopyFile function copies only the default stream of the source file, so the StreamSize and StreamBytesTransferred parameters to the CopyProgressRoutine function will always match TotalFileSize and TotalBytesTransferred, respectively. The value of the dwStreamNumber parameter will always be 1 and the value of the dwCallBackReason parameter will always be CALLBACK_CHUNK_FINISHED.

If the destination file already exists and has the FILE_ATTRIBUTE_HIDDEN or FILE_ATTRIBUTE_READONLY attribute set, this function fails with ERROR_ACCESS_DENIED.