LPPROGRESS_ROUTINE callback function

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(
  LARGE_INTEGER TotalFileSize,
  LARGE_INTEGER TotalBytesTransferred,
  LARGE_INTEGER StreamSize,
  LARGE_INTEGER StreamBytesTransferred,
  DWORD dwStreamNumber,
  DWORD dwCallbackReason,
  HANDLE hSourceFile,
  HANDLE hDestinationFile,
  LPVOID lpData
)
{...}

Parameters

TotalFileSize

The total size of the file, in bytes.

TotalBytesTransferred

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

StreamSize

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

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.

dwStreamNumber

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

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.

hSourceFile

A handle to the source file.

hDestinationFile

A handle to the destination file

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

   
Windows version Windows XP [desktop apps only] Windows Server 2003 [desktop apps only]
Target Platform Windows
Header winbase.h (include Windows.h)

See Also

CopyFileEx

File Management Functions

MoveFileTransacted

MoveFileWithProgress