Product Documentation

PDK 7.2 Documentation

MSI::Installer - Create and Manipulate Microsoft Installer Databases

NAME

MSI::Installer - Create and Manipulate Microsoft Installer Databases

SYNOPSIS

    use MSI::Installer;

    my $installer = MSI::Installer->new('template.msi', 'foo.msi');

    $installer->SetGUIDFile('GUIDS.txt');

    my $some_component_guid = $installer->GetGUID('some/msi/component');

    $installer->SetSummaryInformation(
            ProductName => 'MyProduct',
            CompanyName => 'MyCompany',
            Keywords    => 'Installer,Perl,Python,IDE',
            Description => 'IDE for Perl and Python Developers',
            Platform    => 'intel;1033',
            PackageCode => $installer->GetGUID(),
            );

    $installer->SetDefaultDialogTemplate($dialog_template);
    
    $installer->AddData(%data);

    $installer->AddCabinet($image, $start_seq, $cab_name);

    $installer->UseDialogSet($name);

    $installer->AddBinaryData($table, $id, $file_name);

    $installer->CreateFeature($FeatureName, $FeatureParent, $Directory, $Title, $Description, $isExpanded, $RunFromSource);

    $installer->SetShortcut($ShortcutPathName,$TargetFile,$argument_string,$working_directory);

    $installer->AddLicenseText($file_name);

    $installer->AddImage($image);
    
    $installer->SetARPInfo($support_url,$update_url,$about_url,$primary_folder);

    $installer->SetSharedFile($file_name);

    $installer->SetSelfRegFile($file_path,$cost);

    $installer->RunLocalFile($file_name,$parameters);

    $installer->AddBannerBitmap($file_name);

    $installer->AddIconFile($file_name);

    $installer->SetReadmeFile($file_name);

    $installer->SetTargetRoot($root_name);

    $installer->SetEnvironmentPath($directory);
    
    $installer->SetComponentSearch($property,$default_value,$component_key,<$type>);

    $installer->SetRegistrySearch($property,$default_value,$reg_key,<$value_name>);

    $installer->SetFileSearch($property,$file_path,$file_name,$sign);

    $installer->SetScript($script_text, $run_on_install,$script_type);

    $installer->SetJScript($script_text,$run_on_install);

    $installer->SetVBcript($script_text,$run_on_install);

    $installer->SetPerMachineInstallationType();

    $installer->SetRebootForWin9x();

    $installer->CreateOptionsDialog($dialog_title,$dialog_description,$dialog_text,$num_columns 
                                    [             
                                     {                 
                                      Property => <property_1>,                  
                                      CheckedCondition => <check_condition>,                  
                                      DisableCondition => <dis_condition>,                  
                                      Caption => <caption>,            
                                     },            
                                     {                 
                                      Property => <property_2>,                 
                                      CheckedCondition => <check_condition>,                 
                                      DisableCondition => <dis_condition>,                 
                                      Caption => <caption>,              
                                     },              ...        ]);

   $installer->FailIfProductsFound(@product_codes);

   $installer->WarnIfProductsFound(@product_codes);

Create a new MSI::Installer object based on a template. $src is the filename of an extisting MSI database to be used as the template. $target is the filename of the MSI database to be created. Returns an MSI::Installer object.

$installer->`SetGUIDFile($file_name)`

Set the name of the file containing the GUIDS database. $file_name is the filename of the GUIDS database.

$installer->`GetGUID($component_path)`

Gets the GUID for the specified component. $component_path is the identifier of an existing component in the GUIDS database or a component to be added to the GUIDS database. Returns the GUID of the specified component.

$installer->`SetSummaryInformation(%info)`

Sets the summary information for the the MSI database file. %info is a hash containing the names and values of the summary information properties to be set. The following summary information properties may be set and are keys in the %info hash:

ProductName: The name of the application being packaged.
CompanyName: The name of the company that publishes the application being packaged.
Keywords: A comma-separated list of keywords describing the application being packaged.
Description: The description of the application being packaged.
Platform: Describes the platforms supported by the application being packaged.
PackageCode: A GUID that serves as the package code for the application being packaged.

$installer->`UseDialogSet($name)`

Should be called once in the setup script. $name specifies a package in the MSI::Dialog namespace that contains a complete user interface. If $name is not specified, the installer uses the default dialog set.

$installer->`SetDefaultDialogTemplate($dialog_template)`

Sets the default dialog template applied to all dialogs subsequently added to the MSI database. dialog_template is a dialog template previously created by a call to MSI::Dialog-CreateTemplate()>.

$installer->`AddData(%data)`

Add data to the MSI database. The following is an example that illustrates the format of the %data hash:

        Table1 =>
        [
            {
                Field1 => 'Value1',
                Field2 => 'Value2'
            },
            {
                Field1 => 'Value1',
                Field2 => 'Value2'
            }
        ],

        Table2 =>
        [
            {
                Field1 => 'Value1',
                Field2 => 'Value2',
                Field3 => 'Value3'
            }
        ]

$installer->AddCabinet($image, $start_seq, $cab_name)

Builds a cabinet file based on the information contained in $image and adds the cabinet file to the MSI database as a binary data stream. c<$image> is an c<MSI::Image> object previously created by a call to c<MSI::Image->new()>. start_seq is the index in the cabinet file of the first file to be added from $image. MSI::File objects contained in $image are updated with their indicies within the cabinet file. $cab_name is the filename of the cabinet file to be created. Returns the index of the last file added to the cabinet file as a result of this call.

$installer->AddBinaryData($table, $id, $file_name)

Adds binary data to the MSI database. $table is the name of the MSI database table to which the data is added. $id is the identifier for the binary data within the MSI database. $file_name is the name of the file containing the binary data to be added.

$installer->CreateFeature($FeatureName, $FeatureParent, $Directory, $Title, $Description, $isExpanded, $RunFromSource)

$installer->SetShortcut($ShortcutPathName,$TargetFile, $argument_string,$working_directory)

Creates a shortcut on the desktop or in the Program Menu folder. <shortcut_path_name> must be like 'ProgramMenuFolder/...' or 'DesktopFolder/...' <target_file> - path to the file relative to image folder

$installer->`AddImage($image)`

Add files and components to the MSI database from a directory specified by $image.

$installer->`AddLicenseText($file_name)`

$installer-UseDialogSet()> should be called prior to calling this method. Adds a text control containing license information specified in $file_name to a license agreement dialog, defined in UseDialogSet(). $file_name must be a rich text format (RTF) file.

$installer->`SetARPInfo($support_url,$update_url,$about_url,$primary_folder)`

Sets Add/Remove Program info, including a product support URL, a product update URL, an "about product" URL, and the product's install location.

$installer->`SetSharedFile($file_name)`

Sets $file_name as a shared file.

$installer->`SetTargetRoot($root_name)`

Sets the initial root directory for the product to $root_name.

$installer->`RunLocalFile($file_name,$parameters)`

Executes file ($file_name) with associated parameters ($parameters) following product installation and uninstallation.

$installer->`AddBannerBitmap($file_name)`

$installer->`AddIconFile($file_name)`

$installer->`SetSelfRegFile($file_path,$cost)`

Sets file in $file_path as a self-registered DLL.

$installer->`SetEnvironmentPath($directory)`

Appends $directory to the PATH environment variable upon installation.

$installer->`SetReadmeFile($readme_file)`

Associates a check box to the display of a README file ($readme_file) at the end of product installation (i.e. if the check box is selected, the README file is displayed; otherwise, it is not).

$installer->SetRegistrySearch($property,$default_value,$reg_key,<$value_name>)

Sets the property specified by $property to $default_value provided that $reg_key, with optional value ($value_name) exists in the registry.

$installer->SetComponentSearch($property,$default_value,$component_key,<$type>)

Sets the property specified by $property to the directory holding the component specified by $component_key. Otherwise, the property is set to $default_value. The type parameter is optional and specifies whether the component type is a directory or a file (the default is file).

$installer->SetFileSearch($property,$file_path,$file_name,<\%signature>)

Sets <property> to the full path name of the file, if the file is found. $property is the new property name (must be uppercase). $file_path is the absolute path or property that contains the full path to the file folder. The structure of the \%signature is:

    {
        MinVersion => <min_ver>,       
        MaxVersion => <max_ver>,       
        MinSize => <min_zs>,           
        MaxSize => <max_sz>,           
        MinDate => <min_dt>,           
        MaxDate => <max_dt>            
    }
                
All elements in the C<\%signature> are optional.

$installer->`SetJScript($script_text,$run_on_install)`

Sets JScript to run on install after files are copied, or on uninstall before files are deleted.

$installer->`SetVBcript($script_text,$run_on_install)`

Sets VBScript to run on install after files are copied, or on uninstall before files are deleted.

$installer->SetScript($script_text, $run_on_install,$script_type)

Sets script (of type $script_type) to run on install after files are copied, or on uninstall before files are deleted.

$installer->`SetPerMachineInstallationType()`

Sets installation to per-machine.

$installer->`SetRebootForWin9x()`

Shows reboot prompt at the end of installation on Windows 9x systems.

$installer->`CreateOptionsDialog($dialog_title,$dialog_description,$dialog_text,$num_columns)`

$installer->`FailIfProductsFound(@product_codes)`

Checks for existing products based on their product code, and terminates the install if one is found.

$installer->`WarnIfProductsFound(@product_codes)`

Checks for existing products based on their product code, and creates a warning dialog if one is found.

$installer->`HelpManager(\%data)`

Takes care of registering/unregistering Help files, and adding/removing your help namespace to/from other existing namespaces if you specify ParentNameSpace. The following is an example illustrating the format of the \%data:

    my $data = {
        <ParentNameSpace => "NOTMY.ProductHelp",>
        NameSpace => "MY.ProductHelp",
        NameSpaceDesc => "My Product Help",
        HxC_File => "path to the file relative to image folder\\MyHelp.HxC",
        HxA_File => "path to the file relative to image folder\\MyHelp.HxA",
        Filters =>[
            {
                FilterName=>"(no filter)",
                FilterString=>""
            },
            {
                FilterName=>"My first filter",
                FilterString=>"\"DevLang\" = \"MyLang\""
            }, ... ,
        ],
        Files=>[
            {
                HelpFileId=>"ProductFunctions",
                HxS_File=>"path to the file relative to image folder\\MyHelp.HxS",
                HxI_File=>"path to the file relative to image folder\\MyHelp.HxS",
                HxQ_File=>"",
                HxR_File=>"",
                LangId=>1033
            }, ... ,
        ] 
    };

$installer->`FilePath($file_name)`

Returns a formatted string that is converted to full file path on the user machine.

$installer->`GetParentComponent($file_name)`

Returns the parent component of the file.

Methods for adding data to individual tables

There is a method for adding data to every table in an MSI database. The method's name takes the form of $installer->Add<table_name>(). The method takes named parameters that correspond to the table's field names and the values to be inserted into those fields. For example, you can add a property the Property table like this:

    $installer->AddProperty(
            Property    => 'ProductName',
            Value       => 'Komodo'
            );

For more information about MSI database tables refer to:

http://msdn.microsoft.com/library/psdk/msi/tref_29ir.htm