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.ValidFileName    #Test whether string is a valid file name - no paths allowed
!define StdUtils.ValidPathSpec    #Test whether string is a valid full(!) path specification
!define StdUtils.SHFileMove       #SHFileOperation(), using the FO_MOVE operation
!define StdUtils.SHFileCopy       #SHFileOperation(), using the FO_COPY operation
!define StdUtils.AppendToFile     #Append contents of an existing file to another file
!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.GetOSEdition     #Get the Windows edition, i.e. "workstation" or "server"
!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.HashText         #Compute hash from text string (CRC32, MD5, SHA1/2/3, BLAKE2)
!define StdUtils.HashFile         #Compute hash from file (CRC32, MD5, SHA1/2/3, BLAKE2)
!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 online documentation, a copy of which is also included in the download package!

(The "offline" documentation can be found at "Docs\StdUtils\StdUtils.html" inside the ZIP package)

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

Source Code (Git)

• https://github.com/lordmulder/stdutils.git (Browse)
• https://gitlab.com/stdutils-plug-in-for-nsis/stdutils-plug-in-for-nsis.git (Browse)
• https://bitbucket.org/lord_mulder/stdutils.git (Browse)

Outdated Versions

Please do not use nowadays!

• StdUtils.2013-02-21.zip (128 KB)
• StdUtils.2012-10-28.zip (121 KB)
• StdUtils.2011-10-18.zip (105 KB)

Support

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

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