zxing_ffi 0.1.0

data/lib/zxing_ffi/loaders/vips.rb

@@ -0,0 +1,332 @@
+# frozen_string_literal: true
+
+module ZXingFFI
+  module Loaders
+    # In-process loader built on libvips via the optional ruby-vips gem: rasters, and PDFs as a fallback.
+    #
+    # Every input is opened with the libvips loader matching its sniffed kind (e.g. +pngload+), so libvips never
+    # re-detects a different format from the content. Operations libvips flags as *untrusted* (in libvips 8.18:
+    # +pdfload+, +magickload+, +ppmload+) are refused while +config.vips_block_untrusted+ is true (the default); this
+    # gives the protection of +vips_block_untrusted_set+ without changing libvips' process-global state.
+    # Consequently vips renders PDFs only after opting in with +vips_block_untrusted = false+ — and a crash in
+    # libvips or poppler-glib then takes down the Ruby process.
+    #
+    # Documents are safe to render concurrently (each render builds its own libvips pipeline).
+    class VipsLoader < Base
+      # Sniffed kind => libvips load operation.
+      OPERATIONS = {
+        png: "pngload", jpeg: "jpegload", tiff: "tiffload", gif: "gifload", webp: "webpload",
+        heif: "heifload", avif: "heifload", pnm: "ppmload", bmp: "magickload", pdf: "pdfload"
+      }.freeze
+
+      # Loaders that take a +page:+ argument.
+      PAGED = %w[tiffload gifload webpload heifload pdfload magickload].freeze
+
+      # VIPS_OPERATION_UNTRUSTED in VipsOperationFlags.
+      UNTRUSTED_FLAG = 16
+
+      # Resolutions (pixels per inch) differing by more than this ratio are corrected.
+      ASPECT_TOLERANCE = 0.05
+
+      class << self
+        # (see Base.loader_name)
+        def loader_name = :vips
+
+        # (see Base.kinds)
+        def kinds = OPERATIONS.keys
+
+        # (see Base.install_hint)
+        def install_hint
+          "install libvips (brew install vips / apt install libvips-tools) and the ruby-vips gem"
+        end
+
+        # Whether this libvips can load +kind+ right now (operation present and, unless opted in, trusted).
+        def supports?(kind)
+          operation = OPERATIONS[kind.to_sym]
+          return false unless operation && available? && operation?(operation)
+
+          !(ZXingFFI.config.vips_block_untrusted && untrusted?(operation))
+        end
+
+        # (see Base.unsupported_reason)
+        def unsupported_reason(kind)
+          operation = OPERATIONS[kind.to_sym]
+          return nil unless operation && available?
+          return "this libvips has no #{operation}" unless operation?(operation)
+          return nil unless ZXingFFI.config.vips_block_untrusted && untrusted?(operation)
+
+          "libvips flags #{operation} as untrusted; it is refused while config.vips_block_untrusted is true " \
+            "(set it to false to allow it)"
+        end
+
+        # (see Base.diagnostics)
+        def diagnostics
+          return super unless available?
+
+          super.merge(
+            version: ::Vips.version_string,
+            block_untrusted: ZXingFFI.config.vips_block_untrusted,
+            untrusted_operations: OPERATIONS.values.uniq.select { |op| operation?(op) && untrusted?(op) }
+          )
+        end
+
+        # @api private
+        def operation?(name)
+          @operations ||= {}
+          return @operations[name] if @operations.key?(name)
+
+          @operations[name] = ::Vips.type_find("VipsOperation", name) != 0
+        end
+
+        # @api private
+        def untrusted?(name)
+          @untrusted ||= {}
+          return @untrusted[name] if @untrusted.key?(name)
+
+          @untrusted[name] = (::Vips.vips_operation_get_flags(::Vips::Operation.new(name)) & UNTRUSTED_FLAG) != 0
+        end
+
+        # (see Base.reset!)
+        def reset!
+          super
+          @operations = nil
+          @untrusted = nil
+        end
+
+        private
+
+        def probe
+          require "vips"
+          true
+        rescue LoadError, StandardError => e
+          @unavailable_reason = "ruby-vips/libvips not loadable (#{e.class}: #{e.message.lines.first&.strip})"
+          false
+        end
+      end
+
+      # (see Base#open)
+      def open(source, password: nil)
+        unless self.class.supports?(source.kind)
+          raise LoaderUnavailable, "libvips cannot load #{source.kind} here (missing or untrusted #{OPERATIONS[source.kind]})"
+        end
+
+        if source.kind == :pdf
+          PdfDocument.new(source, config, password)
+        else
+          RasterDocument.new(source, config, OPERATIONS.fetch(source.kind))
+        end
+      end
+
+      # Shared helpers for libvips-backed documents.
+      module Pipeline
+        # Loads +path+ with +operation+ without libvips' operation cache handing back a stale image: libvips caches
+        # loads by file name, so a file overwritten at the same path would otherwise decode as its old contents
+        # (e.g. an upload handler reusing a temp path). libvips ≥ 8.15 has +revalidate+; older versions load from a
+        # buffer, which is never served from the file-name cache.
+        # @api private
+        def self.load_fresh(operation, path, **options)
+          ::Vips.vips_error_clear # see error_summary
+          if ::Vips.at_least_libvips?(8, 15)
+            ::Vips::Image.public_send(operation, path, revalidate: true, **options)
+          else
+            ::Vips::Image.public_send(:"#{operation}_buffer", File.binread(path), **options)
+          end
+        end
+
+        # The cause of a libvips failure. A +Vips::Error+'s message is libvips' process-wide error buffer, oldest line
+        # first, and successful calls can leave warnings there (e.g. heifload's "bad seek"); so the buffer is cleared
+        # before our calls and the last lines are the ones that describe this failure.
+        # @api private
+        def self.error_summary(error, lines: 3)
+          error.message.lines.map(&:strip).reject(&:empty?).last(lines).join(" ")
+        end
+
+        private
+
+        def vips_call
+          ::Vips.vips_error_clear
+          yield
+        rescue ::Vips::Error => e
+          raise RenderError.new("libvips failed on #{source.name}: #{Pipeline.error_summary(e)}", stderr: e.message[0, 4096])
+        end
+
+        # Flattens alpha onto white, converts to 8-bit single-band luminance and copies it into an Image.
+        def to_image(vimage)
+          check_pixels!(vimage.width, vimage.height)
+          if vimage.has_alpha?
+            white = %i[ushort short].include?(vimage.format) ? 65_535 : 255
+            vimage = vimage.flatten(background: [white])
+          end
+          vimage = vimage.colourspace(:b_w) unless vimage.interpretation == :"b-w" && vimage.format == :uchar
+          vimage = vimage.extract_band(0) if vimage.bands > 1
+          vimage = vimage.cast(:uchar) unless vimage.format == :uchar
+          Image.new(vimage.write_to_memory, width: vimage.width, height: vimage.height)
+        end
+
+        def check_pixels!(width, height)
+          pixels = width * height
+          return unless @config.max_pixels && pixels > @config.max_pixels
+
+          raise LimitExceeded.new("#{width}x#{height} (#{pixels} pixels) exceeds max_pixels #{@config.max_pixels}",
+            limit: :max_pixels, value: pixels)
+        end
+      end
+
+      # A raster file: one page per frame (multi-page TIFF, animated GIF/WebP, HEIF collections).
+      class RasterDocument < Document
+        include Pipeline
+
+        def initialize(source, config, operation)
+          super(source)
+          @config = config
+          @operation = operation
+          header = load(0)
+          @page_count = (header.get_typeof("n-pages") != 0) ? [header.get("n-pages"), 1].max : 1
+          @infos = {}
+          @mutex = Mutex.new
+        end
+
+        attr_reader :page_count
+
+        # (see Document#page_info)
+        def page_info(number)
+          check_page!(number)
+          @mutex.synchronize { @infos[number] ||= build_info(number) }
+        end
+
+        # Applies the normalization contract: aspect correction (on the stored axes, because libvips'
+        # autorot does not swap xres/yres), EXIF orientation, alpha → white, 16-bit scaling, 8-bit gray.
+        def render(number, dpi: nil, timeout: nil) # timeout: in-process, cannot be enforced
+          check_page!(number)
+          vips_call do
+            vimage = load(number - 1)
+            vimage, aspect = correct_aspect(vimage)
+            orientation = orientation_of(vimage)
+            orientation = nil if orientation == 1 # "normal": nothing to apply
+            vimage = vimage.autorot if orientation
+            image = to_image(vimage)
+            Page.new(number: number, image: image, dpi: nil, scale_to_base: 1.0, metadata: {
+              loader: :vips, orientation_applied: orientation, aspect_corrected: aspect
+            })
+          end
+        end
+
+        private
+
+        def load(index)
+          vips_call do
+            options = PAGED.include?(@operation) ? {page: index} : {}
+            Pipeline.load_fresh(@operation, source.path, **options)
+          end
+        end
+
+        def build_info(number)
+          vimage = load(number - 1)
+          width, height = corrected_size(vimage)
+          orientation = orientation_of(vimage)
+          width, height = height, width if [5, 6, 7, 8].include?(orientation)
+          PageInfo.new(number: number, width: width, height: height, unit: :px,
+            rotation: {3 => 180, 6 => 90, 8 => 270}.fetch(orientation, 0), native_ppi: ppi(vimage))
+        end
+
+        def orientation_of(vimage)
+          (vimage.get_typeof("orientation") != 0) ? vimage.get("orientation") : nil
+        end
+
+        # libvips resolutions are pixels per millimetre; 1.0 px/mm is its "unknown" default.
+        def resolutions(vimage)
+          x = vimage.xres * 25.4
+          y = vimage.yres * 25.4
+          (x > 25.5 || y > 25.5) ? [x, y] : nil
+        end
+
+        def ppi(vimage)
+          res = resolutions(vimage)
+          res&.max&.round(2)
+        end
+
+        def aspect_scale(vimage)
+          x, y = resolutions(vimage)
+          return nil unless x && y && x.positive? && y.positive?
+          return nil if (x - y).abs / [x, y].max <= ASPECT_TOLERANCE
+
+          (x < y) ? [y / x, 1.0] : [1.0, x / y]
+        end
+
+        def corrected_size(vimage)
+          hscale, vscale = aspect_scale(vimage) || [1.0, 1.0]
+          [(vimage.width * hscale).round, (vimage.height * vscale).round]
+        end
+
+        # Resamples the lower-resolution axis up (standard fax: 204×98 DPI is stored squashed 2:1).
+        def correct_aspect(vimage)
+          hscale, vscale = aspect_scale(vimage)
+          return [vimage, nil] unless hscale
+
+          width, height = corrected_size(vimage)
+          check_pixels!(width, height)
+          resized = vimage.resize(hscale, vscale: vscale, kernel: :linear)
+          [resized, resolutions(vimage).map { |r| r.round(1) }]
+        end
+      end
+
+      # PDF pages rendered in-process by libvips' pdfload (opt-in, see the class comment).
+      class PdfDocument < Document
+        include Pipeline
+
+        def initialize(source, config, password)
+          super(source)
+          @config = config
+          @password = password
+          header = load(0, 72)
+          @page_count = (header.get_typeof("n-pages") != 0) ? header.get("n-pages") : 1
+          @infos = {}
+          @mutex = Mutex.new
+        end
+
+        attr_reader :page_count
+
+        # Sizes in points of the page as displayed (pdfload applies /Rotate).
+        def page_info(number)
+          check_page!(number)
+          @mutex.synchronize do
+            @infos[number] ||= begin
+              vimage = load(number - 1, 72)
+              PageInfo.new(number: number, width: vimage.width, height: vimage.height, unit: :pt, rotation: 0, native_ppi: nil)
+            end
+          end
+        end
+
+        # (see Document#render)
+        def render(number, dpi: nil, timeout: nil) # timeout: in-process, cannot be enforced
+          check_page!(number)
+          dpi ||= @config.default_dpi
+          vips_call do
+            image = to_image(load(number - 1, dpi))
+            Page.new(number: number, image: image, dpi: dpi, scale_to_base: 1.0, metadata: {loader: :vips})
+          end
+        end
+
+        private
+
+        def load(index, dpi)
+          options = {page: index, dpi: dpi, background: [255]}
+          options[:password] = @password if @password
+          Pipeline.load_fresh("pdfload", source.path, **options)
+        rescue ::Vips::Error => e
+          raise password_error(e) if e.message.match?(/encrypted|password/i)
+
+          raise RenderError.new("libvips pdfload failed on #{source.name}: #{Pipeline.error_summary(e, lines: 1)}", stderr: e.message[0, 4096])
+        end
+
+        def password_error(error)
+          if @password
+            IncorrectPassword.new("the password for #{source.name} was rejected")
+          else
+            PasswordRequired.new("#{source.name} is encrypted; pass password:")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/zxing_ffi/loaders.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ZXingFFI
+  # Input loaders: each turns a file into pages of normalized 8-bit grayscale {Image}s.
+  #
+  # Loader classes are looked up by name (+:poppler+, +:vips+, +:image_magick+, +:pnm+). Every loader file can
+  # be required without its external tool or gem; availability is checked at runtime.
+  module Loaders
+    autoload :Base, "zxing_ffi/loaders/base"
+    autoload :Document, "zxing_ffi/loaders/base"
+    autoload :Page, "zxing_ffi/loaders/base"
+    autoload :PageInfo, "zxing_ffi/loaders/base"
+    autoload :Registry, "zxing_ffi/loaders/registry"
+    autoload :PopplerLoader, "zxing_ffi/loaders/poppler"
+    autoload :VipsLoader, "zxing_ffi/loaders/vips"
+    autoload :ImageMagickLoader, "zxing_ffi/loaders/image_magick"
+    autoload :PnmLoader, "zxing_ffi/loaders/pnm"
+
+    # Loader name => class name.
+    NAMES = {
+      poppler: :PopplerLoader,
+      vips: :VipsLoader,
+      image_magick: :ImageMagickLoader,
+      pnm: :PnmLoader
+    }.freeze
+
+    class << self
+      # @param name [Symbol] e.g. +:poppler+
+      # @return [Class<Base>]
+      # @raise [ArgumentError] for unknown names
+      def fetch(name)
+        const_get(NAMES.fetch(name.to_sym) { raise ArgumentError, "unknown loader #{name.inspect}; known: #{NAMES.keys.join(", ")}" })
+      end
+
+      # @return [Hash{Symbol => Class<Base>}] every loader, available or not
+      def registry
+        NAMES.keys.to_h { |name| [name, fetch(name)] }
+      end
+    end
+  end
+end

data/lib/zxing_ffi/native.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module ZXingFFI
+  # FFI declarations for the zxing-cpp C API (ZXingC.h, verified against 3.1.1).
+  #
+  # This module knows nothing about Ruby-level types: it only declares functions, enums and structs.
+  # {Reader} owns every native object's lifetime. The library is loaded lazily by {.load!}.
+  #
+  # Ownership (from the header): non-const +ZXing_X*+ results are freed with +ZXing_X_delete+; non-const
+  # +char*+/+uint8_t*+ results with +ZXing_free+; const results belong to their parent.
+  module Native
+    extend FFI::Library
+
+    # ZXing_ImageFormat (explicit values in the header).
+    enum :image_format, [
+      :none, 0,
+      :lum, 0x01000000,
+      :lum_a, 0x02000000,
+      :rgb, 0x03000102,
+      :bgr, 0x03020100,
+      :rgba, 0x04000102,
+      :argb, 0x04010203,
+      :bgra, 0x04020100,
+      :abgr, 0x04030201
+    ]
+    enum :binarizer, [:local_average, 0, :global_histogram, :fixed_threshold, :bool_cast]
+    enum :ean_add_on_symbol, [:ignore, 0, :read, :require]
+    enum :text_mode, [:plain, 0, :eci, :hri, :escaped, :hex, :hex_eci]
+    enum :content_type, [:text, 0, :binary, :mixed, :gs1, :iso15434, :unknown_eci]
+    enum :error_type, [:none, 0, :format, :checksum, :unsupported]
+
+    # ZXing_BarcodeFormat values are generated by macros and changed in 3.0: never hardcode them.
+    # They are plain C enum values, i.e. ints; see {Formats} for the runtime map.
+    typedef :int, :barcode_format
+
+    # ZXing_PointI
+    class PointI < FFI::Struct
+      layout :x, :int, :y, :int
+    end
+
+    # ZXing_Position
+    class Position < FFI::Struct
+      layout :top_left, PointI, :top_right, PointI, :bottom_right, PointI, :bottom_left, PointI
+    end
+
+    # [name, args, return, options] of functions every supported library exports.
+    REQUIRED_FUNCTIONS = [
+      [:ZXing_Version, [], :string],
+      [:ZXing_free, [:pointer], :void],
+      [:ZXing_LastErrorMsg, [], :pointer],
+
+      [:ZXing_ImageView_new, [:pointer, :int, :int, :image_format, :int, :int], :pointer],
+      [:ZXing_ImageView_delete, [:pointer], :void],
+      [:ZXing_ImageView_crop, [:pointer, :int, :int, :int, :int], :void],
+      [:ZXing_ImageView_rotate, [:pointer, :int], :void],
+
+      [:ZXing_BarcodeFormatSymbology, [:barcode_format], :barcode_format],
+      [:ZXing_BarcodeFormatFromString, [:string], :barcode_format],
+      [:ZXing_BarcodeFormatToString, [:barcode_format], :pointer],
+      [:ZXing_BarcodeFormatsList, [:barcode_format, :pointer], :pointer],
+      [:ZXing_BarcodeFormatsFromString, [:string, :pointer], :pointer],
+      [:ZXing_BarcodeFormatsToString, [:pointer, :int], :pointer],
+
+      [:ZXing_Barcode_isValid, [:pointer], :bool],
+      [:ZXing_Barcode_errorType, [:pointer], :error_type],
+      [:ZXing_Barcode_errorMsg, [:pointer], :pointer],
+      [:ZXing_Barcode_format, [:pointer], :barcode_format],
+      [:ZXing_Barcode_symbology, [:pointer], :barcode_format],
+      [:ZXing_Barcode_contentType, [:pointer], :content_type],
+      [:ZXing_Barcode_bytes, [:pointer, :pointer], :pointer],
+      [:ZXing_Barcode_bytesECI, [:pointer, :pointer], :pointer],
+      [:ZXing_Barcode_text, [:pointer], :pointer],
+      [:ZXing_Barcode_symbologyIdentifier, [:pointer], :pointer],
+      [:ZXing_Barcode_position, [:pointer], Position.by_value],
+      [:ZXing_Barcode_orientation, [:pointer], :int],
+      [:ZXing_Barcode_hasECI, [:pointer], :bool],
+      [:ZXing_Barcode_isInverted, [:pointer], :bool],
+      [:ZXing_Barcode_isMirrored, [:pointer], :bool],
+      [:ZXing_Barcode_lineCount, [:pointer], :int],
+      [:ZXing_Barcode_sequenceIndex, [:pointer], :int],
+      [:ZXing_Barcode_sequenceSize, [:pointer], :int],
+      [:ZXing_Barcode_sequenceId, [:pointer], :pointer],
+      [:ZXing_Barcode_extra, [:pointer, :string], :pointer],
+
+      [:ZXing_Barcodes_delete, [:pointer], :void],
+      [:ZXing_Barcodes_size, [:pointer], :int],
+      [:ZXing_Barcodes_at, [:pointer, :int], :pointer],
+
+      [:ZXing_ReaderOptions_new, [], :pointer],
+      [:ZXing_ReaderOptions_delete, [:pointer], :void],
+      [:ZXing_ReaderOptions_setTryHarder, [:pointer, :bool], :void],
+      [:ZXing_ReaderOptions_setTryRotate, [:pointer, :bool], :void],
+      [:ZXing_ReaderOptions_setTryInvert, [:pointer, :bool], :void],
+      [:ZXing_ReaderOptions_setTryDownscale, [:pointer, :bool], :void],
+      [:ZXing_ReaderOptions_setIsPure, [:pointer, :bool], :void],
+      [:ZXing_ReaderOptions_setValidateOptionalChecksum, [:pointer, :bool], :void],
+      [:ZXing_ReaderOptions_setReturnErrors, [:pointer, :bool], :void],
+      [:ZXing_ReaderOptions_setFormats, [:pointer, :pointer, :int], :void],
+      [:ZXing_ReaderOptions_setBinarizer, [:pointer, :binarizer], :void],
+      [:ZXing_ReaderOptions_setEanAddOnSymbol, [:pointer, :ean_add_on_symbol], :void],
+      [:ZXing_ReaderOptions_setTextMode, [:pointer, :text_mode], :void],
+      [:ZXing_ReaderOptions_setMinLineCount, [:pointer, :int], :void],
+      [:ZXing_ReaderOptions_setMaxNumberOfSymbols, [:pointer, :int], :void],
+      [:ZXing_ReaderOptions_getTryHarder, [:pointer], :bool],
+      [:ZXing_ReaderOptions_getTryRotate, [:pointer], :bool],
+      [:ZXing_ReaderOptions_getTryInvert, [:pointer], :bool],
+      [:ZXing_ReaderOptions_getTryDownscale, [:pointer], :bool],
+      [:ZXing_ReaderOptions_getIsPure, [:pointer], :bool],
+      [:ZXing_ReaderOptions_getValidateOptionalChecksum, [:pointer], :bool],
+      [:ZXing_ReaderOptions_getReturnErrors, [:pointer], :bool],
+      [:ZXing_ReaderOptions_getFormats, [:pointer, :pointer], :pointer],
+      [:ZXing_ReaderOptions_getBinarizer, [:pointer], :binarizer],
+      [:ZXing_ReaderOptions_getEanAddOnSymbol, [:pointer], :ean_add_on_symbol],
+      [:ZXing_ReaderOptions_getTextMode, [:pointer], :text_mode],
+      [:ZXing_ReaderOptions_getMinLineCount, [:pointer], :int],
+      [:ZXing_ReaderOptions_getMaxNumberOfSymbols, [:pointer], :int],
+
+      # Releases the GVL so several threads decode concurrently.
+      [:ZXing_ReadBarcodes, [:pointer, :pointer], :pointer, {blocking: true}]
+    ].freeze
+
+    # Optional features: feature name => [[name, args, return], ...]; all functions must resolve.
+    OPTIONAL_FUNCTIONS = {
+      # only with ZXING_EXPERIMENTAL_API
+      try_denoise: [
+        [:ZXing_ReaderOptions_setTryDenoise, [:pointer, :bool], :void],
+        [:ZXing_ReaderOptions_getTryDenoise, [:pointer], :bool]
+      ],
+      # newer name of ZXing_Barcode_orientation
+      rotation: [[:ZXing_Barcode_rotation, [:pointer], :int]],
+      # bounds-checked ImageView constructor
+      image_view_new_checked: [
+        [:ZXing_ImageView_new_checked, [:pointer, :int, :int, :int, :image_format, :int, :int], :pointer]
+      ]
+    }.freeze
+
+    @mutex = Mutex.new
+    @library = nil
+    @features = {}.freeze
+
+    class << self
+      # Loads and attaches libZXing once (thread safe). Later calls are no-ops.
+      #
+      # @return [LibraryLoader::Found]
+      # @raise [LibraryNotFound, IncompatibleLibrary]
+      def load!
+        return @library if @library
+
+        @mutex.synchronize do
+          return @library if @library
+
+          found = LibraryLoader.find
+          ffi_lib(found.path)
+          REQUIRED_FUNCTIONS.each { |name, args, ret, opts| attach_function(name, args, ret, **(opts || {})) }
+          @features = OPTIONAL_FUNCTIONS.to_h { |feature, functions| [feature, attach_optional(functions)] }.freeze
+          @library = found
+        end
+      end
+
+      # @return [Boolean] whether {.load!} has succeeded
+      def loaded?
+        !@library.nil?
+      end
+
+      # @return [LibraryLoader::Found, nil]
+      attr_reader :library
+
+      # Whether an optional native feature is present: +:try_denoise+, +:rotation+, +:image_view_new_checked+.
+      # @return [Boolean]
+      def supports?(feature)
+        load!
+        @features.fetch(feature.to_sym) { raise ArgumentError, "unknown native feature: #{feature.inspect}" }
+      end
+
+      # @return [Array<Symbol>] optional features present in the loaded library
+      def optional_features
+        load!
+        @features.select { |_, present| present }.keys
+      end
+
+      # Rotation of a barcode in degrees as reported by the library (-180..180).
+      def barcode_rotation(barcode)
+        @features[:rotation] ? ZXing_Barcode_rotation(barcode) : ZXing_Barcode_orientation(barcode)
+      end
+
+      # Copies a caller-owned C string into a UTF-8 Ruby String and frees it. NULL → nil.
+      def take_string(pointer)
+        return nil if pointer.nil? || pointer.null?
+
+        pointer.read_string.force_encoding(Encoding::UTF_8)
+      ensure
+        ZXing_free(pointer) if pointer && !pointer.null?
+      end
+
+      # Calls the block with an +int*+ out-parameter, copies the returned caller-owned
+      # buffer of that many bytes into a BINARY String and frees it.
+      def take_bytes
+        length = FFI::MemoryPointer.new(:int)
+        pointer = yield length
+        return "".b if pointer.nil? || pointer.null?
+
+        pointer.read_bytes(length.read_int)
+      ensure
+        ZXing_free(pointer) if pointer && !pointer.null?
+      end
+
+      # Like {.take_bytes} for caller-owned +ZXing_BarcodeFormat*+ arrays.
+      # @return [Array<Integer>, nil] nil when the library returned NULL
+      def take_formats
+        count = FFI::MemoryPointer.new(:int)
+        pointer = yield count
+        return nil if pointer.nil? || pointer.null?
+
+        pointer.read_array_of_int(count.read_int)
+      ensure
+        ZXing_free(pointer) if pointer && !pointer.null?
+      end
+
+      # Fetches (and clears) the calling thread's last error message.
+      # @return [String, nil]
+      def last_error_message
+        take_string(ZXing_LastErrorMsg())
+      end
+
+      private
+
+      def attach_optional(functions)
+        functions.each { |name, args, ret| attach_function(name, args, ret) }
+        true
+      rescue FFI::NotFoundError
+        false
+      end
+    end
+  end
+end