windows-pr 0.1.0

data/CHANGES

@@ -0,0 +1,2 @@
+= 0.1.0 - 4-Apr-2006
+* Initial release

data/MANIFEST

@@ -0,0 +1,20 @@
+CHANGES
+MANIFEST
+README
+install.rb
+windows-pr.gemspec
+
+doc/conversion_guide.txt
+
+lib/windows/clipboard.rb
+lib/windows/device_io.rb
+lib/windows/error.rb
+lib/windows/file.rb
+lib/windows/handle.rb
+lib/windows/memory.rb
+lib/windows/path.rb
+lib/windows/sound.rb
+lib/windows/synchronize.rb
+
+lib/windows/msvcrt/buffer.rb
+lib/windows/msvcrt/file.rb

data/README

@@ -0,0 +1,117 @@
+= windows-pr
+== Description
+   A collection of Windows functions predefined for you via Win32API.  Hence,
+   the 'pr', for 'Pure Ruby'.
+   
+== Synopsis
+   require 'windows/path'
+   
+   class Foo
+      include Windows::Path
+   
+      if PathIsRoot.call("C:\\") > 0
+         ...
+      end
+      
+      # or
+      
+      if PathIsRoot("C:\\")
+         ...
+      end
+   end
+   
+== Methods
+   Each of the various files included as part of this package provide a series
+   of constants corresponding to the equivalent Windows API function and
+   related numeric constants.  For example, if you require 'windows/path',
+   you now have PathIsRoot, PathIsUNC, etc, available to you as Win32API
+   objects in the form of constants.
+   
+   A wrapper has been provided for each method in order to avoid the
+   Win32API#call method.  So, instead of PathIsRoot.call(path) you can
+   invoke it as PathIsRoot(path).  If the original function is lower case
+   then the wrapper method is lower case as well.  For example, instead of
+   doing 'Memcpy.call(dest, src, size)' you can do 'memcpy(dest, src, size)'.
+   
+   Remember boys and girls, if you write PathIsRoot, you're referring to
+   the constant.  If you write PathIsRoot(), you're calling the wrapper
+   method.
+   
+   Boolean methods automatically perform a check for success or failure.  So,
+   instead of having to do something like 'if PathIsRoot(path) > 0' you can
+   just do 'if PathIsRoot(path)'.
+   
+   Files contain related functions, by topic.  For example, the clipboard.rb
+   file contains clipboard related functions, such as CloseClipboard(), as
+   well as constants such as CF_TEXT, CF_BITMAP, etc.
+   
+== Where are the tests, dude?
+   While I've made some effort to test these functions, there are simply too
+   many for me to effectively test them all.  We're ultimately talking about
+   hundreds, if not thousands, of functions, and I don't know what all of them
+   actually do.  That being said, I will add tests where and when I can.
+   
+   If you find that I've declared the function prototype wrong for a given
+   function, please let me know ASAP and I'll fix it.  An example program
+   demonstrating the problem would be helpful, too.  Or, if you'd just like
+   to contribute some test cases, that's fine as well.
+     
+== What's the point?
+   I became tired of redefining Windows functions over and over whenever I
+   wanted to use the Win32API package.  I thought it would be very handy to
+   have them predefined for me in a package with convenient wrapper methods
+   to boot.
+   
+   While it's true that Moonwolf has a package on the RAA that includes many
+   of these functions defined already, there are a few issues with it.  First,
+   it puts *every* function and constant in one or two files.  That's a waste
+   of memory, hard to organize & maintain, and impossible to test.  Second,
+   some of his function declarations are wrong.  Third, some of the functions
+   I needed for my own projects are missing.  Fourth, there's no gem.  Lastly,
+   I haven't seen an update in over 5 years, which leads me to believe it is
+   no longer maintained.
+   
+== Hey, I'm missing function X!
+   I have only defined a small subset of the overall Windows API.  It would
+   take me years to define them *all*.  I defined the ones I needed first,
+   plus some that I thought would be useful to others.  I will continue to
+   add functions in my spare time, or (especially) by request.
+   
+== Bugs
+   None that I'm aware of.  Please report any bugs on the project page at
+   http://www.rubyforge.org/projects/win32utils.
+   
+   The only real bugs you could find are either bad prototype declarations
+   or bad constant values.  But, please report either.
+   
+== Known Issues
+   In some cases the MSDN docs are wrong, and we have to learn it the hard
+   way.  If you should happen to find a documentation bug on their site,
+   please contact them and let them know.  They're generally good about fixing
+   them.
+   
+   In other cases library functions are not exported by the dll.  For example,
+   my version of shlwapi.dll does not export the PathIsHTMLFile() function,
+   despite being well past the minimum version for that dll file.  There is
+   nothing you or I can do about it short of rebuilding the dll file from
+   scratch and/or reporting the issue to Microsoft.
+   
+== Supported Platforms
+   I only support the Windows NT familiy of Windows, and really only Windows
+   2000 and later, though I'll make an effort to support NT 4 if there are
+   any NT 4 related issues and requests to support it.
+   
+== License
+   Ruby's
+   
+== Warranty
+   This package is provided "as is" and without any express or
+   implied warranties, including, without limitation, the implied
+   warranties of merchantability and fitness for a particular purpose.
+
+== Copyright
+   (C) 2006, Daniel J. Berger
+   All Rights Reserved
+   
+== Author
+   Daniel Berger

data/doc/conversion_guide.txt

@@ -0,0 +1,25 @@
+= Parameters
+Long:    'N' or 'L'
+Integer: 'I'
+Pointer: 'P'
+Void:    'V'
+
+= Windows Data Types
+BOOL  		=> 'I'
+DWORD 		=> 'L'
+HANDLE		=> 'L'
+LPDWORD		=> 'P'
+LPTSTR 		=> 'P'
+UINT  		=> 'I'
+VOID        => 'V'
+WORD		   => 'I'
+
+= C Data Types
+void     	=> 'V'
+void*    	=> 'P'
+char*    	=> 'P'
+const char* => 'L'
+int			=> 'I'
+long			=> 'L'
+struct      => 'P'
+struct*     => 'P'

data/lib/windows/clipboard.rb

@@ -0,0 +1,105 @@
+#############################################################################
+# clipboard.rb
+#
+# Includes the following functions:
+#
+# CloseClipboard()
+# CoundClipboardFormats()
+# EmptyClipboard()
+# EnumClipboardFormats()
+# GetClipboardData()
+# GetClipboardFormatName()
+# IsClipboardFormatAvailable()
+# OpenClipboard()
+# RegisterClipboardFormat()
+# SetClipboardData()
+#
+# Defines the following constants:
+#
+# CF_TEXT
+# CF_BITMAP
+# CF_METAFILEPICT
+# CF_SYLK
+# CF_DIF
+# CF_TIFF
+# CF_OEMTEXT
+# CF_DIB
+# CF_PALETTE
+# CF_PENDATA
+# CF_RIFF
+# CF_WAVE
+# CF_UNICODETEXT
+# CF_ENHMETAFILE
+#############################################################################
+require 'Win32API'
+
+module Windows
+   module Clipboard
+      CF_TEXT         = 1
+      CF_BITMAP       = 2
+      CF_METAFILEPICT = 3
+      CF_SYLK         = 4
+      CF_DIF          = 5
+      CF_TIFF         = 6
+      CF_OEMTEXT      = 7
+      CF_DIB          = 8
+      CF_PALETTE      = 9
+      CF_PENDATA      = 10
+      CF_RIFF         = 11
+      CF_WAVE         = 12
+      CF_UNICODETEXT  = 13
+      CF_ENHMETAFILE  = 14
+
+      OpenClipboard    = Win32API.new('user32', 'OpenClipboard', 'L', 'I')
+      CloseClipboard   = Win32API.new('user32', 'CloseClipboard', 'V', 'I')
+      GetClipboardData = Win32API.new('user32', 'GetClipboardData', 'I', 'P')
+      EmptyClipboard   = Win32API.new('user32', 'EmptyClipboard', 'V', 'I')
+      SetClipboardData = Win32API.new('user32', 'SetClipboardData', 'II', 'I')
+
+      CountClipboardFormats      = Win32API.new('user32', 'CountClipboardFormats', 'V', 'I')
+      IsClipboardFormatAvailable = Win32API.new('user32', 'IsClipboardFormatAvailable', 'I', 'I')
+      GetClipboardFormatName     = Win32API.new('user32', 'GetClipboardFormatName', 'IPI', 'I')
+      EnumClipboardFormats       = Win32API.new('user32', 'EnumClipboardFormats', 'I', 'I')
+      RegisterClipboardFormat    = Win32API.new('user32', 'RegisterClipboardFormat', 'P', 'I')
+
+      def OpenClipboard(handle)
+         OpenClipboard.call(handle) > 0
+      end
+
+      def CloseClipboard
+         CloseClipboard.call > 0
+      end
+
+      def GetClipboardData(format)
+         GetClipboardData.call(format)
+      end
+
+      def EmptyClipboard
+         EmptyClipboard.call > 0
+      end
+
+      def SetClipboardData(format, handle)
+         SetClipboardData.call(format, handle)
+      end
+
+      def CountClipboardFormats
+         CountClipboardFormats.call
+      end
+
+      def IsClipboardFormatAvailable(format)
+         IsClipboardFormatAvailable.call(format) > 0
+      end
+
+      def GetClipboardFormatName(format, format_name, max)
+         GetClipboardFormatName.call(format, format_name, max)
+      end
+
+      def EnumClipboardFormats(format)
+         EnumClipboardFormats.call(format)
+      end
+
+      def RegisterClipboardFormat(format)
+         RegisterClipboardFormat.call(format)
+      end
+   end
+end

data/lib/windows/device_io.rb

@@ -0,0 +1,141 @@
+#####################################################################
+# device_io.rb
+#
+# Defines the following functions:
+#
+# DeviceIoControl()
+#
+# Defines the following constants:
+#
+# FILE_DEVICE_BEEP                = 0x00000001
+# FILE_DEVICE_CD_ROM              = 0x00000002
+# FILE_DEVICE_CD_ROM_FILE_SYSTEM  = 0x00000003
+# FILE_DEVICE_CONTROLLER          = 0x00000004
+# FILE_DEVICE_DATALINK            = 0x00000005
+# FILE_DEVICE_DFS                 = 0x00000006
+# FILE_DEVICE_DISK                = 0x00000007
+# FILE_DEVICE_DISK_FILE_SYSTEM    = 0x00000008
+# FILE_DEVICE_FILE_SYSTEM         = 0x00000009
+# FILE_DEVICE_INPORT_PORT         = 0x0000000a
+# FILE_DEVICE_KEYBOARD            = 0x0000000b
+# FILE_DEVICE_MAILSLOT            = 0x0000000c
+# FILE_DEVICE_MIDI_IN             = 0x0000000d
+# FILE_DEVICE_MIDI_OUT            = 0x0000000e
+# FILE_DEVICE_MOUSE               = 0x0000000f
+# FILE_DEVICE_MULTI_UNC_PROVIDER  = 0x00000010
+# FILE_DEVICE_NAMED_PIPE          = 0x00000011
+# FILE_DEVICE_NETWORK             = 0x00000012
+# FILE_DEVICE_NETWORK_BROWSER     = 0x00000013
+# FILE_DEVICE_NETWORK_FILE_SYSTEM = 0x00000014
+# FILE_DEVICE_NULL                = 0x00000015
+# FILE_DEVICE_PARALLEL_PORT       = 0x00000016
+# FILE_DEVICE_PHYSICAL_NETCARD    = 0x00000017
+# FILE_DEVICE_PRINTER             = 0x00000018
+# FILE_DEVICE_SCANNER             = 0x00000019
+# FILE_DEVICE_SERIAL_MOUSE_PORT   = 0x0000001a
+# FILE_DEVICE_SERIAL_PORT         = 0x0000001b
+# FILE_DEVICE_SCREEN              = 0x0000001c
+# FILE_DEVICE_SOUND               = 0x0000001d
+# FILE_DEVICE_STREAMS             = 0x0000001e
+# FILE_DEVICE_TAPE                = 0x0000001f
+# FILE_DEVICE_TAPE_FILE_SYSTEM    = 0x00000020
+# FILE_DEVICE_TRANSPORT           = 0x00000021
+# FILE_DEVICE_UNKNOWN             = 0x00000022
+# FILE_DEVICE_VIDEO               = 0x00000023
+# FILE_DEVICE_VIRTUAL_DISK        = 0x00000024
+# FILE_DEVICE_WAVE_IN             = 0x00000025
+# FILE_DEVICE_WAVE_OUT            = 0x00000026
+# FILE_DEVICE_8042_PORT           = 0x00000027
+# FILE_DEVICE_NETWORK_REDIRECTOR  = 0x00000028
+# FILE_DEVICE_BATTERY             = 0x00000029
+# FILE_DEVICE_BUS_EXTENDER        = 0x0000002a
+# FILE_DEVICE_MODEM               = 0x0000002b
+# FILE_DEVICE_VDM                 = 0x0000002c
+# FILE_DEVICE_MASS_STORAGE        = 0x0000002d
+# FILE_DEVICE_SMB                 = 0x0000002e
+# FILE_DEVICE_KS                  = 0x0000002f
+# FILE_DEVICE_CHANGER             = 0x00000030
+# FILE_DEVICE_SMARTCARD           = 0x00000031
+# FILE_DEVICE_ACPI                = 0x00000032
+# FILE_DEVICE_DVD                 = 0x00000033
+# FILE_DEVICE_FULLSCREEN_VIDEO    = 0x00000034
+# FILE_DEVICE_DFS_FILE_SYSTEM     = 0x00000035
+# FILE_DEVICE_DFS_VOLUME          = 0x00000036
+# FILE_DEVICE_SERENUM             = 0x00000037
+# FILE_DEVICE_TERMSRV             = 0x00000038
+# FILE_DEVICE_KSEC                = 0x00000039
+# FILE_DEVICE_FIPS                = 0x0000003A
+# FILE_DEVICE_INFINIBAND          = 0x0000003B
+#####################################################################
+require 'Win32API'
+
+module Windows
+   module DeviceIO
+      # Device Types
+      FILE_DEVICE_BEEP                = 0x00000001
+      FILE_DEVICE_CD_ROM              = 0x00000002
+      FILE_DEVICE_CD_ROM_FILE_SYSTEM  = 0x00000003
+      FILE_DEVICE_CONTROLLER          = 0x00000004
+      FILE_DEVICE_DATALINK            = 0x00000005
+      FILE_DEVICE_DFS                 = 0x00000006
+      FILE_DEVICE_DISK                = 0x00000007
+      FILE_DEVICE_DISK_FILE_SYSTEM    = 0x00000008
+      FILE_DEVICE_FILE_SYSTEM         = 0x00000009
+      FILE_DEVICE_INPORT_PORT         = 0x0000000a
+      FILE_DEVICE_KEYBOARD            = 0x0000000b
+      FILE_DEVICE_MAILSLOT            = 0x0000000c
+      FILE_DEVICE_MIDI_IN             = 0x0000000d
+      FILE_DEVICE_MIDI_OUT            = 0x0000000e
+      FILE_DEVICE_MOUSE               = 0x0000000f
+      FILE_DEVICE_MULTI_UNC_PROVIDER  = 0x00000010
+      FILE_DEVICE_NAMED_PIPE          = 0x00000011
+      FILE_DEVICE_NETWORK             = 0x00000012
+      FILE_DEVICE_NETWORK_BROWSER     = 0x00000013
+      FILE_DEVICE_NETWORK_FILE_SYSTEM = 0x00000014
+      FILE_DEVICE_NULL                = 0x00000015
+      FILE_DEVICE_PARALLEL_PORT       = 0x00000016
+      FILE_DEVICE_PHYSICAL_NETCARD    = 0x00000017
+      FILE_DEVICE_PRINTER             = 0x00000018
+      FILE_DEVICE_SCANNER             = 0x00000019
+      FILE_DEVICE_SERIAL_MOUSE_PORT   = 0x0000001a
+      FILE_DEVICE_SERIAL_PORT         = 0x0000001b
+      FILE_DEVICE_SCREEN              = 0x0000001c
+      FILE_DEVICE_SOUND               = 0x0000001d
+      FILE_DEVICE_STREAMS             = 0x0000001e
+      FILE_DEVICE_TAPE                = 0x0000001f
+      FILE_DEVICE_TAPE_FILE_SYSTEM    = 0x00000020
+      FILE_DEVICE_TRANSPORT           = 0x00000021
+      FILE_DEVICE_UNKNOWN             = 0x00000022
+      FILE_DEVICE_VIDEO               = 0x00000023
+      FILE_DEVICE_VIRTUAL_DISK        = 0x00000024
+      FILE_DEVICE_WAVE_IN             = 0x00000025
+      FILE_DEVICE_WAVE_OUT            = 0x00000026
+      FILE_DEVICE_8042_PORT           = 0x00000027
+      FILE_DEVICE_NETWORK_REDIRECTOR  = 0x00000028
+      FILE_DEVICE_BATTERY             = 0x00000029
+      FILE_DEVICE_BUS_EXTENDER        = 0x0000002a
+      FILE_DEVICE_MODEM               = 0x0000002b
+      FILE_DEVICE_VDM                 = 0x0000002c
+      FILE_DEVICE_MASS_STORAGE        = 0x0000002d
+      FILE_DEVICE_SMB                 = 0x0000002e
+      FILE_DEVICE_KS                  = 0x0000002f
+      FILE_DEVICE_CHANGER             = 0x00000030
+      FILE_DEVICE_SMARTCARD           = 0x00000031
+      FILE_DEVICE_ACPI                = 0x00000032
+      FILE_DEVICE_DVD                 = 0x00000033
+      FILE_DEVICE_FULLSCREEN_VIDEO    = 0x00000034
+      FILE_DEVICE_DFS_FILE_SYSTEM     = 0x00000035
+      FILE_DEVICE_DFS_VOLUME          = 0x00000036
+      FILE_DEVICE_SERENUM             = 0x00000037
+      FILE_DEVICE_TERMSRV             = 0x00000038
+      FILE_DEVICE_KSEC                = 0x00000039
+      FILE_DEVICE_FIPS                = 0x0000003A
+      FILE_DEVICE_INFINIBAND          = 0x0000003B
+      
+      DeviceIoControl = Win32API.new('kernel32', 'DeviceIoControl', 'LLPLPLPP', 'I')
+      
+      def DeviceIoControl(dev, code, in_buf, in_buf_size, out_buf, out_buf_size, bytes, overlapped)
+         DeviceIoControl.call(dev, code, in_buf, in_buf_size, out_buf, out_buf_size, bytes, overlapped)
+      end
+   end
+end

data/lib/windows/error.rb

@@ -0,0 +1,92 @@
+############################################################################
+# error.rb
+#
+# Includes the following functions:
+#
+# GetLastError()
+# FormatError()
+# SetErrorMode()
+# SetLastError()
+# SetLastErrorex()
+#
+# Defines the following constants:
+#
+# FORMAT_MESSAGE_ALLOCATE_BUFFER
+# FORMAT_MESSAGE_IGNORE_INSERTS
+# FORMAT_MESSAGE_FROM_STRING
+# FORMAT_MESSAGE_FROM_HMODULE
+# FORMAT_MESSAGE_FROM_SYSTEM
+# FORMAT_MESSAGE_ARGUMENT_ARRAY
+# FORMAT_MESSAGE_MAX_WIDTH_MASK
+#
+# SEM_FAILCRITICALERRORS
+# SEM_NOALIGNMENTFAULTEXCEPT
+# SEM_NOGPFAULTERRORBOX
+# SEM_NOOPENFILEERRORBOX
+#
+# Adds the following convenience methods:
+#
+# get_last_error - Returns a human readable string for the error returned
+# by the GetLastError() function.
+############################################################################
+require "Win32API"
+
+module Windows
+   module Error
+      FORMAT_MESSAGE_ALLOCATE_BUFFER   = 0x00000100
+      FORMAT_MESSAGE_IGNORE_INSERTS    = 0x00000200
+      FORMAT_MESSAGE_FROM_STRING       = 0x00000400
+      FORMAT_MESSAGE_FROM_HMODULE      = 0x00000800
+      FORMAT_MESSAGE_FROM_SYSTEM       = 0x00001000
+      FORMAT_MESSAGE_ARGUMENT_ARRAY    = 0x00002000
+      FORMAT_MESSAGE_MAX_WIDTH_MASK    = 0x000000FF
+         
+      SEM_FAILCRITICALERRORS           = 0x0001
+      SEM_NOALIGNMENTFAULTEXCEPT       = 0x0004
+      SEM_NOGPFAULTERRORBOX            = 0x0002
+      SEM_NOOPENFILEERRORBOX           = 0x8000
+         
+      GetLastError   = Win32API.new('kernel32', 'GetLastError', 'V', 'L')
+      SetLastError   = Win32API.new('kernel32', 'GetLastError', 'L', 'V')
+      SetLastErrorEx = Win32API.new('kernel32', 'GetLastError', 'LL', 'V')
+      SetErrorMode   = Win32API.new('kernel32', 'SetErrorMode', 'I', 'I')
+      FormatMessage  = Win32API.new('kernel32', 'FormatMessage', 'LPLLPLP', 'L')
+      
+      def GetLastError
+         GetLastError.call
+      end
+      
+      def SetLastError(error)
+         SetLastError.call(error)
+      end
+      
+      def SetLastErrorEx(error, type=0)
+         SetLastErrorEx.call(error, type)
+      end
+      
+      def SetErrorMode(mode)
+         SetErrorMode.call(mode)
+      end
+      
+      def FormatMessage(flags, src, msg_id, lang_id, buf, size, args)
+         FormatMessage.call(flags, src, msg_id, lang_id, buf, size, args)
+      end
+      
+      # Convenience method that wraps FormatMessage with some sane defaults and
+      # returns a human readable string.
+      #
+      def get_last_error(err_num = GetLastError.call)
+         buf = 0.chr * 260
+         FormatMessage.call(
+            FORMAT_MESSAGE_FROM_SYSTEM + FORMAT_MESSAGE_ARGUMENT_ARRAY,
+            0,
+            err_num,
+            0,
+            buf,
+            buf.length,
+            0
+         )
+         buf.split(0.chr).first.chomp
+      end
+   end
+end