metasploit-framework/lib/gemcache/ruby/1.9.1/arch/win32/windows-pr-1.2.1

== Description

  A collection of Windows functions predefined for you via Win32::API.

  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

   

== Installation

  gem install windows-pr

   

== 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

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

  method:

   

  if defined? AttachConsole

    # Do something

  else

    # Do something else

  end

   

== 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

  http://www.rubyforge.org/projects/win32utils.

   

  The only real bugs you could 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

  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. 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.

   

== 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-2010, Daniel J. Berger

  All Rights Reserved

   

== Author(s)

  Daniel Berger

  Park Heesob