ext/wasm/api/sqlite3-vfs-helper.c-pp.js

   1 /*
   2 ** 2022-11-30
   3 **
   4 ** The author disclaims copyright to this source code.  In place of a
   5 ** legal notice, here is a blessing:
   6 **
   7 ** *   May you do good and not evil.
   8 ** *   May you find forgiveness for yourself and forgive others.
   9 ** *   May you share freely, never taking more than you give.
  10 */
  11
  12 /**
  13    This file installs sqlite3.vfs, a namespace of helpers for use in
  14    the creation of JavaScript implementations of sqlite3_vfs.
  15 */
  16 'use strict';
  17 globalThis.sqlite3ApiBootstrap.initializers.push(function(sqlite3){
  18   const wasm = sqlite3.wasm, capi = sqlite3.capi, toss = sqlite3.util.toss3;
  19   const vfs = Object.create(null);
  20   sqlite3.vfs = vfs;
  21
  22   /**
  23      Uses sqlite3_vfs_register() to register this
  24      sqlite3.capi.sqlite3_vfs instance. This object must have already
  25      been filled out properly. If the first argument is truthy, the
  26      VFS is registered as the default VFS, else it is not.
  27
  28      On success, returns this object. Throws on error.
  29   */
  30   capi.sqlite3_vfs.prototype.registerVfs = function(asDefault=false){
  31     if(!(this instanceof sqlite3.capi.sqlite3_vfs)){
  32       toss("Expecting a sqlite3_vfs-type argument.");
  33     }
  34     const rc = capi.sqlite3_vfs_register(this, asDefault ? 1 : 0);
  35     if(rc){
  36       toss("sqlite3_vfs_register(",this,") failed with rc",rc);
  37     }
  38     if(this.pointer !== capi.sqlite3_vfs_find(this.$zName)){
  39       toss("BUG: sqlite3_vfs_find(vfs.$zName) failed for just-installed VFS",
  40            this);
  41     }
  42     return this;
  43   };
  44
  45   /**
  46      A wrapper for
  47      sqlite3.StructBinder.StructType.prototype.installMethods() or
  48      registerVfs() to reduce installation of a VFS and/or its I/O
  49      methods to a single call.
  50
  51      Accepts an object which contains the properties "io" and/or
  52      "vfs", each of which is itself an object with following properties:
  53
  54      - `struct`: an sqlite3.StructBinder.StructType-type struct. This
  55        must be a populated (except for the methods) object of type
  56        sqlite3_io_methods (for the "io" entry) or sqlite3_vfs (for the
  57        "vfs" entry).
  58
  59      - `methods`: an object mapping sqlite3_io_methods method names
  60        (e.g. 'xClose') to JS implementations of those methods. The JS
  61        implementations must be call-compatible with their native
  62        counterparts.
  63
  64      For each of those object, this function passes its (`struct`,
  65      `methods`, (optional) `applyArgcCheck`) properties to
  66      installMethods().
  67
  68      If the `vfs` entry is set then:
  69
  70      - Its `struct` property's registerVfs() is called. The
  71        `vfs` entry may optionally have an `asDefault` property, which
  72        gets passed as the argument to registerVfs().
  73
  74      - If `struct.$zName` is falsy and the entry has a string-type
  75        `name` property, `struct.$zName` is set to the C-string form of
  76        that `name` value before registerVfs() is called. That string
  77        gets added to the on-dispose state of the struct.
  78
  79      On success returns this object. Throws on error.
  80   */
  81   vfs.installVfs = function(opt){
  82     let count = 0;
  83     const propList = ['io','vfs'];
  84     for(const key of propList){
  85       const o = opt[key];
  86       if(o){
  87         ++count;
  88         o.struct.installMethods(o.methods, !!o.applyArgcCheck);
  89         if('vfs'===key){
  90           if(!o.struct.$zName && 'string'===typeof o.name){
  91             o.struct.addOnDispose(
  92               o.struct.$zName = wasm.allocCString(o.name)
  93             );
  94           }
  95           o.struct.registerVfs(!!o.asDefault);
  96         }
  97       }
  98     }
  99     if(!count) toss("Misuse: installVfs() options object requires at least",
 100                     "one of:", propList);
 101     return this;
 102   };
 103 }/*sqlite3ApiBootstrap.initializers.push()*/);