/usr/share/doc/nsis/Docs/AppendixD.html is in nsis-doc 2.51-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns='http://www.w3.org/1999/xhtml'>
<head>
<title>Useful Information</title>
<meta name="generator" content="Halibut version 1.0 (NSIS Custom Build) xhtml-backend" />
<link rel="stylesheet" href="style.css" type='text/css' />
</head>
<body>
<p><a href='AppendixC.html'>Previous</a> | <a href='Contents.html'>Contents</a> | <a href='AppendixE.html'>Next</a></p>
<ul>
<li><a class="btitle" href="AppendixD.html#D"><b>Appendix D: </b>Useful Information</a></li>
<ul>
<li><a href="AppendixD.html#D.1">Error Levels</a></li>
<li><a href="AppendixD.html#D.2">Add uninstall information to Add/Remove Programs</a></li>
<li><a href="AppendixD.html#D.3">Calling an external DLL using the System.dll plug-in</a></li>
<li><a href="AppendixD.html#D.4">Dump Content of Log Window to File</a></li>
<li><a href="AppendixD.html#D.5">How to Read REG_MULTI_SZ Values</a></li>
</ul>
</ul>
<a name="D"></a><h1>Appendix D: Useful Information</h1>
<a name="D.1"></a><h2>D.1 Error Levels</h2>
<p>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.</p>
<ul>
<li>0 - Normal execution (no error)</li><li>1 - Installation aborted by user (cancel button)</li><li>2 - Installation aborted by script</li></ul>
<p>As of NSIS 2.01, you can set the error level to other values using <a href="Chapter4.html#4.9.7.5">SetErrorLevel</a>.</p>
<p>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:</p>
<pre>InitPluginsDir
CopyFiles $INSTDIR\uninstaller.exe $PLUGINSDIR
ExecWait '"$PLUGINSDIR\uninstaller.exe" _?=$INSTDIR' $0
DetailPrint "uninstaller set error level $0"
</pre>
<p>If you don't do this, you'll only be able to know if the uninstaller failed copying itself to the temporary directory.</p>
<a name="D.2"></a><h2>D.2 Add uninstall information to Add/Remove Programs</h2>
<p>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. 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:</p>
<pre>WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\Product" "DisplayName" "Application Name"
</pre>
<p><b>Required values</b></p>
<p><em>DisplayName</em> (string) - Name of the application <br> <em>UninstallString</em> (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.</p>
<p><b>Optional values</b></p>
<p>Some of the following values will not be used by older Windows versions.</p>
<p><em>InstallLocation</em> (string) - Installation directory ($INSTDIR) <br> <em>DisplayIcon</em> (string) - Path, filename and index of the icon that will be displayed next to your application name</p>
<p><em>Publisher</em> (string) - (Company) name of the publisher</p>
<p><em>ModifyPath</em> (string) - Path and filename of the application modify program <br> <em>InstallSource</em> (string) - Location where the application was installed from</p>
<p><em>ProductID</em> (string) - Product ID of the application <br> <em>RegOwner</em> (string) - Registered owner of the application <br> <em>RegCompany</em> (string) - Registered company of the application</p>
<p><em>HelpLink</em> (string) - Link to the support website <br> <em>HelpTelephone</em> (string) - Telephone number for support</p>
<p><em>URLUpdateInfo</em> (string) - Link to the website for application updates <br> <em>URLInfoAbout</em> (string) - Link to the application home page</p>
<p><em>DisplayVersion</em> (string) - Displayed version of the application <br> <em>VersionMajor</em> (DWORD) - Major version number of the application <br> <em>VersionMinor</em> (DWORD) - Minor version number of the application</p>
<p><em>NoModify</em> (DWORD) - 1 if uninstaller has no option to modify the installed application <br> <em>NoRepair</em> (DWORD) - 1 if the uninstaller has no option to repair the installation</p>
<p>If both NoModify and NoRepair are set to 1, the button displays "Remove" instead of "Modify/Remove".</p>
<a name="D.3"></a><h2>D.3 Calling an external DLL using the System.dll plug-in</h2>
<p>Some installers need to call functions in third-party DLLs. A prime example of this is when installing a Palm(TM) conduit.</p>
<p><b>Some background about System.dll</b> <br> The System.dll plug-in 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 <a href="../Docs/System/System.html">System readme</a>.</p>
<p><u>Data Types</u> <br> System.dll recognises the following data types:</p>
<ul>
<li>v - void (generally for return)</li><li>p - pointers and handles</li><li>i - int (includes char, byte, short and 32bit integers)</li><li>l - large integer (also known as int64)</li><li>t - text, string (LPCSTR, pointer to first character)</li><li>b - boolean (needs/returns 'true':'false') - by the fact this type is senseless -> usual integer can be used ('0':'1')</li><li>k - callback. See Callback section in system.html.</li><li>* - pointer specifier -> the proc needs the pointer to type, affects next char (parameter) [ex: '*i' - pointer to int]</li></ul>
<p><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:</p>
<p>NSIS $0..$9 becomes System.dll r0..r9 NSIS $R0..$R9 becomes System.dll r10..r19</p>
<p>Each parameter is specified by type, input and output. To skip input or output use a dot. Examples:</p>
<p>String (pointer to a character array), input is 'happy calling':</p>
<pre>t 'happy calling'
</pre>
<p>String (pointer to a character array), input is taken from $5 and changes to the array made by the call are saved into $R8:</p>
<pre>t r5R8
</pre>
<p>Pointer to an integer, value taken from $1 and put into $2:</p>
<pre>*i r1r2
</pre>
<p>Pointer to a 64-bit integer, output pushed on stack, no input:</p>
<pre>*l .s
</pre>
<p>Using System.dll::Call To call a function in a third party DLL, the Call function is used like this:</p>
<pre>System::Call 'YourDllName::YourDllFunction(i, *i, t) i(r0, .r1, r2) .r3'
</pre>
<p>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.</p>
<p><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'.</p>
<p><u>Function Definition</u> <br></p>
<p>int __stdcall CmGetHotSyncExecPath(TCHAR *pPath, int *piSize);</p>
<p>where</p>
<ul>
<li>pPath is a pointer to a character buffer. Upon return, this is the path & file name of the installed HotSync manager.</li><li>piSize is a pointer to an integer that specifies the size (in TCHAR's), of the buffer referenced by the pPath parameter.</li></ul>
<p>return values:</p>
<ul>
<li>0: No error</li><li>-1: A non-specific error occurred</li><li>ERR_REGISTRY_ACCESS(-1006):Unable to access the Palm configuration entries</li><li>ERR_BUFFER_TOO_SMALL(-1010): The buffer is too small to hold the requested information</li><li>ERR_INVALID_POINTER(-1013):The specified pointer is not a valid pointer</li></ul>
<p>Also, if the buffer is too small the value in *int is the size (in TCHARs) that the buffer should be.</p>
<p>This function definition maps to the following System.dll definition:</p>
<p>CmGetHotSyncExecPath(t, *i) i</p>
<p>i.e. It takes a text variable, a pointer to int, and returns an int value.</p>
<p><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.</p>
<p>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.</p>
<p>The following code fragment will install 'condmgr.dll' to a temporary directory, execute the CmGetHotSyncExecPath function and display returned data. Save this script</p>
<pre>; **** snip ****
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, r1r1).r2'
DetailPrint 'Path: "$0"'
DetailPrint "Path length: $1"
DetailPrint "Return value: $2"
FunctionEnd
; **** snip ****
</pre>
<p>and this function produces the following output in the 'details' page:</p>
<p>Output folder: c:\windows\TEMP\eInspect <br> Extract: CondMgr.dll <br> Path: "C:\Dave\palm\Hotsync.exe" <br> Path length: 24 <br> Return value: 0</p>
<p>Written by <a href="http://nsis.sourceforge.net/archive/profile.php?userid=78">djc</a></p>
<p><u>Acknowledgements & Thanks</u> <br> 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. Good Luck!</p>
<a name="D.4"></a><h2>D.4 Dump Content of Log Window to File</h2>
<p>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 <a href="http://forums.winamp.com/showthread.php?s=&threadid=125431">this forum thread</a>.</p>
<p>To use it, push a file name and call it. It will dump the log to the file specified. For example:</p>
<pre>GetTempFileName $0
Push $0
Call DumpLog
</pre>
<p>Here is the function:</p>
<pre>!define LVM_GETITEMCOUNT 0x1004
!define LVM_GETITEMTEXTA 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_GETITEMTEXTA}, $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
</pre>
<p>written by KiCHiK</p>
<a name="D.5"></a><h2>D.5 How to Read REG_MULTI_SZ Values</h2>
<p>KiCHiK wrote this script to help rpetges in <a href="http://forums.winamp.com/showthread.php?s=&threadid=131154">this forum thread</a>. 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.</p>
<pre>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"
!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 ""
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 "${RegQueryValueEx}(r0, '${VALUE}', 0, .r1, 0, .r2) .r3"
StrCmp $3 0 read
MessageBox MB_OK|MB_ICONSTOP "Can't query registry value size! ($3)"
Goto done
read:
StrCmp $1 ${REG_MULTI_SZ} multisz
MessageBox MB_OK|MB_ICONSTOP "Registry value no REG_MULTI_SZ! ($3)"
Goto done
multisz:
StrCmp $2 0 0 multiszalloc
MessageBox MB_OK|MB_ICONSTOP "Registry value empty! ($3)"
Goto done
multiszalloc:
System::Alloc $2
Pop $1
StrCmp $1 0 0 multiszget
MessageBox MB_OK|MB_ICONSTOP "Can't allocate enough memory! ($3)"
Goto done
multiszget:
System::Call "${RegQueryValueEx}(r0, '${VALUE}', 0, n, r1, r2) .r3"
StrCmp $3 0 multiszprocess
MessageBox MB_OK|MB_ICONSTOP "Can't query registry value data! ($3)"
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 $1
StrCmp $0 0 noClose
System::Call "${RegCloseKey}(r0)"
noClose:
SectionEnd
</pre>
<p>written by KiCHiK</p>
<p><a href='AppendixC.html'>Previous</a> | <a href='Contents.html'>Contents</a> | <a href='AppendixE.html'>Next</a></p>
<hr />
<address>
</address>
</body>
</html>
|