windows-virtual-devices 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 49c2e50115117734e671b3ffbcc4e6cea74d686ae8bef707d08b123647f58b94
+  data.tar.gz: bf1c6b5b02008bd3d9c44c9a433184b3f30d1c7d38d3be04b6c3b60149d5b6c6
+SHA512:
+  metadata.gz: 70bf89b8a89f41cee28bece09dc33e775efe014c1e9ee2322943057832d280e6ac77ce0353511c7dfc7090544657f9db0b1f80a44dfa4c60a69fa855efacf79c
+  data.tar.gz: c09275cc63dbbe8c3cd3a0c65f20b31c80c46f160889415f17e12e8287b1146b4fe01d560ccdde6c6ed5c4a2c0f71f3bb4799beb69e2745f7a8e7cab886ea014

data/LICENSE

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2026 TitanCSA
+
+This license applies to the user-mode source code, examples, build scripts,
+and documentation in this repository.
+It does not apply to the prebuilt kernel
+driver, driver catalogs, or INF files under Installer/UI/Package; those files are
+covered by licenses/BINARY-LICENSE.txt. Third-party names and projects retain their own
+licenses and trademarks.
+
+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.

data/README.md

@@ -0,0 +1,12 @@
+# Windows-Virtual-Devices Ruby SDK
+
+`gem install windows-virtual-devices`
+
+Windows x64 Ruby3.1+.
+
+```ruby
+require "windows_virtual_devices"
+WindowsVirtualDevicesSDK::Client.open { |client| p client.call("status") }
+```
+
+[API and operation schema](docs/API.md). Matching driver installed separately.

data/docs/API.md

@@ -0,0 +1,16 @@
+# Device operations
+
+All operations take an argument object; absent arguments mean `{}`.
+
+- `check` and `connect`: `{speed:2,input_depth:32,delegate_controls:false,descriptors:[{kind:1,index:0,language:0,interface_number:0,data:[...]}],rules:[{setup:[8 bytes],mask:[8 bytes],action:1,data:[]}]}`. Exact descriptors define USB identity; check validates offline. Connect returns opaque decimal `handle`, actual decimal `device_id`, and token.
+- `status`: returns capabilities, licensing and devices/counters. All uint64 values use decimal strings.
+- `send`: `{handle,endpoint:129,data:[0,1,255]}` uses the explicit native endpoint overload.
+- `disconnect`: `{handle}`. Close also disconnects owned devices.
+- `receive`: `{timeout:0}`; bounded 0..100 ms per call so close cannot wait indefinitely. Poll from a worker if necessary. Returns kind, endpoint, setup, data, IDs and timed_out. Control outputs include opaque reply_handle.
+- `reply`: `{reply_handle,data:[],stall:false}`. Failed replies may be retried; successful handles become stale. Maximum 4096 outstanding control requests.
+
+JSON requests are bounded to 1 MiB, byte arrays to4096, descriptors64, rules32, devices16. Original SDK applies additional semantic validation. Unknown/stale/foreign handles fail. Operations are serialized; concurrent operations return busy. Input capture/driver operations are performed only on explicit calls. Production tests only open/close and reject an invalid config offline. Synthetic tests cover the rest without real devices.
+
+## Language client
+
+The client calls the native SDK directly. Use the call method with an operation name and argument object. Receive is synchronous and bounded to100ms; use an application worker for responsive UI/event loops. Explicitly close the client after use. 64-bit identifiers and counters are decimal strings. Native errors expose their Windows code. Matching driver and licensing are separate requirements.

data/docs/LICENSE.nlohmann-json

@@ -0,0 +1,21 @@
+MIT License 
+
+Copyright (c) 2013-2025 Niels Lohmann
+
+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.

data/lib/windows_virtual_devices.rb

@@ -0,0 +1,46 @@
+require 'json'
+require 'fiddle'
+require 'thread'
+module WindowsVirtualDevicesSDK
+  class NativeError < StandardError
+    attr_reader :code
+    def initialize(code,message);@code=code;super(message);end
+  end
+  class Client
+    def self.open(library_path: nil)
+      client=new(library_path: library_path)
+      return client unless block_given?
+      begin;yield client;ensure;client.close;end
+    end
+    def initialize(library_path: nil)
+      raise 'Windows x64 required' unless Fiddle::SIZEOF_VOIDP==8 && RUBY_PLATFORM.match?(/mingw|mswin/)
+      @library=Fiddle::Handle.new(library_path || ENV['WINDOWS_VIRTUAL_DEVICES_SDK_NATIVE_PATH'] || File.expand_path('../native/WindowsVirtualDevicesJsonSDK.dll',__dir__))
+      @mutex=Mutex.new
+      @open=Fiddle::Function.new(@library['windows_virtual_devices_json_open'],[Fiddle::TYPE_VOIDP],Fiddle::TYPE_INT)
+      @close=Fiddle::Function.new(@library['windows_virtual_devices_json_close'],[Fiddle::TYPE_LONG_LONG],Fiddle::TYPE_INT)
+      @call=Fiddle::Function.new(@library['windows_virtual_devices_json_call'],[Fiddle::TYPE_LONG_LONG,Fiddle::TYPE_VOIDP,Fiddle::TYPE_INT],Fiddle::TYPE_VOIDP)
+      @free=Fiddle::Function.new(@library['windows_virtual_devices_json_free'],[Fiddle::TYPE_VOIDP],Fiddle::TYPE_VOID)
+      out=Fiddle::Pointer.malloc(8,Fiddle::RUBY_FREE);out[0,8]=[0].pack('Q<');code=@open.call(out);raise NativeError.new(code,'Cannot open SDK') if code!=0
+      @session=out[0,8].unpack1('Q<')
+    end
+    def call(operation,arguments={})
+      payload=JSON.generate({operation:operation,arguments:arguments}).encode('UTF-8')
+      raise ArgumentError,'Request exceeds 1 MiB' if payload.bytesize>1024*1024
+      @mutex.synchronize do
+        raise 'SDK is closed' if @session==0
+        pointer=@call.call(@session,payload,payload.bytesize);raise NoMemoryError,'Native response allocation failed' if pointer.null?
+        begin;response=JSON.parse(pointer.to_s);ensure;@free.call(pointer);end
+        raise NativeError.new(response['code'],response['message']) unless response['ok']
+        response['result']
+      end
+    end
+    def close
+      @mutex.synchronize do
+        if @session!=0
+          code=@close.call(@session);raise NativeError.new(code,'Native close failed') if code!=0
+          @session=0
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: windows-virtual-devices
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- TitanCSA
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: fiddle
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+description: Product native SDK operations through a UTF-8 JSON C ABI; driver installed
+  separately.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- docs/API.md
+- docs/LICENSE.nlohmann-json
+- lib/windows_virtual_devices.rb
+- native/WindowsVirtualDevicesJsonSDK.dll
+homepage: https://github.com/titanfyre/Windows-Virtual-Devices
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/titanfyre/Windows-Virtual-Devices
+  documentation_uri: https://github.com/titanfyre/Windows-Virtual-Devices/tree/main/Windows-Virtual-Devices-Ruby-rubygems/docs
+  allowed_push_host: https://rubygems.org
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Windows x64 Windows-Virtual-Devices direct SDK
+test_files: []