FILE_CopyEX

<< Click to Display Table of Contents >>

Navigation:  ThinBASIC Modules > File > FILE: functions working on files >

FILE_CopyEX

 

Description

 

Copy a file from one location into another location/name using a callback function to control copy progress.

 

Syntax

 

n = FILE_COPYEX(FileName_Source, FileName_Destination, CallbackFunction [, lpData [, dwCopyFlags]])

 

Returns

 

Number.

0 means no errors.

 

Parameters

 

Name

Type

Optional

Meaning

FileName_Source

String

No

Source file name, full path.

FileName_Destination

String

No

Destination file name, full path.

CallbackFunction

No

Name of the callback function used to control progress of the copy operation.

 
Callback function MUST have exactly the following declaration
callback Function CopyProgressRoutine(

ByVal TotalFileSize          As Quad, 'total file size, in bytes

ByVal TotalBytesTransferred  As Quad, 'total number of bytes transferred

ByVal StreamSize             As Quad, 'total number of bytes for this stream

ByVal StreamBytesTransferred As Quad, 'total number of bytes transferred for stream

ByVal dwStreamNumber         As Long, 'the current stream

ByVal dwCallbackReason       As Long, 'reason for callback

ByVal hSourceFile            As Long, 'handle to the source file

ByVal hDestinationFile       As Long, 'handle to the destination file

ByVal lpData                 As Long) As Long

 

See example below to see how to use this command

 

lpData

Number

Yes

a LONG/DWORD number that will be passed to CallbackFunction when executed.

It can be used to pass callback function some data needed to its execution

dwCopyFlags

Number

Yes

a LONG/DWORD flags that specify how the file is to be copied.

 
This parameter can be a combination of the following values:

 
%COPY_FILE_ALLOW_DECRYPTED_DESTINATION
An attempt to copy an encrypted file will succeed even if the destination copy cannot be encrypted.

 

%COPY_FILE_COPY_SYMLINK
If the source file is a symbolic link, the destination file is also a symbolic link pointing to the same file that the source symbolic link is pointing to.

Windows Server 2003 and Windows XP:  This value is not supported.

 

%COPY_FILE_FAIL_IF_EXISTS
The copy operation fails immediately if the target file already exists.
 

%COPY_FILE_NO_BUFFERING
The copy operation is performed using unbuffered I/O, bypassing system I/O cache resources. Recommended for very large file transfers.

Windows Server 2003 and Windows XP:  This value is not supported.

 

%COPY_FILE_RESTARTABLE
Progress of the copy is tracked in the target file in case the copy fails. The failed copy can be restarted at a later time by specifying the same values for FileName_Source and FileName_Destination as those used in the call that failed. This can significantly slow down the copy operation as the new file may be flushed multiple times during the copy operation.

     

 

Remarks

 

Internally FILE_COPYEX uses CopyFileExW Windows API function

 

CallBack function MUST send back one of the following equates:

•%FILE_PROGRESS_CONTINUE
Continue the copy operation
 

•%FILE_PROGRESS_CANCEL
Cancel the copy operation and delete the destination file
 

•%FILE_PROGRESS_STOP
Stop the copy operation. It can be restarted at a later time.
 

•%FILE_PROGRESS_QUIET
Continue the copy operation, but stop invoking CopyProgressRoutine to report progress

 

Restrictions

 

See also

 

File Module,

 

References:

 https://docs.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-copyfileexw

 

Examples

 

'---References

'     https://docs.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-copyfileexa

'     https://docs.microsoft.com/it-it/windows/win32/api/winbase/nc-winbase-lpprogress_routine

'---------------------------------------------------------------------------------------------

 

uses "Console"

uses "File"

 

callback Function CopyProgressRoutine( 

            ByVal TotalFileSize           As Quad,

            ByVal TotalBytesTransferred   As Quad,

            ByVal StreamSize              As Quad,

            ByVal StreamBytesTransferred  As Quad,

            ByVal dwStreamNumber          As Long,

            ByVal dwCallbackReason        As Long,

            ByVal hSourceFile             As Long,

            ByVal hDestinationFile        As Long,

            ByVal lpData                  As Long  ) As Long

 

  printl "TotalFileSize............", TotalFileSize         at 10, 10

  printl "TotalBytesTransferred....", TotalBytesTransferred At 10, 11

 

  function = %FILE_PROGRESS_CONTINUE

 

end Function

 

string sFileSource      = APP_ScriptFullName

string sFileDestination = sFileSource & ".File_CopyEX.txt"

long   lRet

 

printl "Copying: " & sFileSource

printl "To.....: " & sFileDestination

 

lRet = file_copyex(sFileSource, sFileDestination, CopyProgressRoutine)

 

printl "Result.: " & lret

 

printl "All done. Press a key to end"

WaitKey