Win32Utils - Ruby Libraries for MS Windows

Please contribute
win32-changenotify
win32-clipboard
win32-dir
win32-event
win32-eventlog
win32-ipc
win32-mmap
win32-mutex
win32-process
win32-sapi
win32-service
Service Controller
Daemon
win32-shortcut
win32-sound
Author: Daniel J. Berger
Author: Park Heesob
Contributor: Shashank Date
Here you will find documentation for the libraries of the win32utils project. These libraries are designed to help you interface with various MS Windows systems, ranging from the clipboard to services.

The Win32Utils project only supports the NT family of operating systems. That means Windows NT 4, Windows 2000, Windows XP Pro, Windows 2003 Server, etc.

Click on the library name on the left to go to the documentation for that library. In some cases the documentation is generic. In others it's platform specific.

Most of these libraries are pure Ruby. A few are C extensions, and require a compiler. However, even if you don't have a compiler, you can download and manually install the pre-build shared object from the download area. Look for the '.so' files.

Note that some libraries, such as win32-api and win32-service, have gems that contain prebuilt binaries so no compiler is necessary for those libraries. Just install them as you would any other gem.

Below is a quick synopsis of each library. Those that require a compiler are specifically tagged as such.

win32-changenotify

The win32-changenotify library lets you monitor files or directories for certain events, such as when a file is created, modified, deleted, etc.

Although deprecated in favor of win32-changejournal on NTFS filesystems, this library is still maintained because not everyone uses NTFS. It also has the advantage of being pure Ruby, which may or may not be a selling point for you.

Installation: gem install win32-changenotify.

win32-clipboard

The win32-clipboard library lets you interface with your system's clipboard. You can get, set or clear you clipboard, among other things.

Installation: gem install win32-clipboard

win32-dir

The win32-dir library adds methods and constants over and above the core Ruby 'Dir' class. In addition to adding support for creating junctions (symlinks for directories), a series of extra system constants are provided that can help you write more robust code.

For example, instead of hard coding 'C:\WINNT' you could use Dir::WINDOWS. This is a better approach, because there's no guarantee that your Windows directory is actually set to 'C:\WINNT', e.g. on some systems it's set to 'C:\WINDOWS'.

Installation: gem install win32-dir

win32-event

The win32-event library provides an interface to native MS Windows Event objects.

Applications use event objects in a number of situations to notify a waiting thread of the occurrence of an event. For example, overlapped I/O operations on files, named pipes, and communications devices use an event object to signal their completion.

Installation: gem install win32-event

win32-eventlog

The win32-eventlog library provides an interface for you to read from, and write to, the MS Windows Event Log.

In addition, a wrapper for the 'mc' (message category) command line utility is provided. This allows you to create your own event source, which you can then write to.

There is also a Tutorial that describes how to create your own event source.

Installation: gem install win32-eventlog

win32-ipc

The win32-ipc library provides an abstract base class (with methods) for use with native MS Windows Interprocess Communication, such as events and semaphores.

It is unlikely that you would ever use this library directly, but it is a prerequisite for several other libraries.

Installation: gem install win32-ipc

win32-mmap

The win32-mmap library provides an interface for native memory mapped IO (i.e. shared memory) on MS Windows.

Installation: gem install win32-mmap

win32-mutex

The win32-mutex library provides an interface for native MS Windows Mutexes.

You can use a mutex object to protect a shared resource from simultaneous access by multiple threads or processes. Each thread must wait for ownership of the mutex before it can execute the code that accesses the shared resource.

win32-process

The win32-process library adds the Process.create and Process.fork methods for MS Windows. In add addition, it provides different implementations of the wait, wait2, waitpid, and waitpid2 methods.

The Process.create method allows you to create native MS Windows processes using a variety of different configuration options.

The Process.fork implementation should be considered experimental and not used in production code.

Installation: gem install win32-process

win32-sapi

The win32-sapi library provides an interface for the Microsoft Sound API (5.1 or later). With this library you can do things such as synthesized speech, among others. Potentially useful for the sight disabled.

You can find more information about the MS Sound API at http://www.microsoft.com/speech/download/old/sapi5.asp. If that address becomes defunct, just go to http://www.microsoft.com and search for 'SAPI'.

Installation: gem install win32-sapi

win32-service

The win32-service library provides an interface for creating, controlling and configuring existing Windows services. In addition, you can create your own services using the Daemon class that comes as part of this library.

Installation: gem install win32-service

win32-shortcut

The win32-shortcut library allows you to create or modify shortcuts on MS Windows. You can also find out various tidbits of information, such as the file it points to, path, etc.

Installation: gem install win32-shortcut

win32-sound

The win32-sound library provides an interface for playing system sounds or .wav files. It also provides basic methods for gathering sound device information and volume control.

Installation: gem install win32-sound