< Previous PageNext Page > Hide TOC

Checking the Installation Volume With VolumeCheck

You can prevent users from installing your software on volumes that do not meet certain criteria. To do so, you supply an executable file, named VolumeCheck, in your installation package that determines whether a volume should be allowed as a possible installation destination.

For another possible approach to specifying volume requirements, see “Specifying Installation Requirements.”

Contents:

VolumeCheck Overview
File Placement for Volume Checking
Arguments and Environment Variables
Return Value for the VolumeCheck Executable
VolumeCheck Message Strings
VolumeCheck Example

VolumeCheck Overview

The Installer application looks for the VolumeCheck executable file in the Resources directory of the package. If found, the file is executed before Installer asks the user to choose an installation volume (and possibly a specific directory). This takes place after the user has already performed any required preliminary steps, such as authenticating or accepting a license agreement. See “The Installation Process” for a look at the larger picture of what happens during an installation.

Installer runs VolumeCheck once for each currently mounted volume. VolumeCheck can use any criteria to accept or reject a volume. VolumeCheck returns a value that tells Installer whether or not to allow the volume as an installation destination. For details on this value, see “Return Value for the VolumeCheck Executable.” If a volume is disallowed, Installer displays its icon with a badge that indicates the volume can’t be used for this installation. If the user attempts to select the volume anyway, you can supply a message that explains why that volume is not suitable.

When VolumeCheck returns a value that indicates that a volume should be disallowed, the return value also indicates what message to display if the user clicks the icon for that volume. Installer obtains the message from a VolumeCheck.strings file you supply in the installation package. If you supply VolumeCheck.strings files for multiple locales, Installer displays the appropriate version based on the user’s current Languages preference. If you do not supply a message, Installer supplies a default message.

The following sections describe

• where the VolumeCheck file and message files are placed in the installation package

• the arguments and environment variables available to VolumeCheck

• the return values VolumeCheck uses to specify an action and a message

• the default messages supplied by Installer

• the format of messages in a message file

• a sample VolumeCheck script file

In addition, see “Working With Script Files” for tips on using executables with PackageMaker and Installer.

File Placement for Volume Checking

Each file executed as part of an installation, including VolumeCheck, should be placed in the Resources directory of the package and must have its execution bit set. If you place the file correctly and build the package with PackageMaker, it will automatically set the execution bit for the file. However, you may need to set explicit permissions for the executable file—for more information, see “Authorization, File Ownership, and Permissions.”

Any VolumeCheck.strings message files you provide should also be placed in the Resources directory, within a localized resource directory with the appropriate name. For example, the items labeled -1- through -5- in Listing 1 show the file placement in a test package, where the strings files are localized for English and French. For information on which localized folder names you can use, see “Localized Folder Names.”

Warning: If no VolumeCheck.strings files are placed in localized directories or no localized version is found for the user’s current language selection, Installer should look for a default version at the highest level in the Resources directory. Due to a bug, however, only string files in localized resource directories are currently used.

Listing 1  Location of VolumeCheck executable and strings files in a package

Test.pkg

    Contents

        Archive.bom

        Archive.pax.gz

        Info.plist

        Resources

            Description.plist

            VolumeCheck             -1-

            English.lproj           -2-

                VolumeCheck.strings -3-

            French.lproj            -4-

                VolumeCheck.strings -5-

Arguments and Environment Variables

When Installer executes the VolumeCheck file, it provides one argument:

• $1: The full path to the volume to evaluate. For example:

  /Volumes/Mac_OS_X_Work

Installer also makes one environment variable available:

• $PACKAGE_PATH: The full path to the installation package. For example:

  /Volumes/Projects/Testing/Simple_Carbon_App.pkg

  VolumeCheck can use this path to obtain resources within the package.

Return Value for the VolumeCheck Executable

VolumeCheck returns a value that Installer interprets as a pair of bit fields, as shown in Figure 1. Bit 5 of the return value determines the action—that is, whether to allow or disallow the volume as a destination for the installation.

Figure 1  Bit fields in the value returned by VolumeCheck

If a volume is disallowed, Installer displays the icon for that volume with a badge that indicates it can’t be used for this installation. It also saves the value from the second bit field, consisting of bits 0–4. If the user later clicks the icon for the disallowed volume, Installer displays a message in the following format:

You cannot install this software on this disk. <message>

Installer uses the value from the second bit field to obtain the string <message> from the VolumeCheck.strings file. The strings file currently must be in a localized directory, as described in “File Placement for Volume Checking.” If no strings file is provided or if the specified message cannot be found, Installer provides a default message. Possible bit field values are shown in Table 2. Default string values are shown in Table 3. A sample strings file is shown in Listing 2.

Table 1 describes how Installer interprets the action bit (bit 5) in the value returned by VolumeCheck:

Table 2 describes how Installer interprets the message bits (bits 0 through 4) in the value returned by VolumeCheck. The five bits allow for a value between 0 and 31.

If the package contains strings files for multiple locales, Installer displays the appropriate version based on the user’s current Languages preference. For a sample strings file, see “Strings Files for the VolumeCheck Executable.”

VolumeCheck Message Strings

As described in “Return Value for the VolumeCheck Executable,” if a user clicks an icon for a disallowed volume, Installer displays a message based on a bit-field value specified previously by VolumeCheck. The message begins with “You cannot install this software on this disk.” It is followed by the specified message string from the file VolumeCheck.strings, which may be stored in a localized resource directory in the installation package. If the package does not supply a strings file or if the file doesn’t contain the specified message, Installer displays a default message.

Default Messages Provided by Installer

Based on the value VolumeCheck returns in the message bit field (bits 0–4), Installer provides the default message strings described in Table 3. These messages are concatenated with the string “You cannot install this software on this disk. “

Strings Files for the VolumeCheck Executable

To display a message when a user clicks the icon for a disallowed volume, you provide one or more files named VolumeCheck.strings and place them in the appropriate localized directory within the package’s Resources directory. “File Placement for Volume Checking” describes the placement of strings files in the package.

A strings file contains messages in the following format:

"number string" = "message string";

where "number string" represents a numeric value between 16 and 31, as described in Table 2 and "message string" is the string to display. Strings always end with a semicolon. An English strings file with two messages might look like the one in Listing 2.

Listing 2  A sample VolumeCheck.strings file

"16" = "Can't install on volumes named Jaguar.";

"17" = "Can’t install on volumes named Puma.";

For example, if the message index returned to the Installer is 48 (or a bit value of 110000, indicating the volume should be disallowed and the message index is 16), the message displayed to the user is

You cannot install this software on this disk. Can't install on volumes named Jaguar.

The bit fields in the VolumeCheck return value are described in detail in “Return Value for the VolumeCheck Executable”

VolumeCheck Example

Listing 3 shows a simple VolumeCheck script. This script checks the volume name and disallows any volumes named Jaguar, but a VolumeCheck script is free to perform checking of arbitrary complexity. You can examine output from VolumeCheck in the Console application (available in /Applications/Utilities). Alternatively, you can redirect output to a log file, using script statements like the following: echo "Full volume path is: $path" >> /tmp/scripts.log

The first line in this script (#!/bin/bash) indicates that the script uses the bash shell, located in /bin. Other lines that begin with the # character are comments.

Listing 3  A VolumeCheck script that checks the volume name

#!/bin/bash

#

# Argument 1 (the only argument to VolumeCheck) is the full path to a volume

#   in Installer's Target Select panel that a user can choose to

#   install the software on.

# The path is of the form "/" or /Volume/{volume name}

#

# For convenience, this script echoes the path and name of each volume.

path=$1

echo "Full volume path is: $path"

#

# Get the volume name from the full path.

#

path=${path##/*/}

echo "Volume name is: $path"

#

# You can perform testing of arbitrary complexity here.

# This script just disallows installing on volumes named "Jaguar".

#

# Note: If $path were not enclosed in quotes in the next statement,

#       the script would get an error if the volume name included a space.

#

if ([ "$path" = "Jaguar" ]) then

#

# If the volume has the disallowed name, return a value that tells Installer

# not to allow installation on the volume.

# The value should also specify a string from the VolumeCheck.strings file

# to display if the user clicks the volume icon.

#

# To do this, supply an error return value of 32.

#

# Sets the action bit (bit 5) to 1, to disallow the volume.

let retval=(1<<5)

#

# Sets the message value bits (bits 0 to 4) to 16,

# specifying the message associated with "16" in the strings file.

#

let retval=(retval|16)

#

else

#

# The volume name is OK, so allow it as a possible destination.

#

retval=0

fi

exit $retval

< Previous PageNext Page > Hide TOC