Previous | Contents | Next

Appendix C: Useful Information

C.1 Compiling NSIS Sources

If you want to compile NSIS by yourself you have to install the Sources. The Sources are shipped with every official NSIS distribution as well with the nightly development Snapshots. NSIS is programmed in Microsoft Visual C 6.0. Therefore it contains all necessary files including the Project Files. You can also use the current Version 7.0 of Visual C but the output is a few KB larger. The Sources also include a makefile for the famous Open Source Compiler GCC but unfortunately it is a little bit outdated. If you are working with GCC and want to provide a updated working makefile or your using an other Compiler like Borland C++ Builder or Open Watcom C/C++ and want to provide makefiles or project files please drop a line on the NSIS Forum.

Note: If your using Visual C 6.0 you have to update the Platform SDK to avoid crashes when using CopyFiles. See here for further informations. You should also install the Processor Pack for decreasing the excutable Size.

C.2 Errorlevels

Like any other program installers made by NSIS return errorlevels as a result of their execution. Very useful if you call an NSIS Installer from within an other installer with Execwait.

On normal Installers:

On silent Installers:

C.3 Add uninstall information to Add/Remove Programs

Create a key with your product name under HKLM/Software/Microsoft/Windows/CurrentVersion/Uninstall to add entries to the "Add/Remove Programs" section in the Control Panel. For Windows NT (NT4/2000/XP), it's also possible to create the key in the HKCU hive, so it will only appear for the current user. There are several values you can write to key to give information about your application and the uninstaller. Write a value using the WriteRegStr command (for strings) or WriteRegDWORD command (for DWORD values). Example:

WriteRegStr HKLM "Software/Microsoft/Windows/CurrentVersion/Uninstall/Product" "DisplayName" "Application Name"

Required values

DisplayName (string) - Name of the application
UninstallString (string) - Path and filename of the uninstaller

Optional values

Some of the following values will not be used by older Windows versions.

InstallLocation (string) - Installation directory ($INSTDIR)
DisplayIcon (string) - Path, filename and index of of the icon which will be displayed next to your application name

Publisher (string) - (Company) name of the publisher

ModifyPath (string) - Path and filename of the application modify program
InstallSource (string) - Location where the application was installed from

ProductID (string) - Product ID of the application
RegOwner (string) - Registered owner of the application
RegCompany (string) - Registered company of the application

HelpLink (string) - Link to the support website
HelpTelephone (string) - Telephone number for support

URLUpdateInfo (string) - Link to the website for application updates
URLInfoAbout (string) - Link to the application home page

DisplayVersion (string) - Displayed version of the application
VersionMajor (DWORD) - Major version number of the application
VersionMinor (DWORD) - Minor version number of the application

NoModify (DWORD) - 1 if uninstaller has no option to modify the installed application
NoRepair (DWORD) - 1 if the uninstaller has no option to repair the installation

If both NoModify and NoRepair are set to 1, the button displays "Remove" instead of "Modify/Remove".

C.4 How to install the VB6 runtimes

The best way to install the VB6 runtimes is to use the UpgradeDLL macro to upgrade the DLL files, and the AddSharedDLL macro when installing the software for the first time to increase the shared DLL count. Define UPGRADEDLL_NOREGISTER before upgrading Stdole2.tlb (and undefine it before upgrading other files).

Use the Modern UI with a Finish page to ask for a reboot if required or use IfRebootFlag and make your own page or messagebox.

You can extract the files from vbrun60sp5.exe using any archiver that supports CAB compression, or if you have installed the latest version on your system, copy the following files from your system directory:

Asycfilt.dll
Comcat.dll
Msvbvm60.dll
Oleaut32.dll
Olepro32.dll
Stdole2.tlb

In the uninstaller, use un.RemoveSharedDLL to decrement the shared DLL count, but remove the Delete /REBOOTOK $R1 line, because it's never a good idea to remove the VB runtimes. The system to registering shared DLL files does now always work and many application require these files.

# Don't forget to copy the macro's!

!define VBFILESDIR C:\Windows\System
# or
#!define VBFILESDIR C:\Path\to\where\vbrun60sp5.exe\extracted

Section "Install VB DLLs"
  !insertmacro UpgradeDLL ${VBFILESDIR}\Asycfilt.dll $SYSDIR\Asycfilt.dll
  !insertmacro UpgradeDLL ${VBFILESDIR}\Comcat.dll $SYSDIR\Comcat.dll
  !insertmacro UpgradeDLL ${VBFILESDIR}\Msvbvm60.dll $SYSDIR\Msvbvm60.dll
  !insertmacro UpgradeDLL ${VBFILESDIR}\Oleaut32.dll $SYSDIR\Oleaut32.dll
  !insertmacro UpgradeDLL ${VBFILESDIR}\Olepro32.dll $SYSDIR\Olepro32.dll
  !define UPGRADEDLL_NOREGISTER
    !insertmacro UpgradeDLL ${VBFILESDIR}\Stdole2.tlb $SYSDIR\Stdole2.tlb
  !undef UPGRADEDLL_NOREGISTER
  # skip shared count increasing if already done once for this application
  IfFileExists $INSTDIR\myprog.exe skipAddShared
    Push $SYSDIR\Asycfilt.dll
    Call AddSharedDLL
    Push $SYSDIR\Comcat.dll
    Call AddSharedDLL
    Push $SYSDIR\Msvbvm60.dll
    Call AddSharedDLL
    Push $SYSDIR\Oleaut32.dll
    Call AddSharedDLL
    Push $SYSDIR\Olepro32.dll
    Call AddSharedDLL
    Push $SYSDIR\Stdole2.tlb
    Call AddSharedDLL
  skipAddShared:
SectionEnd

Section "Uninstall"
  Push $SYSDIR\Asycfilt.dll
  Call un.RemoveSharedDLL
  Push $SYSDIR\Comcat.dll
  Call un.RemoveSharedDLL
  Push $SYSDIR\Msvbvm60.dll
  Call un.RemoveSharedDLL
  Push $SYSDIR\Oleaut32.dll
  Call un.RemoveSharedDLL
  Push $SYSDIR\Olepro32.dll
  Call un.RemoveSharedDLL
  Push $SYSDIR\Stdole2.tlb
  Call un.RemoveSharedDLL
SectionEnd

C.5 Calling an external DLL using the System.dll plugin

Some install processes are required to call functions contained inside third party DLLs. A prime example of this is when installing a Palm(TM) conduit.

Some background about System.dll
The System.dll plug-in (by Brainsucker) enables calling of external DLLs by providing the 'Call' function. There are a number of other functions provided by System.dll, but they will not be covered here. For more details about the other functions, lock the doors, take the phone off the hook, screw your head on *real* tight and head on over to the Contrib/System directory and read the doco there.

Data Types
System.dll recognises the following data types:

Mapping System.dll variables to NSIS script variables
There's not much point in being able to call an external function if you can't get any data back. System.dll maps function variables to NSIS script variables in the following way:

NSIS $0..$9 become System.dll r0..r9 NSIS $R0..$R9 become System.dll r10..r19

There is one final wrinkle: placing a period/dot ('.') in front of a System.dll variable means 'makes no change to source' and it appears to be used everywhere except where a pointer is returned. This is important and WILL cause you grief if you forget!! See the example below.

Using System.dll::Call To call a function in a third party DLL, the Call function is used like this:

System::Call 'YourDllName::YourDllFunction(i, *i, t) i(.r0, r1, .r2) .r3'

'(.r0, r1, .r2) .r3'

section at the end are the parameters that are passed between your DLL and your NSIS script. Note the absence of the dot in front of the 'r1' parameter...

Before starting to code the NSIS script
Before you start to code any NSIS code, you need to know the full prototype of the function you are going to call. For the purposes of this example, we will use the 'CmGetHotSyncExecPath' function from the Palm 'CondMgr.dll'. This function is used to return the full path of 'HotSync.exe'.

Function Definition

int CmGetHotSyncExecPath(TCHAR *pPath, int *piSize);

where

return values:

Also, if the buffer is too small the value in *int is the size (in TCHARs) that the buffer should be.

This function definition maps to the following System.dll definition:

CmGetHotSyncExecPath(t, *i) i

i.e. It takes a text variable, a pointer to int, and returns an int value.

Using the external dll function
Now that we've sorted out what the function does, and how it maps to the System.dll format, we can use the function in a NSIS script.

First, it is recommended to turn 'PluginUnload' off before making multiple calls to System.dll. According to Brainsucker (and others), this will speed up execution of the installer package.

Second, you have to change the output directory to that where the DLL you want to use is. It may also work if the DLL is on the system path, but this hasn't been tested.

The following code fragment will install 'condmgr.dll' to a temporary directory, execute the CmGetHotSyncExecPath function, display returned data and finally unload the System.dll plug-in. Save this script

; **** snip ****
SetPluginUnload  alwaysoff

Function loadDll

  SetOutPath $TEMP\eInspect             ; create temp directory
  File bin\CondMgr.dll                  ; copy dll there
  StrCpy $1 ${NSIS_MAX_STRLEN}          ; assign memory to $0
  System::Call 'CondMgr::CmGetHotSyncExecPath(t, *i) i(.r0, r1).r2'
  DetailPrint 'Path: "$0"'
  DetailPrint "Path length (I think): $1"
  DetailPrint "Return value: $2"

; last plugin call must not have /NOUNLOAD so NSIS will be able to delete
; the temporary DLL

  SetPluginUnload manual
; do nothing (but let the installer unload the System dll)
  System::Free 0
FunctionEnd
; **** snip ****

and this function produces the following output in the 'details' page:

Output folder: c:\windows\TEMP\eInspect
Extract: CondMgr.dll
Path: "C:\Dave\palm\Hotsync.exe"
Path length (I think): 1024
Return value: 0

Written by djc

Acknowledgements & Thanks
Lots of thanks go to kichik and Sunjammer for spending a lot of time assisting in solving this problem. Also to brainsucker for creating the System.dll plug-in in the first place. Good Luck!

C.6 Dump Content of Log Window to File

This function will dump the log of the installer (installer details) to a file of your choice. I created this function for Afrow_UK who requested a way to dump the log to a file in this forum thread.

To use it push a file name and call it. It will dump the log to the file specified. For example:

GetTempFileName $0
Push $0
Call DumpLog

Here is the function:

!define LVM_GETITEMCOUNT 0x1004
!define LVM_GETITEMTEXT 0x102D

Function DumpLog
  Exch $5
  Push $0
  Push $1
  Push $2
  Push $3
  Push $4
  Push $6

  FindWindow $0 "#32770" "" $HWNDPARENT
  GetDlgItem $0 $0 1016
  StrCmp $0 0 error
  FileOpen $5 $5 "w"
  StrCmp $5 0 error
    SendMessage $0 ${LVM_GETITEMCOUNT} 0 0 $6
    System::Alloc ${NSIS_MAX_STRLEN}
    Pop $3
    StrCpy $2 0
    System::Call "*(i, i, i, i, i, i, i, i, i) i \
      (0, 0, 0, 0, 0, r3, ${NSIS_MAX_STRLEN}) .r1"
    loop: StrCmp $2 $6 done
      System::Call "User32::SendMessageA(i, i, i, i) i \
        ($0, ${LVM_GETITEMTEXT}, $2, r1)"
      System::Call "*$3(&t${NSIS_MAX_STRLEN} .r4)"
      FileWrite $5 "$4$\r$\n"
      IntOp $2 $2 + 1
      Goto loop
    done:
      FileClose $5
      System::Free $1
      System::Free $3
      Goto exit
  error:
    MessageBox MB_OK error
  exit:
    Pop $6
    Pop $4
    Pop $3
    Pop $2
    Pop $1
    Pop $0
    Exch $5
FunctionEnd

written by KiCHiK

C.7 How to Read REG_MULTI_SZ Values

I wrote this script to help rpetges in this forum thread. It reads a registry value of the type REG_MULTI_SZ and prints it out. Don't forget to edit where it says "Edit this!" when you test this script. The values must point to a REG_MULTI_SZ value or the example will spit out an error.

OutFile "REG_MULTI_SZ Reader.exe"

Name "REG_MULTI_SZ Reader"

ShowInstDetails show

!define HKEY_CLASSES_ROOT        0x80000000
!define HKEY_CURRENT_USER        0x80000001
!define HKEY_LOCAL_MACHINE       0x80000002
!define HKEY_USERS               0x80000003
!define HKEY_PERFORMANCE_DATA    0x80000004
!define HKEY_PERFORMANCE_TEXT    0x80000050
!define HKEY_PERFORMANCE_NLSTEXT 0x80000060
!define HKEY_CURRENT_CONFIG      0x80000005
!define HKEY_DYN_DATA            0x80000006

!define KEY_QUERY_VALUE          0x0001
!define KEY_ENUMERATE_SUB_KEYS   0x0008

!define REG_NONE                 0
!define REG_SZ                   1
!define REG_EXPAND_SZ            2
!define REG_BINARY               3
!define REG_DWORD                4
!define REG_DWORD_LITTLE_ENDIAN  4
!define REG_DWORD_BIG_ENDIAN     5
!define REG_LINK                 6
!define REG_MULTI_SZ             7

!define RegOpenKeyEx     "Advapi32::RegOpenKeyExA(i, t, i, i, i) i"
!define RegQueryValueEx  "Advapi32::RegQueryValueExA(i, t, i, i, i, i, i) i"
!define RegCloseKey      "Advapi32::RegCloseKeyA(i) i"

####### Edit this!

!define ROOT_KEY         ${HKEY_CURRENT_USER}
!define SUB_KEY          "Software\Joe Software"
!define VALUE            "Strings"

####### Stop editing

Section "Read"
  StrCpy $0 ""
  StrCpy $1 ""
  StrCpy $2 ""
  StrCpy $3 ""
  SetPluginUnload alwaysoff
  System::Call "*(i) i (0) .r0"
  System::Call "*(i) i (0) .r1"
  System::Call "*(i) i (0) .r2"
  System::Call "${RegOpenKeyEx}(${ROOT_KEY}, '${SUB_KEY}', \
    0, ${KEY_QUERY_VALUE}|${KEY_ENUMERATE_SUB_KEYS}, r0) .r3"

  StrCmp $3 0 goon
    MessageBox MB_OK|MB_ICONSTOP "Can't open registry key! ($3)"
    Goto done
goon:

  System::Call "*$0(&i4 .r4)"
  System::Call "${RegQueryValueEx}(r4, '${VALUE}', 0, r1, 0, r2) .r3"

  StrCmp $3 0 read
    MessageBox MB_OK|MB_ICONSTOP "Can't query registry value! ($3)"
    Goto done

read:

  System::Call "*$1(&i4 .r3)"

  StrCmp $3 ${REG_MULTI_SZ} multisz
    MessageBox MB_OK|MB_ICONSTOP "Registry value no SZ_MULTI_SZ! ($3)"
    Goto done

multisz:

  System::Call "*$2(&i4 .r3)"

  StrCmp $3 0 0 multiszalloc
    MessageBox MB_OK|MB_ICONSTOP "Registry value empty! ($3)"
    Goto done

multiszalloc:

  System::Free $1
  System::Alloc $3
  Pop $1

  StrCmp $1 0 0 multiszget
    MessageBox MB_OK|MB_ICONSTOP "Can't allocate enough memory! ($3)"
    Goto done

multiszget:

  System::Call "${RegQueryValueEx}(r4, 'bla', 0, 0, r1, r2) .r3"

  StrCmp $3 0 multiszprocess
    MessageBox MB_OK|MB_ICONSTOP "Can't query registry value! ($3)[2]"
    Goto done

multiszprocess:

  StrCpy $4 $1

  loop:

    System::Call "*$4(&t${NSIS_MAX_STRLEN} .r3)"
    StrCmp $3 "" done
    DetailPrint $3
    StrLen $5 $3
    IntOp $4 $4 + $5
    IntOp $4 $4 + 1
    Goto loop

done:

  System::Free $2
  System::Free $1

  StrCmp $0 0 noClose
    System::Call "${RegCloseKey}(r0)"

noClose:

  SetPluginUnload manual
  System::Free $0
SectionEnd

written by KiCHiK

Previous | Contents | Next