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.
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:
Create a key with your product name under \\<b\\>HKLM\\Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\</b\\> to add entries to the "Add/Remove Programs" section in the Control Panel.
\e{UninstallString} (string) - Path and filename of the uninstaller. You should \\<b\\>always\\</b\\> quote the path to make sure spaces in the path will not disrupt Windows to find the uninstaller.
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.
\\<b\\>Some background about System.dll\\</b\\> \\<br\\>
The System.dll plug-in (by Brainsucker) enables calling of external DLLs by providing the '\R{call}{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 \L{../Docs/System/System.html}{System readme}.
\b * - pointer specifier -> the proc needs the pointer to type, affects next char (parameter) [ex: '*i' - pointer to int]
\\<u\\>Mapping System.dll variables to NSIS script variables\\</u\\> \\<br\\>
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:
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.
\\<b\\>Before starting to code the NSIS script\\</b\\> \\<br\\>
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'.
\\<u\\>Function Definition\\</u\\> \\<br\\>
int CmGetHotSyncExecPath(TCHAR *pPath, int *piSize);
where
\b pPath is a pointer to a character buffer. Upon return, this is the path & file name of the installed HotSync manager.
\b piSize is a pointer to an integer that specifies the size (in TCHAR's), of the buffer referenced by the pPath parameter.
return values:
\b 0: No error
\b -1: A non-specific error occurred
\b ERR_REGISTRY_ACCESS(-1006):Unable to access the Palm configuration entries
\b ERR_BUFFER_TOO_SMALL(-1010): The buffer is too small to hold the requested information
\b 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.
\\<u\\>Using the external dll function\\</u\\> \\<br\\>
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 on the system path, but this hasn't been tested.
Lots of thanks go to \\<b\\>kichik\\</b\\> and \\<b\\>Sunjammer\\</b\\> for spending a lot of time assisting in solving this problem. Also to \\<b\\>brainsucker\\</b\\> for creating the System.dll plug-in in the first place.
\H{dumplogtofile} 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 \W{http://forums.winamp.com/showthread.php?s=&threadid=125431}{this forum thread}.
\H{readreg_multi_sz} How to Read REG_MULTI_SZ Values
I wrote this script to help rpetges in \W{http://forums.winamp.com/showthread.php?s=&threadid=131154}{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.
\H{unicode_defines}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 check for $\{NSIS_UNICODE\}. To see what the size of the default character is, use $\{NSIS_CHAR_SIZE\}. It will be 1 for ANSI and 2 for Unicode installers.
