src/CustomActions/SystemTools/Win32Impl.cpp File Reference

#include "StdAfx.h"
#include "Win32Impl.h"
#include "FlagMaps.h"

Namespaces
namespace	Win32_CopyFiles
namespace	Win32_MoveFiles
namespace	Win32_DeleteFiles
Enumerations
enum	Win32_CopyFiles::CopyFilesAttributes { Win32_CopyFiles::CopyOnInstall = 1, Win32_CopyFiles::CopyOnUnInstall = 2, Win32_CopyFiles::CopyRecurse = 16 }
enum	Win32_MoveFiles::MoveFilesAttributes { Win32_MoveFiles::MoveOnInstall = 1, Win32_MoveFiles::MoveOnUnInstall = 2, Win32_MoveFiles::MoveRecurse = 16, Win32_MoveFiles::DeleteEmptyDirectories = 32 }
enum	Win32_DeleteFiles::DeleteFilesAttributes {   Win32_DeleteFiles::DeleteOnInstall = 1, Win32_DeleteFiles::DeleteOnUnInstall = 2, Win32_DeleteFiles::CheckIfExists = 16, Win32_DeleteFiles::DeleteRecurse = 32,   Win32_DeleteFiles::DeleteEmptyDirectories = 64 }
enum	ExecuteAttributes {   ExecuteOnInstall = 1, ExecuteOnUnInstall = 2, ContinueOnError = 1, ExecuteOnInstall = 2,   ExecuteOnUnInstall = 4, ScheduleIndependently = 32 }
Functions
CA_API UINT __stdcall	Win32_CopyFile (MSIHANDLE hInstall)
	Copy a file.
CA_API UINT __stdcall	Win32_MoveFile (MSIHANDLE hInstall)
	Move a file.
CA_API UINT __stdcall	Win32_DeleteFile (MSIHANDLE hInstall)
	Delete a file.
CA_API UINT __stdcall	Win32_DeleteDirectory (MSIHANDLE hInstall)
	Delete a directory with all subdirectories and files.
CA_API UINT __stdcall	Win32_CreateDirectory (MSIHANDLE hInstall)
	Create a directory.
CA_API UINT __stdcall	Win32_CopyFiles_Deferred (MSIHANDLE hInstall)
CA_API UINT __stdcall	Win32_CopyFiles_Immediate (MSIHANDLE hInstall)
	Copy files. This is a table-driven custom action. Use in combination with AppSecInc::Wix::Extensions::SystemToolsExtension.
CA_API UINT __stdcall	Win32_MoveFiles_Deferred (MSIHANDLE hInstall)
CA_API UINT __stdcall	Win32_MoveFiles_Immediate (MSIHANDLE hInstall)
	Move files. This is a table-driven custom action. Use in combination with AppSecInc::Wix::Extensions::SystemToolsExtension.
CA_API UINT __stdcall	Win32_DeleteFiles_Deferred (MSIHANDLE hInstall)
CA_API UINT __stdcall	Win32_DeleteFiles_Immediate (MSIHANDLE hInstall)
	Delete files. This is a table-driven custom action. Use in combination with AppSecInc::Wix::Extensions::SystemToolsExtension.
CA_API UINT __stdcall	Win32_Execute_Immediate (MSIHANDLE hInstall)
	Execute commands (immediate). This is a table-driven custom action. Use in combination with AppSecInc::Wix::Extensions::SystemToolsExtension.
CA_API UINT __stdcall	Win32_Execute_Rollback (MSIHANDLE hInstall)
	Execute commands (rollback). This is a table-driven custom action. Use in combination with AppSecInc::Wix::Extensions::SystemToolsExtension.
CA_API UINT __stdcall	Win32_Execute_Deferred (MSIHANDLE hInstall)
	Execute commands (deferred). This is a table-driven custom action. Use in combination with AppSecInc::Wix::Extensions::SystemToolsExtension.
CA_API UINT __stdcall	Win32_GetFileSize (MSIHANDLE hInstall)
	Get the size of a file.
CA_API UINT __stdcall	Win32_FileExists (MSIHANDLE hInstall)
	Check if file exists.
CA_API UINT __stdcall	Win32_GetParentDirectory (MSIHANDLE hInstall)
	Get the parent directory.
CA_API UINT __stdcall	Win32_WriteFile (MSIHANDLE hInstall)
	Write to an ANSI text file.
CA_API UINT __stdcall	Win32_ReadFile (MSIHANDLE hInstall)
	Read contents of an ANSI file into a property.
CA_API UINT __stdcall	Win32_GetSpecialFolderPath (MSIHANDLE hInstall)
	Retrieves the path of a special folder, identified by its CSIDL.

---

Enumeration Type Documentation

enum ExecuteAttributes

Enumerator:

ExecuteOnInstall
ExecuteOnUnInstall
ContinueOnError
ExecuteOnInstall
ExecuteOnUnInstall
ScheduleIndependently

---

Function Documentation

CA_API UINT __stdcall Win32_CopyFile

(

MSIHANDLE

hInstall

)

Copy a file.

Parameters:

WIN32_SOURCE_FILENAME	Fully qualified path to the file to copy.
WIN32_TARGET_FILENAME	Fully qualified path to the target file.
WIN32_TARGET_OVERWRITE	One of "yes", "no", "error".

Unlike wix built-in custom actions the files copied with Win32_CopyFile are not tracked by MSI. Use Win32_CopyFile to copy a configuration file that will be preserved on uninstall for example.

CA_API UINT __stdcall Win32_CopyFiles_Deferred

(

MSIHANDLE

hInstall

)

CA_API UINT __stdcall Win32_CopyFiles_Immediate

(

MSIHANDLE

hInstall

)

Copy files. This is a table-driven custom action. Use in combination with AppSecInc::Wix::Extensions::SystemToolsExtension.

CA_API UINT __stdcall Win32_CreateDirectory

(

MSIHANDLE

hInstall

)

Create a directory.

Parameters:

WIN32_PATH

Fully qualified path to the directory to create; may contain several levels of directories to make.

Returns:

WIN32_PATH_CREATED Fully qualified path that has been created first; this is the top level directory that didn't exist.

CA_API UINT __stdcall Win32_DeleteDirectory

(

MSIHANDLE

hInstall

)

Delete a directory with all subdirectories and files.

Parameters:

WIN32_PATH

Fully qualified path to the directory to delete.

CA_API UINT __stdcall Win32_DeleteFile

(

MSIHANDLE

hInstall

)

Delete a file.

Parameters:

WIN32_FILENAME

Fully qualified path to the file to delete.

Unlike Wix FileCopy the files deleted by Win32_DeleteFile are not tracked by MSI. Do not delete a file that belongs to a component.

CA_API UINT __stdcall Win32_DeleteFiles_Deferred

(

MSIHANDLE

hInstall

)

CA_API UINT __stdcall Win32_DeleteFiles_Immediate

(

MSIHANDLE

hInstall

)

Delete files. This is a table-driven custom action. Use in combination with AppSecInc::Wix::Extensions::SystemToolsExtension.

CA_API UINT __stdcall Win32_Execute_Deferred

(

MSIHANDLE

hInstall

)

Execute commands (deferred). This is a table-driven custom action. Use in combination with AppSecInc::Wix::Extensions::SystemToolsExtension.

CA_API UINT __stdcall Win32_Execute_Immediate

(

MSIHANDLE

hInstall

)

Execute commands (immediate). This is a table-driven custom action. Use in combination with AppSecInc::Wix::Extensions::SystemToolsExtension.

CA_API UINT __stdcall Win32_Execute_Rollback

(

MSIHANDLE

hInstall

)

Execute commands (rollback). This is a table-driven custom action. Use in combination with AppSecInc::Wix::Extensions::SystemToolsExtension.

CA_API UINT __stdcall Win32_FileExists

(

MSIHANDLE

hInstall

)

Check if file exists.

Parameters:

WIN32_FILENAME

Fully qualified path to the file to check

Returns:

WIN32_FILE_EXISTS "1" if file exists; "0" otherwise.

Example:

<CustomAction Id="Win32_FileExists_SetFilename" Property="WIN32_FILENAME" Value="[SystemFolder]\shell32.dll" />
<CustomAction Id="Win32_FileExists" DllEntry="Win32_FileSize" BinaryKey="SystemTools" />
<CustomAction Id="GetSizeIfExists" DllEntry="Win32_FileSize" BinaryKey="SystemTools" />
<InstallExecuteSequence>
  <Custom Action="Win32_FileExists_SetFilename" After="AppSearch">1</Custom>
  <Custom Action="Win32_FileExists" After="Win32_GetFileSize_SetFilename">1</Custom>
  <Custom Action="GetSizeIfExists" After="Win32_FileExists" >WIN32_FILE_EXISTS = "1"</Custom>
</InstallExecuteSequence>

CA_API UINT __stdcall Win32_GetFileSize

(

MSIHANDLE

hInstall

)

Get the size of a file.

Parameters:

WIN32_FILENAME	Fully qualified path to the file to get the size of.
WIN32_FILESIZE_FORMAT	File size format, "AUTO" (default) for automatic, "BYTES", "KB", "MB" or "GB".
WIN32_FILESIZE_PRECISION	Number of decimal digits in the result, default is 0. Results are rounded to the number of decimal digits specified.

Returns:

WIN32_FILESIZE String representing the size of the file, numbers only, without type (eg. 1.23)

WIN32_FILESIZE_FORMATTED String representing the size of the file, numbers and type only (eg. 1.23 GB).

WIN32_FILESIZE_BYTES String representing the size of the file in bytes, numbers only (eg. 12300000000).

Example:

<CustomAction Id="Win32_GetFileSize_SetFilename" Property="WIN32_FILENAME" Value="[SystemFolder]\shell32.dll" />
<CustomAction Id="Win32_GetFileSize_SetFormat" Property="WIN32_FILESIZE_FORMAT" Value="MB" />
<CustomAction Id="Win32_GetFileSize_SetPrecision" Property="WIN32_FILESIZE_PRECISION" Value="2" />
<CustomAction Id="Win32_FileSize" Property="SHELL32FILE_SIZE" Value="[WIN32_FILESIZE_FORMATTED]" />
<InstallExecuteSequence>
  <Custom Action="Win32_GetFileSize_SetFilename" After="AppSearch">1</Custom>
  <Custom Action="Win32_GetFileSize_SetFormat" After="Win32_GetFileSize_SetFilename">1</Custom>
  <Custom Action="Win32_GetFileSize_SetPrecision" After="Win32_GetFileSize_SetFormat">1</Custom>
  <Custom Action="Win32_GetFileSize" After="Win32_GetFileSize_SetPrecision">1</Custom>
  <Custom Action="Win32_FileSize" After="Win32_GetFileSize" />
</InstallExecuteSequence>

CA_API UINT __stdcall Win32_GetParentDirectory

(

MSIHANDLE

hInstall

)

Get the parent directory.

Parameters:

WIN32_DIRECTORY

Fully qualified path to a directory

Returns:

WIN32_PARENT_DIRECTORY Fully qualified path to the parent directory terminated with a backslash

The value returned is either blank or always terminated with a backslash. If the directory doesn't have a parent (eg. C:\), the same directory is returned. If the directory is blank, a blank value is returned.

CA_API UINT __stdcall Win32_GetSpecialFolderPath

(

MSIHANDLE

hInstall

)

Retrieves the path of a special folder, identified by its CSIDL.

Parameters:

WIN32_FOLDER_CSIDL	A CSIDL that identifies the folder of interest, such as CSIDL_APPDATA.
WIN32_FOLDER_CREATE	Set to "1" to indicate whether the folder should be created if it does not already exist.

Returns:

WIN32_SPECIAL_FOLDER Fully qualified path to the special folder.

CA_API UINT __stdcall Win32_MoveFile

(

MSIHANDLE

hInstall

)

Move a file.

Parameters:

WIN32_SOURCE_FILENAME	Fully qualified path to the file to move.
WIN32_TARGET_FILENAME	Fully qualified path to the target file.
WIN32_TARGET_OVERWRITE	One of "yes", "no", "error".

Unlike wix built-in custom actions the files being moved with Win32_MoveFile are not tracked by MSI. Do not use Win32_MoveFile to copy a file that belongs to a component.

CA_API UINT __stdcall Win32_MoveFiles_Deferred

(

MSIHANDLE

hInstall

)

CA_API UINT __stdcall Win32_MoveFiles_Immediate

(

MSIHANDLE

hInstall

)

Move files. This is a table-driven custom action. Use in combination with AppSecInc::Wix::Extensions::SystemToolsExtension.

CA_API UINT __stdcall Win32_ReadFile

(

MSIHANDLE

hInstall

)

Read contents of an ANSI file into a property.

Parameters:

WIN32_FILE_NAME

Fully qualified path to the target file.

Returns:

WIN32_FILE_DATA Data in the file.

If the file is in the UTF-8 format, the data is converted to UNICODE.

CA_API UINT __stdcall Win32_WriteFile

(

MSIHANDLE

hInstall

)

Write to an ANSI text file.

Parameters:

WIN32_FILE_DATA	Data to write to a file.
WIN32_FILE_NAME	Fully qualified path to the target file.
WIN32_FILE_ENCODING	Set to "UTF-8" to write a file in the UTF-8 format, "ANSI" to write the file in the ANSI format. Default is ANSI.