windows-api 0.1.0

data/CHANGES

@@ -0,0 +1,2 @@
+= 0.1.0 - 24-May-2007
+* Initial release

data/MANIFEST

@@ -0,0 +1,9 @@
+* CHANGES
+* MANIFEST
+* README
+* Rakefile
+* windows-api.gemspec
+* ext/extconf.rb
+* ext/windows/api.c
+* lib/windows/api.rb
+* test/tc_windows_api.rb

data/README

@@ -0,0 +1,82 @@
+= Description
+   This is a wrapper for Win32API that simplifies various idioms typically
+   used by people who use Win32API.
+
+= 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 Win32API
+   * 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

data/Rakefile

@@ -0,0 +1,54 @@
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rbconfig'
+include Config
+
+desc 'Install the windows-api package (non-gem)'
+task :install do
+   sitelibdir = CONFIG["sitelibdir"]
+   installdir = File.join(sitelibdir, 'windows')
+   Dir.mkdir(installdir) unless File.exists?(installdir)
+   file = "lib/windows/api.rb"
+   FileUtils.cp(file, installdir, :verbose => true)
+end
+
+task :install_gem do
+   ruby 'windows-api.gemspec'
+   file = Dir["*.gem"].first
+   sh "gem install #{file}"
+end
+
+desc "Clean any build files for Windows::API"
+task :clean do
+   Dir.chdir('ext') do
+      if File.exists?("api.so") || File.exists?("windows/api.so")
+         sh "nmake distclean"
+         rm "api.c" if File.exists?("api.c")
+         rm "windows/api.so" if File.exists?("windows/api.so") 
+      end
+   end
+end
+
+desc "Build Windows::API (but don't install it)"
+task :build_c => [:clean] do
+   Dir.chdir('ext') do
+      cp "windows/api.c", "."
+      sh "ruby extconf.rb"
+      sh "nmake"
+      mv "api.so", "windows"
+   end
+end
+
+Rake::TestTask.new('test_c') do |test|
+   task :test_c => [:build_c]
+   test.libs << 'ext'
+   test.test_files = FileList['test/tc*']
+end
+
+Rake::TestTask.new do |test|
+   test.libs << 'lib'
+   test.warning = true
+   test.verbose = true
+   test.test_files = FileList['test/tc*']
+end

data/lib/windows/api.rb

@@ -0,0 +1,358 @@
+require 'Win32API'
+
+module Windows
+   class API
+      VERSION = '0.1.0'
+      
+      class Error < RuntimeError; end
+      
+      @@auto_constant  = false
+      @@auto_method    = false
+      @@auto_unicode   = false
+      @@auto_namespace = nil
+      
+      # Returns the value of the @@auto_constant class variable. The default
+      # is nil, i.e. none. See the Windows::API.auto_constant= documentation
+      # for more information.
+      #
+      def self.auto_constant
+         @@auto_constant
+      end
+
+      # Automatically sets a constant to match the function name.
+      # 
+      # The standard practice for defining Windows::API objects is to use 
+      # a constant that matches the function name. For example, this is a
+      # typical idiom:
+      # 
+      #    module Windows
+      #       module File
+      #          GetFileAttributes = API.new('GetFileAttributes', 'P','L')
+      #       end
+      #    end
+      # 
+      # With the API.auto_constant value set to true you can avoid the
+      # assignment step and the matching constant name will be automatically
+      # set for you in the namespace defined in API.auto_namespace. In other
+      # words, this example is identical to the one above:
+      # 
+      #    module Windows
+      #       module File
+      #          API.auto_constant  = true
+      #          API.auto_namespace = 'Windows::File'
+      #          API.new('GetFileAttributes', 'P', 'L')
+      #       end
+      #    end
+      # 
+      # If the auto_constant class variable is set to true, but no
+      # auto_namespace is set, an error will be raised. Note that the
+      # namespace must refer to an existing module (not a class).
+      #--
+      # TODO: If there's a way to automatically grab the namespace internally,
+      # nesting and all, I'd love to know the solution.
+      #
+      def self.auto_constant=(bool)
+         @@auto_constant = bool
+      end
+      
+      # Returns the value of the auto_namespace class variable.  Used in
+      # conjunction with API.auto_constant and/or API.auto_method.
+      # 
+      def self.auto_namespace
+         @@auto_namespace
+      end
+      
+      # Sets the value of the auto_namespace class variable. The default is
+      # nil, i.e. none. Use in conjunction with the auto_constant and/or
+      # auto_method class variables, this method will automatically set a
+      # constant and/or method in +namespace+ equal to the function name set
+      # in the constructor.
+      # 
+      # The +namespace+ must refer to an existing module, not a class.
+      # 
+      def self.auto_namespace=(namespace)
+         @@auto_namespace = namespace
+      end
+      
+      # Returns the value of the auto_method class variable. Used in
+      # conjunction with auto_unicode.  See API.auto_method= for more
+      # information.
+      # 
+      def self.auto_method
+         @@auto_method
+      end
+      
+      # If this option is set to true then a corresponding method is
+      # automatically generated when you create a new Windows::API object.
+      # 
+      # For example, instead of doing this:
+      # 
+      #    module Windows
+      #       module File
+      #          GetFileAttributes = API.new('GetFileAttributes', 'P', 'L')
+      # 
+      #          def GetFileAttributes(x)
+      #             GetFileAttributes.call(x)
+      #          end
+      #       end
+      #    end
+      # 
+      # You can do this, and have the method autogenerated for you.
+      # 
+      #    module Windows
+      #       module File
+      #          API.auto_namespace = 'Windows::File'
+      #          API.auto_constant  = true
+      #          API.auto_method    = true
+      #          GetFileAttributes  = API.new('GetFileAttributes', 'P', 'L')
+      #       end
+      #    end
+      # 
+      # If the Windows::API object is declared to be a boolean in the
+      # constructor, then the method definition automatically includes a
+      # '!= 0' clause at the end of the call. That way, you can do
+      # 'if SomeMethod(x)' instead of having to do 'if SomeMethod(x) != 0',
+      # and it will do the right thing.
+      # 
+      # If the API.auto_unicode option is also set to true, then you will
+      # get three method definitions. The standard function name, the explicit
+      # ANSI ('A') version and the explicit Unicode/wide version ('W'). The
+      # exception to this rule is that the explicit ANSI and Unicode methods
+      # will NOT be generated if the function passed to the constructor
+      # already ends with 'A' or 'W'.
+      #
+      def self.auto_method=(bool)
+         @@auto_method = bool
+      end
+      
+      # Returns the value of the auto_unicode class variable. This is used
+      # in conjunction with the auto_method and/or auto_constant class
+      # variables. Not significant if neither of those variables are set.
+      # 
+      def self.auto_unicode
+         @@auto_unicode
+      end
+      
+      # If set to true, and the auto_constant variable is set, then the
+      # automatic constant generation will generate the explicit ANSI ('A')
+      # and Unicode/wide ('W') versions of the function passed to the
+      # constructor, if such versions exist.  Likewise, if the the
+      # auto_method variable is set, then explicit ANSI and Unicode methods
+      # are generated.
+      # 
+      # Here's a typical idiom:
+      # 
+      # module Windows
+      #    module Path
+      #       API.auto_namespace = Windows::Path
+      #       API.auto_constant = true
+      #       API.new('shlwapi', 'PathAddBackslash', 'P', 'P')
+      #       API.new('shlwapi', 'PathAddBackslashA', 'P', 'P')
+      #       API.new('shlwapi', 'PathAddBackslashW', 'P', 'P')
+      #    end
+      # end
+      #
+      # That can be reduced to this:
+      # 
+      # module Windows
+      #    module Path
+      #       API.auto_namespace = Windows::Path
+      #       API.auto_constant = true
+      #       API.auto_unicode  = true
+      #       API.new('shlwapi', 'PathAddBackslash', 'P', 'P')
+      #    end
+      # end
+      # 
+      # This value is ignored if the function passed to the constructor
+      # already ends with an 'A' or 'W'.
+      # 
+      def self.auto_unicode=(bool)
+         @@auto_unicode = bool
+      end
+
+      attr_reader :function_name
+      attr_reader :dll_name
+      attr_reader :prototype
+      attr_reader :return_type
+      
+      # call-seq:
+      #    API.new(func, proto='V', rtype='L', dll='kernel32')
+      # 
+      # Creates and returns a new Windows::API object.  The +func+ is the
+      # name of the Windows function.
+      # 
+      # The +proto+ is the function prototype for +func+.  This can be a
+      # string or an array of characters.  The possible valid characters
+      # are 'I' (integer), 'B' (BOOL), 'L' (long), 'V' (void), or 'P' (pointer).
+      # The default is void ('V').
+      # 
+      # The +rtype+ argument is the return type for the function.  The valid
+      # characters are the same as for the +proto+. The default is long ('L').
+      #
+      # The 'B' (BOOL) return type is the same as 'I' (Integer). This is
+      # significant only if the API.auto_method option is set to true, in which
+      # case it alters the generated method definition slightly. See the
+      # API.auto_method= class method for more information.
+      # 
+      # The +dll+ is the name of the DLL file that the function is exported
+      # from. The default is 'kernel32'.
+      # 
+      # If the function cannot be found then an API::Error is raised (a subclass
+      # of RuntimeError).
+      # 
+      def initialize(func, proto='V', rtype='L', dll='kernel32')
+         @function_name = func
+         @prototype     = proto
+         @return_type   = rtype == 'B' ? 'I' : rtype
+         @dll_name      = dll
+         @boolean       = rtype == 'B' ? true : false
+         
+         begin
+            @api = Win32API.new(
+               @dll_name,
+               @function_name,
+               @prototype,
+               @return_type
+            )
+         rescue RuntimeError => err
+            raise Error, err
+         end
+         
+         api_a = nil
+         api_w = nil
+         
+         # If the auto_unicode option is set, and the func is not already
+         # an explicit ANSI or Unicode function name, generate Win32API
+         # objects for those functions as well. Ignore errors because not
+         # all functions have explicit ANSI or Unicode equivalents.
+         # 
+         if @@auto_unicode
+            begin
+               if func[-1].chr != 'A'
+                  api_a = Win32API.new(dll, "#{func}A", proto, rtype)
+               end
+            rescue RuntimeError
+            end
+         
+            begin
+               if func[-1].chr != 'W'
+                  api_w = Win32API.new(dll, "#{func}W", proto, rtype)
+               end
+            rescue RuntimeError
+            end
+         end
+         
+         # Automatically define a constant matching the function name if the
+         # auto_constant option is set.
+         # 
+         if @@auto_constant && @@auto_namespace
+            if @@auto_namespace != 'Windows'
+               namespace = class_for(@@auto_namespace)
+            else
+               namespace = @@auto_namespace
+            end
+            
+            namespace.const_set(func, @api)
+            
+            # Automatically define the explicit ANSI and Unicode functions
+            # as constants as well, if appropriate.
+            # 
+            if @@auto_unicode
+               namespace.const_set("#{func}A", api_a) if api_a
+               namespace.const_set("#{func}W", api_w) if api_w
+            end
+         end
+         
+         # Automatically define a method in the auto_namespace if the
+         # auto_method option is set. The explicit ANSI and Unicode methods
+         # are added as well if the auto_unicode option is set to true.
+         # 
+         if @@auto_method && @@auto_namespace
+            n = 0
+            if proto.is_a?(String)
+               proto = proto.split('').map{ |e|
+                  n += 1
+                  e.downcase + n.to_s
+               }.join(', ')
+            else
+               proto = proto.map{ |e|
+                  n += 1
+                  e.downcase + n.to_s
+               }.join(', ')
+            end
+
+            if @boolean
+               string = <<-EOC
+                  module #{@@auto_namespace} 
+                     def #{func}(#{proto})
+                        #{func}.call(#{proto}) != 0
+                     end
+                  EOC
+                  
+               if api_a
+                  string << %Q{
+                     def #{func}A(#{proto})
+                        #{func}A.call(#{proto}) != 0
+                     end
+                  }
+               end
+               
+               if api_w
+                  string << %Q{
+                     def #{func}W(#{proto})
+                        #{func}W.call(#{proto}) != 0
+                     end
+                  }
+               end
+               
+               string << 'end'
+            else
+               string = <<-EOC
+                  module #{@@auto_namespace} 
+                     def #{func}(#{proto})
+                        #{func}.call(#{proto})
+                     end
+                  EOC
+                  
+               if api_a
+                  string << %Q{
+                     def #{func}A(#{proto})
+                        #{func}A.call(#{proto})
+                     end
+                  }
+               end
+               
+               if api_w
+                  string << %Q{
+                     def #{func}W(#{proto})
+                        #{func}W.call(#{proto})
+                     end
+                  }
+               end
+               
+               string << 'end'
+            end
+            
+            eval(string)
+         end
+      end
+
+      # Calls the function name set in the constructor.
+      #
+      def call(*args)
+         @api.call(*args)
+      end
+      
+      private
+      
+      # Get a module's namespace. This is basically the equivalent of
+      # the rb_path2class() function from intern.h
+      # 
+      def class_for(class_name) 
+         names = class_name.split("::")
+         result = Object 
+         names.each{ |n| result = result.const_get(n) }
+         result 
+      end
+   end
+end

data/test/tc_windows_api.rb

@@ -0,0 +1,104 @@
+############################################################################
+# tc_windows_api.rb
+# 
+# Test case for the Windows::API class. You should run this as Rake task,
+# i.e. 'rake test', instead of running it directly.
+############################################################################
+require 'windows/api'
+require 'test/unit'
+include Windows
+
+module Windows
+   module Test
+      API.auto_namespace = 'Windows::Test'
+      API.auto_unicode   = true
+      API.auto_method    = true
+      API.auto_constant  = true
+      $test_method = API.new('GetCurrentDirectory', 'PP', 'L')
+   end
+
+   module Foo
+      API.auto_namespace = 'Windows::Foo'
+      API.auto_unicode  = false
+      API.auto_method   = false
+      API.auto_constant = false
+      $foo_method = API.new('GetSystemDirectory', 'PL', 'L')
+   end
+
+   module Bar
+      API.auto_namespace = 'Windows::Bar'
+      API.auto_constant = true
+      API.auto_method   = true
+      $bar_method = API.new('GetUserName', 'PP', 'I', 'advapi32')
+   end
+end
+
+class TC_Windows_API < Test::Unit::TestCase
+   include Windows::Test
+   include Windows::Foo
+   include Windows::Bar
+
+   def setup
+      @buf = 0.chr * 256
+   end
+
+   def test_version
+      assert_equal('0.1.0', API::VERSION)
+   end
+
+   def test_auto_unicode
+      assert_not_nil(Windows::Bar::GetUserName)
+      assert_equal(true, self.respond_to?(:GetUserName))
+      assert_equal(false, self.respond_to?(:GetUserNameA))
+      assert_equal(false, self.respond_to?(:GetUserNameW))
+   end
+
+   def test_auto_constant
+      assert_not_nil(Windows::Test::GetCurrentDirectory)
+      assert_not_nil(Windows::Bar::GetUserName)
+
+      assert_kind_of(Win32API, Windows::Test::GetCurrentDirectory)
+      assert_respond_to(Windows::Test::GetCurrentDirectory, :call)
+   end
+
+   def test_auto_method
+      assert_respond_to(self, :GetCurrentDirectory)
+      assert_respond_to(self, :GetCurrentDirectoryA)
+      assert_respond_to(self, :GetCurrentDirectoryW)
+
+      assert_equal(false, self.respond_to?(:GetSystemDirectory))
+      assert_equal(false, self.respond_to?(:GetSystemDirectoryA))
+      assert_equal(false, self.respond_to?(:GetSystemDirectoryW))
+   end
+
+   def test_call
+      assert_respond_to($test_method, :call)
+      assert_respond_to($foo_method, :call)
+      assert_nothing_raised{ $test_method.call(@buf.length, @buf) }
+      assert_nothing_raised{ $foo_method.call(@buf, @buf.length) }
+   end
+   
+   def test_dll_name
+      assert_respond_to($test_method, :dll_name)
+      assert_equal('kernel32', $test_method.dll_name)
+   end
+   
+   def test_function_name
+      assert_respond_to($test_method, :function_name)
+      assert_equal('GetCurrentDirectory', $test_method.function_name)
+   end
+   
+   def test_prototype
+      assert_respond_to($test_method, :prototype)
+      assert_equal('PP', $test_method.prototype)
+   end
+   
+   def test_return_type
+      assert_respond_to($test_method, :return_type)
+      assert_equal('L', $test_method.return_type)
+   end
+   
+   def teardown
+      @buf = nil
+   end
+end

data/windows-api.gemspec

@@ -0,0 +1,23 @@
+require "rubygems"
+
+spec = Gem::Specification.new do |gem|
+   gem.name        = "windows-api"
+   gem.version     = "0.1.0"
+   gem.author      = "Daniel J. Berger"
+   gem.email       = "djberg96@gmail.com"
+   gem.homepage    = "http://www.rubyforge.org/projects/win32utils"
+   gem.platform    = Gem::Platform::RUBY
+   gem.summary     = "An easier way to create methods using Win32API"
+   gem.description = "An easier way to create methods using Win32API"
+   gem.test_file   = "test/tc_windows_api.rb"
+   gem.has_rdoc    = true
+   gem.files       = Dir["lib/windows/*.rb"] + Dir["test/*"] + Dir["[A-Z]*"]
+   gem.files.reject! { |fn| fn.include? "CVS" }
+   gem.require_path = "lib"
+   gem.extra_rdoc_files = ["README", "CHANGES", "MANIFEST"]
+end
+
+if $0 == __FILE__
+   Gem.manage_gems
+   Gem::Builder.new(spec).build
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.9.4
+specification_version: 1
+name: windows-api
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+date: 2007-05-24 00:00:00 -06:00
+summary: An easier way to create methods using Win32API
+require_paths: 
+- lib
+email: djberg96@gmail.com
+homepage: http://www.rubyforge.org/projects/win32utils
+rubyforge_project: 
+description: An easier way to create methods using Win32API
+autorequire: 
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+post_install_message: 
+authors: 
+- Daniel J. Berger
+files: 
+- lib/windows/api.rb
+- test/CVS
+- test/tc_windows_api.rb
+- CHANGES
+- CVS
+- ext
+- lib
+- MANIFEST
+- Rakefile
+- README
+- test
+- windows-api.gemspec
+test_files: 
+- test/tc_windows_api.rb
+rdoc_options: []
+
+extra_rdoc_files: 
+- README
+- CHANGES
+- MANIFEST
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: []
+