koffi 2.10.1 → 2.11.0

package/doc/assets.ini

@@ -11,7 +11,7 @@ Ignore = favicon.png *.js *.css
 
 [static/site.min.js]
 Type = Bundle
-Source = flaat/flaat.js
+Source = flat/static.js
 
 [static/highlight.min.js]
 Type = Bundle

package/doc/{flaat/flaat.css → flat/flat.css}

@@ -20,6 +20,8 @@
    OTHER DEALINGS IN THE SOFTWARE. */
 
 @import url('../../../vendor/opensans/OpenSans.css');
+@import url('./reset.css');
+
 @import url('./normal.css');
 @import url('./small.css');
 @import url('./print.css');

package/doc/{flaat → flat}/normal.css

@@ -20,9 +20,16 @@
    OTHER DEALINGS IN THE SOFTWARE. */
 
 html {
+    --top_color: #ccc;
+    --anchor_color: #383838;
+    --button_color: #888;
+    --focus_color: #ececec;
+
     --top_height: 90px;
     --top_padding: 6px;
     --small_height: 80px;
+    --top_background: white;
+    --footer_background: #f6f6f9;
 
     height: 100%;
     scroll-padding-top: calc(var(--top_height) + 10px);
@@ -44,8 +51,13 @@ body {
     flex-direction: column;
 }
 
+canvas:focus {
+    border: none;
+    outline: none;
+}
+
 a {
-    color: var(--primary_color, #383838);
+    color: var(--color, var(--anchor_color));
     cursor: pointer;
     text-decoration: none;
 }
@@ -55,9 +67,9 @@ a:has(> img) { text-decoration: none !important; }
 #top {
     position: sticky;
     top: 0;
-    background: white;
+    background: var(--top_background);
     z-index: 9;
-    border-bottom: 2px solid white;
+    border-bottom: 2px solid var(--top_background);
     transition: border-bottom-color 0.4s ease;
 }
 #top.border { border-bottom-color: #383838; }
@@ -94,14 +106,20 @@ a:has(> img) { text-decoration: none !important; }
     display: block;
     border-bottom: 1px solid #383838;
     text-transform: uppercase;
+    text-wrap: nowrap;
 }
 #top li > a:hover, #top li.active > a {
     margin-bottom: -1px;
-    border-bottom: 2px solid var(--primary_color);
+    border-bottom: 2px solid var(--top_color);
+    color: var(--top_color);
+}
+#top li > a.active {
+    font-weight: bold;
+    border-bottom-color: var(--top_color);
+    color: var(--top_color);
 }
-#top li > a.active { font-weight: bold; }
 #top li > div { display: none; }
-.nojs #top li:has(> div):hover, #top li:has(> div).active { border-left-color: var(--primary_color); }
+.nojs #top li:has(> div):hover, #top li:has(> div).active { border-left-color: var(--top_color); }
 .nojs #top li:has(> div):hover > a, #top li:has(> div).active > a {
     margin-bottom: 1px;
     border-bottom: none;
@@ -114,9 +132,9 @@ a:has(> img) { text-decoration: none !important; }
     padding: 12px 1em 10px 1em;
     display: flex;
     flex-direction: column;
-    background: white;
-    border-left: 2px solid var(--primary_color);
-    border-bottom: 2px solid var(--primary_color);
+    background: var(--top_background);
+    border-left: 2px solid var(--top_color);
+    border-bottom: 2px solid var(--top_color);
 }
 #top li > div > a { margin-top: 3px; }
 #top li > div > a.active { font-weight: bold; }
@@ -126,7 +144,6 @@ a:has(> img) { text-decoration: none !important; }
     height: 70%;
     object-fit: contain;
     margin-right: 2em;
-    transition: filter 0.4s ease;
 }
 #logo > img {
     width: 100%;
@@ -163,7 +180,7 @@ a:has(> img) { text-decoration: none !important; }
 #side a.lv5 { padding-left: 72px; }
 #side a.lv6 { padding-left: 87px; }
 
-#deploy { display: none; }
+:is(#deploy, .deploy) { display: none; }
 
 main {
     flex: 1;
@@ -177,7 +194,7 @@ main {
 
 footer {
     padding: 0.5em;
-    background: #f6f6f9;
+    background: var(--footer_background);
     display: flex;
     gap: 1.5em;
     align-items: center;
@@ -222,55 +239,131 @@ h3 {
 * + h1, * + h2, * + h3 { margin-top: 1.2em; }
 
 table {
-    margin: 1em auto;
+    margin: 0 auto;
     border-collapse: collapse;
+    empty-cells: show;
 }
-th {
+* + table { margin-top: 1em; }
+tr {
+    border-bottom: 1px solid #ededf0;
+    vertical-align: middle;
+}
+th, td {
+    height: 1.5em;
     padding: 0.5em;
-    background: #fafafa;
+    vertical-align: middle;
+}
+th {
+    background: #f8f8f8;
+    font-size: 0.9em;
+    font-variant: small-caps;
+    text-align: left;
+    user-select: none;
+    -webkit-user-select: none;
+}
+td {
+    background: white;
     border: 1px solid #ebebeb;
 }
+thead > tr { border: 1px solid #ededf0; }
 thead th { text-align: center; }
 tbody th {
     text-align: left;
     font-weight: normal;
     font-style: italic;
 }
-td {
-    padding: 0.5em;
-    background: white;
-    border: 1px solid #ebebeb;
-}
 th.center, td.center { text-align: center; }
 th.right, td.right { text-align: right; }
-
+table :is(td, th, col).check { width: 2em; }
+table :is(td, th).center { text-align: center; }
+table :is(td, th).right { text-align: right; }
+table :is(tr, td, th, col).missing {
+    font-style: italic;
+    color: var(--color, gray);
+}
+table :is(td, th).picture { padding: 6px 0 0 6px; }
+table :is(td, th).picture > img {
+    width: 24px;
+    height: 24px;
+}
 table + div.legend {
-    margin-top: calc(-1em + 2px);
+    margin-top: 6px;
     text-align: center;
     font-size: 0.8em;
 }
 
-.buttons {
-    margin: 1em;
+hr {
+    margin: 4px auto;
+    width: 90%;
+    border: none;
+    border-bottom: 1px solid #ededf0;
+}
+
+button {
+    padding: 0.35em 1em 0.45em 1em;
+    background: var(--button_color);
+    border: none;
+    border-radius: 10px;
+    color: white;
+    cursor: pointer;
+    white-space: nowrap;
+}
+button::-moz-focus-inner { border: 0; }
+button:not(:disabled):not(.active):hover {
+    background: color-mix(in srgb, var(--button_color) 90%, black);
+    color: white;
+}
+button:disabled {
+    filter: saturate(10%) brightness(80%);
+    cursor: not-allowed;
+    pointer-events: none;
+}
+button:disabled > * { opacity: 0.3; }
+button.active { background: color-mix(in srgb, var(--button_color) 50%, black); }
+button > img {
+    width: 16px;
+    height: 16px;
+    transform: translateY(2px);
+}
+button > img:only-child {
+    width: 32px;
+    height: 32px;
+    transform: translateY(4px);
+}
+
+.actions {
     display: flex;
+    margin-top: 1em;
     gap: 20px;
     justify-content: center;
+    align-items: start;
     flex-wrap: wrap;
 }
-.buttons > a {
+.actions + * { margin-top: 1em; }
+.actions > :is(a, button) {
     display: block;
-    width: 40%;
-    min-width: 250px;
-    background: var(--secondary_color);
+    width: 30%;
+    min-width: 10em;
+    background: var(--button_color);
     color: white;
-    padding: 0.6em 1em;
+    padding: 0.35em 2em 0.45em 2em;
     text-decoration: none;
     text-align: center;
 }
-.buttons > a:hover {
-    filter: brightness(80%) contrast(150%);
+.actions > :is(a, button):hover {
+    background: color-mix(in srgb, var(--button_color) 90%, black);
     color: white;
 }
+.actions > :is(a, button).disabled {
+    pointer-events: none;
+    filter: saturate(10%) brightness(50%);
+}
+
+span.warning { color: var(--color, red); }
+span.warning:before {
+    content: "⚠\FE0E";
+    margin-right: 2px;
+}
 
 code:not(.hljs) {
     padding: 2px 6px;

package/doc/{flaat → flat}/print.css

@@ -22,8 +22,7 @@
 @media print {
     #top { display: none; }
     #side { display: none; }
-
-    main { padding-right: 16px !important; }
+    #side ~ main { padding-right: 16px; }
     footer { display: none; }
 
     h1:not(:first-child) { break-before: page; }

package/doc/flat/reset.css

@@ -0,0 +1,41 @@
+/* Copyright (C) 2024  Niels Martignène <niels.martignene@protonmail.com>
+
+   Permission is hereby granted, free of charge, to any person obtaining a copy of
+   this software and associated documentation files (the “Software”), to deal in
+   the Software without restriction, including without limitation the rights to use,
+   copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+   Software, and to permit persons to whom the Software is furnished to do so,
+   subject to the following conditions:
+
+   The above copyright notice and this permission notice shall be included in all
+   copies or substantial portions of the Software.
+
+   THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
+   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+   OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+   NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+   HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+   WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+   FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+   OTHER DEALINGS IN THE SOFTWARE. */
+
+/* -------------------- Normalization -------------------- */
+
+button, input, optgroup, select, textarea {
+    box-sizing: border-box;
+    font-family: inherit;
+    font-size: 100%;
+}
+input[type='checkbox'], input[type='radio'] { vertical-align: -2px; }
+
+a { cursor: pointer; }
+
+p { margin: 0; }
+p + p { margin-top: 1em; }
+
+/* -------------------- Miscellaneous -------------------- */
+
+.disabled, .disabled * {
+    pointer-events: none !important;
+    user-select: none !important;
+}

package/doc/{flaat → flat}/small.css

@@ -27,7 +27,9 @@
         position: static;
     }
 
-    main { padding-right: 16px !important; }
+    #side ~ main { padding-right: 16px; }
+
+    button > span { display: none; }
 }
 
 @media screen and (max-width: 960px) {
@@ -35,6 +37,7 @@
 
     #top menu {
         height: var(--small_height);
+        padding-top: 16px;
         padding-left: 60px;
         flex-direction: column;
         gap: 0;
@@ -76,7 +79,7 @@
     .js #top.active #logo { display: none; }
     .nojs #top:hover #logo { display: none; }
 
-    #deploy {
+    :is(#deploy, .deploy) {
         display: block !important;
         position: fixed;
         width: 42px;

package/doc/{flaat/flaat.js → flat/static.js}

@@ -18,18 +18,18 @@ window.addEventListener('load', e => {
     initMenu();
     initSide();
     initScroll();
-
-    document.documentElement.classList.remove('nojs');
-    document.documentElement.classList.add('js');
 });
 
 function initDeploy() {
-    let deploy = document.querySelector('#deploy');
+    let el = document.querySelector('#deploy');
 
-    deploy.addEventListener('click', e => {
-        let top = document.querySelector('nav#top');
-        top.classList.toggle('active');
-    });
+    if (el != null)
+        el.addEventListener('click', deploy);
+}
+
+function deploy() {
+    let top = document.querySelector('nav#top');
+    top.classList.toggle('active');
 }
 
 function initMenu() {
@@ -99,10 +99,13 @@ function initSide() {
         if (ignore_scroll)
             return;
 
+        let style = window.getComputedStyle(document.documentElement);
+        let treshold = parseFloat(style.getPropertyValue('scroll-padding-top')) + 10;
+
         let idx;
         for (idx = 0; idx < items.length; idx++) {
             let rect = items[idx][1].getBoundingClientRect();
-            if (rect.top >= 50)
+            if (rect.top >= treshold)
                 break;
         }
         if (idx)
@@ -139,7 +142,9 @@ function initScroll() {
 
     function adjust_top() {
         let top = document.querySelector('nav#top');
-        top.classList.toggle('border', window.pageYOffset >= 20);
+
+        if (top != null)
+            top.classList.toggle('border', window.pageYOffset >= 20);
     }
 }
 
@@ -148,3 +153,9 @@ function findParent(el, func) {
         el = el.parentElement;
     return el;
 }
+
+
+document.documentElement.classList.remove('nojs');
+document.documentElement.classList.add('js');
+
+export { deploy }

package/doc/pages/contribute.md

@@ -2,7 +2,7 @@
 
 Use the official repository for bugs, ideas and features requests: https://github.com/Koromix/koffi
 
-Please note that the source code is not in this repository, instead it lives in a monorepo: https://github.com/Koromix/rygel/ (in the *src/koffi* subdirectory).
+Please note that the source code is not in this repository, instead it lives in a monorepo: https://codeberg.org/Koromix/rygel/ (in the *src/koffi* subdirectory).
 
 # Build from source
 
@@ -11,7 +11,7 @@ We provide prebuilt binaries, packaged in the NPM archive, so in most cases it s
 Start by cloning the repository with [Git](https://git-scm.com/):
 
 ```sh
-git clone https://github.com/Koromix/rygel
+git clone https://codeberg.org/Koromix/rygel
 cd rygel
 ```
 
@@ -145,4 +145,4 @@ Koffi is programmed in a mix of C++ and assembly code (architecture-specific cod
 
 My personal preference goes to a rather C-like C++ style, with careful use of templates (mainly for containers) and little object-oriented programming. I strongly prefer tagged unions and code locality over inheritance and virtual methods. Exceptions are disabled.
 
-Find more information about code style in the [monorepository README](https://github.com/Koromix/rygel/?tab=readme-ov-file#c-flavor) file.
+Find more information about code style in the [monorepository README](https://codeberg.org/Koromix/rygel/#c-flavor) file.

package/doc/pages/output.md

@@ -17,6 +17,13 @@ The same can be done when declaring a function with a C-like prototype string, w
 - `_Out_` for output parameters
 - `_Inout_` for dual input/output parameters
 
+> [!TIP]
+> The Win32 API provides many functions that take a pointer to an empty struct for output, except that the first member of the struct (often named `cbSize`) must be set to the size of the struct before calling the function. An example of such a function is `GetLastInputInfo()`.
+>
+> In order to use these functions in Koffi, you must define the parameter as `_Inout_`: the value must be copied in (to provide `cbSize` to the function) and then the filled struct must be copied out to JS.
+>
+> Look at the [Win32 example](#win32-struct-example) below for more information.
+
 ## Primitive value
 
 This Windows example enumerate all Chrome windows along with their PID and their title. The `GetWindowThreadProcessId()` function illustrates how to get a primitive value from an output argument.
@@ -73,7 +80,9 @@ for (let hwnd = null;;) {
 }
 ```
 
-## Struct example
+## Struct examples
+
+### POSIX struct example
 
 This example calls the POSIX function `gettimeofday()`, and uses the prototype-like syntax.
 
@@ -101,6 +110,28 @@ gettimeofday(tv, null);
 console.log(tv);
 ```
 
+### Win32 struct example
+
+Many Win32 functions that use struct outputs require you to set a size member (often named `cbSize`). These functions won't work with `_Out_` because the size value must be copied from JS to C, use `_Inout_` in this case.
+
+```js
+// ES6 syntax: import koffi from 'koffi';
+const koffi = require('koffi');
+
+const user32 = koffi.load('user32.dll');
+
+const LASTINPUTINFO = koffi.struct('LASTINPUTINFO', {
+    cbSize: 'uint',
+    dwTime: 'uint32'
+});
+const GetLastInputInfo = user32.func('bool __stdcall GetLastInputInfo(_Inout_ LASTINPUTINFO *plii)');
+
+let info = { cbSize: koffi.sizeof(LASTINPUTINFO) };
+let success = GetLastInputInfo(info);
+
+console.log(success, info);
+```
+
 ## Opaque type example
 
 This example opens an in-memory SQLite database, and uses the node-ffi-style function declaration syntax.

package/doc/pages/packaging.md

@@ -53,7 +53,7 @@ In this case, you can use `require('koffi/indirect')` but you will need to make
 
 Packaging with electron-builder should work as-is.
 
-Take a look at the full [working example in the repository](https://github.com/Koromix/rygel/tree/master/src/koffi/examples/electron-builder).
+Take a look at the full [working example in the repository](https://codeberg.org/Koromix/rygel/src/branch/master/src/koffi/examples/electron-builder).
 
 ## Electron Forge
 
@@ -63,13 +63,13 @@ Packaging with Electron Force should work as-is, even when using webpack as conf
 npm init electron-app@latest my-app -- --template=webpack
 ```
 
-Take a look at the full [working example in the repository](https://github.com/Koromix/rygel/tree/master/src/koffi/examples/electron-forge).
+Take a look at the full [working example in the repository](https://codeberg.org/Koromix/rygel/src/branch/master/src/koffi/examples/electron-forge).
 
 ## NW.js
 
 Packagers such as nw-builder should work as-is.
 
-You can find a full [working example in the repository](https://github.com/Koromix/rygel/tree/master/src/koffi/examples/nwjs).
+You can find a full [working example in the repository](https://codeberg.org/Koromix/rygel/src/branch/master/src/koffi/examples/nwjs).
 
 ## Node.js and esbuild
 
@@ -79,10 +79,10 @@ You can easily tell esbuild to copy the native files with the copy loader and th
 esbuild index.js --platform=node --bundle --loader:.node=copy --outdir=dist/
 ```
 
-You can find a full [working example in the repository](https://github.com/Koromix/rygel/tree/master/src/koffi/examples/node-esbuild).
+You can find a full [working example in the repository](https://codeberg.org/Koromix/rygel/src/branch/master/src/koffi/examples/node-esbuild).
 
 ## Node.js and yao-pkg
 
 Use [yao-pkg](https://github.com/yao-pkg/pkg) to make binary packages of your Node.js-based project.
 
-You can find a full [working example in the repository](https://github.com/Koromix/rygel/tree/master/src/koffi/examples/yao-pkg).
+You can find a full [working example in the repository](https://codeberg.org/Koromix/rygel/src/branch/master/src/koffi/examples/yao-pkg).

package/doc/pages/pointers.md

@@ -248,6 +248,15 @@ Disposable types can only be created from pointer or string types.
 > [!WARNING]
 > Be careful on Windows: if your shared library uses a different CRT (such as msvcrt), the memory could have been allocated by a different malloc/free implementation or heap, resulting in undefined behavior if you use `koffi.free()`.
 
+# External buffers (views)
+
+*New in Koffi 2.11.0*
+
+You can access unmanaged memory with `koffi.view(ptr, len)`. This function takes a pointer and a length, and creates an ArrayBuffer through which you can access the underlying memory without copy.
+
+> [!NOTE]
+> Some runtimes (such as Electron) forbid the use of external buffers. In this case, trying to create a view will trigger an exception.
+
 # Unwrap pointers
 
 You can use `koffi.address(ptr)` on a pointer to get the numeric value as a [BigInt object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt).

package/doc/static/koffi.css

@@ -13,9 +13,10 @@
    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <https://www.gnu.org/licenses/>. */
 
-@import url('../flaat/flaat.css');
+@import url('../flat/flat.css');
 @import url('../../../vendor/highlight.js/styles/base16/tomorrow.css');
 
 html {
-    --primary_color: #ec7400;
+    --top_color: #ec7400;
+    --anchor_color: #ec7400;
 }

package/index.js

@@ -363,8 +363,8 @@ var require_package = __commonJS({
   "../../bin/Koffi/package/src/koffi/package.json"(exports2, module2) {
     module2.exports = {
       name: "koffi",
-      version: "2.10.1",
-      stable: "2.10.1",
+      version: "2.11.0",
+      stable: "2.11.0",
       description: "Fast and simple C FFI (foreign function interface) for Node.js",
       keywords: [
         "foreign",

package/indirect.js

@@ -363,8 +363,8 @@ var require_package = __commonJS({
   "../../bin/Koffi/package/src/koffi/package.json"(exports2, module2) {
     module2.exports = {
       name: "koffi",
-      version: "2.10.1",
-      stable: "2.10.1",
+      version: "2.11.0",
+      stable: "2.11.0",
       description: "Fast and simple C FFI (foreign function interface) for Node.js",
       keywords: [
         "foreign",

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "koffi",
-    "version": "2.10.1",
-    "stable": "2.10.1",
+    "version": "2.11.0",
+    "stable": "2.11.0",
     "description": "Fast and simple C FFI (foreign function interface) for Node.js",
     "keywords": [
         "foreign",