Appendix D: Useful Information

    Like other applications, installers made by NSIS return error levels as a result of their execution. Checking the error level can be useful if you call an NSIS installer from another application or installer.

    • 0 - Normal execution (no error)
    • 1 - Installation aborted by user (cancel button)
    • 2 - Installation aborted by script

    You can set the error level to other values using SetErrorLevel.

    Note that uninstallers copy themselves to the temporary directory and execute from there so the original uninstaller can be deleted. This means the error level the uninstaller sets is not available to the executing process, unless it simulates this copy process and executes the copied uninstaller. To simulate this process, use:

    If you don't do this, you'll only be able to know if the uninstaller failed copying itself to the temporary directory.

    D.2 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 command (for strings) or WriteRegDWORD command (for DWORD values).

    Example:

    1. WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\MyProduct" "DisplayName" "Application Name"
    2. WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\MyProduct" "UninstallString" '"$INSTDIR\uninst.exe"'

    Required values

    DisplayName (string) - Name of the application UninstallString (string) - Path and filename of the uninstaller. You should always quote the path.

    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 the icon that 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

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

    Some installers need to call functions in 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 enables calling of external DLLs by using its '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 System readme.

    Data Types System.dll recognises the following data types:

    • v - void (generally for return)
    • p - pointer (includes void*, HANDLE, HWND, UINT_PTR and so on)
    • i - int (a 32bit integer)
    • l - large integer (also known as int64)
    • t - text, string (LPTSTR, pointer to first character)
    • k - callback. See Callback section in system.html.
        • pointer specifier -> the proc needs the pointer to type, affects next char (parameter) [ex: '*i' - pointer to int]

    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 becomes System.dll r0..r9 NSIS $R0..$R9 becomes System.dll r10..r19

    Each parameter is specified by type, input and output. To skip input or output use a dot. Examples:

    String (pointer to a character array), input is 'happy calling':

    1. t 'happy calling'

    String (pointer to a character array), input is taken from $5 and changes to the array made by the callee are saved into $R8:

    1. t r5R8

    Pointer to an integer, value taken from $1 and put into $2:

    Pointer to a 64-bit integer, output pushed on stack, no input:

    1. *l .s

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

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

    The '(r0, .r1, r2) .r3' section at the end are the parameters that are passed between your DLL and your NSIS script. As can be seen in this parameters list, type and input/output can be separated. Each block of "(parms list) return value" overrides and/or adds to the last one. In this case, the first block specifies the types and the second specifies input and output.

    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 __stdcall CmGetHotSyncExecPath(TCHAR pPath, int piSize);

    where

    • pPath is a pointer to a character buffer. Upon return, this is the path & file name of the installed HotSync manager.
    • piSize is a pointer to an integer that specifies the size (in TCHAR's), of the buffer referenced by the pPath parameter.
    • 0: No error
    • -1: A non-specific error occurred
    • ERR_REGISTRY_ACCESS(-1006):Unable to access the Palm configuration entries
    • ERR_BUFFER_TOO_SMALL(-1010): The buffer is too small to hold the requested information
    • ERR_INVALID_POINTER(-1013):The specified pointer is not a valid pointer

    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 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 in 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 and display returned data. Save this script

    1. ; **** snip ****
    2. Function loadDll
    3.  
    4.   SetOutPath $TEMP\eInspect             ; create temp directory
    5.   File bin\CondMgr.dll                  ; copy dll there
    6.   StrCpy $1 ${NSIS_MAX_STRLEN}          ; assign memory to $0
    7.   System::Call 'CondMgr::CmGetHotSyncExecPath(t, *i) i(.r0, r1r1).r2'
    8.   DetailPrint 'Path: "$0"'
    9.   DetailPrint "Path length: $1"
    10.   DetailPrint "Return value: $2"
    11.  
    12. FunctionEnd
    13. ; **** 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: 24 Return value: 0

    Written by

    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!

    D.4 Dump Content of Log Window to File

    This function will dump the log of the installer (installer details) to a file of your choice.

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

    Here is the function:

    1. !define LVM_GETITEMCOUNT 0x1004
    2. !define LVM_GETITEMTEXTA 0x102D
    3.  
    4. Function DumpLog # Written by KiCHiK
    5.   Exch $5
    6.   Push $0
    7.   Push $1
    8.   Push $2
    9.   Push $3
    10.   Push $4
    11.   Push $6
    12.  
    13.   FindWindow $0 "#32770" "" $HWNDPARENT
    14.   GetDlgItem $0 $0 1016
    15.   StrCmp $0 0 error
    16.   FileOpen $5 $5 "w"
    17.   StrCmp $5 0 error
    18.     SendMessage $0 ${LVM_GETITEMCOUNT} 0 0 $6
    19.     System::StrAlloc ${NSIS_MAX_STRLEN}
    20.     Pop $3
    21.     StrCpy $2 0
    22.     System::Call "*(i, i, i, i, i, i, i, i, i) p \
    23.       (0, 0, 0, 0, 0, r3, ${NSIS_MAX_STRLEN}) .r1"
    24.     loop: StrCmp $2 $6 done
    25.       System::Call "User32::SendMessageA(p, i, p, p) i \
    26.         ($0, ${LVM_GETITEMTEXTA}, $2, r1)"
    27.       System::Call "*$3(&t${NSIS_MAX_STRLEN} .r4)"
    28.       FileWrite $5 "$4$\r$\n"
    29.       IntOp $2 $2 + 1
    30.       Goto loop
    31.     done:
    32.       FileClose $5
    33.       System::Free $1
    34.       System::Free $3
    35.       Goto exit
    36.   error:
    37.     MessageBox MB_OK error
    38.     Pop $6
    39.     Pop $4
    40.     Pop $3
    41.     Pop $2
    42.     Pop $1
    43.     Pop $0
    44.     Exch $5
    45. FunctionEnd

    Here's the function to generate a UTF-16LE file if you're building a Unicode installer.

    1. !define LVM_GETITEMCOUNT 0x1004
    2. !define LVM_GETITEMTEXTW 0x1073
    3.  
    4. Function DumpLog # Written by KiCHiK, modified by Jim Park
    5.   Exch $5
    6.   Push $0
    7.   Push $1
    8.   Push $2
    9.   Push $3
    10.   Push $4
    11.   Push $6
    12.  
    13.   FindWindow $0 "#32770" "" $HWNDPARENT
    14.   GetDlgItem $0 $0 1016
    15.   StrCmp $0 0 error
    16.   FileOpen $5 $5 "w"
    17.   FileWriteWord $5 0xfeff ; Write the BOM
    18.   StrCmp $5 0 error
    19.     SendMessage $0 ${LVM_GETITEMCOUNT} 0 0 $6
    20.     System::StrAlloc ${NSIS_MAX_STRLEN}
    21.     Pop $3
    22.     StrCpy $2 0
    23.     System::Call "*(i, i, i, i, i, i, i, i, i) p \
    24.       (0, 0, 0, 0, 0, r3, ${NSIS_MAX_STRLEN}) .r1"
    25.     loop: StrCmp $2 $6 done
    26.       System::Call "User32::SendMessageW(p, i, p, p) i \
    27.         ($0, ${LVM_GETITEMTEXTW}, $2, r1)"
    28.       System::Call "*$3(&t${NSIS_MAX_STRLEN} .r4)"
    29.       FileWriteUTF16LE $5 "$4$\r$\n"
    30.       IntOp $2 $2 + 1
    31.       Goto loop
    32.     done:
    33.       FileClose $5
    34.       System::Free $1
    35.       System::Free $3
    36.       Goto exit
    37.   error:
    38.     MessageBox MB_OK error
    39.   exit:
    40.     Pop $6
    41.     Pop $4
    42.     Pop $3
    43.     Pop $2
    44.     Pop $1
    45.     Pop $0
    46.     Exch $5
    47. FunctionEnd

    KiCHiK 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.

    1. OutFile "REG_MULTI_SZ Reader.exe"
    2. Name "REG_MULTI_SZ Reader"
    3. ShowInstDetails show
    4.  
    5. !define HKEY_CLASSES_ROOT        0x80000000
    6. !define HKEY_CURRENT_USER        0x80000001
    7. !define HKEY_LOCAL_MACHINE       0x80000002
    8. !define HKEY_USERS               0x80000003
    9. !define HKEY_PERFORMANCE_DATA    0x80000004
    10. !define HKEY_PERFORMANCE_TEXT    0x80000050
    11. !define HKEY_PERFORMANCE_NLSTEXT 0x80000060
    12. !define HKEY_CURRENT_CONFIG      0x80000005
    13. !define HKEY_DYN_DATA            0x80000006
    14. !define KEY_QUERY_VALUE          0x0001
    15. !define KEY_ENUMERATE_SUB_KEYS   0x0008
    16. !define REG_NONE                 0
    17. !define REG_SZ                   1
    18. !define REG_EXPAND_SZ            2
    19. !define REG_BINARY               3
    20. !define REG_DWORD                4
    21. !define REG_DWORD_LITTLE_ENDIAN  4
    22. !define REG_DWORD_BIG_ENDIAN     5
    23. !define REG_LINK                 6
    24. !define REG_MULTI_SZ             7
    25.  
    26. !define RegOpenKeyEx     "Advapi32::RegOpenKeyExA(i, t, i, i, *i) i"
    27. !define RegCloseKey      "Advapi32::RegCloseKeyA(i) i"
    28.  
    29. ####### Edit this!
    30.  
    31. !define ROOT_KEY         ${HKEY_CURRENT_USER}
    32. !define SUB_KEY          "Software\Joe Software"
    33. !define VALUE            "Strings"
    34.  
    35. ####### Stop editing
    36.  
    37. Section "Read"
    38.   StrCpy $0 ""
    39.   StrCpy $1 ""
    40.   StrCpy $2 ""
    41.   StrCpy $3 ""
    42.   System::Call "${RegOpenKeyEx}(${ROOT_KEY}, '${SUB_KEY}', \
    43.     0, ${KEY_QUERY_VALUE}|${KEY_ENUMERATE_SUB_KEYS}, .r0) .r3"
    44.  
    45.   StrCmp $3 0 goon
    46.     MessageBox MB_OK|MB_ICONSTOP "Can't open registry key! ($3)"
    47.     Goto done
    48. goon:
    49.  
    50.   System::Call "${RegQueryValueEx}(r0, '${VALUE}', 0, .r1, 0, .r2) .r3"
    51.  
    52.   StrCmp $3 0 read
    53.     MessageBox MB_OK|MB_ICONSTOP "Can't query registry value size! ($3)"
    54.     Goto done
    55.  
    56. read:
    57.  
    58.   StrCmp $1 ${REG_MULTI_SZ} multisz
    59.     MessageBox MB_OK|MB_ICONSTOP "Registry value no REG_MULTI_SZ! ($3)"
    60.     Goto done
    61.  
    62. multisz:
    63.  
    64.   StrCmp $2 0 0 multiszalloc
    65.     MessageBox MB_OK|MB_ICONSTOP "Registry value empty! ($3)"
    66.     Goto done
    67.  
    68. multiszalloc:
    69.  
    70.   System::Alloc $2
    71.   Pop $1
    72.  
    73.   StrCmp $1 0 0 multiszget
    74.     MessageBox MB_OK|MB_ICONSTOP "Can't allocate enough memory! ($3)"
    75.     Goto done
    76.  
    77. multiszget:
    78.  
    79.   System::Call "${RegQueryValueEx}(r0, '${VALUE}', 0, n, r1, r2) .r3"
    80.  
    81.   StrCmp $3 0 multiszprocess
    82.     MessageBox MB_OK|MB_ICONSTOP "Can't query registry value data! ($3)"
    83.     Goto done
    84.  
    85. multiszprocess:
    86.  
    87.   StrCpy $4 $1
    88.  
    89.   loop:
    90.  
    91.     System::Call "*$4(&t${NSIS_MAX_STRLEN} .r3)"
    92.     StrCmp $3 "" done
    93.     DetailPrint $3
    94.     StrLen $5 $3
    95.     IntOp $4 $4 + $5
    96.     IntOp $4 $4 + 1
    97.     Goto loop
    98.  
    99. done:
    100.  
    101.   System::Free $1
    102.  
    103.   StrCmp $0 0 noClose
    104.     System::Call "${RegCloseKey}(r0)"
    105.  
    106. noClose:
    107.  

    D.6 Predefined Macros for Unicode support

    There are two macros that can help you write scripts that work for both Unicode and ANSI installers. To figure out if the script is being compiled to generate a Unicode installer, use !ifdef to check for ${NSIS_UNICODE}. To see what the size of a character is, use ${NSIS_CHAR_SIZE}. It will be 1 for ANSI and 2 for Unicode installers.