413 lines
15 KiB
HTML
413 lines
15 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html>
|
|
<head>
|
|
<title>Multi-User Header File (MultiUser.nsh)</title>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
|
|
<style type="text/css">
|
|
td
|
|
{
|
|
padding: 5px;
|
|
vertical-align: top;
|
|
border-bottom: 1px solid black;
|
|
}
|
|
</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">Initalization and Execution Level</a>
|
|
<li><a href="#installationmode">Installation Mode</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,
|
|
set MULTIUSER_NOUNINSTALL.</p>
|
|
<blockquote>
|
|
<pre>!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</pre>
|
|
</blockquote>
|
|
<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<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.</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>
|
|
</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 User.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>!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
|
|
</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 combo button for a per-machine installation.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
MULTIUSER_INSTALLMODEPAGE_TEXT_CURRENTUSER
|
|
</td>
|
|
<td>
|
|
Text to display on the combo button for a per-user installation.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<h3>
|
|
Installation Mode Initalization</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>
|
|
</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 fuction 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>
|
|
</body>
|
|
</html>
|