A collection of Windows functions, constants and macros predefined for you for win32-api
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


== Description
  A collection of Windows functions predefined for you via Win32::API.
  Hence the 'pr', for 'Pure Ruby'.

== Installation
  gem install windows-pr

== Synopsis
  require 'windows/path'
  class Foo
    include Windows::Path
    if PathIsRoot.call("C:\\") > 0
    # or
    if PathIsRoot("C:\\")
== 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 Win32::API
  objects in the form of constants.
  A wrapper has been provided for each method in order to avoid the
  Win32::API#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
  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)'. However, I do not add this nicety for the
  MSVCRT functions that return int's because some functions have multiple
  return values which you may want to inspect. So, rather than making you
  guess, I have simply declared that you must inspect return values manually
  for any MSVCRT module.
  Source 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.
== Wide character functions
  I decided that the $KCODE handling was a bad idea, so most of the $KCODE
  handling has been removed. The only methods that change their behavior
  based on $KCODE are the multi_to_wide and wide_to_multi helper methods
  in the Windows::Unicode module. If $KCODE is set to UTF8, then the code
  point used is CP_UTF8. Otherwise, CP_ACP is used.
  The modules all come with explicit ANSI and Wide (Unicode) functions,
  when available from MS Windows. By default, a function without an explicit
  'A' at the end of the function name uses the ANSI version. It is up to you
  to use the wide ('W') functions explicitly if you wish.
== Platform specific functions
  Not all functions are defined on all platforms. For example, the
   AttachConsole() function is only defined on Windows XP and later. If you
  eed to conditionally test for its existence, simply use the 'defined?'
  if defined? AttachConsole
    # Do something
    # Do something else
== 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 library. I thought it would be very handy to
  have them predefined for me in a library with convenient wrapper methods
  to boot.
  While it's true that Moonwolf has a library 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 6 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:

  The only real bugs you should find are either bad prototype declarations
  or bad constant values.  Sometimes I forget to wrap functions properly
  that may not be defined on older Windows platforms.  But, please report
  any of these issues on the project page should you stumble into them.
== 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
  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. 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 family of Windows, and then only Windows
  2000 and later.

== Future Plans
  I plan on converting this library to use FFI instead of win32-api. There
  is already an ffi branch with some of that work done.
== License
  Artistic 2.0
== 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-2014, Daniel J. Berger
  (C) 2016, Hiroshi Hatake
  All Rights Reserved

== Author(s)
  Daniel Berger
  Park Heesob
  Hiroshi Hatake