Win32::MSI::HighLevel - Perl wrapper for Windows Installer API
Version 1.0008
use Win32::MSI::HighLevel; my $filename = 'demo.msi'; unlink $filename; my $msi = HighLevel->new (-file => $filename, -mode => Win32::MSI::HighLevel::Common::kMSIDBOPEN_CREATE); $msi->addFeature ( -Feature => 'Complete', -Title => 'Full install', -Description => 'Install the whole ball of wax' ); $msi->createTable ( -table => 'Feature', -columnSpec => [ Feature => ['Key', 'Identifier'], Feature_Parent => 'Identifier', Title => 'Text(64)', Description => 'Text(255)', Display => 'Integer', Level => 'Integer', Directory_ => 'Directory', Attributes => 'Integer', ] ); $msi->writeTables (); $msi->commit (); $msi = 0;
Win32::MSI::HighLevel allows the creation (and editing) of Microsoft's Windows Installer technology based installer files (.msi files).
The initial impetus to create this module came from trying to find an automated build system friendly way of creating Windows installers. This has been very nicely achieved, especially as the core table information can be provided in text based table description files and thus managed with a revision control system.
Windows Installer files are simply database files. Almost all the information required for an installer is managed in tables in the database. This module facilitates manipulating the information in the tables.
MSI::HighLevel::new ($filename, $mode) returns a new database object. $mode may be one of:
MSI::HighLevel::new ($filename, $mode)
$mode
This doesn't really open the file read-only, but changes will not be written to disk.
Open in transactional mode so that changes are written only on commit. This is the default.
Opens read/write without transactional behavior.
This creates a new database in transactional mode.
Generally sample usage is provided for each method followed by a description of the method, then followed by any named parameters recognized by the method.
Most methods require named parameters. Named parameters with an uppercase first letter map directly on to table columns. Named parameters with a lower case first letter generally use contextual information to simplify using the method.
Table column names with a trailing _ are key columns for their table.
Create a new HighLevel instance given a file and open mode.
HighLevel
my $msi = HighLevel->new (-file => $file, -mode => Win32::MSI::HighLevel::Common::kMSIDBOPEN_DIRECT);
the .msi file to open/create
parameter - the open/create mode. Defaults to Common::kMSIDBOPEN_TRANSACT
Common::kMSIDBOPEN_TRANSACT
Must be one of:
open for read only assess only
open existing file for transacted access
open existing file for direct (non-transacted) access
create a new file for transacted access (see "commit" below)
create a new file for direct (non-transacted) access
Provide the (absolute) source directory that corresponds to the TARGETDIR directory on the target system. Directories on the target system have the same relative path from TARGETDIR as directories on the source system have to the source folder.
-sourceRoot defaults to the cwd.
-sourceRoot
Provide the default (absolute) target directory for the install. Note that the actual location can be set at install time by the user.
Provide the path to a scratch location that can be used to create intermediate files and folders during the installer build process.
$msi->autovivifyTables (qw(Components Dialog Feature Properties));
Ensure that a list of tables exist. Create any tables in the list that do not exist already.
This should be called after "populateTables" has been called if you are not dealing with a new .msi file.
Close the database. Generally "close" is not required to be called explicitly as the database should close cleanly when the HighLevel object is destroyed.
$msi->close ();
"commit" is used to update the database in transacted mode. Although the .msi database API provides a commit which must be called in transacted mode, there doesn't seem to be anything like an explicit rollback! An implicit rollback happens when the database is closed without a commit however.
$msi->commit ();
Add an entry to the AppSearch table.
Property that is set by the AppSearch action when it finds a match for the signature.
An entry into the Signature table (for a file) or a directory name.
Add a binary file to the installation.
Id to be used as the key entry in the binary file table. This entry must be unique.
Path to the file to be added on the source system.
Adds a cabinet file the the Cabs table and updates the media table to match.
This routine is primarily used by createCabs and should not generally be required by users.
"addComponent" adds a component associated with a specific Directory table entry and a group of files.
my $newId = $msi->addComponent (-Directory_ => 'wibble', -features => ['Complete']);
Component attribute flags ored together. Default value is 0 (no flags set).
A condition that is used at install time to determine if the component should be installed.
Identifier for the directory entry associated with the component.
Array of Feature table Feature identifiers that the component is referenced by.
This parameter is required to generate appropriate entries in the FeatureComponents table.
Optional file name for the key file associated with the component.
If the directory is to be used in the CreateFolder table then the file name should be omitted and the directory name will be used as the key for the component.
Provide an UpgradeCode guid so that a component installer can provide an upgraded component for an product installed using a different installer.
The UpgradeCode guid must be the UprgadeCode guid used by the main product installer.
-guidSeed would normally be used with -requestedId.
Primary key into either the File, ODBCDataSource or Registry table. This is only required for generating a component that installs registry entries and doesn't install any files or directories.
Do not use -File and -KeyPath together.
Desired id for component. If there exists a component with the same Id already then the suggested Id will be used as a base to generate a new Id.
"addControlCondition" adds an entry to the control condition table.
$msi->addControlCondition ( -Dialog_ => 'LicenseAgreementDlg', -Control_ => 'Install', -Action => Disable, -Condition => 'IAgree <> "Yes"' );
Id of the dialog containing the control.
Id of the control affected by the entry.
Action to be taken if the condition is met.
Condition to be met for the action to be performed.
"addCreateFolder" adds an entry to the create folder table for the given folder. Component and directory table entries will be generated as required.
my $entry = $msi->addCreateFolder (-folderPath => $dirPath);
Path name of the folder to create on the target system.
-features provides an array reference for the list of feature ids for features that install the component that creates the folder.
Add an entry to the custom action table.
$msi->addCustomAction ( -Action => 'InstallDriver', -Type => 3074, -Source => 'DriverInstaller', -Target => "[CommonFilesFolder]\\$Manufacturer\\driver.inf", );
This provides fairly raw access to the CustomAction table and is only part of the work required to set up a custom action. See the CustomAction Table section in the documentation referenced in the See Also section for further information.
Id for the custom action.
A number comprised of various bit flags ored together.
A property name or external key into another table. This depends on the Type.
Additional information depending on the Type.
Add an inline JScript entry to the custom action table.
$msi->addCustomActionJScriptFragment ( -Action => 'GetName', -script => '["TheName"] = ["Path"].match (/".*\\(.*)/)[1]' );
This adds a JScript custom action row.
The JScript to execute.
["..."] is expanded to Session.Property ("...")
The expanded string must be 255 characters or fewer. It may be multiple statements and may contain multiple lines. Line breaks will be removed however.
Add JScript entry to the custom action table.
$msi->addCustomActionJScriptFile ( -Action => 'GetRegString', -call => '["AppRelVers"] = CmpVersion ("foo.exe", "1.0.3");' -file => 'vercheck.js', );
A fragment (255 characters or fewer) of JScript to be executed after the script has been loaded.
Watch out for \ characters in file paths. You will need \\\\ to get a single \ in a quoted string by the time Perl has changed \\\\ to \\ then JScript changes \\ to \.
-item -file: required
Name of the file containing the script to be processed.
Add an inline VBScript entry to the custom action table.
$msi->addCustomActionVBScriptFragment ( -Action => 'GetName', -script => '["TheName"] = ["Path"].match (/".*\\(.*)/)[1]' );
This adds a VBScript custom action row.
The VBScript to execute.
Add VBScript entry to the custom action table.
$msi->addCustomActionVBScriptFile ( -Action => 'GetRegString', -call => '["AppRelVers"] = CmpVersion ("foo.exe", "1.0.3");' -file => 'vercheck.vbs', );
A fragment (255 characters or fewer) of VBScript to be executed after the script has been loaded.
Watch out for \ characters in file paths. You will need \\\\ to get a single \ in a quoted string by the time Perl has changed \\\\ to \\ then VBScript changes \\ to \.
"addDirectory" adds a directory with a specified parent directory to the directory table.
my $entry = $msi->addDirectory (-Directory => $dir, -DefaultDir => $def, -Diretory_Parent => $parent);
Identifier for the directory entry to create. This identifier may be the name of a property set to the full path of the target directory.
This must be a Directory table -Directory column entry or undef. If -Diretory_Parent is undef or has the same value as -Directory the added entry is for a root directory and the root directory name is specified by -DefaultDir. There must only be one root directory in the Directory table.
Except in the case of a root directory entry, the value given for -Diretory_Parent must already exist as a -Directory entry in the Directory table.
-DefaultDir provides directory names for the source and target directories for this table entry. -target and -source may be used instead of -DefaultDir.
Different target and source directory names may be provided separated by a colon:
[targetname]:[sourcename]
Directory names may be given as [shortName]|[longName] pairs. [longName] may not include any of: \ ? | > < : / * "
[shortName] additionally may not include spaces or any of: + , ; = [ ]
A . may be used in place of [targetname] to indicate that the parent directory should be used rather than specifying a subdirectory.
If none of -DefaultDir, -target and -source are provided, -DefaultDir is set to '.' (use parent directory).
The [targetname] part of -DefaultDir.
"addDirPath" is not fully implemented should not be used. Use multiple calls to "addDirectory" instead.
"addDrLocator" adds a DrLocator table row. It is used with addAppSearch and addSignature to provide the information needed by the AppSearch action.
Adds a device driver package to the installer.
$msi->addMsiDriverPackages (-Component => 'InstallDriver', -Flags => (2 | 4));
See the MsiDriverPackages Custom Table Schema topic in the Windows Driver Kit: Device Installation documentation for the use of this parameter. the default value is 0.
Determines driver installation order. Packages are installed in increasing order of sequence number. Packages with the same sequence value are installed in arbitrary order.
Add an installation feature. Parent features must be added before child features are added. Multiple root features are allowed and provide different installation configurations.
my $root = $msi->addFeature (-name => 'Complete', -Title => 'Full install');
The following parameters are recognized by "addFeature"
-Attributes is set to msidbFeatureAttributesFavorLocal by default. For a discussion of the -Attributes parameter see the Feature Table documentation (see See Also below).
-Attributes
A textual description of the feature shown in the text control of the selection dialog.
Directory associated with the feature that may be configured by the user at install time. The directory must already have been added with "addDirectory", "addDirPath" or "createDirectory".
Determines the display state and order of this feature in the feature list.
If -Display is not provided it will be set so that the new feature is shown after any previous features and is shown collapsed.
-Display
If -Display is set to 0 it is not shown.
If -Display is odd is is shown expanded. If -Display is even it is shown collapsed.
Display values must be unique.
Identifier for the parent feature. If this parameter is missing a root feature is generated.
Initial installation level for the feature. See the Feature Table documentation for a discussion of installation level (see See Also below). For a single feature install a value of 3 (the default) is often used. 0 may be used for a feature that is not to be installed at all.
The name of the feature to add.
Add FeatureComponent rows for a given Component and each of a list of Features.
$msi->addFeatureComponents (-Component_ => 'Wibble', -features => ['Complete']);
addFeatureComponents returns the number of rows actually added to the FeatureComponents table. Duplicate rows will not be added, but are not an error.
The Component table key id.
A reference to an array of Feature table key ids.
"addFile" is used to add a file to be installed. Adding a file associated with a feature (or features) updates the File and DiskId tables and may update the Component, FeatureComponent and DuplicateFile tables.
my $file = $msi->addFile (-source => $filepath, -featureId => 'Complete');
Default values are determined for -Sequence and -Version from the source file which must be available when "addFile" is called.
-Sequence
-Version
Provide the name of a cab file the current file should be added to. By default the file is added to an internally generated cab file.
If the file is to not to be compressed and stored internally in a cab file -cabFile should be set to undef.
-cabFile
undef
See also "createCabs".
If provided the -condition is applied to the component the file is installed by. A new component will be created if the condition does not match the condition on an existing component that would otherwise have been used.
Id of the Feature that the file is to be installed for.
Id to be used as the File column (and thus key) entry for the file being added. By default -fileName is used for this value.
-fileId must be unique. -skipDupAdd will be ignored if -fileId is provided.
Name of the file to be installed. Note that a long file name should be given: "addFile" generates the required short file name.
If present this parameter forces a new component to be generated. If the value is scalar it is used as a suggested component name otherwise an array ref containing a list of parameters to be passed to addComponent is expected.
If a parameter list is provided it may be empty and required parameters for addComponent will be generated.
File is a key file for a component. Required to be set true if there is to be a shortcut to the file. If the file is a PE format file (.exe, .dll, ...) -isKey is implied.
-isKey
Specify the language ID or IDs for the file. If more than one ID is appropriate use a comma separated list.
If this parameter is omitted the value '1033' (US English) is used. To specify that no ID should be used (for font files for example) use an empty string.
A suggested component name. If the name has been used and the file being inserted is not suitable for the existing component a new component name based on the requested name will be used.
Determines the order in which files are installed. By default files are installed in the order that they are added. Setting -Sequence for a file sets the install position for that file and any files added subsequently.
If setting the sequence number for a file causes a collision with any file already added the previously added files are moved later in the install sequence (their sequence number is increased). Note that any subsequently added files may also cause previously added files to be installed later. In other words, setting -Sequence for a file allows a group of files to be inserted at a particular place in the install order.
Use:
-Sequence => undef
to reset to adding files at the end of the install order.
Path to the directory containing the file to be installed.
Skip adding the file if an entry already exists for it. This option is ignored if -fileId is provided.
Path to the directory the file is to be installed to on the target system.
If -targetDir is not provided the target directory will be set to be in the same relative location as the source directory is to the source root directory. -sourceDir must be in the directory tree below the source root directory if -targetDir is not provided.
-targetDir
-sourceDir
-Version should only be set to specify a companion file (see "Companion Files" in the SDK documentation). For a versioned file the version number is obtained from the file's version resource.
Add an icon file to the installation.
my $iconId = $msi->addIconFile ('path/to/unique_file_name.ico');
Note that an internal ID is generated from the file name (excluding the path to the file). The file name must thus only contain alphanumeric characters, periods and the underscore character.
Two icon files that differ only in their path, but have the same name will cause grief (only one of the files will be used). This condition is not checked for!
The generated internal Id is returned and may be used for the -Icon_ parameter required in other tables.
-Icon_
The file must exist at the time that addIconFile is called.
addIconFile may be called multiple times with the same file
$msi->addInstallExecuteSequence ( -Action => 'InstallDriver', -Condition => 'NOT MYDRIVERINSTALLED AND NOT Installed', -Sequence => 3959, );
Id for the action. This must be either a built-in action or a custom action.
A matching entry must exist in the CustomAction table if this is a custom action.
A conditional expression that must evaluate true at run time for the step to be executed.
Sequence position for execution of this action.
A public property or array ref containing a list of public properties used in the -Condition expression that need to be passed securely into the execute context.
The property names will be added to the SecureCustomProperties property during "writeTables".
$msi->addInstallUISequence ( -Action => 'SetDefTargetDir', -Condition => '', -Sequence => 1100, );
$msi->addLaunchCondition ( -Condition => 'NOT Version9X', -Description => 'Windows versions prior to XP are not supported.', );
A conditional expression that must evaluate true at run time for the install to proceed.
Error text shown if the launch condition evaluates false.
Add a cabinet file to the Media table.
$msi->addMedia (-Cabinet => '#cab1', -DiskId => 1, -LastSequence => 20);
If all the files required by the install are to be part of the .msi file then addMedia can be ignored - "createCabs" does all the work required.
Name of the cabinet file.
A # as the first character in the name indicates that the cabinet file will be stored in a stream in the .msi file. In this case the name is case sensitive.
If the first character in the name is not a # then the name must be given as a short file name (8.3 format) and the cabinet is stored in a separate file located at the root of the source tree specified by the Directory Table.
A number (1 or greater) that determines the sort order of the media table.
Sequence number of the last file in this media.
Name (on the label for physical media) used to identify the physical media associated with this media entry.
Source to be used for patching.
Volume label to be used to identify physical media.
Add a property value to the Property table. A new property id is generated based on the supplied id if a property of the same name exists already.
$msi->addProperty (-Property => 'Manufacturer', -Value => 'Wibble Corp.');
The actual property id used is returned.
Suggested property name
Property value
Add a registry entry.
$msi->addRegistry ( -root => HighLevel::msidbRegistryRootClassesRoot, -Component_ => 'Application', -Key => '.app', -Name => undef, -Value => 'MyApp' );
Id of the component controlling installation of the registry value.
This parameter is required unless -genRegKey is used.
Generates the registry table key and returns it, but doesn't generate the table entry.
This option is required to solve a chicken and egg problem with components that use a Registry table key for their KeyPath.
Key path which may include properties but must not start or end with a backslash (\).
Registry value to add.
Add a RegLocator table entry.
$msi->addRegLocator ( -Signature_ => 'MyDriver', -Root => HighLevel::msidbRegistryRootLocalMachine, -Key => 'SYSTEM\CurrentControlSet\Control\Class\{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}', -Name => 'Class', -Type => HighLevel::msidbLocatorTypeRawValue, );
Set to search the 64-bit portion of the registry. The 32-bit portion of the registry will not be searched if -64Bit is set.
A key into the Directory table to be set from the registry.
One of -directory, -file and -property is required.
A key into the File table to be set from the registry.
Key path.
Registry value name. If omitted the default value is used.
A key into the AppSearch table for the row that contains the property to be set to the registry value.
One of -directory, file and -property is required.
One of:
Add a SelfReg table entry.
$msi->addSelfReg ( -File_ => $fileTableKey, -Cost => HighLevel::msidbRegistryRootLocalMachine );
The cost in bytes due to self registering this .dll.
The key in the File table for the .dll to self register.
The following parameters are recognized by "addShortcut":
The command line arguments for the shortcut.
-target
-Target
The id for the Component table entry which determines whether the the shortcut will be deleted or created. The shortcut is created if the component has been installed and is deleted otherwise.
If -Component_ is not provided the component associated with -target or -Target will be used.
-Component_
The localizable description of the shortcut.
-location
The id for the Directory table entry which specifies where the shortcut file will be created. The Directory entry need not exist until "writeTables" is called and is not checked.
One only of -location and -Directory_ must be provided.
-Directory_
The feature the shortcut is installed by.
The hotkey for the shortcut. The low-order byte contains the virtual-key code for the key, and the high-order byte contains modifier flags.
The folder pointed to by the shortcut. Note that this folder must already have been provided using "addDirectory", "addDirPath" or "createDirectory".
One only of -folderTarget, -target and -Target must be provided.
-folderTarget
The directory where the shortcut file will be created. Note that the directory must already have been added with "addDirectory", "addDirPath" or "createDirectory".
The directory provided will be searched for in the Directory table to find the directory id to be used for -Directory_.
Name to be shown for the shortcut. Note that the name need not be unique.
Suggested internal id to be used for the shortcut. Note that if there is another shortcut with the same id already a new id will be generated by appending a number to the given id. The id actually used is returned.
If -Shortcut is omitted a suitable id will be generated from the -Name value.
-Shortcut
-Name
The mode used to show the window used by the shortcut when run. May be one of the following constants:
If -ShowCmd is omitted default Windows behavior is used (SW_SHOWNORMAL).
-ShowCmd
The Feature id or a Property id that specifies the target of the shortcut.
If a Feature id is provided the target is the key file of the Component_ table entry associated with the Feature.
If a Property id is provided the target is the file or directory specified as the value of the property.
The file pointed to by the shortcut. Note that this file must already have been provided using "addFile" or "addFiles".
-wkdir
The Directory id that specifies the working directory for the shortcut.
One only of -wkdir and -WkDir may be provided.
-WkDir
The working directory for the shortcut.
A directory table will be created if required.
Add an entry to the Signature table used by the AppSearch action to match previously installed applications.
The following parameters are recognized by "addSignature":
The name of the file to search for.
Specify the language ID or IDs for the file. If more than one ID is specified use a comma separated list. Multiple entries require a file supporting all specified languages for a match.
The maximum creation date of the file. If this parameter is specified, then the file must have a creation date that is at most equal to MaxDate. This must be a non-negative number. The format of this field is two packed 16-bit values of type WORD. The high order WORD value specifies the date in MS-DOS date format. The low order WORD value specifies the time in MS-DOS time format. A value of 0 for the time value represents midnight.
The formula for calculating the value is:
(($Year - 1980) * 512 + $Month * 32 + $Day) * 65536 + $Hours * 2048 + $Minutes * 32 + $Seconds / 2
The minimum modification date and time of the file. If this field is specified, then the file under inspection must have a modification date and time that is at least equal to MinDate.
See -MaxSize above.
The minimum size of the file. If this parameter is specified, then the file under inspection must have a size that is at least equal to MinSize. This must be a non-negative number.
The maximum version of the file. If this parameter is specified, then the file must have a version that is at most equal to MaxVersion.
The minimum version of the file, with a language comparison. If this field is specified, then the file must have a version that is at least equal to MinVersion. If the file has an equal version to the MinVersion field value but the language specified in the Languages column differs, the file does not satisfy the signature filter criteria.
Note The language specified in the Languages parameter is used in the comparison and there is no way to ignore language. If you want a file to meet the MinVersion field requirement regardless of language, you must enter a value in the MinVersion field that is one less than the actual value. For example, if the minimum version for the filter is 2.0.2600.1183, use 2.0.2600.1182 to find the file without matching the language information.
This required parameter must be a unique id that is used as an external key by various tables involved in searching for applications and related files, directories and registry entries.
Add a binary file to the installation as a storage.
Id to be used as the key entry in the storages table. This entry must be unique.
Add an upgrade table entry.
$msi->addUpgrade ( -UpgradeCode => $UpgradeGUID, -VersionMin => 1.0, -VersionMax => 2.0 );
UpgradeCode GUID associated with the product detected by the Upgrade table entry being added.
If this parameter is omitted the UpgradeCode Property table entry will be used. Calling setProduct sets the UpgradeCode Property table entry.
setProduct
Version numbers (if provided) must be in the form x[.y[.z]]. y and z will be set to 0 if they are omitted. x, y, and z must be numeric. A fourth value is not allowed.
x[.y[.z]]
Minimum product version number that this table entry will detect.
If both -VersionMin and -VersionMax are omitted -VersionMin will be set to 0 to find all product versions.
-VersionMin
-VersionMax
Maximum product version number that this table entry will detect.
If both -VersionMin and -VersionMax are omitted -VersionMax will be set to null to find all product versions.
Must be one of Microsoft's language codes. For example US English is 0x0409.
Language matching will be ignored if -Language is omitted.
-Language
The following attributes may be ored together:
msidbUpgradeAttributesMigrateFeatures Copy selected features msidbUpgradeAttributesOnlyDetect Detect only - don't uninstall msidbUpgradeAttributesIgnoreRemoveFailure Ignore uninstall failure msidbUpgradeAttributesVersionMinInclusive Include min version msidbUpgradeAttributesVersionMaxInclusive Include max version msidbUpgradeAttributesLanguagesExclusive Include all langs except listed
See the MSDN documentation for further information about these attributes.
List of features to be removed during the install. A single feature name or an array reference containing feature names is expected.
Public property name (must be upper case) of the property that will be set to the list of product codes for installed products matching this upgrade entry.
This property name will be added to the SecureCustomProperties property during "writeTables".
Creates the cab files as required from the files that have been added with "addFile" or "addFiles".
$msi->createCabs ();
Note that "createCabs" must be called after all files have been added and before "writeTables" is called.
Note too that makecab.exe must be available on the system being used. With versions of Windows from Windows 2000 on makecab.exe seems to be provided with the system so this should not generally be an issue. If "createCabs" generates a 'makecabs.exe not found' error copy makecabs.exe into the working directory or add the path to makecabs.exe to the PATH environment variable.
"createCabs" updates the Media table as appropriate.
Media
Note that "createCabs" generates a cab.dff file that may be used as a manifest of the files added to the install (ignore lines starting with .).
cab.dff
Creates a new database table.
my $table = $msi->createTable (-table => 'Feature'); my $table = $msi->createTable ( -table => 'Properties', -columnSpec => [ Property => [qw(Key Identifier(72) Required)], Value => [qw(Text(0) Required)], ] );
createTable knows the column specification for the following commonly used tables: AppSearch, Binary, Component, CustomAction, Directory , Extension, Feature, FeatureComponents, File, Icon, LaunchCondition, Media, MsiDriverPackages, Property, ProgId, RegLocator, Shortcut, Verb.
createTable
AppSearch, Binary, Component, CustomAction, Directory , Extension, Feature, FeatureComponents, File, Icon, LaunchCondition, Media, MsiDriverPackages, Property, ProgId, RegLocator, Shortcut, Verb
Any other tables must be created by providing a suitable -columnSpec parameter. If there are tables that you use regularly that are not included in the list above contact the module maintainer with the column specification and suggest that it be added.
Specification for the table's columns. This is required for tables that Win32::MSI::HighLevel doesn't handle by default.
Note that custom tables may be added to the installer file.
The column specification comprises an array of column name => type pairs. Most of the types mentioned in the MSDN documentation are recognized, including:
Where the default type includes a size (number in parenthesis) a different size may be supplied by including it in parenthesis following the type:
Text(0)
Name of the table to create.
Removes a database table.
my $table = $msi->dropTable ('Feature');
Expand a path including system folder properties to a path with the system folders resolved by examining Directory table entries.
my $path = expandPath ($filePath);
"expandPath" returns a long path.
Saves a database table in a .csv file format.
my $table = $msi->exportTable ('Directory', '.\Tables');
Important! You must "writeTables" before calling "exportTable" to ensure that the database version of the table matches the internal cached version.
The sample code would export the Directory table as the file 'Directory.idt' to the sub-directory Tables in the current working directory.
If the table includes streams a sub-directory to the directory containing the exported file will be created with the same base name as the table. A file for each stream will then be created in the sub-directory. The created files will have the extension '.idb'.
Note that the table name _SummaryInformation may be used to write out the Summary Information Stream.
Also note that the exported file format is ideal for management using a revision control system.
See also "importTable".
Return the component Id for the given file Id.
my %entry = getComponentIdFromFileId ('Wibble.txt');
This call does not create a component or file entry. It returns null if there is not a matching file id.
Return the component Id for the component that has a null KeyPath and a Directory_ value matching the directory id passed in.
my %entry = getComponentIdForDirId (-Directory => 'Wibble', -features => ['Complete']);
A component is created if there is not an appropriate existing component. FeatureComponent table entries will be generated if a Component table entry is generated.
Directory Id to find (or create) a matching component Id for.
The list of features that install the component associated with the directory.
Return the table key id generated for a given id. For example:
my $dirId = $msi->getId ('MyDir', 'Directory', 'my\\path');
will return the unique id generated for the MyDir directory entry in the Directory table with 'my\path' as the parent path.
Returns the parent Directory table id given an existing directory id.
my $dirId = $msi->getParentDirID ('WibbleApp');
If the dirId passed in does not exist an undef will be returned, otherwise a string (which may be empty for a root dir) will be returned.
Return a string containing product and major version information.
my $productString = $msi->getProduct ();
Return a GUID as a string containing product code for the installer.
my $productGUID = $msi->getProductCode ();
If a product code does not yet exist it will be generated as the MD5 sum of the ProductName, ProductLanguage, ProductVersion and Manufacturer property values.
Return the Property value for the given property name. Returns undef of the property entry doesn't exist.
my %entry = $msi->getProperty ($propName);
Return a reference to the table column data for a given table entry.
my $entry = $msi->getTableEntry ('File', {-File => 'wibble.exe'});
Returns undef if the table or key doesn't exist.
If fields within the $entry hash ref are edited "updateTableEntry" must be called.
A degree of caution is advised in using this member. Very little checking can be performed on the results of editing the hash returned. Generally errors will result in failures at "writeTables" time.
"getTargetDirID" returns a Directory table id given an install time target file path. Entries in the Directory table will be created as required to generate an appropriate id.
my $dirId = $msi->getTargetDirID ('[ProgramFilesFolder]\Wibbler\WibbleApp');
An existing Directory table entry may be used as the first element of a directory path. If an existing Directory table entry is used it must be the first element of the directory path. Relative paths are with respect to the target install directory (TARGETDIR).
Where existing Directory table entries match a given path prefix the existing entries are used to reduce proliferation of table entries.
"getTargetDirID" generally takes a single unnamed parameter which is the install time (target) path to match.
Note that the paths may use either \ or / delimiters. All path components are assumed to be long (not short "filename"). Short "filenames" will be generated as required.
An optional (second) boolean parameter may be provided to indicate that the Directory is public. That is, that at install time the user may change the install location for the directory. If a true value is provided as the second parameter the directory Id is forced to upper case to make the entry a public directory entry.
An optional third parameter may be provided to suggest an Id. If provided the boolean 'public' parameter must be provided also.
The following system folder properties may be used directly as shown in the sample code above:
Full path to the file directory containing application data for all users
Full path to the Common Files folder for the current user
Full path to the Start Menu folder
Returns a reference to the Directory table entry for given directory Id if it exists or undef otherwise.
my $dirEntry = $msi->haveDirId ('Wibble');
Imports an exported database table in a .csv file format.
my $table = $msi->importTable ('.\Tables', 'Directory'); $msi->writeTables (); $msi->populateTables ();
Important! You should "writeTables" and then "populateTables" following calling "importTable" to ensure the cached table information matches the database version.
The sample code would import the Directory table from the file 'Directory.idt' in the Tables sub-directory of current working directory.
importTable will create an absolute path from the folder path passed in as the second parameter.
importTable
undef will be returned on success and an error string will be returned on failure.
Note that the table name _SummaryInformation may be used to import the Summary Information Stream.
Install a Win32 service that runs its own process.
$msi->installService(-serviceName => 'MyService', -Component_ => $component);
At install time a previous instance of the service will be stopped and uninstalled. The new instance will then be installed and optionally started.
Name used to identify the service. This must uniquely identify the service on the target system or unhappy things will happen.
The component that the service file is installed by. This is used by the installer to ensure the service is installed at the correct time.
The name of the service to be installed. If a name is not provided -serviceName is used.
One of 'auto' or 'demand' with 'auto' used by default.
If the state is 'auto' the service will be started at install time and when the system boots.
If the type is supplied it must currently be 'interactive' to set SERVICE_INTERACTIVE_PROCESS.
SERVICE_WIN32_OWN_PROCESS is assumed.
A brief (fewer than 256 characters) description of the service. -name will be used by default.
Set various optional behavior.
Fix the separator bug which can generates bogus identifiers for Component names and in other situations. Note that this can lead to components with different names in installers where this setting has changed state and lead to bad behavior when updating installed components.
Read the current .msi file and build an internal representation of it.
An optional boolean parameter may be passed. If set true populateTables will warn about any table files it finds that it doesn't know how to generate an internal representation for. Such unknown tables can not be manipulated and will be written to the output unchanged.
populateTables
Add table entries to register a file extension and hook it up to an application. Note that Extension, ProgId and Verb tables may be affected by this call depending on the parameters supplied.
$msi->registerExtension ( -Extension => 'myext', -Component_ => $componentId, -ProgId => 'MyApp.Data.1', -Feature_ => $featureId, -Description => 'MyApp data file', -Verb => 'Open', -Argument => '%1', );
Command line argument to be used when launching the application. %1 may be used to pass the file on the command line.
Id of the component that controls installation of the extension.
File extension (excluding the .) that is to be registered.
If multiple extensions need to be mapped to the same ProgId an array reference may be used for the value of this parameter:
$msi->registerExtension (..., -Extension => [qw(myext1 myext2)], ...);
Text that is shown in explorer for the file type.
Feature that supplies the application associated with the extension.
Entry in the Icon table that supplies an icon used for files of this type.
Path to the file containing the icon referred to by -IconIndex.
Note that the file name must be a unique icon file name independently of the path and must only contain alphanumeric characters, periods and underscores. This is because registerExtension forms an ID that is used internally to identify the specific icon file. Multiple extensions may use the same icon file so it is important that registerExtension can generate a one to one mapping between the file name and the internally generated ID.
Index to the icon resource in the file provided by the -Icon_ table entry (which may be provided using -iconFile).
MIME table Content Type entry specifying the MIME type of the contents of files of this extension.
A -MIMECLSID is required if this parameter is supplied.
-MIMECLSID
CLSID for the COM server that is associated with the MIME type for files of this extension type.
This parameter is required only if a -MIME_ parameter is provided.
-MIME_
ProgId table entry for the application associated with the file extension.
Note that several extensions may reference the same ProgId. However, if more than one extension references the same ProgId the -Description and -Icon* parameters for the first registered (or pre-existing) entry is used.
Explorer's right click menu entry text for an action associated with files of this type.
If a -Verb parameter is supplied a -ProgId_ is required also.
Set various product related information.
$msi->setProduct ( -Language => 1033, -Name => 'Wibble', -Version => '1.0.0', -Manufacturer => 'Wibble Mfg. Co.' );
For a new installer this should be called before any addComponent calls are made as information from the product details is used to generate information required to generate component table entries.
Property table entries are generated or updated by this call. In addition to the properties discussed in conjunction with the parameters described below, a ProductCode value is generated and added to the Property table.
The product code value is returned.
Product name.
Manufacturer's name.
Language code (LangId).
Product version
A GUID that will be used as the UpgradeCode for Upgrade table entries and is used as part of the string used to generate Component GUIDs.
If not provided setProduct will generate an UpgradeCode GUID using the -Name and -Manufacturer values. By default this will allow different language version of a product to be upgraded interchangeably.
Do not include version information in -Name if you rely on the default UpgradeCode GUID generation unless the version information is invariant across all product versions you expect to be able to upgrade. For most upgrade purposes this means that including a major version number in the name is OK, but including a minor version number is not.
Set a property value in the Property table. The property is added if it didn't exist already.
$msi->setProperty (-Property => 'Manufacturer', -Value => 'Wibble Corp.');
The previous value is returned or undef is returned if a new property is added.
Property name
Sets specified fields in an existing table entry.
$msi->setTableEntryField ( 'Control', {-Dialog_ => 'Start_Installation_Dialog', -Control => InstallNow}, {-Text => 'Install'} );
The first hash ref parameter must include entries for all the table's key fields.
Note that this method provides fairly raw access to table entries and does not perform very much validation. In particular fields that are linked to other tables should not be altered using "setTableEntryField"!
Returns the count of the rows in a given table.
my $count = $msi->tableRows ('File');
A single parameter giving the name of the table is required. undef is returned if the table does not exist.
Update the table column data for a table entry obtained using getTableEntry.
my $entry = $msi->getTableEntry ('File', {-File => 'wibble.exe'}); $entry->{-File} = 'Wibble.exe'; $msi->updateTableEntry ($entry);
Use with caution. In particular, do not create new keys in the hash.
Creates a Win32::MSI::HighLevel::View into the database.
my $view = $msi->view (-table => 'Feature');
Generally other ways of manipulating the database are more useful than through a view. However a Win32::MSI::HighLevel::View can be created to search tables for specific information using the -columns, -where, -order and -tables parameters to return selected records.
-columns
-where
-order
-tables
Write changes that have been made to the tables using the add* members. Until writeTables is called the changes that have been made are cached in memory. writeTables writes these changes through to the .msi database in preparation for a "commit".
"writeTables" also updates the SecureCustomProperties property with Upgrade table "-ActionProperty_" properties.
This module depends on Win32::API, which is used to import the functions out of the msi.dll. Microsoft's Windows Installer technology must be installed on your system for this module to work.
Win32::API
Please report any bugs or feature requests to bug-win32-msi-highlevel at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Win32-MSI-HighLevel. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-win32-msi-highlevel at rt.cpan.org
This module is supported by the author through CPAN. The following links may be of assistance:
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Win32-MSI-HighLevel
CPAN Ratings
http://cpanratings.perl.org/d/Win32-MSI-HighLevel
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Win32-MSI-HighLevel
Search CPAN
http://search.cpan.org/dist/Win32-MSI-HighLevel
This module was inspired by, and is derived in part from Philipp Marek's http://search.cpan.org/dist/Win32-MSI-DB.
Peter Jaquiery CPAN ID: GRANDPA grandpa@cpan.org
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.
Microsoft MSDN Installer Database documentation: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/installer_database.asp
To install Win32::MSI::HighLevel, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Win32::MSI::HighLevel
CPAN shell
perl -MCPAN -e shell install Win32::MSI::HighLevel
For more information on module installation, please visit the detailed CPAN module installation guide.