XCopyFile

Feedback

Syntax

XCopyFile (szSrcFile, szTargetPath, nOp);

Description

The XCopyFile function copies one or more files from a source directory to a target directory. This function can copy subdirectories as well as files. XCopyFile creates subdirectories on the target directory if necessary when the constant INCLUDE_SUBDIR is passed in the parameter nOp.

You cannot rename files using XCopyFile. To rename a file during a file copy operation, use the CopyFile function.

Parameters

szSrcFile

Specifies which files to copy. If the filespec is qualified, that is, if it includes a path, XCopyFile will copy the file from the specified location. If szSrcFile contains an unqualified filename, that is, without path information, CopyFile will copy from the directory identified by the system variable SRCDIR. To copy multiple files, use wild card characters in this parameter.

szTargetPath

Specifies the directory to which the files specified by szSrcFile should be copied. If this parameter contains a null string (""), the files will be copied to the directory specified by the system variable TARGETDIR.

nOp

Specifies the type of copy operation to perform. Pass one of the following predefined constants in this parameter. To specify more than one option, combine constants with the OR (|) operator.

COMP_NORMAL

Copies files to the target system, updating existing same-named files regardless of date, time, or version information.

COMP_UPDATE_SAME

Update the files even if the date, time, or version of the source file is identical to the target file. You must also specify either COMP_UPDATE_DATE or COMP_UPDATE_VERSION with this constant. Otherwise, InstallShield ignores this constant.

COMP_UPDATE_DATE

Updates the files based on the file date and time. This constant updates the file if the source file is newer than the target file.

COMP_UPDATE_VERSION

Updates the files based on the file version. This constant updates the file if the source file is newer than the target file. If the file version does not exist in both the source and the target files, date and time are used for comparison. If the file version does not exist for only one file, InstallShield assumes that the file containing version information is the newer file.

SELFREGISTER

Carries out the self-registration process immediately, when using the "non-batch method" of installing self-registering files.

If you have called Enable(SELFREGISTERBATCH), this option queues up self-registering files for registration. The files are registered once Do(SELFREGISTRATIONPROCESS) is called, when using the "batch method" of installing self-registering files.

Always use SELFREGISTER together with the SHAREDFILE option, combining them with the bitwise OR operator ( | ).

SHAREDFILE

Combines shared and locked file handling by causing XCopyFile to treat all files as shared, and to record locked .dll and .exe files for update when Windows or the system restarts. See RebootDialog and SdFinishReboot.

The SHAREDFILE option causes XCopyFile to treat all files as shared files and increment the registry reference counter by one when the file exists in the target directory and it has a reference count greater than 0. If the shared file does not exist in the target directory and it has no reference counter, InstallShield creates the counter and sets it to 1. If the shared file already exists in the target directory but has no reference counter, InstallShield creates the counter and initializes it to 2 as a precaution against accidental removal during uninstallation.

LOCKEDFILE

Causes XCopyFile to record locked .dll and .exe files for update when Windows or the system is rebooted. A locked file is a file that is in use by an application or the system when InstallShield attempts to access or update the file. The LOCKEDFILE option works like SHAREDFILE except that LOCKEDFILE does not create registry entries or modify the registry reference counter. You cannot use the LOCKEDFILE option when using the SHAREDFILE option. There are some unshared files (such as shell extensions) for which the script writer does not want a registry entry and reference counter. These files should never be uninstalled, except by the application itself. LOCKEDFILE allows XCopyFile to handle locked files that are not shared.

EXCLUDE_SUBDIR

Specifies not to include subdirectories contained in the source path.

INCLUDE_SUBDIR

Specifies that subdirectories below the source path must also be copied. Note that empty subdirectories are not copied.

Return values

0

Indicates that the function successfully copied the files.

< 0

Indicates that the function was unable to copy the files.

You can obtain the error message text associated with a large negative return value—for example, -2147024891 (0x80070005)—by calling FormatMessage.

Comments

• If you use unqualified filenames and set values for SRCDIR and TARGETDIR when using XCopyFile, save the current values using VarSave before calling XCopyFile and then restore them using VarRestore.
   
  
• Since Windows 95 and later do not allow an empty file to be copied and Windows NT does not allow creation of empty files, XCopyFile will not work under these platforms when used to copy empty files (Size = 0 KB).
   
  
• After modifying .ini files with WriteProfString, you will need to flush the cache buffer on Windows 95 or later before using XCopyFile. All .ini files are cached under Windows 95 and later; this behavior can cause a delay in writing changes to the specified files. This in turn can interfere with subsequent file operations. To avoid this problem, simply call WriteProfString with null parameters to force Windows 95 or later to write the data to the .ini file immediately:

         WriteProfString ("C:\\Test.ini", "Windows", "KeyboardDelay", "100");
         WriteProfString ("","","","");  //null string ("") for all four parameters

         //XCopyFile should now have access to updated file.
         XCopyFile ("C:\\Test.ini", "C:\\Temp", EXCLUDE_SUBDIR);