win 0.3.11 → 0.3.16

data/HISTORY

@@ -38,3 +38,23 @@
 == 0.3.11 / 2010-06-03
 
 * GetDlgCtrlID function added
+
+== 0.3.12 / 2010-06-07
+
+* Library::function improved: treatment of snake_case API fubctions changed
+
+== 0.3.13 / 2010-06-09
+
+* Win::System::Info module started
+
+== 0.3.14 / 2010-06-10
+
+* System::Version and System::Info functions added
+
+== 0.3.15 / 2010-06-10
+
+* System::Version specs added
+
+== 0.3.16 / 2010-06-11
+
+* System::Version module completed

data/VERSION

@@ -1 +1 @@
-0.3.11
+0.3.16

data/lib/win/gui/dialog.rb

@@ -217,6 +217,36 @@ module Win
       #
       function :GetDlgItem, [:ulong, :int], :ulong, zeronil: true
 
+      ##
+      # The GetDlgCtrlID function retrieves the identifier of the specified control. In other words,
+      # you give it a handle (say, for a button window inside a dialog), and it returns control ID
+      # that this window is associated with (say IDOK - meaning this window is in fact "OK" button.
+      #
+      # [*Syntax*] int GetDlgCtrlID( HWND hwndCtl );
+      #
+      # hwndCtl:: [in] Handle to the control.
+      #
+      # *Returns*:: If the function succeeds, the return value is the identifier of the control.
+      # If the function fails, the return value is zero. An invalid value for the hwndCtl parameter, for
+      # example, will cause the function to fail. To get extended error information, call GetLastError.
+      # ---
+      # *Remarks*:
+      # GetDlgCtrlID accepts child window handles as well as handles of controls in dialog boxes. An
+      # application sets the identifier for a child window when it creates the window by assigning the
+      # identifier value to the hmenu parameter when calling the CreateWindow or CreateWindowEx function.
+      # Although GetDlgCtrlID may return a value if hwndCtl is a handle to a top-level window, top-level
+      # windows cannot have identifiers and such a return value is never valid.
+      # ---
+      # *See* *Also*
+      # Dialog Boxes Overview, CreateWindow, CreateWindowEx, GetDlgItem
+      # ---
+      # <b>Enhanced (snake_case) API: returns nil instead of zero if function fails</b>
+      #
+      # :call-seq:
+      #  control_id = get_dlg_ctrl_id(control_handle)
+      #
+      function :GetDlgCtrlID, [:HWND], :int, zeronil: true
+
       ##
       # MessageBox Function
       # --------------------------------------------------------------------------------
@@ -300,36 +330,6 @@ module Win
                   caption_pointer = FFI::MemoryPointer.from_string(caption)
                   api.call handle, text_pointer, caption_pointer, type }
 
-      ##
-      # The GetDlgCtrlID function retrieves the identifier of the specified control. In other words,
-      # you give it a handle (say, for a button window inside a dialog), and it returns control ID
-      # that this window is associated with (say IDOK - meaning this window is in fact "OK" button.
-      #
-      # [*Syntax*] int GetDlgCtrlID( HWND hwndCtl );
-      #
-      # hwndCtl:: [in] Handle to the control.
-      #
-      # *Returns*:: If the function succeeds, the return value is the identifier of the control.
-      # If the function fails, the return value is zero. An invalid value for the hwndCtl parameter, for
-      # example, will cause the function to fail. To get extended error information, call GetLastError.
-      # ---
-      # *Remarks*:
-      # GetDlgCtrlID accepts child window handles as well as handles of controls in dialog boxes. An
-      # application sets the identifier for a child window when it creates the window by assigning the
-      # identifier value to the hmenu parameter when calling the CreateWindow or CreateWindowEx function.
-      # Although GetDlgCtrlID may return a value if hwndCtl is a handle to a top-level window, top-level
-      # windows cannot have identifiers and such a return value is never valid.
-      # ---
-      # *See* *Also*
-      # Dialog Boxes Overview, CreateWindow, CreateWindowEx, GetDlgItem
-      # ---
-      # <b>Enhanced (snake_case) API: returns nil instead of zero if function fails</b>
-      #
-      # :call-seq:
-      #  control_id = get_dlg_ctrl_id(control_handle)
-      #
-      function :GetDlgCtrlID, [:HWND], :int, zeronil: true
-
       # Untested:
 
       ##

data/lib/win/gui/input.rb

@@ -134,7 +134,6 @@ module Win
       # Indicates NO data if dwFlags are NOT any of MOUSEEVENTF_WHEEL, MOUSEEVENTF_XDOWN, or MOUSEEVENTF_XUP
       INPUT_MOUSE = 0
 
-
       ##
       # The keybd_event function synthesizes a keystroke. The system can use such a synthesized keystroke to generate
       # a WM_KEYUP or WM_KEYDOWN message. The keyboard driver's interrupt handler calls the keybd_event function.

data/lib/win/gui/message.rb

@@ -439,7 +439,7 @@ module Win
       #          with the dwThreadId parameter set to the identifier of the current thread.
       # Msg:: <in> Specifies the message to be posted.
       # wParam:: <in> Specifies additional message-specific information.
-      # lParam:: <in> Specifies additional message-specific information.
+      # lParam:: <in> Specifies additional message-specific information (can be either :pointer or :long).
       #
       # *Returns*:: Nonzero if the function succeeds, zero if it fails. For extended error info, call GetLastError.
       # ---
@@ -456,11 +456,34 @@ module Win
       #   the operation will fail. The functions will return before the receiving thread has had a chance to
       #   process the message and the sender will free the memory before it is used. Use the PostQuitMessage
       #   instead of PostMessage to post WM_QUIT message.
+      # ---
+      # <b>Enhanced (snake_case) API: accepts either long or pointer lParam</b>
       #
       #:call-seq:
       # success = post_message(handle, msg, w_param, l_param)
       #
-      function :PostMessage, [:ulong, :uint, :uint, :pointer], :int, boolean: true
+      function :PostMessage, [:ulong, :uint, :uint, :pointer], :int,
+               boolean: true, camel_name: :PostMessagePointer, snake_name: :post_message_pointer
+      function :PostMessage, [:ulong, :uint, :uint, :long], :int,
+               boolean: true, camel_name: :PostMessageLong, snake_name: :post_message_long
+
+      def PostMessage(handle, msg, w_param, l_param)
+        # Routes call depending on lParam type (:pointer or :long)
+        case l_param
+          when Fixnum
+            PostMessageLong(handle, msg, w_param, l_param)
+          else
+            PostMessagePointer(handle, msg, w_param, l_param)
+        end
+      end
+
+      def post_message(handle, msg, w_param, l_param, &block)
+        if block
+          block[PostMessage(handle, msg, w_param, l_param)]
+        else
+          PostMessage(handle, msg, w_param, l_param) != 0
+        end
+      end
 
       ##
       # The SendMessage function sends the specified message to a window or windows. It calls the window procedure for

data/lib/win/library.rb

@@ -225,8 +225,9 @@ module Win
             SHORT:     :short, # A 16-bit integer. The range is –32768 through 32767 decimal.
             SIZE_T:    :ulong, #  The maximum number of bytes to which a pointer can point. Use for a count that must span the full range of a pointer.
             SSIZE_T:   :long, # Signed SIZE_T.
-            TBYTE:     :short, # A WCHAR if UNICODE is defined, a CHAR otherwise.TCHAR:
-            TCHAR:     :short, # A WCHAR if UNICODE is defined, a CHAR otherwise.TCHAR:
+            TBYTE:     :char, # A WCHAR if UNICODE is defined, a CHAR otherwise.TCHAR:
+            # http://msdn.microsoft.com/en-us/library/c426s321%28VS.80%29.aspx
+            TCHAR:     :char, # A WCHAR if UNICODE is defined, a CHAR otherwise.TCHAR:
             UCHAR:     :uchar, # Unsigned CHAR (8 bit)
             UHALF_PTR: :uint, # Unsigned HALF_PTR. Use within a structure that contains a pointer and two small fields.
             UINT:      :uint, # Unsigned INT. The range is 0 through 4294967295 decimal.
@@ -274,70 +275,22 @@ module Win
     # - do other stuff that you think is appropriate to make Windows API function behavior more Ruby-like...
     # ---
     # Accepts following options:
-    # :dll:: Use this dll instead of default 'user32'
-    # :rename:: Use this name instead of standard (conventional) function name
+    # :dll:: Use this dll instead of default ['user32', 'kernel32']
+    # :snake_name:: Overrides default snake_case method name being defined
+    # :camel_name:: Overrides default CamelCase name for function being attached
+    # :camel_only:: If true, no snake_case method is defined
     # :alias(es):: Provides additional alias(es) for defined method
     # :boolean:: Forces method to return true/false instead of nonzero/zero
     # :zeronil:: Forces method to return nil if function result is zero
     #
     def function(name, params, returns, options={}, &def_block)
-      snake_name, effective_names, aliases = generate_names(name, options)
-      params, returns = generate_signature(params, returns)
-      libs = ffi_libraries.map(&:name)
-      boolean = options[:boolean]
-      zeronil = options[:zeronil]
-
-      effective_name = effective_names.inject(nil) do |func, effective_name|
-        func || begin
-          # tries to attach basic CamelCase method via FFI
-          attach_function(name, effective_name, params.dup, returns)
-          effective_name
-        rescue FFI::NotFoundError
-          nil
-        end
-      end
-
-      raise Win::Errors::NotFoundError.new(name, libs) unless effective_name
-
-      # Create API object that holds information about function names, params, etc
-      api = API.new(namespace, name, effective_name, params, returns, libs)
-
-      # Only define enhanced API if snake_name is different from original name (e.g. keybd_event),
-      # If names are the same, this function is already "attached", not possible to enhance its API
-      unless snake_name.to_s == name.to_s
-        method_body = if def_block
-          if zeronil
-            ->(*args, &block){ (res = def_block.(api, *args, &block)) != 0 ? res : nil }
-          elsif boolean
-            ->(*args, &block){ def_block.(api, *args, &block) != 0 }
-          else
-            ->(*args, &block){ def_block.(api, *args, &block) }
-          end
-        else
-          if zeronil
-            ->(*args, &block){ (res = block ? block[api.call(*args)] : api.call(*args)) != 0 ? res : nil }
-          elsif boolean
-            ->(*args, &block){ block ? block[api.call(*args)] : api.call(*args) != 0 }
-          else
-            ->(*args, &block){ block ? block[api.call(*args)] : api.call(*args) }
-          end
-        end
-
-        define_method snake_name, &method_body       # define snake_case instance method
+      snake_name, camel_name, effective_names, aliases = generate_names(name, options)
 
-#        module_function snake_name    # TODO: Doesn't work as a perfect replacement for eigen_class stuff. :( Why?
+      api = define_api(name, camel_name, effective_names, params, returns, options)
 
-        eigen_class = class << self;
-          self;
-        end        # Extracting eigenclass
+      define_snake_method(snake_name, aliases, api, options, &def_block) unless options[:camel_only]
 
-        eigen_class.class_eval do
-          define_method snake_name, &method_body       # define snake_case class method
-        end
-      end
-
-      aliases.each {|ali| alias_method ali, snake_name }  # define aliases
-      api   #return api object from function declaration
+      api   # Return api object from function declaration # TODO: Do we even NEED api object?
     end
 
     # Try to define platform-specific function, rescue error, return message
@@ -350,15 +303,82 @@ module Win
       end
     end
 
+    # Defines CamelCase method calling Win32 API function, and associated API object
+    #
+    def define_api(name, camel_name, effective_names, params, returns, options)
+      params, returns = generate_signature(params.dup, returns)
+
+      ffi_lib *(ffi_libraries.map(&:name) << options[:dll]) if options[:dll]
+      libs = ffi_libraries.map(&:name)
+
+      effective_name = if options[:alternative]
+
+        alt_params, alt_returns, condition = generate_signature(*options.dup[:alternative])
+        api = function name, params, returns,
+                       options.dup.merge( camel_only: true, camel_name: "#{camel_name}Original")
+        alt_api = function name, alt_params, alt_returns,
+                           options.dup.merge( camel_only: true, camel_name: "#{camel_name}Alternative")
+        define_method camel_name do |*args|
+          (condition[*args] ? alt_api : api).call(*args)
+        end
+        api.effective_name
+      else
+        effective_names.inject(nil) do |func, effective_name|
+          func || begin
+            # Try to attach basic CamelCase method via FFI
+            attach_function(camel_name, effective_name, params.dup, returns)
+            effective_name
+          rescue FFI::NotFoundError
+            nil
+          end
+        end
+      end
+
+      raise Win::Errors::NotFoundError.new(name, libs) unless effective_name
+
+      # Create API object that holds information about defined and effective function names, params, etc.
+      # This object is further used by enhanced snake_case method to reflect on underlying API and
+      # intelligently call it.
+      API.new(namespace, camel_name, effective_name, params, returns, libs)
+    end
+
+    # Defines enhanced snake_case method and (optionally) aliases to it.
+    # Both instance method and module-level method with the same name is defined
+    #
+    def define_snake_method(snake_name, aliases, api, options, &def_block)
+      # Generate body for snake_case method
+      method_body = generate_snake_method_body(api, options, &def_block)
+
+      # Define snake_case instance method
+      define_method snake_name, &method_body
+
+      # We need to define module(class) level method, but something went wrong with module_function :(
+#      module_function snake_name    # TODO: Doesn't work as a perfect replacement for eigen_class stuff. :( Why?
+
+      # OK, instead of module_method we're going to directly modify eigenclass
+      eigen_class = class << self;
+        self;
+      end
+
+      # Define snake_case class method inside eigenclass, that should do it
+      eigen_class.class_eval do
+        define_method snake_name, &method_body
+      end
+
+      # Define (instance method!) aliases, if any
+      aliases.each {|ali| alias_method ali, snake_name }
+    end
+
     # Generates possible effective names for function in Win32 dll (name+A/W),
-    # Rubyesque name and aliases for method(s) defined based on function name,
+    # camel_case, snake_case and aliases method names
     #
     def generate_names(name, options={})
       name = name.to_s
       effective_names = [name]
       effective_names += ["#{name}A", "#{name}W"] unless name =~ /[WA]$/
       aliases = ([options[:alias]] + [options[:aliases]]).flatten.compact
-      snake_name = options[:rename] || name.snake_case
+      snake_name = options[:snake_name] || name.snake_case
+      camel_name = options[:camel_name] || name.camel_case
       case snake_name
         when /^is_/
           aliases << snake_name.sub(/^is_/, '') + '?'
@@ -367,17 +387,40 @@ module Win
         when /^get_/
           aliases << snake_name.sub(/^get_/, '')
       end
-      [snake_name, effective_names, aliases]
+      [snake_name, camel_name, effective_names, aliases]
     end
 
     ##
     # Generates params and returns (signature) containing only FFI-compliant types
     #
-    def generate_signature(params, returns)
+    def generate_signature(params, returns, condition=nil)
       params = params.split(//) if params.respond_to?(:split) # Convert params string into array
       params.map! {|param| TYPES[param.to_sym] || param} # Convert chars into FFI type symbols
       returns = TYPES[returns.to_sym] || returns # Convert chars into FFI type symbols
-      [params, returns]
+      [params, returns, condition]
+    end
+
+    # Generates body for snake_case method according to directives contained in options
+    # options (:boolean, :zeronil) currently supported
+    #
+    def generate_snake_method_body(api, options, &def_block)
+      if def_block
+        if options[:zeronil]
+          ->(*args, &block){ (res = def_block.(api, *args, &block)) != 0 ? res : nil }
+        elsif options[:boolean]
+          ->(*args, &block){ def_block.(api, *args, &block) != 0 }
+        else
+          ->(*args, &block){ def_block.(api, *args, &block) }
+        end
+      else
+        if options[:zeronil]
+          ->(*args, &block){ (res = block ? block[api.call(*args)] : api.call(*args)) != 0 ? res : nil }
+        elsif options[:boolean]
+          ->(*args, &block){ block ? block[api.call(*args)] : api.call(*args) != 0 }
+        else
+          ->(*args, &block){ block ? block[api.call(*args)] : api.call(*args) }
+        end
+      end
     end
 
     ##
@@ -424,12 +467,13 @@ module Win
     class API
 
       # The name of the DLL(s) that export this API function
-      attr_reader :dll_name
+      attr_reader :dll
+      alias_method :dll_name, :dll
 
       # Ruby namespace (module) where this API function is attached
       attr_reader :namespace
 
-      # The name of the function passed to the constructor
+      # The name of the (CamelCase) function passed to the constructor
       attr_reader :function_name
 
       # The name of the actual Windows API function. For example, if you passed 'GetUserName' to the
@@ -442,18 +486,18 @@ module Win
       # The return type (:void for no return value)
       attr_reader :return_type
 
-      def initialize( namespace, function_name, effective_function_name, prototype, return_type, dll_name )
+      def initialize( namespace, function_name, effective_function_name, prototype, return_type, dll )
         @namespace = namespace
-        @function_name = function_name
-        @effective_function_name = effective_function_name
+        @function_name = function_name.to_sym
+        @effective_function_name = effective_function_name.to_sym
         @prototype = prototype
         @return_type = return_type
-        @dll_name = dll_name
+        @dll = dll
       end
 
       # Calls underlying CamelCase Windows API function with supplied args
       def call( *args )
-        @namespace.send(@function_name.to_sym, *args)
+        @namespace.send(@function_name, *args)
       end
 
       # alias_method :[], :call

data/lib/win/system/info.rb

@@ -0,0 +1,163 @@
+require 'win/library'
+
+module Win
+  module System
+
+    # Contains constants and Win32 API functions related to dialog manipulation.
+    # Windows dialog basics can be found here:
+    # http://msdn.microsoft.com/en-us/library/ms644996#init_box
+    module Info
+      extend Win::Library
+
+      # Enum COMPUTER_NAME_FORMAT (for GetComputerNameEx)
+
+      ComputerNameNetBIOS                    = 0
+      ComputerNameDnsHostname                = 1
+      ComputerNameDnsDomain                  = 2
+      ComputerNameDnsFullyQualified          = 3
+      ComputerNamePhysicalNetBIOS            = 4
+      ComputerNamePhysicalDnsHostname        = 5
+      ComputerNamePhysicalDnsDomain          = 6
+      ComputerNamePhysicalDnsFullyQualified  = 7
+      ComputerNameMax                        = 8
+
+      class << self
+        # Helper method that creates def_block returning (possibly encoded) string as a result of
+        # api function call or nil if api call was not successful. TODO: put this into some kind of helper?
+        #
+        def return_sized_string( encode = nil )  #:nodoc:
+          lambda do |api, *args|
+            namespace.enforce_count( args, api.prototype, -2)
+            buffer = FFI::MemoryPointer.new :char, 1024
+            size = FFI::MemoryPointer.new(:long).write_long(buffer.size)
+            args += [buffer, size]
+            success = api.call(*args)
+            return nil unless success
+            num_chars = size.read_long
+            if encode
+              string = buffer.get_bytes(0, num_chars*2)
+              string = string.force_encoding('utf-16LE').encode(encode)
+            else
+              string = buffer.get_bytes(0, num_chars)
+            end
+            string.rstrip
+          end
+        end
+
+        private :return_sized_string
+      end
+
+      ##
+      # GetComputerName Function.
+      # Retrieves the NetBIOS name of the local computer. This name is established at system startup, when the
+      # system reads it from the registry.
+      # GetComputerName retrieves only the NetBIOS name of the local computer. To retrieve the DNS host name,
+      # DNS domain name, or the fully qualified DNS name, call the GetComputerNameEx function. Additional
+      # information is provided by the IADsADSystemInfo interface.
+      # The behavior of this function can be affected if the local computer is a node in a cluster. For more
+      # information, see ResUtilGetEnvironmentWithNetName and UseNetworkName.
+      #
+      # [*Syntax*] BOOL GetComputerName( LPTSTR lpBuffer, LPDWORD lpnSize );
+      #
+      # lpBuffer:: A pointer to a buffer that receives the computer name or the cluster virtual server name. The buffer
+      #            size should be large enough to contain MAX_COMPUTERNAME_LENGTH + 1 characters.
+      # lpnSize:: On input, specifies the size of the buffer, in TCHARs. On output, the number of TCHARs copied to the
+      #           destination buffer, not including the terminating null character.
+      #           If the buffer is too small, the function fails and GetLastError returns ERROR_BUFFER_OVERFLOW. The
+      #           lpnSize parameter specifies the size of the buffer required, not including the terminating null char.
+      #
+      # *Returns*:: If the function succeeds, the return value is a nonzero value.
+      #             If the function fails, the return value is zero. To get extended error info, call GetLastError.
+      # ---
+      # *Remarks*:
+      # The GetComputerName function retrieves the NetBIOS name established at system startup. Name changes
+      # made by the SetComputerName or SetComputerNameEx functions do not take effect until the user restarts
+      # the computer.
+      # If the caller is running under a client session, this function returns the server name. To retrieve
+      # the client name, use the WTSQuerySessionInformation function.
+      # DLL Requires Kernel32.dll.
+      # Unicode Implemented as GetComputerNameW (Unicode) and GetComputerNameA (ANSI).
+      # ---
+      # *See* *Also*
+      # Computer Names
+      # GetComputerNameEx
+      # SetComputerName
+      # SetComputerNameEx
+      # System Information Functions
+      #
+      # ---
+      # <b>Enhanced (snake_case) API: no arguments needed</b>
+      #
+      # :call-seq:
+      #  name = [get_]computer_name()
+      #
+      function :GetComputerName, [:pointer, :pointer], :int8, &return_sized_string
+
+      ##
+      # GetUserName Function.
+      # Retrieves the name of the user associated with the current thread.
+      # Use the GetUserNameEx function to retrieve the user name in a specified format. Additional information
+      # is provided by the IADsADSystemInfo interface.
+      #
+      # [*Syntax*] BOOL WINAPI GetUserName( LPTSTR lpBuffer, LPDWORD lpnSize );
+      #
+      # lpBuffer:: A pointer to the buffer to receive the user's logon name. If this buffer is not large enough to
+      #            contain the entire user name, the function fails. A buffer size of (UNLEN + 1) characters will hold
+      #            the maximum length user name including the terminating null character. UNLEN is defined in Lmcons.h.
+      # lpnSize:: On input, this variable specifies the size of the lpBuffer buffer, in TCHARs. On output, the variable
+      #           receives the number of TCHARs copied to the buffer, including the terminating null character.
+      #           If lpBuffer is too small, the function fails and GetLastError returns ERROR_INSUFFICIENT_BUFFER. This
+      #           parameter receives the required buffer size, including the terminating null character.
+      #           If it is greater than 32767, function fails and GetLastError returns ERROR_INSUFFICIENT_BUFFER.
+      #
+      # *Returns*:: If the function succeeds, the return value is a nonzero value, and the variable pointed to
+      #             by lpnSize contains the number of TCHARs copied to the buffer specified by lpBuffer,
+      #             including the terminating null character. If the function fails, the return value is zero.
+      #             To get extended error information, call GetLastError.
+      # ---
+      # *Remarks*:
+      # If the current thread is impersonating another client, the GetUserName function returns the user name
+      # of the client that the thread is impersonating.
+      # Example Code
+      # For an example, see Getting System Information.
+      # Requirements
+      # Client Requires Windows Vista, Windows XP, or Windows 2000 Professional.
+      # Server Requires Windows Server 2008, Windows Server 2003, or Windows 2000 Server.
+      # Header Declared in Winbase.h; include Windows.h.
+      # Library Use Advapi32.lib.
+      # DLL Requires Advapi32.dll.
+      # Unicode Implemented as GetUserNameW (Unicode) and GetUserNameA (ANSI).
+      # ---
+      # *See* *Also*:
+      # GetUserNameEx
+      # LookupAccountName
+      # System Information Functions
+      #
+      # ---
+      # <b>Enhanced (snake_case) API: no arguments needed</b>
+      #
+      # :call-seq:
+      #  username = [get_]user_name()
+      #
+      function :GetUserName, [:pointer, :pointer], :int8, :dll=> 'advapi32', &return_sized_string
+
+      # Untested
+
+      ##
+      function :GetComputerNameEx, 'PPP', :int8, boolean: true
+      ##
+      function :GetUserNameEx, 'LPP', :int8, boolean: true, dll: 'secur32'
+      ##
+      function :ExpandEnvironmentStrings, 'PPL', :long
+      ##
+      function :GetSystemInfo, 'P', :void
+      ##
+      function :GetWindowsDirectory, 'PI', :int
+      ##
+      # XP or later
+      try_function :GetSystemWow64Directory, 'PI', :int
+
+    end
+  end
+end
+