other-licenses/nsis/Contrib/UAC/UAC Readme.html
author Steve Snyder <swsnyder@snydernet.net>
Thu, 01 Oct 2009 14:19:41 -0400
changeset 33346 8a43f01f1d6478ad072c1f4a41fb633f8a5e3a32
parent 23964 ba15a84af7e6c364570feb7b5a66cea87ba460c8
permissions -rw-r--r--
Bug 512865. qcms: Improve SSE2 performance, add SSE support. r=jrmuizel This patch greatly improves the performance of QCMS transformations on x86 & x86_64 systems. Some notes: 0. On 32-bit x86 systems it does runtime selection between non-SIMD, SSE, and SSE2 code paths. 1. On x86_64 systems the SSE2 code path is always taken. The non-SIMD and SSE code paths are left intact, but contemporary versions of the GCC and MSVC compilers will see that they cannot be reached and optimize them away. 2. The execution of the SSE2 code path is reduced by 67%, relative to the original Intel/Microsoft formatted ASM code. The relative performance is seen on a Pentium4 (Northwood) 2.4GHz CPU with DDR1 RAM. 3. The SSE code path provides a 80% reduction in execution time, relative to the non-SIMD code path. The relative performance is seen on a Pentium3 (Coppermine) 1.26GHz CPU with SDRAM. 4. The code has been split out into separate files so that it can be built with different cflags (-msse, and -msse2) when using gcc. 5. Try to land again, this time with __attribute__((__force_align_arg_pointer__)) to avoid crashes on linux.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html><head>
<title>UAC plug-in readme</title>
<script type="text/javascript">
function NavGL(q){window.open("http://www.google.com/search?hl=en&btnI=I&num=2&q="+escape(q));return 0;}
</script>
<style type="text/css">
html,body {background-color:#FFF; color:#000;}
a:link, a:visited, a:active {color:#00F;}
h2 {border-bottom:0.1em solid #000;}
#docHdrHdln{text-align:center;}
.importanttxt {color:#e00;}
.code {font-family:monospace;}
.nsisvar {color:#C00;}
.str {color:#390}
.inifile {background-color:#EEE;border:1px solid #000;padding:0.2em;}
.inicomment {background-color:#f5f5c5;color:#555;}
table.piexport {text-align:left;margin-bottom:1em;}
table.piexport td {vertical-align:top;}
table.piexport table.ret {padding:0;margin:0;border:0;}
</style>
</head><body>
<h1 id="docHdrHdln">UAC plug-in</h1>


<code><pre>
Interactive User (MediumIL)        Admin user(HighIL)
+++[Setup.exe]++++++++++++++       +++[Setup.exe]++++++++++++++
+                          +       +                          +
+ ***[.OnInit]************ +       + ***[.OnInit]************ +
+ * UAC::RunElevated >---+-+------>+ *                      * +
+ * NSIS.Quit()          * +       + *                      * +
+ ************************ +       + ***********||*********** +
+                          +       +            ||            +
+                          +       +            \/            +
+ ***[Sections]*********** +       + ***[Sections]*********** +
+ *                      * +    /--+-+-< UAC::Exec          * +
+ ************************ +    |  + ************************ +
+                          +    |  +                          +
+  Win32.CreateProcess() <-+----/  +                          +
+                          +       +                          +
++++++++++++++++++++++++++++       ++++++++++++++++++++++++++++
</pre></code>


<h2>Contents</h2>
<ul>
<li><a href="#exports">Plugin Functions</a>
<li><a href="#lang">Language support</a>
<li><a href="#knownissues">Known Issues</a>
<li><a href="#glossary">Glossary</a>
</ul>






<a name="exports"><h2>Plugin Functions</h2></a><div class="CntSec"><p>
Every function will try to emulate the basic NSIS instruction (of similar name) when UAC::RunElevated has not "succeeded" or running on a system that does not support elevation (Win9x/NT4)</p>

<table class="piexport"><tr><th colspan=2>UAC::RunElevated</th></tr>
<tr><td>Parameters:</td><td></td></tr>
<tr><td>Returns:</td><td>
	<table class="ret">
	<tr><td><span class="nsisvar">$0</span></td><td>Win32 error code (0 on success, 1223 if user aborted elevation dialog, anything else should be treated as a fatal error)</td></tr>
	<tr><td><span class="nsisvar">$1</span></td><td><span class="code">If <span class="nsisvar">$0</span>==0</span>:
		<table class="ret">
		<tr><td>0</td><td>UAC is not supported by the OS</td></tr>
		<tr><td>1</td><td>Started a elevated child process, the current process should act like a wrapper (Call Quit without any further processing)</td></tr>
		<tr><td>2</td><td>The process is already running @ HighIL (Member of admin group)</td></tr>
		<tr><td>3</td><td>You should call RunElevated again (This can happen if a user without admin priv. is used in the runas dialog)</td></tr>
		</table>	
		</td></tr>
	<tr><td><span class="nsisvar">$2</span></td><td><span class="code">If <span class="nsisvar">$0</span>==0 && <span class="nsisvar">$1</span>==1</span>: ExitCode of the elevated fork process (The NSIS errlvl is also set)</td></tr>
	<tr><td><span class="nsisvar">$3</span></td><td><span class="code">If <span class="nsisvar">$0</span>==0</span>: 1 if the user is a member of the admin group or 0 otherwise</td></tr>
	</table></td></tr>
<tr><td>Description:</td><td>Allows non-admin/UAC.LUA users to re-spawn the installer as another user and UAC.Admin users to elevate.</td></tr>
</table>
<!--table class="piexport"><tr><th colspan=2>UAC::RunElevatedAndProcessMessages <i style="font-size:smaller;">(Experimental)</i></th></tr>
<tr><td>Parameters:</td><td></td></tr>
<tr><td>Returns:</td><td><i>See UAC::RunElevated</i></td></tr>
<tr><td>Description:</td><td>Version of UAC::RunElevated that can be called from a page</td></tr>
</table-->

<table class="piexport"><tr><th colspan=2>UAC::Unload</th></tr>
<tr><td>Parameters:</td><td></td></tr>
<tr><td>Returns:</td><td></td></tr>
<tr><td>Description:</td><td>Cleanup, you must call this function in .OnInstFailed, .onUserAbort and .OnInstSuccess</td></tr>
</table>

<table class="piexport"><tr>
<th colspan=2>UAC::Exec</th></tr>
<tr><td>Parameters:</td><td>&lt;INT:ShowWindow&gt; &lt;STR:App&gt; &lt;STR:Parameters&gt; &lt;STR:WorkingDir&gt;</td></tr>
<tr><td>Returns:</td><td>
	<table class="ret">
	<tr><td><span class="nsisvar">$0</span></td><td>Win32 error code, 0 on success (ErrorFlag is also set on error)</td></tr>
	</table></td></tr>
</table>
<table class="piexport"><tr>
<th colspan=2>UAC::ExecWait</th></tr>
<tr><td>Parameters:</td><td>&lt;INT:ShowWindow&gt; &lt;STR:App&gt; &lt;STR:Parameters&gt; &lt;STR:WorkingDir&gt;</td></tr>
<tr><td>Returns:</td><td>
	<table class="ret">
	<tr><td><span class="nsisvar">$0</span></td><td>Win32 error code, 0 on success (ErrorFlag is also set on error)</td></tr>
	<tr><td><span class="nsisvar">$1</span></td><td>Exitcode of new process</td></tr>
	</table></td></tr>
</table>
<table class="piexport"><tr>
<th colspan=2>UAC::ShellExec</th></tr>
<tr><td>Parameters:</td><td>&lt;STR:Verb&gt; &lt;INT:ShowWindow&gt; &lt;STR:App&gt; &lt;STR:Parameters&gt; &lt;STR:WorkingDir&gt;</td></tr>
<tr><td>Returns:</td><td>
	<table class="ret">
	<tr><td><span class="nsisvar">$0</span></td><td>Win32 error code, 0 on success (ErrorFlag is also set on error)</td></tr>
	</table></td></tr>
</table>
<table class="piexport"><tr>
<th colspan=2>UAC::ShellExecWait</th></tr>
<tr><td>Parameters:</td><td>&lt;STR:Verb&gt; &lt;INT:ShowWindow&gt; &lt;STR:App&gt; &lt;STR:Parameters&gt; &lt;STR:WorkingDir&gt;</td></tr>
<tr><td>Returns:</td><td>
	<table class="ret">
	<tr><td><span class="nsisvar">$0</span></td><td>Win32 error code, 0 on success (ErrorFlag is also set on error)</td></tr>
	<tr><td><span class="nsisvar">$1</span></td><td>Exitcode of new process</td></tr>
	</table></td></tr>
</table>

<table class="piexport"><tr><th colspan=2>UAC::IsAdmin</th></tr>
<tr><td>Parameters:</td><td></td></tr>
<tr><td>Returns:</td><td><span class="nsisvar">$0</span> (BOOL) result</td></tr>
<tr><td>Description:</td><td>Check current thread/process token for a non-deny admin group SID entry</td></tr>
</table>

<table class="piexport"><tr><th colspan=2>UAC::ExecCodeSegment</th></tr>
<tr><td>Parameters:</td><td>&lt;INT:NSISFunctionAddress&gt;</td></tr>
<tr><td>Returns:</td><td>[None] (ErrorFlag is set on error)</td></tr>
<tr><td>Description:</td><td>Calls NSIS function in LUA/outer instance (If you use instructions that alter the UI or the stack/variables in the code segment (StrCpy,Push/Pop/Exch,DetailPrint etc.) they will affect the hidden wrapper installer and not "your" installer instance)</td></tr>
</table>

<table class="piexport"><tr><th colspan=2>UAC::StackPush</th></tr>
<tr><td>Parameters:</td><td>&lt;STR:String&gt;</td></tr>
<tr><td>Returns:</td><td>[None] (ErrorFlag is set on error)</td></tr>
<tr><td>Description:</td><td>Push to outer instance stack (For use with UAC::ExecCodeSegment)</td></tr>
</table>

<table class="piexport"><tr><th colspan=2>UAC::GetOuterHwnd</th></tr>
<tr><td>Parameters:</td><td></td></tr>
<tr><td>Returns:</td><td><span class="nsisvar">$0</span> HWNDPARENT of outer instance</td></tr>
<tr><td>Description:</td><td>For use with ${UAC.RunElevatedAndProcessMessages}</td></tr>
</table>

<table class="piexport"><tr><th colspan=2>UAC::SupportsUAC</th></tr>
<tr><td>Parameters:</td><td></td></tr>
<tr><td>Returns:</td><td><span class="nsisvar">$0</span> !=0 if supported</td></tr>
<tr><td>Description:</td><td>Check if the OS supports UAC (And the user has UAC turned on) <span class="importanttxt">This function only tests if UAC is active, will return 0 on NT5 even though runas is implemented on those platforms, will also return 0 on NT6+ if UAC is off. You should only call this function during testing, NOT to determine if you can call UAC::RunElevated</span></td></tr>
</table>

<table class="piexport"><tr><th colspan=2>UAC::GetElevationType</th></tr>
<tr><td>Parameters:</td><td></td></tr>
<tr><td>Returns:</td><td>
	<table class="ret">
	<tr><td><span class="nsisvar">$0</span></td><td><a href="#" OnClick="return NavGL('TOKEN_ELEVATION_TYPE Enumeration')">TOKEN_ELEVATION_TYPE</a>:
		<table class="ret">
		<tr><td>0</td><td>Unsupported/Failed (ErrorFlag is also set)</td></tr>
		<tr><td>1</td><td>TokenElevationTypeDefault: User is not using a split token (UAC disabled)</td></tr>
		<tr><td>2</td><td>TokenElevationTypeFull: UAC enabled, the (current) process is elevated</td></tr>
		<tr><td>3</td><td>TokenElevationTypeLimited: UAC enabled, the process is not elevated</td></tr>
		</table>	
		</td></tr>
	</table></td></tr>
</table>

</div>





<a name="lang"><h2>Language support</h2></a><div class="CntSec">
<p>If the plugin is built with FEAT_CUSTOMRUNASDLG_TRANSLATE (Enabled by default), 
you can extract a file named <span class="str">UAC.LNG</span> to <span class="nsisvar">$pluginsdir</span>. 
It is a ini file with the following sections:
</p><pre class="inifile">
[MyRunAsCfg]
<span class="inicomment">;Set to 1 to disable the radio button</span>
DisableCurrUserOpt=
<span class="inicomment">;Set to 1 to hide the radio button</span>
HideCurrUserOpt=

[MyRunAsStrings]
DlgTitle=Hello There!
HelpText=Just do your thing!
<span class="inicomment">;Label for current user radio button, %s is replaced with result of GetUserNameEx(NameSamCompatible,...)</span>
OptCurrUser=Self service (%s)
OptOtherUser=Run as someone:
UserName=Who:
Pwd=PIN:
OK=Okey!
Cancel=No Way</pre>
</div>

<a name="knownissues"><h2>Known Issues</h2></a><div class="CntSec">
<ul>
<li>UACPI.KI#1: DetailPrint in outer process is ignored
<li>UACPI.KI#2: Elevation can fail if the installer is located on a remote share that requires authentication
</ul>
</div>


<a name="glossary"><h2>Glossary</h2></a><div class="CntSec">
<ul>
<li>AAM: Admin Approval Mode
<li>IL: Integrity level (Part of the new MIC/WIC security levels added to NT6)
<li>LUA: Limited/Least-privilege User Account
<li>MIC: <a href="http://en.wikipedia.org/wiki/Mandatory_Integrity_Control">Mandatory Integrity Controls</a> (Now known as WIC)
<li>UAC: User Account Control (Part of the UAP umbrella)
<li>UAP: User Account Protection
<li>WIC: <a href="http://www.securityfocus.com/infocus/1887">Windows Integrity Controls</a>
<li>Win32 error code: Standard windows error codes, ERROR_???
</ul>
</div>

</body></html>