Welcome to libwin32 version 0.15.


WHAT
----

This used to be a bundle of extensions that provided a quick migration path
for people wanting to use the core support for win32 in perl 5.004 and later.

With the release of Perl version 5.005 (which brings ActiveState's changes
to Perl sources into the mainstream), this library of extensions has
assumed loftier motives.  The long term goal of this project is to provide
a coherent collection of modules that allow access to the functionality
provided by the Win32 API, while maintaining the style and spirit of Perl.
Like Perl, the intention is to make "easy things easy, and hard things
possible".  Note that we are nowhere close to this goal at the present
time, but we are slowly getting there.

As the name suggests, all modules in this distribution are Win32-specific.
They cannot be used on platforms that do not support the Win32 API.

This distribution contains pre-compiled binaries for the x86 architecture.
See the "WHAT TO DO" section for installation instructions.


WHAT HAS CHANGED
----------------

The top level "Changes" file contains a version by version overview of
the most significant changes.

This release has the following changes over the previous one (version 0.14):

  + Win32API-File-0.07 has been added (thanks to Tye McQueen).  This module
    provides low-level access to file and directory functions.

  + Win32-OLE has been upgraded to v0.1101 (thanks to Jan Dubois).
    Be sure to check out the cool new component browser (needs IE5).
    Type "perldoc Win32::OLE::NEWS" and/or see OLE/Changes for detailed
    notes.

  + Win32API-Net has been upgraded to v0.08 (thanks to Bret Giddings).
    NOTE: There is a POTENTIAL INCOMPATIBILITY in how empty string values
    are handled in input hashes.
    See APINet/Changes and the pod documentation for detailed notes.

  + Win32API-Registry has been upgraded to v0.17 (from Tye McQueen).
    See APIRegistry/Changes for detailed notes.

  + Win32-TieRegistry has been upgraded to v0.23 (from Tye McQueen).
    See TieRegistry/Changes for detailed notes.

  + Win32-Sound has been upgraded to v0.45 (from Aldo Calpini).  The new
    version supports wave devices and volume controls, and also sports pod
    documentation.

  + A few bugs in Win32-EventLog have been fixed (thanks to Bret Giddings
    and Jan Dubois).  There is also newer documentation in pod format.
    NOTE: There is a POTENTIAL INCOMPATIBILITY in the Report() method,
    which will now use the "Source" and "Computer" fields in the passed
    hashref if they exist.
    See EventLog/Changes and the pod documentation for details.

  + A typo in Win32::Console::GenerateCtrlEvent() has been fixed.
    Documentation in pod format has been added (from Jan Dubois).

  + Win32::NetResource::GetSharedResources() now continues the enumeration
    when there are "Access denied" errors; on other errors, it enumerates
    all the resources seen until the point the error occurred.

  + Minor changes in Win32-ODBC from various people have been included.
    See ODBC/Changes for a summary.

  + Other small changes for Perl 5.005xx compatibility and minor bug
    fixes round out this release.

Many thanks to all the contributors.


WHAT IT HAS
-----------

This bundle contains:

  * The collection of modules originally distributed by the ActiveState
    folks as part of their "Perl for Win32"(TM) port.  These have been
    modified so that they will build under MakeMaker using perls greater
    than 5.004.  There have been many bugfixes.

    The following extensions are available:

       Win32/ChangeNotify
       Win32/EventLog
       Win32/File
       Win32/FileSecurity
       Win32/IPC
       Win32/Mutex
       Win32/NetAdmin
       Win32/NetResource
       Win32/OLE
       Win32/Process
       Win32/Registry
       Win32/Semaphore
       Win32/Service
       Win32/WinError

    Note this covers all of the Win32 extensions distributed by
    ActiveState (as of build 316).  Win32::OLE is currently most
    actively maintained by Jan Dubois <[email protected]>.

    These extensions have been re-engineered to use the XS interface
    language, but the changes are compatible with the originals.  This
    should minimize any problems for people wanting to migrate their
    application to 5.004 or later.  The design of these modules is
    subject to change in future.

    The only deliberately incompatible change is in the Win32::OLE
    module.  While the ActiveState port used the "OLE::" and "Win32::"
    namespaces for the functionality contained in this module, this
    port uses "Win32::OLE::" consistently.  For a list of other
    incompatibilities in Win32::OLE, see the embedded documentation
    in "OLE/OLE.pm".

  * The following five modules maintained by Aldo Calpini
    <[email protected]>:

       Win32/Clipboard
       Win32/Console
       Win32/Internet
       Win32/Shortcut
       Win32/Sound

    These also have been converted back to XS.  I have added
    bug fixes as I found them during the conversion process.

  * Two useful modules maintained by Dave Roth <[email protected]>.

       Win32/ODBC
       Win32/Pipe

    These have only received just the bare modifications needed to
    build them under MakeMaker.  *.xs are really C/C++ files
    masquerading as XS.

  * The Win32::PerfLib module to access performance counters on
    remote and local Windows NT systems, contributed by
    Jutta M. Klebe <[email protected]>.

  * The Win32::TieRegistry module for easy access to the registry,
    layered over the Win32API::Registry module that exposes the
    Registry API functions.  Both modules are maintained by Tye McQueen
    <[email protected]>.

  * The Win32API::File module to provide low level access to most
    Win32 API calls related to files, also maintained by Tye McQueen
    <[email protected]>.

  * The Win32API::Net module, which is a small step towards
    comprehensive Net* API functionality, maintained by Bret Giddings
    <[email protected]>.


WHAT TO DO
----------

NOTE: If you already have ActivePerl build 520 or later, you do not
need to install this!  ActivePerl build 520 and later are already
bundled with libwin32-0.15 (or better).

If you built Perl from source using your C compiler, you need to
ignore the binaries supplied here and rebuild all the extensions
here from scratch.

If you have either a compatible ActivePerl (later than build 509) or
the older 5.00402 distribution, you can install the binaries that come
with this distribution.

If you are using ActivePerl build 509 or later:

  + You will use the PPM tool supplied with ActivePerl for the
    installation.  Type the following at a command prompt:

       ppm install .\libwin32.ppd

    That's it.

If you are using $CPAN/authors/id/GSAR/perl5.00402-bindist04-bc.zip :

  + Note that the above distribution comes with an older version of
    libwin32, but you'll be completely replacing that in the next step.

  + Run the "install.bat" in this distribution from the command prompt.
    This should take care of installing everything in the right place.

Many modules come with their own test files.  You may want to use them
as a source of examples.  Many of the test files will only run on
Windows NT, others may require Windows NT 4.0, and still others may
require Administrator privileges, or a full-fledged Windows network.

The following applies only if you need to rebuild using your C compiler.
(Note that you HAVE to do this if you built Perl yourself.)  Otherwise,
skip to the next section.

This set of modules will build with perl5.004_01 and later on the Windows
NT platform.  Building on Windows 95 is not supported (it *may* be
possible if you use the 4DOS command shell, but your mileage may vary).

  + First you need to build perl 5.005_03 or later (you will need
    either Visual C++ 4.x+ or Borland C++ 5.02+), and install it.  See
    README.win32 in the perl distribution for details on how to build
    perl for the Win32 platform.

  + Make sure your perl is properly configured.  "perl -V:libpth" should
    report a valid path to your compiler's library files.  Some versions
    of ActivePerl are known to report a bogus value here.

    To fix the problem, you will have to edit the Config.pm file (found
    somewhere like c:\perl\5.00503\lib\MSWin32-x86-object\Config.pm) and
    set the line that begins with "libpth=" to something like:

               libpth='c:\devstudio\vc\lib'

    If you built perl yourself and see the problem, it probably means you
    didn't specify the library location properly in the Makefile used to
    build perl.

    If your C compiler and libraries are installed in a path with
    spaces, you'll need to quote any components with spaces.  For
    example:

               libpth='c:\"Program Files"\DevStudio\vc\lib'

    Another common problem is not making perlcrt.lib available at
    your 'libpth' location.  perlcrt.lib may or may not be needed
    if you have perl 5.005 or later, depending on whether you built
    perl to use it.  ActivePerl needs it.

  + All that done, you need to extract this distribution into an NTFS
    partition (the tests in the FileSecurity module and Net* modules
    will fail otherwise).  The testsuite for OLE needs Excel to
    run.  NetAdmin will only work if you have some kind of
    live network connection, and are in a domain with a properly
    configured domain controller.  NetResource requires that you
    be part of a domain or workgroup.  You may also need
    Administrator privileges for running some of the tests.
    If one or more of these conditions will not be met, you may
    wish to build in the subdirectories one by one.  The steps
    below will work either at the toplevel directory, or in each
    of the individual extension subdirectories.

  + You need either MS Visual C++ (OLE needs 4.2b, NetAdmin needs ver.
    4.x+, Internet needs ver. 5.0. ver. 2.0 should suffice for the
    others) or Borland C++ 5.02.  Make sure you have the full installation
    of either of these compilers ("Minimal" installations or CDROM-based
    installations may have problems finding all the libraries).

  + If the Internet extension doesn't build due to lack of libraries
    (the wininet.h header is included), fetch the Platform SDK from
    "http://www.microsoft.com/msdn/sdk/".  You need to look for wininet.h
    and wininet.dll.  If either of those is newer than the ones you already
    have, replace the older ones, and copy the newer wininet.lib into the
    Internet/ directory.

  + Remove the 'blib' directory (it contains precompiled binaries)

  + perl Makefile.PL               [either at toplevel or in subdirs]

  + $MAKE                          [either at toplevel or in subdirs]

  + $MAKE test                     [optional, some interactive tests]

  + $MAKE install                  [either at toplevel or in subdirs]

$MAKE above stands for either "dmake" or "nmake" depending on your
available compiler, and perl configuration.


WHAT THEN
---------

If you find any problems with these modules, kindly report them to both
the original author and to me.  While I have fixed many problems in these
modules, I may also have introduced brand new bugs in the process :)

I wish to thank the authors of these modules for their effort in making
them useful, and for making them freely available.

Suggestions, patches, testsuite additions, and wholesale rewrites welcome.

Enjoy!

Gurusamy Sarathy
[email protected]
25 Sep 1999


WHATEVER
--------

Copyright for many of the modules is held by their respective authors.
Look in the module subdirectories for any conditions of use.

The following copyright applies to all files that don't have an explicit
copyright statement:

   (c) 1995 Microsoft Corporation. All rights reserved.
       Developed by ActiveWare Internet Corp., http://www.ActiveWare.com

   Other modifications (c) 1997-1999 by Gurusamy Sarathy <[email protected]>

   You may distribute under the terms of either the GNU General Public
   License or the Artistic License, as specified in the README file
   of the Perl distribution.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.