LPPROGRESS_ROUTINE callback function (winbase.h)

Article
02/22/2024

An application-defined callback function used with the CopyFileEx, MoveFileTransacted, and MoveFileWithProgress functions. It is called when a portion of a copy or move operation is completed. The LPPROGRESS_ROUTINE type defines a pointer to this callback function. CopyProgressRoutine is a placeholder for the application-defined function name.

Syntax

LPPROGRESS_ROUTINE LpprogressRoutine;

DWORD LpprogressRoutine(
  [in]           LARGE_INTEGER TotalFileSize,
  [in]           LARGE_INTEGER TotalBytesTransferred,
  [in]           LARGE_INTEGER StreamSize,
  [in]           LARGE_INTEGER StreamBytesTransferred,
  [in]           DWORD dwStreamNumber,
  [in]           DWORD dwCallbackReason,
  [in]           HANDLE hSourceFile,
  [in]           HANDLE hDestinationFile,
  [in, optional] LPVOID lpData
)
{...}

Parameters

[in] TotalFileSize

The total size of the file, in bytes.

[in] TotalBytesTransferred

The total number of bytes transferred from the source file to the destination file since the copy operation began.

[in] StreamSize

The total size of the current file stream, in bytes.

[in] StreamBytesTransferred

The total number of bytes in the current stream that have been transferred from the source file to the destination file since the copy operation began.

[in] dwStreamNumber

A handle to the current stream. The first time CopyProgressRoutine is called, the stream number is 1.

[in] dwCallbackReason

The reason that CopyProgressRoutine was called. This parameter can be one of the following values.

Value	Meaning
CALLBACK_CHUNK_FINISHED 0x00000000	Another part of the data file was copied.
CALLBACK_STREAM_SWITCH 0x00000001	Another stream was created and is about to be copied. This is the callback reason given when the callback routine is first invoked.

[in] hSourceFile

A handle to the source file.

[in] hDestinationFile

A handle to the destination file

[in, optional] lpData

Argument passed to CopyProgressRoutine by CopyFileEx, MoveFileTransacted, or MoveFileWithProgress.

Return value

The CopyProgressRoutine function should return one of the following values.

Return code/value	Description
PROGRESS_CANCEL 1	Cancel the copy operation and delete the destination file.
PROGRESS_CONTINUE 0	Continue the copy operation.
PROGRESS_QUIET 3	Continue the copy operation, but stop invoking CopyProgressRoutine to report progress.
PROGRESS_STOP 2	Stop the copy operation. It can be restarted at a later time.

Remarks

An application can use this information to display a progress bar that shows the total number of bytes copied as a percent of the total file size.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	winbase.h (include Windows.h)