107 lines
3.9 KiB
Plaintext
107 lines
3.9 KiB
Plaintext
= Description
|
|
This is a drop-in replacement for the Win32API library currently part of
|
|
Ruby's standard library.
|
|
|
|
= Synopsis
|
|
require 'win32/api'
|
|
include Win32
|
|
|
|
# Typical example - Get user name
|
|
buf = 0.chr * 260
|
|
len = [buf.length].pack('L')
|
|
|
|
GetUserName = API.new('GetUserName', 'PP', 'I', 'advapi32')
|
|
GetUserName.call(buf, len)
|
|
|
|
puts buf.strip
|
|
|
|
# Callback example - Enumerate windows
|
|
EnumWindows = API.new('EnumWindows', 'KP', 'L', 'user32')
|
|
GetWindowText = API.new('GetWindowText', 'LPI', 'I', 'user32')
|
|
EnumWindowsProc = API::Callback.new('LP', 'I'){ |handle, param|
|
|
buf = "\0" * 200
|
|
GetWindowText.call(handle, buf, 200);
|
|
puts buf.strip unless buf.strip.empty?
|
|
buf.index(param).nil? ? true : false
|
|
}
|
|
|
|
EnumWindows.call(EnumWindowsProc, 'UEDIT32')
|
|
|
|
# Raw function pointer example - System beep
|
|
LoadLibrary = API.new('LoadLibrary', 'P', 'L')
|
|
GetProcAddress = API.new('GetProcAddress', 'LP', 'L')
|
|
|
|
hlib = LoadLibrary.call('user32')
|
|
addr = GetProcAddress.call(hlib, 'MessageBeep')
|
|
func = Win32::API::Function.new(addr, 'L', 'L')
|
|
func.call(0)
|
|
|
|
= Differences between win32-api and Win32API
|
|
* This library has callback support
|
|
* This library supports raw function pointers.
|
|
* This library supports a separate string type for const char* (S).
|
|
* Argument order change. The DLL name is now last, not first.
|
|
* Removed the 'N' and 'n' prototypes. Always use 'L' for longs now.
|
|
* Sensible default arguments for the prototype, return type and DLL name.
|
|
* Reader methods for the function name, effective function name, prototype,
|
|
return type and DLL.
|
|
* Removed the support for lower case prototype and return types. Always
|
|
use capital letters.
|
|
|
|
= Developer's Notes
|
|
The current Win32API library that ships with the standard library has been
|
|
slated for removal from Ruby 2.0 and it will not receive any updates in the
|
|
Ruby 1.8.x branch. I have far too many libraries invested in it to let it
|
|
die at this point.
|
|
|
|
In addition, the current Win32API library was written in the bad old Ruby
|
|
1.6.x days, which means it doesn't use the newer allocation framework.
|
|
There were several other refactorings that I felt it needed to more closely
|
|
match how it was actually being used in practice.
|
|
|
|
The first order of business was changing the order of the arguments. By
|
|
moving the DLL name from first to last, I was able to provide reasonable
|
|
default arguments for the prototype, return type and the DLL. Only the
|
|
function name is required now.
|
|
|
|
There was a laundry list of other refactorings that were needed: sensical
|
|
instance variable names with proper accessors, removing support for lower
|
|
case prototype and return value characters that no one used in practice,
|
|
better naming conventions, the addition of RDoc ready comments and,
|
|
especially, callback and raw function pointer support.
|
|
|
|
Most importantly, we can now add, modify and fix any features that we feel
|
|
best benefit our end users.
|
|
|
|
= Multiple Binaries
|
|
As of win32-api 1.4.8 a binary gem is shipped that contains binaries for
|
|
both Ruby 1.8 and Ruby 1.9. The file under lib/win32 dynamically requires
|
|
the correct binary based on your version of Ruby.
|
|
|
|
= Documentation
|
|
The source file contains inline RDoc documentation. If you installed
|
|
this file as a gem, then you have the docs. Run "gem server" and point
|
|
your browser at http://localhost:8808 to see them.
|
|
|
|
= 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.
|
|
|
|
= Known Issues
|
|
Possible callback issues when dealing with multi-threaded applications.
|
|
|
|
Please submit any bug reports to the project page at
|
|
http://www.rubyforge.org/projects/win32utils.
|
|
|
|
= Copyright
|
|
(C) 2003-2011 Daniel J. Berger
|
|
All Rights Reserved
|
|
|
|
= License
|
|
Artistic 2.0
|
|
|
|
= Authors
|
|
Daniel J. Berger
|
|
Park Heesob
|