150 lines
6.2 KiB
Plaintext
150 lines
6.2 KiB
Plaintext
|
== 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
|