diff options
Diffstat (limited to 'Contrib/System/System.html')
| -rwxr-xr-x | Contrib/System/System.html | 95 |
1 files changed, 79 insertions, 16 deletions
diff --git a/Contrib/System/System.html b/Contrib/System/System.html index 19bb8d4..a10845b 100755 --- a/Contrib/System/System.html +++ b/Contrib/System/System.html @@ -7,7 +7,7 @@ <body> <h1>NSIS System Plug-in</h1> <p> -<i>Copyright © 2002 brainsucker (Nik Medved)</i><br><i>Copyright © 2002-2017 NSIS Contributors</i> +<i>Copyright © 2002 brainsucker (Nik Medved)</i><br><i>Copyright © 2002-2018 NSIS Contributors</i> </p> <h2>Table of Contents</h2> @@ -254,12 +254,20 @@ DetailPrint $4 <td>pointer (and other pointer sized types like handles and HWNDs)</td> </tr> <tr> +<th>b</th> +<td>int8, byte</td> +</tr> +<tr> +<th>h</th> +<td>int16, short</td> +</tr> +<tr> <th>i</th> -<td>int (includes char, byte, short and so on)</td> +<td>int32 (includes char, byte, short and so on when used as a pointer)</td> </tr> <tr> <th>l</th> -<td>large integer, int64</td> +<td>int64, large integer</td> </tr> <tr> <th>m</th> @@ -299,22 +307,22 @@ DetailPrint $4 </tr> <tr> <th>&t<i>N</i></th> -<td>array of <i>N</i> text characters TCHAR (structures only)</td> +<td>array of <i>N</i> TCHAR text characters (structures only)</td> </tr> <tr> <th>&m<i>N</i></th> -<td>array of <i>N</i> ANSI characters CHAR (structures only)</td> +<td>array of <i>N</i> CHAR ANSI characters (structures only)</td> </tr> <tr> <th>&w<i>N</i></th> -<td>array of <i>N</i> Unicode characters WCHAR (structures only)</td> +<td>array of <i>N</i> WCHAR Unicode characters (structures only)</td> </tr> <tr> -<th>&g<i>N</i></th> -<td><i>N</i> bytes of GUID (structures only)</td> +<th>&g<i>16</i></th> +<td><i>16</i> bytes of GUID (structures only)</td> </tr> </table> -<p>Additionally, each type can be prefixed with an asterisk to denote a pointer. When using an asterisk, the System plug-in still expects the value of the parameter, rather than the pointer's address. To pass a direct address, use `p' with no asterisk. A <a href="#pointer">usage example</a> is available. <a href="#memfuncs">Alloc</a> returns addresses and its return value should therefore be used with `p', without an asterisk.</p> +<p>Additionally, each type (except <i>b</i>, <i>h</i>, <i>k</i> and <i>@</i>) can be prefixed with an asterisk to denote a pointer. When using an asterisk, the System plug-in still expects the value of the parameter, rather than the pointer's address. To pass a direct address, use `p' with no asterisk. A <a href="#pointer">usage example</a> is available. <a href="#memfuncs">Alloc</a> returns addresses and its return value should therefore be used with `p', without an asterisk.</p> </blockquote> <h4>Available Sources and Destinations</h4> @@ -381,7 +389,7 @@ DetailPrint $4 <h4>Callbacks</h4> <blockquote> -<p>Callback functions are simply functions which are passed to a function and called back by it. They are frequently used to pass a possibly large set of data item by item. For example, <a href="https://msdn.microsoft.com/en-us/library/ms633494">EnumChildWindows</a> uses a <a href="https://msdn.microsoft.com/en-us/library/ms633493p">callback function</a>. As NSIS functions are not quite regular functions, the System plug-in provides its own mechanism to support callback functions. It allows you to create callback functions and notifies you each time a callback function was called.</p> +<p>Callback functions are simply functions which are passed to a function and called back by it. They are frequently used to pass a possibly large set of data item by item. For example, <a href="https://msdn.microsoft.com/en-us/library/ms633494">EnumChildWindows</a> uses a <a href="https://msdn.microsoft.com/en-us/library/ms633493">callback function</a>. As NSIS functions are not quite regular functions, the System plug-in provides its own mechanism to support callback functions. It allows you to create callback functions and notifies you each time a callback function was called.</p> <p>Creation of callback functions is done using <a href="#callfuncs">Get</a> and the callback creation syntax. As you will not call the callbacks yourself, the source of the parameters should be omitted using a dot. When the callback is called, the destination of the parameters will be filled with the values passed on to the callback. The value the callback will return is set by the source of the return "parameter". The destination of the return "parameter" should always be set as that's where System will notify you the callback was called.</p> @@ -464,9 +472,20 @@ System::Free $0 <th>u</th> <td>Unload DLL after call (using FreeLibrary, so you'll be able to delete it for example).</td> </tr> +<tr> +<th>2</th> +<td>Experimental v2 syntax</td> +</tr> </table> </blockquote> +<h4>Experimental v2 syntax</h4> + +<ul> +<li>Struct types in <a href="#v2typealign">uppercase are aligned</a> to their natural alignment. Lowercased types are packed without alignment. +<li><a href="#v2callback">Callback id</a> based on the allocated callback +</ul> + <h4>Usage Examples</h4> <blockquote><pre> @@ -508,6 +527,19 @@ System::<b>Call</b> "*$0(i .r1)" System::Free $0 DetailPrint $1 </pre></blockquote> +<a name="structsize"></a><blockquote><pre> +System::Call '*0(p, <b>&l.r2,</b> &t2)' ; &l. is not part of the struct +DetailPrint "Struct size=$2" +</pre></blockquote> +<a name="structsizemember"></a><blockquote><pre> +System::Call '*(<b>&l4</b>,i,i,i,i,&t128)p.r1' ; Fills dwOSVersionInfoSize with the struct size as a int32 +${If} $1 Z<> 0 + System::Call 'kernel32::GetVersionEx(pr1)i.r0' + System::Call '*$1(i,i.R1,i.R2,i.R3)' + System::Free $1 + ${IfThen} $0 <> 0 ${|} DetailPrint "v$R1.$R2.$R3" ${|} +${EndIf} +</pre></blockquote> <blockquote><pre> <a name="directvarmemparam"></a>System::<b>Call</b> "user32::GetClientRect(p $hwndparent, @ r0)" System::<b>Call</b> "*$0(i,i,i.r1,i.r2)" @@ -534,8 +566,7 @@ end: </pre></blockquote> <blockquote><pre> InitPluginsDir -SetOutPath $PLUGINSDIR -File MyDLL.dll +File "/oname=$PLUGINSDIR\MyDLL.dll" MyDLL.dll System::<b>Call</b> "MyDLL::MyFunc(i 5) ? u" Delete $PLUGINSDIR\MyDLL.dll </pre></blockquote> @@ -556,6 +587,29 @@ loop: done: System::Free $R0 </pre></blockquote> +<a name="v2callback"></a><blockquote><pre> +System::Get '(m.r1)ir2r0 <b>?2</b>' ; v2 syntax +Pop $9 +System::Call 'kernel32::EnumSystemLocalesA(k r9, i 0)' +loop: + StrCmp <b>$0 "callback$9"</b> 0 done + DetailPrint "Locale: $1" + StrCpy $2 1 ; EnumLocalesProc return value + System::Call $9 ; return from EnumLocalesProc + Goto loop +done: +System::Free $9 +</pre></blockquote> +<a name="v2typealign"></a><blockquote><pre> +System::Call '*(&t50 "!")p.r2' ; DecimalSep +System::Call '*(&t50 "`")p.r3' ; ThousandSep +System::Call '*(i 2, i 0, i 3, <b>P r2, P r3</b>, i 1)p.r1 <b>?2</b>' +System::Call 'kernel32::GetNumberFormat(i 0, i 0, t "1337.666" r4, p r1, t.r5, i ${NSIS_MAX_STRLEN})' +DetailPrint "Custom formated $4: $5" +System::Free $3 +System::Free $2 +System::Free $1 +</pre></blockquote> <blockquote><pre> <a name="repeat"></a>!define MB "user32::MessageBox(p$HWNDPARENT,t,t'NSIS System Plug-in',i0)" System::<b>Call</b> "${MB}(,'my message',,)" @@ -585,7 +639,7 @@ good: <ul> <li> -<b>Int64Op</b> <i>ARG1</i> <i>OP</i> [<i>ARG2</i>] +<b id="Int64Op">Int64Op</b> <i>ARG1</i> <i>OP</i> [<i>ARG2</i>] <blockquote> <p>Performs <i>OP</i> on <i>ARG1</i> and optionally <i>ARG2</i> and returns the result on the stack. Both <i>ARG1</i> and <i>ARG2</i> are 64-bit integers. This means they can range between -2^63 and 2^63 - 1.</p> <h4>Available Operations</h4> @@ -595,18 +649,19 @@ good: <li>Multiplication -- <b>*</b></li> <li>Division -- <b>/</b></li> <li>Modulo -- <b>%</b></li> -<li>Shift right -- <b>>></b></li> <li>Shift left -- <b><<</b></li> +<li>Arithmetic shift right -- <b>>></b></li> +<li>Logical shift right -- <b>>>></b></li> <li>Bitwise or -- <b>|</b></li> <li>Bitwise and -- <b>&</b></li> <li>Bitwise xor -- <b>^</b></li> +<li>Bitwise not (one argument) -- <b>~</b></li> +<li>Logical not (one argument) -- <b>!</b></li> <li>Logical or -- <b>||</b></li> <li>Logical and -- <b>&&</b></li> <li>Less than -- <b><</b></li> <li>Equals -- <b>=</b></li> <li>Greater than -- <b>></b></li> -<li>Bitwise not (one argument) -- <b>~</b></li> -<li>Logical not (one argument) -- <b>!</b></li> </ul> <h4>Usage Examples</h4> @@ -645,6 +700,14 @@ DetailPrint "1 << 62 = $0" # 4611686018427387904 System::<b>Int64Op</b> 0x4000000000000000 >> 62 Pop $0 DetailPrint "0x4000000000000000 >> 62 = $0" # 1 + +System::<b>Int64Op</b> 0x8000000000000000 >> 1 +Pop $0 +DetailPrint "0x8000000000000000 >> 1 = $0" # -4611686018427387904 (0xC000000000000000) + +System::<b>Int64Op</b> 0x8000000000000000 >>> 1 +Pop $0 +DetailPrint "0x8000000000000000 >>> 1 = $0" # 4611686018427387904 (0x4000000000000000) </pre></blockquote> <blockquote><pre> System::<b>Int64Op</b> 0xF0F0F0F | 0xF0F0FFF |