annih / windows-api Goto Github PK

== 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
   This library will eventually be dropped in favor of FFI once I'm convinced
   that FFI is stable for both mingw and mswin.

== 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-2014, Daniel J. Berger

== License
   Artistic 2.0

== Author
   Daniel Berger