From 74051c80ded454efd19adc1467f4ebaa538d2b59 Mon Sep 17 00:00:00 2001 From: kichik Date: Fri, 4 Jun 2004 16:31:45 +0000 Subject: [PATCH] new, hopefully more informative, System plug-in documentation git-svn-id: https://svn.code.sf.net/p/nsis/code/NSIS/trunk@3556 212acab6-be3b-0410-9dea-997c60f758d6 --- Contrib/System/System.html | 761 +++++++++++++++++++++++++++++++++++++ Contrib/System/System.txt | 180 --------- Docs/src/history.but | 2 +- Docs/src/usefulinfos.but | 2 +- Examples/makensis.nsi | 28 +- 5 files changed, 779 insertions(+), 194 deletions(-) create mode 100644 Contrib/System/System.html delete mode 100644 Contrib/System/System.txt diff --git a/Contrib/System/System.html b/Contrib/System/System.html new file mode 100644 index 00000000..01080c8c --- /dev/null +++ b/Contrib/System/System.html @@ -0,0 +1,761 @@ + + + +NSIS System Plug-in + + + +

NSIS System Plug-in

+

© brainsucker (Nik Medved), 2002

+ +

Table of Contents

+ + + +

Introduction

+ +

The System plug-in gives developers the ability to call any exported function from any DLL. For example, you can use it to call GetLogicalDriveStrings to get a list of available drives on the user's computer.

+ +

The System plug-in also allows the developer to allocate, free and copy memory; interact with COM objects and perform mathematical operations on 64-bit integers.

+ +

Programming knowledge is highly recommended in order to understand the System plug-in.

+ +

Usage Examples From The Archive

+ + + +

Available Functions

+ +

Memory Related Functions

+ +
+ + +
+ +

Calling Functions

+ +
+ + + +
+ +

64-bit Functions

+ +
+ + + +
+ +

FAQ

+ +
+ + + +
+ + + \ No newline at end of file diff --git a/Contrib/System/System.txt b/Contrib/System/System.txt deleted file mode 100644 index 8b4c785c..00000000 --- a/Contrib/System/System.txt +++ /dev/null @@ -1,180 +0,0 @@ -NSIS System Plugin -(c) brainsucker (Nik Medved), 2002 - - The whole system plugin and this documentation as a part could be a hard -barrier for non Win32 programmers, in this case you could come to NSIS forum -(http://forums.winamp.com/forumdisplay.php?forumid=65) and ask some questions -to the people living there, they'll always help you. - - By the way, any help in writing complete and easy-to-go System plugin -documentation will be appreciated. - - Note: it will be best to turn plugin unload off in case of using System -plugin (SetPluginUnload alwaysoff). - -============== Main functions ============== - -RESULT/PROC System::Get "Proc" -RESULT/RETURN System::Call "Proc" StackArgs... - -These functions return error RESULTs or PROC/RETURN in OK case. -Error result is "error" and callback results are "callbackN", where N is -callback index. - -============== Additional functions ============== - ----------------------------------- -System::Int64Op ARG1 OP1 -System::Int64Op ARG1 OP2 ARG2 ----------------------------------- - Performs operation on ARG1 and ARG2 (or on ARG1 only at single argument -operator cases) and returns result on stack. Here are the OP2s: +, -, *, / DIV, -% MOD, | OR, & AND, ^ XOR, || LOGIC-OR, && LOGIC-AND, < BELOW, > ABOVE, = EQUAL. -There are only 2 OP1s: ~ (BITWISE-NOT) and ! (LOGIC-NOT). - ----------------------------------- -System::Alloc SIZE ----------------------------------- - Allocates SIZE bytes and returns the pointer on stack. - ----------------------------------- -System::Copy 0 SOURCE -System::Copy DESTINATION SOURCE -System::Copy /SIZE 0 SOURCE -System::Copy /SIZE DESTINATION SOURCE ----------------------------------- - Copys data from source to destination, if /SIZE option and SIZE itself -are undefined uses GlobalSize to determine source size. If destination is equal -to 0, allocates the new memory block. - ----------------------------------- -System::Free ADDR ----------------------------------- - Frees memory used by object at ADDR (callbacks too). - ----------------------------------- -System::Store COMMAND ----------------------------------- - Store operations, allows to save/restore registers, pop/push values on -stack. COMMAND is string consisting of following ops: - s, S - push the whole registers range (to separate stack) - l, L - pop the whole registers range (from separate stack) - pN - push $N register to general nsis stack - PN - push $RN register to general nsis stack - rN - pop $N register from general nsis stack - RN - pop $RN register from general nsis stack - -============== Get/Call syntaxis ============== - ----------------------------------- -Syntax: ----------------------------------- - "Proc(Params)Return?Options#Proc(Params)Return?Options..." - ----------------------------------- -Proc: ----------------------------------- - dll::proc -> Proc from DLL - ::addr -> Handle to system proc (memory address) - *addr -> Structure - * -> New structure - IPtr->MemberIdx -> Call member with member index from interface given - by interface pointer IPtr (IPtr will be passed to - proc automatically, use like C++ call). - nothing -> Dup proc, usually callback or for future defenition - - proc -> Ready proc specification for use or redefinition - - - If in System::Call proc specification points to already existing proc, -the existing proc will be adapted and executed, otherwise the new proc will be -created, executed and deleted. - ----------------------------------- -Params syntax: ----------------------------------- - (Param1, Param2, Param3...), the number of params of proc is set -to number of params at last Params section (so params cutting may ocur). If you -need to save previous Param defenition use '_' after last param at Params -section - no param cutting will ocur for it (section). -Syntax of single param: "Type Source Destination", type can be omitted (previous -or void will be used), each of Source and Destination can be replaced with -'.' placeholder. Any parameter can be omitted at all - previous or default -values will be used (example: "(i1,,i2)", 2nd arg omitted). - - Return section is like single param defenition, but the Source defenition is -never used, beside callback cases. - ----------------------------------- -Params & Return - Type: ----------------------------------- - v - void (generaly for return) - i - int (includes char, byte, short, handles, pointers and so on) - l - long & large integer (know as int64) - t - text, string (LPCSTR, pointer to first character) - w - WCHAR text, or unicode string. - g - GUID - k - callback. See Callback section. - - * - pointer specifier -> the proc needs the pointer to type, affects - next char (parameter) [ex: '*i' - pointer to int] - ----------------------------------- -For structures: - & - additional meaning specificator. ----------------------------------- - &v - padding, &vN - pad for N bytes - &i - smaller types: &i4, &i2 (short), &i1 (byte) - &l - cumbersome, but &lN means the structure size (N bytes value), - calculated automaticaly, outputed always as int (N could be 0). - &t - structure contains plain text, &tN, where lenght == N bytes. - &w - structure contains plain unicode text, &tN, - where lenght == (N)/2 chars = N bytes. - &g - &gN copy N bytes of plain GUID. in fact guid size is 16 :) - ----------------------------------- -Params & Return - Source / Destination: ----------------------------------- - . - makes no change to source - 0..9 - starts numeric inline input (accepts 0..9, x, |) - " / ' / ` - starts / ends string inline input - Registers $0-$9 -> r(0..9) - Registers $R0-$R9 -> 'r(10..19)' or 'R(0..9)' - Additional regs -> c(Cmdline) d(instDir) o(Outdir) e(Exedir) a(lAng) - Stack -> s (you could pass arguments from Call line, see examples) - None -> n (0 (null) for input / specifies no output is required) - -Note: If you are using inline input syntax, you shouldn't use the same quotes for -quoting inlines and the whole defenition. If you need to place the -same quotes into input as you used for separation of input expression just use -these characters in doubled way. For example (t "just an ""Example""!"). - ----------------------------------- -Options: - (any option can be turned off (returned to default value) by specifing - '!' where needed, for example _stdcall cc can be turned on by '!c'): ----------------------------------- - c - _cdecl calling convention (the stack restored by caller). By default -stdcall calling convention is used (the stack restored by callee). - r - always return (for GET means you should pop result and proc, -for CALL means you should pop result (at least)). By default result is returned -for errors only (for GET you will pop either error result or right -proc, and for CALL you will get either your return or result at defined -return place. - n - no redefine. Whenever this proc will be used it will never be -redefined either by GET or CALL. This options is never inherited to childs. - s - use general Stack. Whenever the first callback defined the system -starts using the temporary stacks for function calls. - e - call GetLastError() after procedure end and push result on stack, - u - unload DLL after call (using FreeLibrary, so you'll be able to -do something with it, delete for example). - ----------------------------------- -Callback: ----------------------------------- -You should check for callbacked return after every function call which can use -your callback. General scheme is: - 1. Check result for callback or normal return - 2. Input arguments defined for callback are at places. - 3. Place output and return arguments - 4. Call System::Call using callback proc handle \ No newline at end of file diff --git a/Docs/src/history.but b/Docs/src/history.but index 8561f34e..889911c4 100644 --- a/Docs/src/history.but +++ b/Docs/src/history.but @@ -42,7 +42,7 @@ Released on February 7th, 2004 \b Improved plug-ins: \L{../Contrib/InstallOptions/Readme.html}{InstallOptions}, \L{../Contrib/NSISdl/ReadMe.txt}{NSISdl} and \L{../Contrib/Splash/splash.txt}{Splash} -\b New plug-ins: \L{../Contrib/AdvSplash/advsplash.txt}{AdvSplash}, \L{../Contrib/Banner/Readme.txt}{Banner}, \L{../Contrib/BgImage/BgImage.txt}{BgImage}, \L{../Contrib/Dialer/Dialer.txt}{Dialer}, \L{../Examples/languages.nsi}{LangDLL}, \L{../Contrib/Math/Math.txt}{Math}, \L{../Contrib/nsExec/nsExec.txt}{nsExec}, \L{../Contrib/StartMenu/Readme.txt}{StartMenu}, \L{../Contrib/System/System.txt}{System}, \L{../Contrib/UserInfo/UserInfo.nsi}{UserInfo} and \L{../Contrib/VPatch/Readme.html}{VPatch} +\b New plug-ins: \L{../Contrib/AdvSplash/advsplash.txt}{AdvSplash}, \L{../Contrib/Banner/Readme.txt}{Banner}, \L{../Contrib/BgImage/BgImage.txt}{BgImage}, \L{../Contrib/Dialer/Dialer.txt}{Dialer}, \L{../Examples/languages.nsi}{LangDLL}, \L{../Contrib/Math/Math.txt}{Math}, \L{../Contrib/nsExec/nsExec.txt}{nsExec}, \L{../Contrib/StartMenu/Readme.txt}{StartMenu}, \L{../Contrib/System/System.html}{System}, \L{../Contrib/UserInfo/UserInfo.nsi}{UserInfo} and \L{../Contrib/VPatch/Readme.html}{VPatch} \b New and improved utilities: \L{../Contrib/Makensisw/Readme.txt}{MakeNSISw}, NSIS Menu (NSIS.exe), NSIS Update (Bin\\NSIS Update.exe) and zip2exe (Bin\\zip2exe.exe) diff --git a/Docs/src/usefulinfos.but b/Docs/src/usefulinfos.but index 882025c2..b3b1ec81 100644 --- a/Docs/src/usefulinfos.but +++ b/Docs/src/usefulinfos.but @@ -194,7 +194,7 @@ System.dll recognises the following data types: \b b - boolean (needs/returns 'true':'false') - by the fact this type is senseless -> usual integer can be used ('0':'1') -\b k - callback. See Callback section in system.txt. +\b k - callback. See Callback section in system.html. \b * - pointer specifier -> the proc needs the pointer to type, affects next char (parameter) [ex: '*i' - pointer to int] diff --git a/Examples/makensis.nsi b/Examples/makensis.nsi index 29394585..8e9aaa1b 100644 --- a/Examples/makensis.nsi +++ b/Examples/makensis.nsi @@ -539,6 +539,7 @@ Section "System" SecPluginsSystem File ..\Contrib\System\*.nsh File ..\Contrib\System\*.nsi File ..\Contrib\System\*.txt + File ..\Contrib\System\*.html SectionEnd Section "StartMenu" SecPluginsStartMenu @@ -1058,17 +1059,16 @@ Section -post CreateDirectory $SMPROGRAMS\NSIS\Contrib CreateShortCut "$SMPROGRAMS\NSIS\Contrib\MakeNSISW readme.lnk" "$INSTDIR\contrib\MakeNsisw\readme.txt" - Push "MakeNSISW" + Push MakeNSISW Call AddWorkspaceToStartMenu ; ExDLL - Push "ExDLL" + Push ExDLL Call AddWorkspaceToStartMenu ; InstallOptions - Push "InstallOptions\Readme.html" - Push "InstallOptions Readme" - Call AddContribToStartMenu + Push InstallOptions + Call AddReadmeToStartMenu Push "InstallOptions\io.dsw" Push "Source\InstallOptions project workspace" @@ -1082,9 +1082,8 @@ Section -post Call AddWorkspaceToStartMenu ; Modern UI - Push "Modern UI\Readme.html" - Push "Modern UI Readme" - Call AddContribToStartMenu + Push "Modern UI" + Call AddReadmeToStartMenu ; Splash Push Splash @@ -1160,9 +1159,8 @@ Section -post Call AddContribToStartMenu ; VPatch - Push "VPatch\Readme.html" - Push "VPatch Readme" - Call AddContribToStartMenu + Push VPatch + Call AddReadmeToStartMenu no_startshortcuts: !endif @@ -1384,8 +1382,14 @@ Function AddReadmeToStartMenu IfFileExists $INSTDIR\Contrib\$0\$0.txt 0 +3 Push $0\$0.txt Goto create - IfFileExists $INSTDIR\Contrib\$0\Readme.txt 0 done + IfFileExists $INSTDIR\Contrib\$0\$0.html 0 +3 + Push $0\$0.html + Goto create + IfFileExists $INSTDIR\Contrib\$0\Readme.txt 0 +3 Push $0\Readme.txt + Goto create + IfFileExists $INSTDIR\Contrib\$0\Readme.html 0 done + Push $0\Readme.html create: Push "$0 Readme" Call AddContribToStartMenu