Nutshell and Nutshell PRO installers will broadcast messages and send sublaunches to installed executables in order to give programs an opportunity to perform actions.
Pre-Run Notifications
Before installation, the installer will broadcast a Notification Manager notification of notifyType 'nuts'. Additionally, before the Nutshell uninstaller runs, it will broadcast a Notification Manager notification of notifyType 'stun'. Programs may want to register for these notifications in order to close down running libraries or prepare for uninstallation or upgrades.
Important Note: If you decide to register for this notification, you must keep in mind that other Nutshell installers will also broadcast the same notification. In order to make sure that you are only responding to your own installer's notifications, give your Nutshell a custom creator ID. In your app's notification handler, check the broadcaster element of the SysNotifyParamType to make sure that it matches your installer's creator ID.
SyncNotify Launch Code
After installation is complete, all applications and pref panels receive a sysAppLaunchCmdSyncNotify launch code. This simulates the launch code they would receive if installed via HotSync or arrived via a beam.
Pre-Replace Launch Code (Nutshell PRO only)
Before an executable is replaced by the installer, it will send a sublaunch with launch code of (sysAppLaunchCmdCustomBase|0x0911). This will give the application an opportunity to prepare for an upgrade. This option is enabled using Nutshell PRO's -W flag. Note that this launch code was always sent in earlier versions of Nutshell. The functionality was made optional because the launch code was causing problems with "NS Basic" applications.
Resource Merge (Nutshell PRO only)
Since you may want to customize your installer, Nutshell PRO provides the ability to merge an existing resource database into your installer after it has been created. Resources in your file will replace resources in the Nutshell installer. Possible uses include adding a custom icon or changing the wording in an alert message. Resource merge is invoked via the -g flag in Nutshell PRO.
Installer Scripting (Nutshell PRO only)
Nutshell PRO provides an advanced mechanism for performing installation logic and actions before and during installation. This is useful when the Sub-Launches and Notifications are insufficent. For example, your installer may need to check the Palm system for certain files, perform deletions, close libraries, or pick and choose files to install based on the current system. Additionally, the installer may want to bail out if certain conditions are not met. This is all made possible by creating a scripting shared library.
A scripting shared library is a standard Palm OS shared library compiled using CodeWarrior for Palm OS or gcc. Before files are installed, the library is automatically installed and loaded on to the target device.
Pre-Run Entrypoint
The shared library's first custom entry point, containing your custom code, is called before installation begins. The return value determines whether or not the installer will run:
Return 0 to proceed with installation.
Return 1 to cancel installation.
Return 2 to cancel installation and delete the installer.
Each-File Entrypoint
The shared library's second custom entry point, containing your custom code, is called before each file is installed. A string parameter is provided containing the database name. The return value determines whether or not the file will be installed:
Return a non-zero error code to skip the file.
Return errNone to install the file.
After running, the shared library is automatically unloaded and deleted.
Using NSScript CodeWarrior Project
The Nutshell PRO software contains a sample CodeWarrior project which demonstrates the creation of a scriptiing shared library. The project is compatible with CodeWarrior 8 and 9.
Add your code to NSScriptImpl.c in these function:
Err NSScriptPreRunCheck(UInt16 refNum)
{
Err err = errNone;
#pragma unused(refNum)
// your code goes here
// returning a non-zero (!=errNone) code will terminate installation
return err;
}
Err NSScriptEachFileCheck(UInt16 refNum, char* fileName)
{
Err err = errNone;
#pragma unused(refNum)
// your code goes here
// This function will be called for each file installed
// giving you the opportunity to pick and choose files based on the current configuration
// returning a non-zero (!=errNone) code will pass over the specified file
return err;
}
Compile the shared library and specify the name of the scripting shared library PRC using the -p flag in Nutshell PRO.
