StdUtils plug-in

Author: LoRd MuldeR (talk, contrib)

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.

Available Functions

The StdUtils plug-in makes the following functions available in NSIS:

!define StdUtils.Time             #time(), as in C standard library
!define StdUtils.GetMinutes       #GetSystemTimeAsFileTime(), returns the number of minutes
!define StdUtils.GetHours         #GetSystemTimeAsFileTime(), returns the number of hours
!define StdUtils.GetDays          #GetSystemTimeAsFileTime(), returns the number of days
!define StdUtils.Rand             #rand(), as in C standard library
!define StdUtils.RandMax          #rand(), as in C standard library, with maximum value
!define StdUtils.RandMinMax       #rand(), as in C standard library, with minimum/maximum value
!define StdUtils.RandList         #rand(), as in C standard library, with list support
!define StdUtils.FormatStr        #sprintf(), as in C standard library, one '%d' placeholder
!define StdUtils.FormatStr2       #sprintf(), as in C standard library, two '%d' placeholders
!define StdUtils.FormatStr3       #sprintf(), as in C standard library, three '%d' placeholders
!define StdUtils.ScanStr          #sscanf(), as in C standard library, one '%d' placeholder
!define StdUtils.ScanStr2         #sscanf(), as in C standard library, two '%d' placeholders
!define StdUtils.ScanStr3         #sscanf(), as in C standard library, three '%d' placeholders
!define StdUtils.TrimStr          #Remove whitspaces from string, left and right
!define StdUtils.TrimStrLeft      #Remove whitspaces from string, left side only
!define StdUtils.TrimStrRight     #Remove whitspaces from string, right side only
!define StdUtils.RevStr           #Reverse a string, e.g. "reverse me" <-> "em esrever"
!define StdUtils.SHFileMove       #SHFileOperation(), using the FO_MOVE operation
!define StdUtils.SHFileCopy       #SHFileOperation(), using the FO_COPY operation
!define StdUtils.ExecShellAsUser  #ShellExecute() as NON-elevated user from elevated installer
!define StdUtils.InvokeShellVerb  #Invokes a "shell verb", e.g. for pinning items to the taskbar
!define StdUtils.ExecShellWaitEx  #ShellExecuteEx(), returns the handle of the new process
!define StdUtils.WaitForProcEx    #WaitForSingleObject(), e.g. to wait for a running process
!define StdUtils.GetParameter     #Get the value of a specific command-line option
!define StdUtils.GetAllParameters #Get complete command-line, but without executable name
!define StdUtils.GetRealOSVersion #Get the *real* Windows version number, even on Windows 8.1+
!define StdUtils.GetRealOSBuildNo #Get the *real* Windows build number, even on Windows 8.1+
!define StdUtils.GetRealOSName    #Get the *real* Windows version, as a "friendly" name
!define StdUtils.VerifyOSVersion  #Compare *real* operating system to an expected version number
!define StdUtils.VerifyOSBuildNo  #Compare *real* operating system to an expected build number
!define StdUtils.GetLibVersion    #Get the current StdUtils library version (for debugging)
!define StdUtils.SetVerbose       #Enable or disable "verbose" mode (for debugging)

For details please see the manual "Docs\StdUtils\StdUtils.html" included in the download!

(Alternatively, you can have a look at the online documentation)

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 from StdUtils.nsh, which will ensure 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 "Examples\StdUtils" directory of the download!

Acknowledgment

• The StdUtils plug-in for NSIS was created by LoRd_MuldeR.
• 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.

License

StdUtils plug-in for NSIS
Copyright (C) 2004-2013 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 the GNU Lesser General Public License (version 2.1) for details!

Download

Download latest version from GitHub:
https://github.com/lordmulder/stdutils/releases/latest

Previous Versions

Download previous version:
StdUtils.2013-02-21.zip (128 KB)

Download previous version:
StdUtils.2012-10-28.zip (121 KB)

Download historic version:
StdUtils.2011-10-18.zip (105 KB)

Source Code

Public Git Repository:

• https://github.com/lordmulder/stdutils.git (Browse)
• https://bitbucket.org/lord_mulder/stdutils.git (Browse)

Support

Discussion thread at NSIS Forums:
http://forums.winamp.com/showthread.php?t=335435

E-Mail:
MuldeR2 (at) gmx (dot) de