README

Path: README
Last Update: Fri Dec 14 11:49:08 -0300 2007

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')

   # 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.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.
   * Most arguments to the constructor are optional, with sensible defaults.
   * Four attributes added to API objects - dll_name, function_name, prototype
     and return_type.

More documentation

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

Bugs

   None that I'm aware of. Please submit any bugs to the project page at
   http://www.rubyforge.org/projects/win32utils.

Copyright

   (C) 2007, Daniel J. Berger

License

   Ruby's

Author

   Daniel Berger
   djberg96 at gmail dot com

[Validate]