home *** CD-ROM | disk | FTP | other *** search
/ Chip 2004 March / CMCD0304.ISO / Software / Freeware / Programare / nullsoft / nsis20.exe / Contrib / System / System.txt < prev    next >
Text File  |  2003-09-11  |  8KB  |  180 lines
  1. NSIS System Plugin
  2. (c) brainsucker (Nik Medved), 2002
  3.  
  4.         The whole system plugin and this documentation as a part could be a hard
  5. barrier for non Win32 programmers, in this case you could come to NSIS forum 
  6. (http://forums.winamp.com/forumdisplay.php?forumid=65) and ask some questions 
  7. to the people living there, they'll always help you.
  8.  
  9.         By the way, any help in writing complete and easy-to-go System plugin
  10. documentation will be appreciated.
  11.  
  12.         Note: it will be best to turn plugin unload off in case of using System
  13. plugin (SetPluginUnload alwaysoff).
  14.  
  15. ============== Main functions ==============
  16.  
  17. RESULT/PROC System::Get "Proc"
  18. RESULT/RETURN System::Call "Proc" StackArgs...
  19.  
  20. These functions return error RESULTs or PROC/RETURN in OK case.
  21. Error result is "error" and callback results are "callbackN", where N is
  22. callback index.
  23.  
  24. ============== Additional functions ==============
  25.  
  26. ----------------------------------
  27. System::Int64Op ARG1 OP1
  28. System::Int64Op ARG1 OP2 ARG2
  29. ----------------------------------
  30.         Performs operation on ARG1 and ARG2 (or on ARG1 only at single argument
  31. operator cases) and returns result on stack. Here are the OP2s: +, -, *, / DIV, 
  32. % MOD, | OR, & AND, ^ XOR, || LOGIC-OR, && LOGIC-AND, < BELOW, > ABOVE, = EQUAL. 
  33. There are only 2 OP1s: ~ (BITWISE-NOT) and ! (LOGIC-NOT).
  34.  
  35. ----------------------------------
  36. System::Alloc SIZE
  37. ----------------------------------
  38.         Allocates SIZE bytes and returns the pointer on stack.
  39.  
  40. ----------------------------------
  41. System::Copy 0 SOURCE
  42. System::Copy DESTINATION SOURCE
  43. System::Copy /SIZE 0 SOURCE 
  44. System::Copy /SIZE DESTINATION SOURCE 
  45. ----------------------------------
  46.         Copys data from source to destination, if /SIZE option and SIZE itself
  47. are undefined uses GlobalSize to determine source size. If destination is equal
  48. to 0, allocates the new memory block.
  49.  
  50. ----------------------------------
  51. System::Free ADDR
  52. ----------------------------------
  53.         Frees memory used by object at ADDR (callbacks too). 
  54.  
  55. ----------------------------------
  56. System::Store COMMAND
  57. ----------------------------------
  58.         Store operations, allows to save/restore registers, pop/push values on
  59. stack. COMMAND is string consisting of following ops:
  60.         s, S    -       push the whole registers range (to separate stack)
  61.         l, L    -       pop the whole registers range (from separate stack)
  62.         pN      -       push $N register to general nsis stack
  63.         PN      -       push $RN register to general nsis stack
  64.         rN      -       pop $N register from general nsis stack
  65.         RN      -       pop $RN register from general nsis stack
  66.  
  67. ============== Get/Call syntaxis ==============
  68.  
  69. ----------------------------------
  70. Syntax:
  71. ----------------------------------
  72.         "Proc(Params)Return?Options#Proc(Params)Return?Options..."
  73.  
  74. ----------------------------------
  75. Proc:
  76. ----------------------------------
  77.         dll::proc       -> Proc from DLL
  78.         ::addr          -> Handle to system proc (memory address)
  79.         *addr           -> Structure
  80.         *               -> New structure
  81.         IPtr->MemberIdx -> Call member with member index from interface given
  82.                            by interface pointer IPtr (IPtr will be passed to
  83.                            proc automatically, use like C++ call).
  84.         nothing         -> Dup proc, usually callback or for future defenition
  85.  
  86.         proc            -> Ready proc specification for use or redefinition
  87.  
  88.  
  89.         If in System::Call proc specification points to already existing proc,
  90. the existing proc will be adapted and executed, otherwise the new proc will be
  91. created, executed and deleted.
  92.  
  93. ----------------------------------
  94. Params syntax: 
  95. ----------------------------------
  96.         (Param1, Param2, Param3...), the number of params of proc is set
  97. to number of params at last Params section (so params cutting may ocur). If you 
  98. need to save previous Param defenition use '_' after last param at Params 
  99. section - no param cutting will ocur for it (section).
  100. Syntax of single param: "Type Source Destination", type can be omitted (previous
  101. or void will be used), each of Source and Destination can be replaced with 
  102. '.' placeholder. Any parameter can be omitted at all - previous or default 
  103. values will be used (example: "(i1,,i2)", 2nd arg omitted).
  104.  
  105.         Return section is like single param defenition, but the Source defenition is 
  106. never used, beside callback cases.
  107.  
  108. ----------------------------------
  109. Params & Return - Type:
  110. ----------------------------------
  111.         v - void (generaly for return)
  112.         i - int (includes char, byte, short, handles, pointers and so on)
  113.         l - long & large integer (know as int64)
  114.         t - text, string (LPCSTR, pointer to first character)
  115.         w - WCHAR text, or unicode string.
  116.         g - GUID
  117.         k - callback. See Callback section.
  118.  
  119.         * - pointer specifier -> the proc needs the pointer to type, affects
  120.                 next char (parameter) [ex: '*i' - pointer to int]
  121.  
  122. ----------------------------------
  123. For structures: 
  124.         & - additional meaning specificator.
  125. ----------------------------------
  126.         &v      - padding, &vN - pad for N bytes
  127.         &i      - smaller types: &i4, &i2 (short), &i1 (byte)
  128.         &l      - cumbersome, but &lN means the structure size (N bytes value),
  129.                   calculated automaticaly, outputed always as int (N could be 0).
  130.         &t      - structure contains plain text, &tN, where lenght == N bytes.
  131.         &w      - structure contains plain unicode text, &tN, 
  132.                 where lenght == (N)/2 chars = N bytes.
  133.         &g      - &gN copy N bytes of plain GUID. in fact guid size is 16 :)
  134.  
  135. ----------------------------------
  136. Params & Return - Source / Destination:
  137. ----------------------------------
  138.         . - makes no change to source
  139.         0..9 - starts numeric inline input (accepts 0..9, x, |)
  140.         " / ' / ` - starts / ends string inline input
  141.         Registers $0-$9 -> r(0..9)
  142.         Registers $R0-$R9 -> 'r(10..19)' or 'R(0..9)'
  143.         Additional regs -> c(Cmdline) d(instDir) o(Outdir) e(Exedir) a(lAng)
  144.         Stack -> s (you could pass arguments from Call line, see examples)
  145.         None -> n (0 (null) for input / specifies no output is required)
  146.  
  147. Note: If you are using inline input syntax, you shouldn't use the same quotes for
  148. quoting inlines and the whole defenition. If you need to place the
  149. same quotes into input as you used for separation of input expression just use 
  150. these characters in doubled way. For example (t "just an ""Example""!").
  151.  
  152. ----------------------------------
  153. Options:
  154.         (any option can be turned off (returned to default value) by specifing
  155.         '!' where needed, for example _stdcall cc can be turned on by '!c'):
  156. ----------------------------------
  157.         c - _cdecl calling convention (the stack restored by caller). By default
  158. stdcall calling convention is used (the stack restored by callee).
  159.         r - always return (for GET means you should pop result and proc,
  160. for CALL means you should pop result (at least)). By default result is returned
  161. for errors only (for GET you will pop either error result or right 
  162. proc, and for CALL you will get either your return or result at defined 
  163. return place.
  164.         n - no redefine. Whenever this proc will be used it will never be 
  165. redefined either by GET or CALL. This options is never inherited to childs.
  166.         s - use general Stack. Whenever the first callback defined the system
  167. starts using the temporary stacks for function calls. 
  168.         e - call GetLastError() after procedure end and push result on stack,
  169.         u - unload DLL after call (using FreeLibrary, so you'll be able to
  170. do something with it, delete for example).
  171.  
  172. ----------------------------------
  173. Callback:
  174. ----------------------------------
  175. You should check for callbacked return after every function call which can use 
  176. your callback. General scheme is:
  177.         1. Check result for callback or normal return
  178.         2. Input arguments defined for callback are at places.
  179.         3. Place output and return arguments
  180.         4. Call System::Call using callback proc handle