LPPROGRESS_ROUTINE callback function (winbase.h)

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

   
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)

See also

CopyFileEx

File Management Functions

MoveFileTransacted

MoveFileWithProgress