StdUtils for NSIS

This plug-in provides access to a number of "standard" functions from the C Standard Library, which programmers are used to from their C/C++ compilers (and other languages), but which are not available in NSIS by default. In order to keep the plug-in size as small as possible (~15 KB) and for maximum compatibility, the Visual C++ Run-Time v6.0 (MSVCRT.DLL), which is included with all versions of Windows (since Windows 2000), is used - instead of linking the Visual C++ Run-Time library into the plug-in DLL.

Many additional functions, not directly related to the C Standard Library, have sneaked in over the years. For example, this plug-in provides a wrapper for the SHFileOperation function. Moreover it provides a method for launching programs in a non-elevated way (user context) from an elevated installer (admin mode) on UAC-enabled systems (Vista and later) - see below for details! Last but not least, a version of ExecShell with "wait for process termination" feature (based on ShellExecuteEx) as well as a function to invoke "shell verbs" (e.g. for pinning items to the Taskbar in Windows 7) are provided. Overall I use this plug-in as my "Swiss army Army knife" for all the small things I needed in my NSIS-based installers but NSIS didn't provide out-of-the-box.

ANSI and Unicode builds available. Support operating systems: Windows 2000 and later.

Table of Contents:

Available Functions
Installation
General Usage
Time Functions
Pseudorandom Number Generator (PRNG)
String Functions
Shell File Operation
ExecShellAsUser
ExecShellWait
GetParameter / GetAllParameters
InvokeShellVerb
GetRealOSVersion / GetRealOSName / VerifyOSVersion
Debugging Functions
Acknowledgment
License
Download and Sources

Available Functions

The following functions

!define StdUtils.Time !define StdUtils.GetMinutes !define StdUtils.GetHours !define StdUtils.GetDays !define StdUtils.Rand !define StdUtils.RandMax !define StdUtils.RandMinMax !define StdUtils.RandList !define StdUtils.FormatStr !define StdUtils.FormatStr2 !define StdUtils.FormatStr3 !define StdUtils.ScanStr !define StdUtils.ScanStr2 !define StdUtils.ScanStr3 !define StdUtils.TrimStr !define StdUtils.TrimStrLeft !define StdUtils.TrimStrRight !define StdUtils.RevStr !define StdUtils.SHFileMove !define StdUtils.SHFileCopy !define StdUtils.ExecShellAsUser !define StdUtils.InvokeShellVerb !define StdUtils.ExecShellWaitEx !define StdUtils.WaitForProcEx !define StdUtils.GetParameter !define StdUtils.GetAllParameters !define StdUtils.GetRealOSVersion !define StdUtils.GetRealOSName !define StdUtils.VerifyOSVersion !define StdUtils.GetLibVersion !define StdUtils.SetVerbose

Please see the are provided by the StdUtils plug-in: #time(), as in C standard library #GetSystemTimeAsFileTime(), returns the number of minutes #GetSystemTimeAsFileTime(), returns the number of hours #GetSystemTimeAsFileTime(), returns the number of days #rand(), as in C standard library #rand(), as in C standard library, with maximum value #rand(), as in C standard library, with minimum/maximum value #rand(), as in C standard library, with list support #sprintf(), as in C standard library, one '%d' placeholder #sprintf(), as in C standard library, two '%d' placeholders #sprintf(), as in C standard library, three '%d' placeholders #sscanf(), as in C standard library, one '%d' placeholder #sscanf(), as in C standard library, two '%d' placeholders #sscanf(), as in C standard library, three '%d' placeholders #Remove whitspaces from string, left and right #Remove whitspaces from string, left side only #Remove whitspaces from string, right side only #Reverse a string, e.g. "reverse me" <-> "em esrever" #SHFileOperation(), using the FO_MOVE operation #SHFileOperation(), using the FO_COPY operation #ShellExecute() as NON-elevated user from elevated installer #Invokes a "shell verb", e.g. for pinning items to the taskbar #ShellExecuteEx(), returns the handle of the new process #WaitForSingleObject(), e.g. to wait for a running process #Get the value of a specific command-line option #Get complete command-line, but without executable name #Get the *real* Windows version number, even on Windows 8.1+ #Get the *real* Windows version, as a "friendly" name #Compare the *real* operating system to an expected version #Get the current StdUtils library version (for debugging) #Enable or disable "verbose" mode (for debugging)

descriptions below for details on the individual functions!

Installation

Depending on whether you are using the Unicode or ANSI (non-Unicode) variant of NSIS (we highly recommend using the Unicode variant!), you must copy either StdUtils\Plugins\Release_Unicode\StdUtils.dll or StdUtils\Plugins\Release_ANSI\StdUtils.dll into the Plugins sub-directory inside your NSIS installation directory. Also, in both cases, you must copy StdUtils\Include\StdUtils.nsh into the Include sub-directory inside your NSIS installation directory. That's it!

General Usage

In order to use the StdUtils plug-in in your script, simply include StdUtils.nsh and then use the pre-defined ${StdUtils.FunctionName} macros like this:

!include 'StdUtils.nsh'

Section
	${StdUtils.Rand} $1
	DetailPrint "Random number obtained via StdUtils::Rand is: $1"
SectionEnd

Note: We highly recommend to not call the plug-in functions directly. Instead, use the pre-defind macros, which ensures that the plug-in functions are used in the "proper" way.

For more details, please have a look at the example scripts located in the StdUtils\Examples\StdUtils directory!

Time Functions

${StdUtils.Time} user_var(output)

Returns the number of seconds that have elapsed since 00:00, Jan 1, 1970 (UTC), also known as "Unix time", just like the time() function:

!include 'StdUtils.nsh'

RequestExecutionLevel user
ShowInstDetails show

Section
	${StdUtils.Time} $1
	DetailPrint "Time: $1"
	Sleep 500
	${StdUtils.Time} $1
	DetailPrint "Time: $1"
	Sleep 500
	${StdUtils.Time} $1
	DetailPrint "Time: $1"
SectionEnd

${StdUtils.GetMinutes} user_var(output) ${StdUtils.GetHours} user_var(output) ${StdUtils.GetDays} user_var(output)

Retrieves the current system date and time, using the GetSystemTimeAsFileTime() function. Returns the number of minutes, hours or days since 00:00, January 1, 1601 (UTC).

!include 'StdUtils.nsh'

RequestExecutionLevel user
ShowInstDetails show

Section
	${StdUtils.GetMinutes} $1
	DetailPrint "UTC time in minutes: $1"
	${StdUtils.GetHours} $1
	DetailPrint "UTC time in hours: $1"
	${StdUtils.GetDays} $1
	DetailPrint "UTC time in days: $1"
SectionEnd

Pseudorandom Number Generator (PRNG)

${StdUtils.Rand} user_var(output) ${StdUtils.RandMax} user_var(output) max ${StdUtils.RandMinMax} user_var(output) min max

Returns a pseudo-random integral number, similar to the rand() function, but without the need to call srand(). Optionally the minimum and/or maximum value can be specified, so a random number in the min to max range will be returned. If no minimum is specified, the minimum defaults to zero. And if no maximum is specified, the maximum defaults to INT_MAX. Note that this function will use RtlGenRandom(), where possible; otherwise it falls back to a method based on rand(). In the latter case, srand() will be initialized with a suitable seed automatically.

Section
	${StdUtils.Rand} $1
	DetailPrint "Random: $1"
	${StdUtils.Rand} $1
	DetailPrint "Random: $1"
	${StdUtils.Rand} $1
	DetailPrint "Random: $1"
	${StdUtils.Rand} $1
	DetailPrint "Random: $1"
	${StdUtils.Rand} $1
	DetailPrint "Random: $1"
	${StdUtils.Rand} $1
	DetailPrint "Random: $1"
SectionEnd

Section
	${StdUtils.RandMax} $1 42
	DetailPrint "Random Max: $1"
	${StdUtils.RandMax} $1 42
	DetailPrint "Random Max: $1"
	${StdUtils.RandMax} $1 42
	DetailPrint "Random Max: $1"
	${StdUtils.RandMax} $1 42
	DetailPrint "Random Max: $1"
	${StdUtils.RandMax} $1 42
	DetailPrint "Random Max: $1"
	${StdUtils.RandMax} $1 42
	DetailPrint "Random Max: $1"
SectionEnd

Section
	${StdUtils.RandMinMax} $1 -4 -2
	DetailPrint "Random Min/Max: $1"
	${StdUtils.RandMinMax} $1 -4 -2
	DetailPrint "Random Min/Max: $1"
	${StdUtils.RandMinMax} $1 -4 -2
	DetailPrint "Random Min/Max: $1"
	${StdUtils.RandMinMax} $1 -4 -2
	DetailPrint "Random Min/Max: $1"
	${StdUtils.RandMinMax} $1 -4 -2
	DetailPrint "Random Min/Max: $1"
	${StdUtils.RandMinMax} $1 20 21
	DetailPrint "Random Min/Max: $1"
SectionEnd

${StdUtils.RandList} count max

Pushes a list of pseudo-random numbers onto the stack. The string "EOL" is pushed beforehand and thus will indicate the end of the list when popping the numbers off the stack. The count of the random numbers and the max value can be specified; the minimum value is zero.

Section
	${StdUtils.RandList} 50 100
	Pop $1
	StrCmp $1 EOL +3
	DetailPrint "RandList: $1"
	Goto -3
SectionEnd

String Functions

${StdUtils.FormatStr} user_var(output) format_str val1 ${StdUtils.FormatStr2} user_var(output) format_str val1 val2 ${StdUtils.FormatStr3} user_var(output) format_str val1 val2 val3

Returns a formatted string, similar to the sprintf() function. Only the %d placeholder is currently supported. There are versions for one, two and three placeholders:

Section
	${StdUtils.FormatStr} $1 "Hello World is %05d woha!" 89
	DetailPrint "FormatStr: $1"
	${StdUtils.FormatStr2} $1 "Hello World is %05d and %05d woha!" 89 384
	DetailPrint "FormatStr: $1"
	${StdUtils.FormatStr3} $1 "Hello World is %05d and %05d or even %05d woha!" 89 384 2384
	DetailPrint "FormatStr: $1"
	${StdUtils.FormatStr} $1 "Hello World is %09000d." 89
	DetailPrint "FormatStr: $1"
SectionEnd

${StdUtils.ScanStr} user_var(output) format_str input default ${StdUtils.ScanStr2} user_var(output1) user_var(output2) format_str input default1 default2 ${StdUtils.ScanStr3} user_var(output1) user_var(output2) user_var(output3) format_str input default1 default2 default3

Parses input from a string according to a format specification similar to the sscanf() function. Only the %d placeholder is currently supported. There are versions for one, two and three placeholders:

Section
	${StdUtils.ScanStr} $0 "Der Test sagt %d ist toll!" "Der Test sagt 571 ist toll!" 42
	DetailPrint "ScanStr: $0"
	${StdUtils.ScanStr} $0 "Der Hund sagt %d ist toll!" "Der Test sagt 571 ist toll!" 42
	DetailPrint "ScanStr: $0"
SectionEnd

Section
	${StdUtils.ScanStr2} $0 $1 "Der Test sagt %d sowie %d ist toll!" "Der Test sagt 571 sowie 831 ist toll!" 42 43
	DetailPrint "ScanStr2: $0, $1"
	${StdUtils.ScanStr2} $0 $1 "Der Test sagt %d sowie %d ist toll!" "Der Test sagt 571 horch 831 ist toll!" 42 43
	DetailPrint "ScanStr2: $0, $1"
	${StdUtils.ScanStr2} $0 $1 "Der Test sagt %d sowie %d ist toll!" "Der Hund sagt 571 horch 831 ist toll!" 42 43
	DetailPrint "ScanStr2: $0, $1"
SectionEnd

Section
	${StdUtils.ScanStr3} $0 $1 $2 "Der Test sagt %d sowie %d ist toll! Und %d." "Der Test sagt 571 sowie 831 ist toll! Und 325" 42 43 44
	DetailPrint "ScanStr3: $0, $1, $2"
	${StdUtils.ScanStr3} $0 $1 $2 "Der Test sagt %d sowie %d ist toll! Und %d." "Der Test sagt 571 sowie 831 ist toll! OMG 325" 42 43 44
	DetailPrint "ScanStr3: $0, $1, $2"
	${StdUtils.ScanStr3} $0 $1 $2 "Der Test sagt %d sowie %d ist toll! Und %d." "Der Test sagt 571 horch 831 ist toll! OMG 325" 42 43 44
	DetailPrint "ScanStr3: $0, $1, $2"
	${StdUtils.ScanStr3} $0 $1 $2 "Der Test sagt %d sowie %d ist toll! Und %d." "Der Hund sagt 571 horch 831 ist toll! OMG 325" 42 43 44
	DetailPrint "ScanStr3: $0, $1, $2"
SectionEnd

${StdUtils.TrimStr} user_var(input/output) ${StdUtils.TrimStrLeft} user_var(input/output) ${StdUtils.TrimStrRight} user_var(input/output)

Trims a string by removing all leading and/or trailing whitspace (space, tabular, line feed, carriage return) characters in-place:

Section
	StrCpy $1 "        Some Text        "
	DetailPrint "String: '$1'"
	StrCpy $0 $1
	${StdUtils.TrimStr} $0
	DetailPrint "TrimStr: '$0'"
	StrCpy $0 $1
	${StdUtils.TrimStrLeft} $0
	DetailPrint "TrimStrLeft: '$0'"
	StrCpy $0 $1
	${StdUtils.TrimStrRight} $0
	DetailPrint "TrimStrRight: '$0'"
	
	StrCpy $1 "Some Text"
	DetailPrint "String: '$1'"
	StrCpy $0 $1
	${StdUtils.TrimStr} $0
	DetailPrint "TrimStr: '$0'"
	StrCpy $0 $1
	${StdUtils.TrimStrLeft} $0
	DetailPrint "TrimStrLeft: '$0'"
	StrCpy $0 $1
	${StdUtils.TrimStrRight} $0
	DetailPrint "TrimStrRight: '$0'"

	StrCpy $1 ""
	DetailPrint "String: '$1'"
	StrCpy $0 $1
	${StdUtils.TrimStr} $0
	DetailPrint "TrimStr: '$0'"
	StrCpy $0 $1
	${StdUtils.TrimStrLeft} $0
	DetailPrint "TrimStrLeft: '$0'"
	StrCpy $0 $1
	${StdUtils.TrimStrRight} $0
	DetailPrint "TrimStrRight: '$0'"
	
	StrCpy $1 "   "
	DetailPrint "String: '$1'"
	StrCpy $0 $1
	${StdUtils.TrimStr} $0
	DetailPrint "TrimStr: '$0'"
	StrCpy $0 $1
	${StdUtils.TrimStrLeft} $0
	DetailPrint "TrimStrLeft: '$0'"
	StrCpy $0 $1
	${StdUtils.TrimStrRight} $0
	DetailPrint "TrimStrRight: '$0'"

	StrCpy $1 "$\tFoobar$\r$\n"
	DetailPrint "String: '$1'"
	StrCpy $0 $1
	${StdUtils.TrimStr} $0
	DetailPrint "TrimStr: '$0'"
	StrCpy $0 $1
	${StdUtils.TrimStrLeft} $0
	DetailPrint "TrimStrLeft: '$0'"
	StrCpy $0 $1
	${StdUtils.TrimStrRight} $0
	DetailPrint "TrimStrRight: '$0'"
SectionEnd

${StdUtils.RevStr} user_var(input/output)

Reverses the character order of a specified string in-place. For example, it converts "reverse me" to "em esrever", or vice versa.

Section
	StrCpy $0 "ABC"
	DetailPrint "String: $0"
	${StdUtils.RevStr} $0
	DetailPrint "RevStr: $0"
	
	StrCpy $0 "ABCD"
	DetailPrint "String: $0"
	${StdUtils.RevStr} $0
	DetailPrint "RevStr: $0"

	StrCpy $0 "Just a very long text with no specific meaning at all!"
	DetailPrint "String: $0"
	${StdUtils.RevStr} $0
	DetailPrint "RevStr: $0"
SectionEnd

Shell File Operation

${StdUtils.SHFileMove} user_var(output) from to hwnd ${StdUtils.SHFileCopy} user_var(output) from to hwnd

Copies or moves a file system object (e.g. a file or a complete folder) from path from to path to, by using the SHFileOperation() function. The function requires a window handle hwnd and usually the NSIS variable $HWNDPARENT is used for this purpose.

Section
	InitPluginsDir
	SetOutPath "$PLUGINSDIR\TestDirA"
	File "${NSISDIR}\Contrib\Graphics\Checks\*.*"
	SetOutPath "$PLUGINSDIR\TestDirA\SubDir"
	File "${NSISDIR}\Contrib\Graphics\Header\*.*"
	CreateDirectory "$PLUGINSDIR\SubDirX"
	CreateDirectory "$PLUGINSDIR\SubDirY"
	
	${StdUtils.SHFileCopy} $0 "$PLUGINSDIR\TestDirA" "$PLUGINSDIR\SubDirX\TestDirB" $HWNDPARENT
	DetailPrint "SHFileCopy: $0"
	${StdUtils.SHFileMove} $0 "$PLUGINSDIR\TestDirA" "$PLUGINSDIR\SubDirY\TestDirC" $HWNDPARENT
	DetailPrint "SHFileMove: $0"
	ExecShell "explore" "$PLUGINSDIR"
SectionEnd

Section
	MessageBox MB_ICONINFORMATION "The next three operations are going to fail!$\nBut only one will be verbose..."

	${StdUtils.SHFileCopy} $0 "$PLUGINSDIR\TestDirXYZ" "$PLUGINSDIR\SubDirX\TestDirZ" $HWNDPARENT
	DetailPrint "SHFileCopy: $0"
	
	${StdUtils.SetVerbose} 1
	${StdUtils.SHFileCopy} $0 "$PLUGINSDIR\TestDirXYZ" "$PLUGINSDIR\SubDirX\TestDirZ" $HWNDPARENT
	DetailPrint "SHFileCopy: $0"
	
	${StdUtils.SetVerbose} 0
	${StdUtils.SHFileCopy} $0 "$PLUGINSDIR\TestDirXYZ" "$PLUGINSDIR\SubDirX\TestDirZ" $HWNDPARENT
	DetailPrint "SHFileCopy: $0"
SectionEnd

ExecShellAsUser

${StdUtils.ExecShellAsUser} user_var(output) file verb args

The ${StdUtils.ExecShellAsUser} function allows for launching a child process with normal user privileges (user level), directly from an elevated installer instance (admin level). This is in contrast to the built-in Exec, ExecWait and ExecShell instructions, which all cause the child process to be elevated too. Consequently, the ${StdUtils.ExecShellAsUser} function provides a simple and more lightweight alternative to the UAC plug-in. The function expects three arguments: The path to the file to be executed, the verb that shall be used to execute the file (e.g. "open") and the argument string args to be passed to the new process. The last two arguments are optional and can be specified as empty strings (""). If the function succeeded, then it returns either "ok" or "fallback". And if the function failed, then it returns either "einval", "timeout" or "error".

Please note that "einval" indicates that the function was called with invalid parameters and "timeout" indicates that the function encountered a deadlock. Furthermore, note that "ok" indicates that the process has been created using the IShellDispatch2 COM interface, which is the default behavior, because it allows the new process to not be elevated. Finally, note that "fallback" indicates that the normal ShellExecute() method has been used instead of the COM interface, which is the expected behavior on systems without UAC support (e.g. Windows XP or older).

!include 'StdUtils.nsh'
 
; make sure the installer will get elevated rights on UAC-enabled system (Vista+)
RequestExecutionLevel admin 
ShowInstDetails show
 
Section
	DetailPrint 'ExecShell: "$SYSDIR\mspaint.exe"'
	; this instance of MS Paint will be *elevated*, just like the installer!
	ExecShell "open" "$SYSDIR\mspaint.exe"
	MessageBox MB_TOPMOST "Close Paint and click 'OK' to continue..."
SectionEnd
 
Section
	DetailPrint 'ExecShellAsUser: "$SYSDIR\mspaint.exe"'
	Sleep 1000
	; now launch a *non-elevated* instance of MS Paint by using ExecShellAsUser
	${StdUtils.ExecShellAsUser} $0 "$SYSDIR\mspaint.exe" "open" ""
	; expected result is "ok" on UAC-enabled systems or "fallback" otherwise
	DetailPrint "Result: $0"
SectionEnd

ExecShellWait

${StdUtils.ExecShellWaitEx} user_var(output_1) user_var(output_2) file verb args ${StdUtils.WaitForProcEx} user_var(output) handle

The ${StdUtils.ExecShellWaitEx} function works like the built-in ExecShell command, except that you can wait for the process to terminate. The function expects three arguments: The path to the file to be executed, the verb that shall be used to execute the file (e.g. "open") and the arguments to be passed to the new process. The last two arguments are optional and can be specified as empty strings (""). Furthermore, the function returns two values: The first value is either "ok", "no_wait" or "error", while the second value provides additional info. "ok" indicates that the process was created successfully and can be waited for, "no_wait" indicates that we cannot wait for the process (because ShellExecuteEx did not create a new process, but passed the file/URL to a running instance) and "error" indicates that something went wrong.

If the first return value is "ok", the second return value contains the handle of the new process. If the first return value is "error", the second return value contains the Win32 error code. And if the first return value is "no_wait", the second return value is zero. Only if "ok" and a process handle were returned, you can call ${StdUtils.WaitForProcEx} in order to wait until the process has terminated. This means that you must always carefully check the first return value of ${StdUtils.ExecShellWaitEx} before you pass the second return value to ${StdUtils.WaitForProcEx}. The behavior of ${StdUtils.WaitForProcEx} is undefined if you pass something that isn't a valid process handle! If successfull, ${StdUtils.WaitForProcEx} returns the exit code of the process after it has terminated. The function returns "error" if something went wrong.

!include 'StdUtils.nsh'
 
RequestExecutionLevel user
ShowInstDetails show
 
Section
	DetailPrint 'ExecShellWait: "$SYSDIR\mspaint.exe"'
	Sleep 1000
	${StdUtils.ExecShellWaitEx} $0 $1 "$SYSDIR\mspaint.exe" "open" "" ;try to launch the process

	DetailPrint "Result: $0 -> $1" ;returns "ok", "no_wait" or "error".
	StrCmp $0 "error" ExecFailed ;check if process failed to create
	StrCmp $0 "no_wait" WaitNotPossible ;check if process can be waited for - always check this!
	StrCmp $0 "ok" WaitForProc ;make sure process was created successfully
	Abort
	
	WaitForProc:
	DetailPrint "Waiting for process. ZZZzzzZZZzzz..."
	${StdUtils.WaitForProcEx} $2 $1
	DetailPrint "Process just terminated (exit code: $2)"
	Goto WaitDone
	
	ExecFailed:
	DetailPrint "Failed to create process (error code: $1)"
	Goto WaitDone

	WaitNotPossible:
	DetailPrint "Can not wait for process."
	Goto WaitDone
	
	WaitDone:
SectionEnd

GetParameter / GetAllParameters

${StdUtils.GetParameter} user_var(output) name default ${StdUtils.GetAllParameters} user_var(output) truncate

With ${StdUtils.GetParameter} you can check for the presence of a specific command-line parameter. If the parameter was specified with a (non-empty) value, then the parameter's value is return. If the parameter was specified without a value, then an empty string is return. If the parameter has not been specified, then the default value is returned.

Parameters can be passed to the installer like this:

Installer.exe /Foobar
Installer.exe /Foobar=SomeValue
Installer.exe "/Foobar=Some Value With Whitespaces"

Additionally you can use ${StdUtils.GetAllParameters} to get the complete command-line string, but without the executable name. This is useful to forward all command-line parameters to an encapsulated installer, for example. The truncate parameters controls the behavior of this function, if the command-line is too long to fit into an NSIS string. With the parameter set to 1, the command-line will be truncated to a length of NSIS_MAX_STRLEN (usually 1024 or 8192) characters, if necessary. With the parameter set to 0, the command-line will not be truncated. Instead the value "too_long" is returned, if the command-line doesn't fit into an NSIS string.

!include 'StdUtils.nsh'
 
RequestExecutionLevel user
ShowInstDetails show
 
Section
	${StdUtils.GetParameter} $R0 "Foobar" "<N/A>"
 
	StrCmp "$R0" "<N/A>" 0 +3
	DetailPrint "Parameter /Foobar is *not* specified!"
	Goto Finished
 
	StrCmp "$R0" "" 0 +3 ;'Installer.exe [...] /Foobar'
	DetailPrint "Parameter /Foobar specified without a value." 
	Goto Finished
 
	;'Installer.exe /Foobar=Foo' or 'Installer.exe "/Foobar=Foo Bar"'
	${StdUtils.TrimStr} $R0
	DetailPrint "Value of parameter /Foobar is: '$R0'"
 
	Finished:
	${StdUtils.GetAllParameters} $R0 0
	DetailPrint "Complete command-line: '$R0'"
	${StdUtils.GetAllParameters} $R0 1
	DetailPrint "Truncated command-line: '$R0'"
SectionEnd

InvokeShellVerb

${StdUtils.InvokeShellVerb} user_var(output) path file verb_id

The ${StdUtils.InvokeShellVerb} function can be used to invoke a so-called "Shell Verb" on an arbitary item. The most common use for this is pinning (or unpinning) an item to (from) the Taskbar or Startmenu on Windows 7. Despite the fact the Microsoft claimes that there is no API for this, the API does exist and is commonly used (e.g. Firefox' insatller makes use of it too). The function expects three arguments: The directory where the item (e.g. executable file) is located, the name of the item (e.g. executable file) and the resource id of the verbt o be invoked. We need the resource id of the verb, because the verb itself is language-specific, but we certainly do no want to adjust the installer for each system langauge. Resource id's are langauge-independant and you can use the pre-defined constants ${StdUtils.Const.ISV_PinToTaskbar}, ${StdUtils.Const.ISV_UnpinFromTaskbar}, ${StdUtils.Const.ISV_PinToStartmenu} or ${StdUtils.Const.ISV_UnpinFromStartmenu} for convenience. Note that while this function works on Windows 7 (and later) only, it still is perfectly safe to call on older versions of Windows. If the function succeeded, then it returns "ok"; if the function is called with invalid parameters, then it returns "einval"; if the requested verb was not found for the specified item, then "not_found" will be returned (even if the specified item iteself was found!); if this function is used on Windows versions prior to Windows 7 (e.g. Vista or XP), then it will return "unsupported"; and if the function failed for another reason (e.g. file not found or invalid verb_id), then it will return "error".

Hint: If you are getting the "not_found" error for a verb that is supposed to exists, then it's probably because the desired action isn't currently available for the item (e.g. it could be that you are trying to pin an item that already is pinned).

!include 'StdUtils.nsh'

RequestExecutionLevel user ;no elevation needed for this test
ShowInstDetails show

Section
	IfFileExists "$SYSDIR\mspaint.exe" +3
	MessageBox MB_ICONSTOP 'File does not exist:$\n"$SYSDIR\mspaint.exe"$\n$\nExample cannot run!'
	Quit
SectionEnd

Section
	DetailPrint "Going to pin MSPaint..."
	${StdUtils.InvokeShellVerb} $0 "$SYSDIR" "mspaint.exe" ${StdUtils.Const.ISV_PinToTaskbar}
	DetailPrint "Result: $0"

	StrCmp "$0" "ok" 0 +3
	MessageBox MB_TOPMOST "Paint should have been pinned to Taskbar now!"
	Goto +2
	MessageBox MB_TOPMOST "Failed to pin, see log for details!"
SectionEnd

Section
	DetailPrint "Going to un-pin MSPaint..."
	${StdUtils.InvokeShellVerb} $0 "$SYSDIR" "mspaint.exe" ${StdUtils.Const.ISV_UnpinFromTaskbar}
	DetailPrint "Result: $0"
	
	StrCmp "$0" "ok" 0 +3
	MessageBox MB_TOPMOST "Paint should have been un-pinned from Taskbar now!"
	Goto +2
	MessageBox MB_TOPMOST "Failed to un-pin, see log for details!"
SectionEnd

GetRealOSVersion / GetRealOSName / VerifyOSVersion

${StdUtils.GetRealOSVersion} user_var(out_major) user_var(out_minor) user_var(out_spack)

The ${StdUtils.GetRealOSVersion} function returns the real Windows NT version installed on the computer. Note that starting with Windows 8.1 (Windows NT 6.3), Microsoft has broken the GetVersion() and GetVersionEx() functions! This has the consequence that Windows 8.1 (and all future versions?) will now identify itself as Windows 8.0! Various workarounds exist, such as adding certain GUID's to the application Manifest, which is only a temporary solution, or trying to read the Windows version from the Registry, which is unreliable. At the same time, the ${StdUtils.GetRealOSVersion} function reveals the actual Windows version on Windows 8.1 (and later), regardless of the application Manifest. Furthermore, it will continue to work correctly in future Windows versions - provided that Microsoft doesn't break more Win32 API functions. Finally, this function still returns the correct Windows version, when the installer runs in "comaptibility mode". The function will return the major and minor Windows NT version (e.g. "6.3" on Windows 8.1) plus the Service Pack spack. It returns "error", if something went wrong.

Note: This function uses an iterative approach: It first calls GetVersionEx() to get the "fake" Windows version. Then it tries to increase that value, step by step, using the VerifyVersionInfo() function - until the "real" version has been revealed.

!include 'StdUtils.nsh'

RequestExecutionLevel user
ShowInstDetails show

Section
	${StdUtils.GetRealOSVersion} $1 $2 $3
	DetailPrint "Real Windows NT Version: $1,$2 (Service Pack: $3)"
SectionEnd

${StdUtils.GetRealOSBuildNo} user_var(out)

The ${StdUtils.GetRealOSBuildNo} function returns the real Windows NT build number installed on the computer. The function will return the Windows NT build number (e.g. "7600" on Windows 7 RTM). It returns "error", if something went wrong.

Note: This function uses the same algorithm as ${StdUtils.GetRealOSVersion} to determine the real Windows build number, so it will give the expected result on Windows 8.1 and later.

!include 'StdUtils.nsh'

RequestExecutionLevel user
ShowInstDetails show

Section
	${StdUtils.GetRealOSBuildNo} $1
	DetailPrint "Real Windows NT Build No.: $1"
SectionEnd

${StdUtils.GetRealOSName} user_var(out)

${StdUtils.GetRealOSName} is a convenience function that returns the installed Windows version as a friendly name string. Currently the return value can be "winnt" (4.0), "win2k" (5.0), "winxp" (5.1), "xpx64" (5.2), "vista" (6.0), "win70" (6.1), "win80" (6.2) or "win81" (6.3). If an unknown Windows version is encountered, e.g. some future version that is not yet supported, the function will return "unknown". And it will return "error", if something went wrong.

Note: This function uses the same algorithm as ${StdUtils.GetRealOSVersion} to determine the real Windows version that will be converted to a friendly name, so it will give the expected result on Windows 8.1 and later.

!include 'StdUtils.nsh'

RequestExecutionLevel user
ShowInstDetails show

Section
	${StdUtils.GetRealOSName} $1
	DetailPrint "Real Windows NT Friendly Name: $1"
SectionEnd

${StdUtils.VerifyOSVersion} user_var(out) expected_major expected_minor expected_spack

${StdUtils.VerifyOSVersion} is a convenience function to compare the installed Windows version against some expected one. The expected Windows NT version (e.g. "6.2" for Windows 8.0) is specified by the expected_major, expected_minor and expected_spack parameters. The function returns "ok" when the installed Windows version matches the expected one exactly; it returns "older" when the installed version is older than expected; it returns "newer" when the installed version is newer than expected; and it retruns "error" if something went wrong.

Note: This function uses the same algorithm as ${StdUtils.GetRealOSVersion} to determine the real Windows version that will be compared to the expected version, so it will give the expected result on Windows 8.1 and later.

!include 'StdUtils.nsh'

RequestExecutionLevel user
ShowInstDetails show

Section
	${StdUtils.VerifyOSVersion} $1 5 1 0
	DetailPrint "Check for Windows XP (RTM): $1"

	${StdUtils.VerifyOSVersion} $1 5 1 3
	DetailPrint "Check for Windows XP (SP3): $1"

	${StdUtils.VerifyOSVersion} $1 6 1 0
	DetailPrint "Check for Windows 7 (RTM): $1"

	${StdUtils.VerifyOSVersion} $1 6 1 1
	DetailPrint "Check for Windows 7 (SP1): $1"

	${StdUtils.VerifyOSVersion} $1 6 2 0
	DetailPrint "Check for Windows 8.0: $1"

	${StdUtils.VerifyOSVersion} $1 6 3 0
	DetailPrint "Check for Windows 8.1: $1"
SectionEnd

${StdUtils.VerifyOSBuildNo} user_var(out) expected_build

${StdUtils.VerifyOSBuildNo} is a convenience function to compare the installed Windows version against some expected version. The expected Windows NT build number is specified by expected_build (e.g. "7600" on Windows 7 RTM). The function will retrun "ok" when the installed Windows build matches the expected one exactly; it returns "older" when the installed build is older than the expected one; it returns "newer" when the installed version is newer than the expected one; and it retruns "error" if something went wrong.

Note: This function uses the same algorithm as ${StdUtils.GetRealOSVersion} to determine the real Windows build number that will be compared to the expected build number, so it will give the expected result on Windows 8.1 and later.

!include 'StdUtils.nsh'

RequestExecutionLevel user
ShowInstDetails show

Section
	${StdUtils.VerifyOSBuildNo} $1 2600
	DetailPrint "Check for Build #2600, Windows XP: $1"

	${StdUtils.VerifyOSBuildNo} $1 7600
	DetailPrint "Check for Build #7600, Windows 7 (RTM): $1"

	${StdUtils.VerifyOSBuildNo} $1 7601
	DetailPrint "Check for Build #7601, Windows 7 (SP1): $1"

	${StdUtils.VerifyOSBuildNo} $1 9600
	DetailPrint "Check for Build #9600, Windows 8.1: $1"
SectionEnd

List of Windows NT versions:

Marketing Name	NT Version	Friendly Name	Build No.
Windows NT 4.0	`4.0`	`"winnt"`	`1381`
Windows 2000	`5.0`	`"win2k"`	`2195`
Windows XP	`5.1`	`"winxp"`	`2600`
Windows XP - x64 Edition	`5.2`	`"xpx64"`	`3790`
Windows Vista	`6.0`	`"vista"`	`6000` - `6002`
Windows 7	`6.1`	`"win70"`	`7600` - `7601`
Windows 8	`6.2`	`"win80"`	`9200`
Windows 8.1	`6.3`	`"win81"`	`9600`

Debugging Functions

${StdUtils.GetLibVersion} user_var(out_ver) user_var(out_tst)

The ${StdUtils.GetLibVersion} function returns the version of the StdUtils library that is being used. The version string (in the "w.x.y.z" format) is returned in out_ver; the build time-stamp is returned in out_tst.

${StdUtils.SetVerbose} on

The ${StdUtils.SetVerbose} function enables or disables verbose error messages. Set on to '1' to enable verbose outputs or set it to '0' to disable verbose outputs. Verbose outputs are disabled by default. Do not enabled them for release versions of your installer!

Acknowledgment

The StdUtils plug-in for NSIS was created by LoRd_MuldeR <mulder2@gmx.de>.

This plug-in has partly been inspired by the ShellExecAsUser plug-in, created by installer32. This plug-in has partly been inspired by the InvokeShellVerb plug-in, created by Robert Strong.

Special thanks to Afrow UK for providing his excellent plug-ins (his code helped me to understand how to write NSIS plug-ins).

License

StdUtils plug-in for NSIS
Copyright (C) 2004-2014 LoRd_MuldeR <mulder2@gmx.de>

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.

The author of the StdUtils plug-in Library for NSIS adds the following clarification to the GNU Lesser General Public License version 2.1: Installer programs (executables) created with NSIS (Nullsoft Scriptable Install System) that make use of the StdUtils plug-in Library (strictly through the NSIS plug-in interface) and that contain/distribute verbatim copies of the StdUtils plug-in Library are considered a "work that uses the Library"; they do not represent a derivative of the Library.

Please see http://www.gnu.org/licenses/lgpl-2.1.html for details!

Download and Sources

The source codes for the StdUtils plug-in are available from the code repository at:

You can download pre-compiled binaries (i.e. ready-to-use DLL files) of the plug-in here:
https://github.com/lordmulder/stdutils/releases/latest

http://muldersoft.com/ | http://sourceforge.net/projects/muldersoft/ | http://nsis.sourceforge.net/Category:Plugins

Earth Heals Herself