README.rdoc

Description¶ ↑

This is a wrapper for Win32::API that simplifies various idioms typically
used by people who use Win32::API.

Synopsis¶ ↑

require 'windows/api'
include Windows

# Defaults to 'V' prototype, 'L' return type and 'kernel32' library
GetVersion = API.new('GetVersion')

# Defaults to 'L' return type and 'kernel32' library
CloseHandle = API.new('CloseHandle', 'L')

# Defaults to 'kernel32' library
GetWindowsDirectory = API.new('GetWindowsDirectory', 'LI', 'I')

# Explicitly state every argument
GetComputerNameEx = API.new('GetComputerNameEx', 'PPP', 'I', 'kernel32')

# Use long data type names
GetUserName = API.new('GetUserName',['LPTSTR','LPDWORD'],'BOOL','advapi32')

# Attributes for possible inspection
puts GetVersion.dll_name      # 'kernel32'
puts GetVersion.function_name # 'GetVersion'
puts GetVersion.prototype     # ['V']
puts GetVersion.return_type   # 'L'

# Automatic method generation

# This code....
module Windows
  module Foo
    API.auto_namespace = 'Windows::Foo'
    API.auto_constant  = true
    API.auto_method    = true
    API.auto_unicode   = true

    API.new('GetComputerName', 'PP', 'B')
  end
end

# Is the same as this code...
module Windows
  module Foo
    GetComputerName  = Win32API.new('kernel32', 'GetComputerName', 'PP', 'I')
    GetComputerNameA = Win32API.new('kernel32', 'GetComputerNameA', 'PP', 'I')
    GetComputerNameW = Win32API.new('kernel32', 'GetComputerNameW', 'PP', 'I')

    def GetComputerName(p1, p2)
      GetComputerName.call(p1, p2) != 0
    end

    def GetComputerNameA(p1, p2)
      GetComputerName.call(p1, p2) != 0
    end

    def GetComputerNameW(p1, p2)
      GetComputerName.call(p1, p2) != 0
    end
  end
end

Advantages over plain Win32::API¶ ↑

* Automatic constant generation.
* Automatic definition of ANSI and Unicode method wrappers, including
  special handling for boolean methods.
* Ability to use more familiar Windows data types, e.g. DWORD.
* Automatic handling of msvcrt vs msvcrXX via MSVCRT_DLL constant.

Other Stuff¶ ↑

There's also a WideString class for easily creating wide strings for
Ruby 1.8.x. Ruby 1.9.x can use Ruby's encoding methods to accomplish
the same effect, however.

More documentation¶ ↑

See the RDoc documentation, which should have been automatically generated
if you installed this as a gem.

Future Plans¶ ↑

I have no future plans for this library other than bug fixes. You should
use FFI instead of win32-api for all projects where possible.

Bugs¶ ↑

None that I'm aware of. Please submit any bugs to the project page at
https://github.com/djberg96/windows-api.

Copyright¶ ↑

(C) 2007-2015, Daniel J. Berger
(C) 2016-2022, Hiroshi Hatake

License¶ ↑

Artistic 2.0

Author¶ ↑

Daniel Berger
Hiroshi Hatake