StdUtils plug-in
| Author: LoRd MuldeR (talk, contrib) |
Swiss Army Knife for NSIS – This plug-in provides access to a number of "standard" functions from the C Standard Library, which programmers are used to from C/C++ and other "high level" languages, but which are not normally available in NSIS. In order to keep the plug-in size as small as possible and for maximum compatibility, the Visual C++ Runtime v6.0 "MSVCRT.DLL" is used, which is an integral part of all versions of Windows (since Windows 2000). This means that the C++ Runtime neither needs to be shipped as a separate DLL nor does it need to be linked statically into the plug-in.
Many additional functions, not directly related to the C Standard Library, have been added over the years: For example, this plug-in provides a number convenience functions to deal with strings, such as trimming whitespaces or validating a given file name. There also are some functions to conveniently access the command-line parameters that have been passed to the installer. Furthermore, there is a wrapper for the SHFileOperation function, which can be used to copy or move files using the Windows Shell, as well as a function to efficiently append the contents of one file to another file. Moreover, the plug-in provides a method for launching programs in a non-elevated way (aka "user mode") from an installer that is running in elevated context (aka "admin mode"). In addition to that, there is a set of functions that can be used to detect the real Windows version that the installer is running on, which still work correctly/reliably on Windows 8.1 (and later) where Microsoft has broken the GetVersionEx() system function. And, as if this wasn't enough, the plug-in can compute the cryptographic hash of a given file or text message, using various state-of-the-art hash functions, including SHA-{1,2,3}. Last but not least, the plug-in provides a variant of ExecShell with "wait for process termination" feature, based on ShellExecuteEx, as well as a function for invoking "shell verbs" – useful for programmatically pinning shortcuts to the Taskbar.
Overall I use this plug-in as my "Swiss Army Knife" for all the small things I needed in my NSIS-based installers but that NSIS didn't provide out-of-the-box. ANSI and Unicode builds are provided. Supports all Windows versions, starting with Windows XP.
Available Functions
For details please refer to the online documentation, a copy of which is also included in the download package!
(The documentation can be found at "Docs\StdUtils\StdUtils.html" inside the ZIP package)
Overview
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.RandBytes #Generates random bytes, returned as Base64-encoded string !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.ValidDomainName #Test whether string is a valid host name or domain name !define StdUtils.StrToUtf8 #Convert string from Unicode (UTF-16) or ANSI to UTF-8 bytes !define StdUtils.StrFromUtf8 #Convert string from UTF-8 bytes to Unicode (UTF-16) or ANSI !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.TestParameter #Test whether a specific command-line option has been set !define StdUtils.ParameterCnt #Get number of command-line tokens, similar to argc in main() !define StdUtils.ParameterStr #Get the n-th command-line token, similar to argv[i] in main() !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.GetOSReleaseId #Get the Windows release identifier (on Windows 10) !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.NormalizePath #Simplifies the path to produce a direct, well-formed path !define StdUtils.GetParentPath #Get parent path by removing the last component from the path !define StdUtils.SplitPath #Split the components of the given path !define StdUtils.GetDrivePart #Get drive component of path !define StdUtils.GetDirectoryPart #Get directory component of path !define StdUtils.GetFileNamePart #Get file name component of path !define StdUtils.GetExtensionPart #Get file extension component of path !define StdUtils.TimerCreate #Create a new event-timer that will be triggered periodically !define StdUtils.TimerDestroy #Destroy a running timer created with TimerCreate() !define StdUtils.ProtectStr #Protect a given String using Windows' DPAPI !define StdUtils.UnprotectStr #Unprotect a string that was protected via ProtectStr() !define StdUtils.GetLibVersion #Get the current StdUtils library version (for debugging) !define StdUtils.SetVerbose #Enable or disable "verbose" mode (for debugging)
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-2015 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 the latest version from GitHub:
https://github.com/lordmulder/stdutils/releases/latest
Other official download mirrors
- http://sourceforge.net/projects/muldersoft/files/StdUtils-Plugin%20%28NSIS%29/
- https://bitbucket.org/muldersoft/stdutils/downloads
- https://www.assembla.com/spaces/stdutils/documents
