StdUtils plug-in: Difference between revisions

From NSIS Wiki
Jump to navigationJump to search
m (link to proper en.wiki page)
 
(27 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{PageAuthor|LoRd MuldeR}}
{{PageAuthor|LoRd MuldeR}}
[[Category:Plugins]]


This plug-in provides access to a number of "standard" functions from the [http://en.wikipedia.org/wiki/C_standard_library 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.
<b>Swiss Army Knife for NSIS</b> &ndash; This plug-in provides access to a number of "standard" functions from the [[:wikipedia:C Standard Library|C Standard Library]], which programmers are used to from C/C++ and other "high level" languages, but which are <i>not</i> 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 <i>statically</i> into the plug-in.


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 [http://msdn.microsoft.com/en-us/library/windows/desktop/bb762164%28v=vs.85%29.aspx 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 [http://msdn.microsoft.com/en-us/library/windows/desktop/bb762154%28v=vs.85%29.aspx 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.
Many additional functions, <i>not</i> 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 <i>strings</i>, such as trimming whitespaces or validating a given file name. There also are some functions to conveniently access the <i>command-line parameters</i> that have been passed to the installer. Furthermore, there is a wrapper for the [http://msdn.microsoft.com/en-us/library/windows/desktop/bb762164%28v=vs.85%29.aspx SHFileOperation] function, which can be used to <i>copy or move files</i> using the Windows Shell, as well as a function to efficiently <i>append</i> the contents of one file to another file. Moreover, the plug-in provides a method for launching programs in a <i>non-elevated</i> way (aka "user mode") from an installer that is running in <i>elevated</i> context (aka "admin mode"). In addition to that, there is a set of functions that can be used to detect the <i>real</i> Windows version that the installer is running on, which still work correctly/reliably on Windows 8.1 (and later) where Microsoft has <i style="color:darkred">broken</i> the GetVersionEx() system function. And, as if this wasn't enough, the plug-in can compute the <i>cryptographic hash</i> 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 <tt>ExecShell</tt> with "wait for process termination" feature, based on [http://msdn.microsoft.com/en-us/library/windows/desktop/bb762154%28v=vs.85%29.aspx ShellExecuteEx], as well as a function for invoking "shell verbs" &ndash; useful for programmatically <i>pinning shortcuts to the Taskbar</i>.


<b>ANSI and Unicode builds available. Support operating systems: Windows 2000 and later.</b>
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. <b>ANSI</b> <i>and</i> <b>Unicode</b> builds are provided. Supports all Windows versions, starting with <b>Windows XP</b>.


== Available Functions ==
== Available Functions ==
<b style="color:darkred">For details please refer to the [http://muldersoft.com/docs/stdutils_readme.html online documentation], a copy of which is also included in the download package!</b>
(The documentation can be found at <tt>"Docs\StdUtils\StdUtils.html"</tt> inside the ZIP package)
=== Overview ===


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


<highlight-nsis>
<highlight-nsis>!define StdUtils.Time            #time(), as in C standard library
!define StdUtils.Time            #time(), as in C standard library
!define StdUtils.GetMinutes      #GetSystemTimeAsFileTime(), returns the number of minutes
!define StdUtils.GetMinutes      #GetSystemTimeAsFileTime(), returns the number of minutes
!define StdUtils.GetHours        #GetSystemTimeAsFileTime(), returns the number of hours
!define StdUtils.GetHours        #GetSystemTimeAsFileTime(), returns the number of hours
Line 20: Line 26:
!define StdUtils.RandMinMax      #rand(), as in C standard library, with minimum/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.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.FormatStr        #sprintf(), as in C standard library, one '%d' placeholder
!define StdUtils.FormatStr2      #sprintf(), as in C standard library, two '%d' placeholders
!define StdUtils.FormatStr2      #sprintf(), as in C standard library, two '%d' placeholders
Line 30: Line 37:
!define StdUtils.TrimStrRight    #Remove whitspaces from string, right 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.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.SHFileMove      #SHFileOperation(), using the FO_MOVE operation
!define StdUtils.SHFileCopy      #SHFileOperation(), using the FO_COPY 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.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.InvokeShellVerb  #Invokes a "shell verb", e.g. for pinning items to the taskbar
Line 37: Line 50:
!define StdUtils.WaitForProcEx    #WaitForSingleObject(), e.g. to wait for a running 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.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.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.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.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.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.VerifyOSVersion  #Compare *real* operating system to an expected version number
!define StdUtils.VerifyOSBuildNo  #Compare *real* operating system to an expected build 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.GetLibVersion    #Get the current StdUtils library version (for debugging)
!define StdUtils.SetVerbose      #Enable or disable "verbose" mode (for debugging)</highlight-nsis>
!define StdUtils.SetVerbose      #Enable or disable "verbose" mode (for debugging)</highlight-nsis>
<b style="color:darkred">For details please see the [http://muldersoft.com/docs/stdutils_readme.html online documentation], a copy of which is also included in the download package!</b>
Note: The "offline" documentation can be found at <tt>"Docs\StdUtils\StdUtils.html"</tt> inside the ZIP package.


== General Usage ==
== General Usage ==
Line 74: Line 101:


<font size="-1"><pre>StdUtils plug-in for NSIS
<font size="-1"><pre>StdUtils plug-in for NSIS
Copyright (C) 2004-2013 LoRd_MuldeR <mulder2@gmx.de>
Copyright (C) 2004-2015 LoRd_MuldeR <mulder2@gmx.de>


This library is free software; you can redistribute it and/or
This library is free software; you can redistribute it and/or
Line 96: Line 123:
== Download ==
== Download ==


'''<font color="darkred">Download <u>latest</u> version from GitHub:</font><br>https://github.com/lordmulder/stdutils/releases/latest'''
'''<font color="darkred">Download the <u>latest</u> version from GitHub:</font><br>https://github.com/lordmulder/stdutils/releases/latest'''
 
=== Outdated Versions ===


* <attach>StdUtils.2013-02-21.zip</attach>
=== Other official download mirrors ===
* <attach>StdUtils.2012-10-28.zip</attach>
* http://sourceforge.net/projects/muldersoft/files/StdUtils-Plugin%20%28NSIS%29/
* <attach>StdUtils.2011-10-18.zip</attach>
* https://bitbucket.org/muldersoft/stdutils/downloads
* https://www.assembla.com/spaces/stdutils/documents


=== Source Code (Git) ===
=== Source Code Access (Git) ===


* https://github.com/lordmulder/stdutils.git ([https://github.com/lordmulder/stdutils Browse])
* https://github.com/lordmulder/stdutils.git ([https://github.com/lordmulder/stdutils Browse])
* https://git.gitorious.org/stdutils-plug-in-for-nsis/stdutils-plug-in-for-nsis.git ([https://gitorious.org/stdutils-plug-in-for-nsis/stdutils-plug-in-for-nsis Browse])
* https://gitlab.com/stdutils-plug-in-for-nsis/stdutils-plug-in-for-nsis.git ([https://gitlab.com/stdutils-plug-in-for-nsis/stdutils-plug-in-for-nsis/tree/master Browse])
* https://bitbucket.org/lord_mulder/stdutils.git ([https://bitbucket.org/lord_mulder/stdutils/src Browse])
* https://bitbucket.org/muldersoft/stdutils.git ([https://bitbucket.org/muldersoft/stdutils/src Browse])  
 
* https://git.assembla.com/stdutils.git ([https://www.assembla.com/spaces/stdutils/git/source Browse])
[[Category:Plugins]]
 
== Support ==
 
Discussion thread at NSIS Forums:<br>
http://forums.winamp.com/showthread.php?t=335435
 
E-Mail:<br>
<tt>MuldeR2 (at) gmx (dot) de</tt>

Latest revision as of 16:42, 9 March 2022

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

Source Code Access (Git)