Source

nsis64 / Contrib / MultiUser / Readme.html

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
<!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&nbsp;</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 &quot;Program Files&quot; 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_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>