392 lines
16 KiB
HTML
392 lines
16 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html lang="en">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<meta name="color-scheme" content="light dark">
|
|
<title>Multi-User Header File (MultiUser.nsh)</title>
|
|
<style type="text/css">
|
|
:root { color-scheme: light dark; }
|
|
html, body { font-family: Verdana, Arial, Helvetica, sans-serif; font-weight: normal; color: #050505; background-color: #fefefe; }
|
|
html { font-size: 0.9em; }
|
|
body { font-size: 1em; font-size: 1rem; }
|
|
pre, code { font-family: Courier New, Courier, monospace,serif; font-size: 100%; }
|
|
pre, pre code {background-color: #f6f6f6; }
|
|
tr:nth-child(odd) { background-color: #fafafa; }
|
|
table, tr, td { border: 1px solid #dddddd; border-collapse: collapse; }
|
|
td { padding: 0.3em; vertical-align: top; }
|
|
|
|
@media (prefers-color-scheme: dark) {
|
|
html, body { color: #eeeeee; background-color: #161616; }
|
|
a, a:link, a:visited, a:active { color: #79b; } a:hover { color: #3ad; }
|
|
pre, pre code {background-color: #202020; }
|
|
table, tr, td { border-color: #202020; }
|
|
tr:nth-child(odd) { background-color: #181818; }
|
|
}
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<h1>Multi-User Header File (MultiUser.nsh)</h1>
|
|
<p><i>Installer configuration for multi-user Windows environments</i></p>
|
|
<h2>Table of Contents</h2>
|
|
<ul>
|
|
<li><a href="#introduction">Introduction</a></li>
|
|
<li><a href="#executionlevel">Initialization and Execution Level</a>
|
|
<li><a href="#installationmode">Installation Mode</a>
|
|
<li><a href="#examples">Example</a>
|
|
</ul>
|
|
<h2><a name="introduction"></a>Introduction</h2>
|
|
<p>
|
|
Modern Windows versions support multiple users accounts on a single computer, each
|
|
with different privileges. For security reasons, the privileges of applications
|
|
can also be limited. For an installer, the <i>execution level</i> and <i>installation
|
|
mode</i> are important. The execution level determines the privileges of the
|
|
installer application. For example, to install hardware drivers, administrator privileges
|
|
are required. Applications can also be installed for a single user or for all users
|
|
on a computer, which is determined by the installation mode. Installation for all
|
|
users requires a higher execution level as compared with a single user setup. The
|
|
MultiUser.nsh header files provides the features to automatically handle all these
|
|
aspects related to user accounts and installer privileges.</p>
|
|
<p>
|
|
Note that all settings need to be set before including the MultiUser.nsh header
|
|
file.</p>
|
|
<h2>Initialization and <a name="executionlevel"></a>Execution Level </h2>
|
|
<p>
|
|
Before the MultiUser.nsh file is included, the MULTIUSER_EXECUTIONLEVEL define should
|
|
be set to one of the following values depending on the execution level that is required:</p>
|
|
<table>
|
|
<tr>
|
|
<td>
|
|
<b>Value </b>
|
|
</td>
|
|
<td>
|
|
<b>Description</b>
|
|
</td>
|
|
<td>
|
|
<b>Typical application</b>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
Admin
|
|
</td>
|
|
<td>
|
|
Administrator privileges are required
|
|
</td>
|
|
<td>
|
|
Access data of all users accounts
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
Power
|
|
</td>
|
|
<td>
|
|
Power User privileges are required<br>
|
|
(Power Users no longer exist in Windows Vista. For Vista this is equivalent to Admin)
|
|
</td>
|
|
<td>
|
|
Installation for all users (writing to "Program Files" or HKLM registry
|
|
keys), driver installation
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
Highest
|
|
</td>
|
|
<td>
|
|
Request the highest possible execution level for the current user
|
|
</td>
|
|
<td>
|
|
Mixed-mode installer that can both be installed per-machine or per-user
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
Standard
|
|
</td>
|
|
<td>
|
|
No special rights required
|
|
</td>
|
|
<td>
|
|
Installation for current user only
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p>
|
|
Insert the MULTIUSER_INIT and MULTIUSER_UNINT macros in the .onInit and un.onInit
|
|
function to verify these privileges. If no uninstaller is created in the script,
|
|
define MULTIUSER_NOUNINSTALL.</p>
|
|
<pre><code>!define MULTIUSER_EXECUTIONLEVEL Highest
|
|
;!define MULTIUSER_NOUNINSTALL ;Uncomment if no uninstaller is created
|
|
!include MultiUser.nsh
|
|
|
|
...
|
|
|
|
Function .onInit
|
|
!insertmacro MULTIUSER_INIT
|
|
FunctionEnd
|
|
|
|
Function un.onInit
|
|
!insertmacro MULTIUSER_UNINIT
|
|
FunctionEnd</code></pre>
|
|
<p>
|
|
Whether the required privileges can be obtained depends on the user that starts
|
|
the installer:</p>
|
|
<ul>
|
|
<li>Windows NT 4/2000/XP/2003 give the installer the same privileges as the user itself.
|
|
If the privileges of the user are not sufficient (e.g. Admin level is required is
|
|
set but the user has no administrator rights), the macros will display an error
|
|
message and quit the installer. If is however possible to manually run the installer
|
|
with an administrator account.</li>
|
|
<li>Windows Vista restricts the privileges of all applications by default. Depending
|
|
on requested execution level, MultiUser.nsh will set the RequestExecutionLevel flag
|
|
to request privileges. The user will be asked for confirmation and (if necessary)
|
|
for an administrator password.</li>
|
|
<li>Windows 95/98/98 do not set any restrictions on users or applications. Administrator
|
|
rights are always available.</li>
|
|
</ul>
|
|
<p>
|
|
It is recommended to insert these initialization macros before macros that require
|
|
user intervention. For example, it does not make sense to ask a user for an installer
|
|
language if the installer will quit afterwards because the user account does not
|
|
have the required privileges. After the macros are inserted, the variable $MultiUser.Privileges
|
|
will contain the current execution level (Admin, Power, User or Guest).</p>
|
|
<p>
|
|
The following additional settings are available to customize the initialization:</p>
|
|
<table>
|
|
<tr>
|
|
<td><b>Setting</b></td>
|
|
<td><b>Description</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
MULTIUSER_INIT_TEXT_ADMINREQUIRED
|
|
</td>
|
|
<td>
|
|
Error message to be displayed when administrator rights are required but not available.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
MULTIUSER_INIT_TEXT_POWERREQUIRED
|
|
</td>
|
|
<td>
|
|
Error message to be displayed when Power User rights are required but not available.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
MULTIUSER_INIT_TEXT_ALLUSERSNOTPOSSIBLE
|
|
</td>
|
|
<td>
|
|
Error message to be displayed when administrator or Power User rights are required
|
|
because of an installation mode setting on the command line (see below) but are
|
|
not available.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
MULTIUSER_USE_PROGRAMFILES64
|
|
</td>
|
|
<td>
|
|
Use $PROGRAMFILES64 instead of $PROGRAMFILES as the default all users directory.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
MULTIUSER_INIT_FUNCTIONQUIT<br>
|
|
MULTIUSER_INIT_UNFUNCTIONQUIT
|
|
</td>
|
|
<td>
|
|
A custom function to be called when the installer is closed due to insufficient
|
|
privileges.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<h2><a name="installationmode"></a>Installation Mode</h2>
|
|
<p>
|
|
As mentioned before, applications can both be installed for a single users or for
|
|
all users on a computer. Applications for all users are typically installed in the
|
|
Program Files folder and appear in the Start Menu of every user. On the contrary,
|
|
applications for a single user are usually installed in the local Application Data
|
|
folder and only a appear in the Start Menu of the user who installed the application.</p>
|
|
<p>
|
|
By default, MultiUser.nsh will set the installation mode for a per-machine installation
|
|
if Administrator or Power User rights are available (this is always the case if
|
|
the execution level is set to Admin or Power, if Highest is set it depends on the
|
|
user account). For the Standard execution level the installation will always be
|
|
for a single user. On Windows 95/98/Me installation for a single user is not possible, a per-machine installation will be performed.</p>
|
|
<p>
|
|
The following settings are available to change the default installation mode:
|
|
<table>
|
|
<tr>
|
|
<td><b>Setting</b></td>
|
|
<td><b>Description</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
MULTIUSER_INSTALLMODE_DEFAULT_CURRENTUSER
|
|
</td>
|
|
<td>
|
|
Set default to a per-user installation, even if the rights for a per-machine installation
|
|
are available.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
MULTIUSER_INSTALLMODE_DEFAULT_REGISTRY_KEY MULTIUSER_INSTALLMODE_DEFAULT_REGISTRY_VALUENAME
|
|
</td>
|
|
<td>
|
|
Non-empty registry key that is created during the installation in either HKCU or
|
|
HKLM. The default installation mode will automatically be set to the previously
|
|
selected mode depending on the location of the key.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p>
|
|
After initialization, the variable $MultiUser.InstallMode will contain the current
|
|
installation mode (AllUsers or CurrentUser).
|
|
</p>
|
|
<h3>Mixed-Mode Installation</h3>
|
|
<p>
|
|
For the Admin and Power levels, both a per-machine as well as a per-user installation
|
|
is possible. If the Highest level is set and the user is an Administrator or Power
|
|
User, both options are also available.</p>
|
|
<p>
|
|
Usually it's a good thing to give the user to choice between these options. For
|
|
users of the Modern UI version 2, a page is provided that asks the user for the
|
|
installation mode. To use this page, define MULTIUSER_MUI before including MultiUser.nsh.
|
|
Then, the MULTIUSER_PAGE_INSTALLMODE macro can be used just like a normal Modern
|
|
UI page (this page will automatically be skipped when running Windows 95/98/Me):</p>
|
|
<pre><code>!define MULTIUSER_EXECUTIONLEVEL Highest
|
|
<b>!define MULTIUSER_MUI</b>
|
|
!define MULTIUSER_INSTALLMODE_COMMANDLINE
|
|
!include MultiUser.nsh
|
|
!include MUI2.nsh
|
|
|
|
<b>!insertmacro MULTIUSER_PAGE_INSTALLMODE</b>
|
|
!insertmacro MUI_PAGE_DIRECTORY
|
|
!insertmacro MUI_PAGE_INSTFILES
|
|
|
|
!insertmacro MUI_LANGUAGE English
|
|
|
|
...
|
|
|
|
Function .onInit
|
|
!insertmacro MULTIUSER_INIT
|
|
FunctionEnd
|
|
|
|
Function un.onInit
|
|
!insertmacro MULTIUSER_UNINIT
|
|
FunctionEnd</code></pre>
|
|
<p>
|
|
The MULTIUSER_INSTALLMODE_COMMANDLINE setting that also appears in this example
|
|
enables the installation mode to be set using the /AllUsers or /CurrentUser command
|
|
line parameters. This is especially useful for silent setup.</p>
|
|
<p>
|
|
The following settings can be used to customize the texts on the page (in addition
|
|
to the general Modern UI page settings):</p>
|
|
<table>
|
|
<tr>
|
|
<td><b>Setting</b></td>
|
|
<td><b>Description</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td>MULTIUSER_INSTALLMODEPAGE_TEXT_TOP</td>
|
|
<td>Text to display on the top of the page.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>MULTIUSER_INSTALLMODEPAGE_TEXT_ALLUSERS</td>
|
|
<td>Text to display on the radio button for a per-machine installation.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>MULTIUSER_INSTALLMODEPAGE_TEXT_CURRENTUSER</td>
|
|
<td>Text to display on the radio button for a per-user installation.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>MULTIUSER_INSTALLMODEPAGE_SHOWUSERNAME</td>
|
|
<td>Append the username to the per-user radio button.</td>
|
|
</tr>
|
|
</table>
|
|
<h3>Installation Mode Initialization</h3>
|
|
<p>
|
|
The SetShellVarContext flag (which determines the folders for e.g. shortcuts, like
|
|
$DESKTOP) is automatically set depending on the installation mode. In addition,
|
|
the following settings can be used to perform additional actions when the installation
|
|
mode is initialized:</p>
|
|
<table>
|
|
<tr>
|
|
<td><b>Setting</b></td>
|
|
<td><b>Description</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td>MULTIUSER_INSTALLMODE_INSTDIR</td>
|
|
<td>
|
|
Name of the folder in which to install the application, without a path. This folder
|
|
will be located in Program Files for a per-machine installation and in the local
|
|
Application Data folder for a per-user installation (if supported).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>MULTIUSER_INSTALLMODE_INSTDIR_REGISTRY_KEY MULTIUSER_INSTALLMODE_INSTDIR_REGISTRY_VALUENAME</td>
|
|
<td>
|
|
Registry key from which to obtain a previously stored installation folder. It will
|
|
be retrieved from HKCU for per-user and HKLM for per-machine.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
MULTIUSER_INSTALLMODE_FUNCTION<br>
|
|
MULTIUSER_INSTALLMODE_UNFUNCTION
|
|
</td>
|
|
<td>
|
|
A custom function to be called during the initialization of the installation mode
|
|
to set additional installer settings that depend on the mode
|
|
</td>
|
|
</table>
|
|
<p>
|
|
To set the installation mode manually, call one of these four functions:</p>
|
|
<table>
|
|
<tr>
|
|
<td>
|
|
<b>Function name</b>
|
|
</td>
|
|
<td>
|
|
<b>Installation mode</b>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
MultiUser.InstallMode.AllUsers
|
|
</td>
|
|
<td>
|
|
Installer: Per-machine installation
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
MultiUser.InstallMode.CurrentUser
|
|
<td>
|
|
Installer: Per-user installation
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
un.MultiUser.InstallMode.AllUsers<td>
|
|
Uninstaller: Per-machine installation
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
un.MultiUser.InstallMode.CurrentUser<td>
|
|
Uninstaller: Per-user installation
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h2><a name="examples"></a>Example</h2>
|
|
Basic: <a href="../../Examples/MultiUser.nsi">MultiUser.nsi</a><br />
|
|
</body>
|
|
</html>
|