A Simple Installer for Palm Applications

Author: ellocogato (talk, contrib)

Disclaimer

I am not particularly experienced with NSIS. I don't fully understand InstallOptions, the System plugin, or the Modern Interface. I needed an installer for a Palm application, and I could find no such existing NSIS example, so after hacking up an installer myself, I wrote an example based on what I did. It's probably not the most elegant, and it may not even be entirely correct. But it works.

If you find a mistake, find a better way of doing something, or add functionality that others might find useful, send me comments so that I can improve this example

The Script

; DESCRIPTION: Example Installer for simple (i.e. no conduit program) Palm applications
; AUTHOR: Gus Scheidt
; EMAIL: ellocogato <AT> gmail <DOT> com
; REQUIRES:  - The InstAide and UserData DLLs from the Palm Conduit Development Kit
;              (copy to the same directory as the .nsi file)
;            - Originally compiled with NSIS v2.11
;
;  This script supports installation of one or more files (PRC,PDB) to a Palm OS
;  handheld's internal memory plus one or more files to a memory slot (internal
;  expansion or external flash memory card).  It does not demonstrate installation
;  of any kind of conduit.  It does not demonstrate the ability to install for
;  multiple Palm Users at once.
;
;  If you don't need to install any files to a memory slot, then you won't need the
;  following:
;    - The "Page custom ShowSlotList" line
;    - The ShowSlotList function
;    - The ShowSlotList.ini file
;    - The GetPalmSlotList function
;    - The CheckSlotMgrSupport function
;    - The "INSTALL FILES TO EXPANSION MEMORY" section of the InstallFiles function
;    - The second half of the RemoveInstallFiles function
;
 
;Script loosely based on the MUI Basic Example Script Written by Joost Verburg
 
; declare variables
Var PalmUserList  ; Used to dynamically populate dropdown on User Selection page
Var PalmSlotList  ; Used to dynamically populate dropdown on Slot Selection page
Var UserChoice    ; Selected Palm Username
Var UserChoiceID  ; ID of selected Palm Username
Var NumSlots      ; How many memory slots available on the selected Palm User's handheld
Var SlotChoice    ; Selected memory slot
Var SlotChoiceID  ; ID of selected memory slot
Var SlotSupport   ; Does the selected Palm User's hanheld support slot management?
Var InstallStatus ; Defined when the installer is aborting
 
; declare constants
!define MY_PRODUCT "My Palm App" ;Define your own software name here
!define MY_VERSION "v1.0" ;Define your own software version here
!define MY_BUILD "1234"
Name "${MY_PRODUCT} ${MY_VERSION} (build ${MY_BUILD})" ;Display name for installer
 
!include "MUI.nsh"
 
;--------------------------------
;Configuration
 
  ; Name of the resulting executable installer file
  OutFile "${MY_PRODUCT}.exe"
 
  ; I don't intend to install any files permenantly on the PC, so
  ; use the system temporary directory
  InstallDir "$TEMP\MyAppSetup"
;--------------------------------
;Modern UI Configuration
 
  ; Show a license agreement page
  !define MUI_LICENSEPAGE
  ; Show a warning when the user cancels the install
  !define MUI_ABORTWARNING
  ; I'm using some custom pages
  !define MUI_CUSTOMPAGECOMMANDS
  ; Show a finish page at the end of the installation
  !define MUI_FINISHPAGE
  ; Don't present the option to reboot the computer on the finish page
  !define MUI_FINISHPAGE_NOREBOOTSUPPORT
  ; The icon for the installer title bar and .exe file
  ;!define MUI_ICON "myapp.ico"
  ; I want to use my product logo in the installer
  ;!define MUI_HEADERIMAGE
  ; Here is my product logo
  ;!define MUI_HEADERIMAGE_BITMAP "myapp.bmp"
  ; I want the logo to be on the right side of the installer, not the left
  ;!define MUI_HEADERIMAGE_RIGHT
  ; I've written a function that I want to be called when the user cancels the installation
  !define MUI_CUSTOMFUNCTION_ABORT myOnAbort
  ; Override the text on the Finish Page
  !define MUI_FINISHPAGE_TITLE "Installation Complete"
  !define MUI_FINISHPAGE_TEXT "${MY_PRODUCT} has been installed to your Palm device.\r\n\r\nClick Finish now to close the installation program."
 
;--------------------------------
;Pages
 
  ; These are the pages that I want my installer to consist of, in the order
  ; I want them to appear
  !insertmacro MUI_PAGE_LICENSE "License.txt" ; License agreement page.  Use license text from License.txt
  !insertmacro MUI_PAGE_INSTFILES ; File installation page
  Page custom ShowUserList ; My custom page for choosing the Palm user
  Page custom ShowSlotList ; My custom page for choosing the Palm external memory slot
  Page custom InstallFiles ; My custom page for scheduling files to be installed
                           ; and informing the user that a HotSync is required
 
  ; I've written a function that I want to be called just before the finish page is displayed
  !define MUI_PAGE_CUSTOMFUNCTION_PRE myFinishPre
  !insertmacro MUI_PAGE_FINISH ; the Finish page
 
;--------------------------------
;Languages
 
  ; I don't know anything about Internationalization.  But I speak English
  !insertmacro MUI_LANGUAGE "English"
 
;--------------------------------
;Language Strings
 
  ;Description text that I want to appear while files are being copied
  LangString DESC_SecCopyUI ${LANG_ENGLISH} "Copying the Palm files to your computer so they can be installed to your device."
 
  ;Header text for all pages in the installer
  LangString TEXT_IO_TITLE ${LANG_ENGLISH} "My Palm App"
  LangString TEXT_IO_SUBTITLE ${LANG_ENGLISH} "Install the Application and Data Files to your Device"
 
;--------------------------------
;Data
 
  ; Is this redundant?
  LicenseData "License.txt"
 
;--------------------------------
;Reserve Files
 
  ;Things that need to be extracted first (keep these lines before any File command!)
  ;Required for proper behavior when using BZIP2 compression
 
  ReserveFile "showUserList.ini"
  ReserveFile "showSlotList.ini"
  ReserveFile "installFiles.ini"
  !insertmacro MUI_RESERVEFILE_INSTALLOPTIONS
 
;--------------------------------
;Installer Sections
 
Section "MyApp.prc" SecCopyUI
 
  ; Define what files go where
  SetOutPath "$INSTDIR"
  ; Copy the files that we will use
  File "UserData.dll"
  File "InstAide.dll"
  File "MyApp.prc"
  File "MyAppData.dat"
 
SectionEnd
 
;--------------------------------
;Descriptions
 
!insertmacro MUI_FUNCTION_DESCRIPTION_BEGIN
  !insertmacro MUI_DESCRIPTION_TEXT ${SecCopyUI} $(DESC_SecCopyUI)
!insertmacro MUI_FUNCTION_DESCRIPTION_END
 
;--------------------------------
;Installer Functions
 
Function .onInit
 
  ;Extract InstallOptions INI Files
  !insertmacro MUI_INSTALLOPTIONS_EXTRACT "showUserList.ini"
  !insertmacro MUI_INSTALLOPTIONS_EXTRACT "showSlotList.ini"
  !insertmacro MUI_INSTALLOPTIONS_EXTRACT "installfiles.ini"
 
FunctionEnd
 
Function ShowUserList ; This function shows our custom "Select Palm User" page
  ; Get a list of all Palm users on the PC
  Call GetPalmUserList
  ; Use this list to populate the dropdown on our custom page
  !insertmacro MUI_INSTALLOPTIONS_WRITE "showUserList.ini" "Field 3" "ListItems" "$PalmUserList"
 
  !insertmacro MUI_HEADER_TEXT "$(TEXT_IO_TITLE)" "$(TEXT_IO_SUBTITLE)"
  !insertmacro MUI_INSTALLOPTIONS_DISPLAY "showUserList.ini"
 
  ; if we are aborting, do not check the value of UserChoice (if we do, then
  ; if the user cancels the install without selecting a user, it will insist
  ; that the user choose a user before exiting)
  StrCmp $InstallStatus "aborting_ir_install" End 0
    !insertmacro MUI_INSTALLOPTIONS_READ $UserChoice "showUserList.ini" "Field 3" "State"
    ; Verify that the user chose a valid user.  If not, display the ShowUserList
    ; screen again.
    ; Why not simply set MinLen of the dropdown to 1?  This will prevent the user
    ; from continuing without selecting a user, but it will not present any
    ; messagebox or other dialog.  That is confusing to the user!
    StrCmp $UserChoice "" 0 Continue
      MessageBox MB_OK|MB_ICONINFORMATION "You must choose a user to proceed!"
      Call ShowUserList
      GoTo End
    Continue:
    ; Also store the Palm user ID of the chosen user
    StrCpy $1 $UserChoice
    System::Call 'UserData::UmGetIDFromName(t r1, *i r4r4) i .r5'
    StrCpy $UserChoiceID $4
  End:
 
FunctionEnd
 
Function ShowSlotList
 
  ; Determine whether the chosen Palm user's device supports slot management
  ; If not, we can't use any *Slot* calls
  Call CheckSlotMgrSupport
  IntCmp $SlotSupport 0 0 HasSlotSupport HasSlotSupport
    MessageBox MB_OK|MB_ICONINFORMATION "The device used by the selected user does not appear to support External Memory.  Installation will abort."
    Call myOnAbort
    Quit
  HasSlotSupport:
 
  ; Get a list of all Palm external memory slots
  Call GetPalmSlotList
  ; If there are no slots (less than 1), abort.
  ; If there is only one slot, default to Slot 0 and skip the slot selection screen
  IntCmp $NumSlots 1 OneSlot NoSlots MultiSlots
  NoSlots:
    MessageBox MB_OK|MB_ICONINFORMATION "The device used by the selected user does not appear to have any External Memory slots.  Installation will abort."
    Call myOnAbort
    Quit
  OneSlot:
    StrCpy $SlotChoiceID 0
    Goto End
  MultiSlots:
 
  ; Use this list to populate the dropdown on our custom page
  !insertmacro MUI_INSTALLOPTIONS_WRITE "showSlotList.ini" "Field 3" "ListItems" "$PalmSlotList"
 
  !insertmacro MUI_HEADER_TEXT "$(TEXT_IO_TITLE)" "$(TEXT_IO_SUBTITLE)"
  ; Use the _RETURN macro so that we can get the InstallOptions return value
  ; to detect the Back button
  !insertmacro MUI_INSTALLOPTIONS_DISPLAY_RETURN "showSlotList.ini"
  ; Pop return value from the stack
  Pop $1
  ; If back button was selected, skip the rest of this function (we don't
  ; want to inforce selection if they are going back)
  StrCmp $1 "back" End
 
  ; if we are aborting, do not check the value of SlotChoice (if we do, then
  ; if the user cancels the install without selecting a slot, it will insist
  ; that the user choose a slot before exiting)
  StrCmp $InstallStatus "aborting_ir_install" End
    !insertmacro MUI_INSTALLOPTIONS_READ $SlotChoice "showSlotList.ini" "Field 3" "State"
    ; Verify that the user chose a valid slot  If not, display the ShowSlotList
    ; screen again.
    ; Why not simply set MinLen of the dropdown to 1?  This will prevent the user
    ; from continuing without selecting a user, but it will not present any
    ; messagebox or other dialog.  That is confusing to the user!
    StrCmp $SlotChoice "" 0 Continue
      MessageBox MB_OK|MB_ICONINFORMATION "You must choose a memory slot to proceed!"
      Call ShowSlotList
      GoTo End
    Continue:
    ; Extract and Store the Slot ID of the user's choice
    ; (Assume that the slot ID, in parenthesis, is the last 3 characters of the string)
    StrLen $1 $SlotChoice
    IntOp $1 $1 - 2
    StrCpy $SlotChoiceID $SlotChoice 1 $1;
    ;MessageBox MB_OK|MB_ICONINFORMATION "Extraced Slot ID $SlotChoiceID from selection $SlotChoice"
  End:
 
FunctionEnd
 
Function InstallFiles
 
  ; ====================  INSTALL PRC/PDB FILES  ==========================
  ; Set the PRC file to be installed to internal memory on next HotSync
  StrCpy $1 $UserChoice
  StrCpy $2 "$INSTDIR\MyApp.prc"
  ;MessageBox MB_OK|MB_ICONINFORMATION "Installing $2 for user $1"
  System::Call 'InstAide::PltInstallFile(t r1, t r2) i .r3'
  ;MessageBox MB_OK|MB_ICONINFORMATION "PltInstallFile returned value of $3"
  ; StrCpy $2 "$INSTDIR\AnotherFile.pdb"
  ; System::Call 'InstAide::PltInstallFile(t r1, t r2) i .r3'
 
  ; ====================  INSTALL FILES TO EXPANSION MEMORY  ==============
  ; Say our data file is big or is a file type that PalmOS doesn't allow on internal
  ; memory. Schedule the data file to be installed to the Expansion Card on next HotSync
  ; (Note that PltInstallFile uses username while PlmSlotInstallFile uses userID.)
  StrCpy $4 $UserChoiceID
  StrCpy $6 $SlotChoiceID
  ; Set the data file to be installed to external memory
  StrCpy $2 "$INSTDIR\MyAppData.dat"
  ;MessageBox MB_OK|MB_ICONINFORMATION "Installing $2 for user $4 ($1) to slot $6"
  System::Call 'InstAide::PlmSlotInstallFile(i r4, i r6, t r2) i .r5'
  ;MessageBox MB_OK|MB_ICONINFORMATION "PlmSlotInstallFile returned value of $5"
  ; StrCpy $2 "$INSTDIR\AnotherDataFile.dat"
  ; System::Call 'InstAide::PlmSlotInstallFile(i r4, i r6, t r2) i .r5'
 
  ; ====================  SHOW CUSTOM PAGE  ==========================
  !insertmacro MUI_HEADER_TEXT "$(TEXT_IO_TITLE)" "$(TEXT_IO_SUBTITLE)"
  !insertmacro MUI_INSTALLOPTIONS_DISPLAY "installfiles.ini"
FunctionEnd
 
 
Function GetPalmUserList
  ; NSIS has to be using the directory containing the dll for it to find it
  SetOutPath "$INSTDIR"
  File "UserData.dll" ; copy dll there
  System::Call 'UserData::UmGetUserCount(v) i .r1'
  ;MessageBox MB_OK|MB_ICONINFORMATION "There seem to be $1 Palm users"
 
  IntCmp $1 0 0 0 foundInstaller ; if return value of PltGetUserCount is 0 or negative, then we can't continue
    MessageBox MB_OK|MB_ICONINFORMATION "No Palm Installer was found on your system.  The installation cannot complete.  Please ensure that the latest version of the Palm Desktop Software is installed on your computer before installing."
    Abort
  foundInstaller:
 
  ; Compile the list of Palm Users
  StrCpy $2 0 ; Initialize counter
  StrCpy $PalmUserList "" ; Initialize list
  Loop:
    StrCpy $4 ${NSIS_MAX_STRLEN} ; $4 will tell the function the buffer length of $3
    ; $3 will be set to the username of the user indexed by $2
    System::Call 'UserData::UmGetUserID(i r2, *i r6r6) i .r5'
    System::Call 'UserData::UmGetUserName(i r6, t .r3, *i r4) i .r5'
    ;MessageBox MB_OK|MB_ICONINFORMATION "User indexed at $2 has ID $6 and name $3"
    StrCpy $PalmUserList "$PalmUserList$3|"
    IntOp $2 $2 + 1 ; Incriment the counter
    IntCmp $2 $1 0 Loop 0
 
  ;user list built, but it has an extra | on the end of it
  StrCpy $PalmUserList "$PalmUserList" -1
 
FunctionEnd
 
Function GetPalmSlotList
  ; NSIS has to be using the directory containing the dll for it to find it
  SetOutPath "$INSTDIR"
  File "UserData.dll" ; copy dll there
 
  StrCpy $3 $UserChoice
  StrCpy $6 $UserChoiceID
  ;MessageBox MB_OK|MB_ICONINFORMATION "Checking Slots for Palm user $6 ($3)"
  System::Call 'UserData::UmSlotGetSlotCount(i r6, *i r1r1) i .r5'
  StrCpy $NumSlots $1
  ;MessageBox MB_OK|MB_ICONINFORMATION "There seem to be $NumSlots Slot(s) (rv $5)"
 
  ; Compile the list of Slots
  StrCpy $2 0 ; Initialize counter
  StrCpy $PalmSlotList "" ; Initialize list
  Loop:
    StrCpy $4 ${NSIS_MAX_STRLEN} ; $4 will tell the function the buffer length of $3
    ; $3 will be set to the name of the slot indexed by $2
    System::Call 'UserData::UmSlotGetDisplayName(i r6, i r2, t .r3, *i r4) i .r5'
    ; We need to keep track of the slot ID of each slot, so append it to the display
    ; string so we can extract it later.
    StrCpy $PalmSlotList "$PalmSlotList$3 (Slot $2)|"
    IntOp $2 $2 + 1 ; Incriment the counter
    IntCmp $2 $1 0 Loop 0
 
  ;user list built, but it has an extra | on the end of it
  StrCpy $PalmSlotList "$PalmSlotList" -1
 
FunctionEnd
 
Function CheckSlotMgrSupport
  StrCpy $1 $UserChoiceID
  System::Call 'UserData::UmSlotGetExpMgrVersion(i r1, *i r2r2) i .r5'
  IntCmp $5 0 Success
    StrCpy $SlotSupport 0
    MessageBox MB_OK|MB_ICONINFORMATION "Error ($5).  No Slot Support."
    Goto End
  Success:
  StrCpy $SlotSupport $2
  ;MessageBox MB_OK|MB_ICONINFORMATION "Slot Support (v $SlotSupport)."
  End:
FunctionEnd
 
Function RemoveFiles
  ; We need to Unload the dll so that it can be deleted
  System::Call 'InstAide::PltGetUserCount(v) i .r1 ?u'
  System::Call 'UserData::UmGetUserCount(v) i .r1 ?u'
  ; I read somewhere that you should do this.  Don't know what it does
  SetPluginUnload manual
  System::Free 0
  ; Remove all of the files
  SetOutPath $TEMP
  Delete "$INSTDIR\InstAide.dll"
  Delete "$INSTDIR\UserData.dll"
  RMDir /r "$INSTDIR"
FunctionEnd
 
Function RemoveInstallFiles
  ; Un-schedule the PRC file for installation to internal memory
  StrCpy $1 $UserChoice
  StrCpy $2 "MyApp.prc"
  System::Call 'InstAide::PltRemoveInstallFile(t r1, t r2) i .r3'
  ;MessageBox MB_OK|MB_ICONINFORMATION "PltRemoveInstallFile returned value of $3"
  ; StrCpy $2 "AnotherFile.pdb"
  ; System::Call 'InstAide::PltRemoveInstallFile(t r1, t r2) i .r3'
 
  ; Un-schedule the data file for installation to external memory
  StrCpy $4 $UserChoiceID
  StrCpy $6 $SlotChoiceID
  StrCpy $2 "$INSTDIR\MyAppData.dat"
  System::Call 'InstAide::PlmSlotRemoveInstallFile(i r4, i r6, t r2) i .r5'
  ; StrCpy $2 "$INSTDIR\AnotherDataFile.dat"
  ; System::Call 'InstAide::PlmSlotRemoveInstallFile(i r4, i r6, t r2) i .r5'
 
FunctionEnd
 
Function myFinishPre
  ; Before we exit the installer, clean up all of the files that we copied
  ; to the PC
  Call RemoveFiles
FunctionEnd
 
Function myOnAbort
  ;MessageBox MB_OK|MB_ICONINFORMATION "WE ARE ABORTING !!!"
  ; Let other parts of the installer know that we are aborting
  StrCpy $InstallStatus "aborting_ir_install"
  ; In case we've already scheduled files for installation on the next HotSync,
  ; we should un-schedule them
  Call RemoveInstallFiles
  ; Clean up all of the files that we copied to the PC
  Call RemoveFiles
FunctionEnd

INI Files

Here are the .ini files that are referenced in the script

showUserList.ini

[Settings]
NumFields=4
 
[Field 1]
Type=Label
Text=After you have selected a user, click "Next".
Left=0
Right=171
Top=123
Bottom=132
 
[Field 2]
Type=Label
Text=STEP 1 -- Choose the User for Installation
Left=85
Right=226
Top=4
Bottom=12
 
[Field 3]
Type=Droplist
Text=droplist
ListItems=
Left=60
Right=157
Top=74
Bottom=116
 
[Field 4]
Type=Label
Text=Select the user for whom you wish to install My Palm App from the dropdown box below.  (Note that this script only supports installing for one user at a time.  If you wanted to be able to select multiple users and have your program scheduled for installation on the next HotSync, you would have to change the dropdown box to a listbox and change the script to call the InstAide functions for each user selected.)
Left=0
Right=272
Top=24
Bottom=69

showSlotList.ini

[Settings]
NumFields=4
 
[Field 1]
Type=Label
Text=After you have selected a slot, click "Next".
Left=0
Right=171
Top=123
Bottom=132
 
[Field 2]
Type=Label
Text=STEP 1 -- Choose the Memory Slot for Installation
Left=85
Right=226
Top=4
Bottom=12
 
[Field 3]
Type=Droplist
Text=droplist
ListItems=
Left=60
Right=176
Top=73
Bottom=116
 
[Field 4]
Type=Label
Text=Select the memory slot to which you wish to install the program's data files.
Left=0
Right=272
Top=24
Bottom=68

installFiles.ini

[Settings]
NumFields=3
 
[Field 1]
Type=Label
Text=You must now perform a HotSync to install My Palm App to your device.\r\n\r\nPerform a HotSync now.
Left=0
Right=278
Top=24
Bottom=94
 
[Field 2]
Type=Label
Text=When the HotSync is complete, click "Next" below.
Left=0
Right=181
Top=121
Bottom=129
 
[Field 3]
Type=Label
Text=STEP 2 -- Perform a HotSync
Left=85
Right=185
Top=4
Bottom=12

Credits

This example is roughly based on the MUI Basic Example Script written by Joost Verburg

The ini files were created with HM NIS Edit.