APMLib 1.0 package
==================

The APMLib package provides an interface to program the APM BIOS for PC, version
1.1 or later, to shut down and suspend your PC. It also provides routines
for rebooting and flushing the caches of your PC.

1.- Components, packages and versions
2.- Usage
3.- Limitations
4.- Future plans
5.- Error messages
6.- Contacting and reporting bugs
7.- Copyright


1.- COMPONENTS, PACKAGES AND VERSIONS
======================================

Each APMLib package is distributed including the following files:

MAKEDJ.BAT	      Script for building the DJGPP version

DOC                   Documentation folder
DOC\README.TXT        The Read Me document for APMLib (description and copyright)
DOC\NEWS09.TXT        News items posted to the FreeDOS mailing list, for versions 0.9
		      and Beta2
DOC\NEWS.TXT          News item posted to the FreeDOS mailing list
DOC\LGPL.TXT          A copy of the LGPL license, under which APMLib is released
DOC\APMLIB.TXT        This file

INCLUDE               Header files for the C source
INCLUDE\APMLIB.H      Header for the AMPLib library
INCLUDE\CEXT.H        Additional header used by APMLib (C extensions)

BIN                   Precompiled Borland C modules
BIN\APMLIBS.OBJ       APMLib compiled in the small memory model

LIB                   Borland C Libraries
LIB\APMLIBS.LIB       APMLib.LIB made from the small memory model compiled APM

UNITS                 Pascal units
UNITS\APMLIB.TPU      TurboPascal unit
UNITS\APMLIB.PPU      FreePascal unit

SOURCE                Source files
SOURCE\APMLIB.C       C source file
SOURCE\APMLIB.PAS     Pascal source file

EXAMPLES              Examples (source and executables)
EXAMPLES\APMTest.EXE  APM Library testing program (DOS executable)
EXAMPLES\APMTest.PAS  APM Library testing program (source)
EXAMPLES\SHUTDOWN.C   Shut down your PC (source)
EXAMPLES\SHUTDOWN.EXE Shut down your PC (DOS Executable)
EXAMPLES\SHUTDOWN.GDT/.GPR DJGPP RHide project files

This package is labeled as:
     APMLib 1.00 English

This version is compatible with TC++1.0, TurboPascal 7.0, FreePascal 0.99.14a
and DJGPP 2.03

If you want to know about the latest update of the program, please contact
the authors as specified in (6).


2.- USAGE
=========
apmlib uses the functions implemented by this library/unit are (pseudocode):

------------------------------------------------------------------
   func apmlib (funktion: BYTE)
        ret ErrorCode;

manages the power of your PC. Constant codes for funktion are:

  APM_REBOOT_WARM :  performs a warm shutdown
  APM_REBOOT_COLD :  performs a cold shutdown
  APM_SUSPEND     :  suspends the system
  APM_CTRLALTDEL  :  reboots the PC
  APM_SHUTDOWN    :  turns the PC off

possible return codes: 

  APM_NOTHING        : invalid function code
  APM_NOT_INSTALLED  : APM interface is not present in your PC
  APM_ERROR_FLUSHING : one or more caches couldn't be flushed; check FlushAllCaches
  APM_SUSPEND_OK     : system was suspended, ok


------------------------------------------------------------------
   func FlushAllCaches () 
        ret ErrorCode;

flushes all caches. If returner code=0, then everything Ok. Else, one of the
caches failed to be flushed. Check section 5 to know which one failed, as well as a
list of the caches supported. It will also reset the disk system at the end. It
produces a log of the process into screen.

------------------------------------------------------------------
   func Reboot  (warm: bool);

Reboots your system. The warm value indicates if reboot should be warm or cold.
NOTE THAT CACHES ARE *NOT* FLUSHED. You should flush the caches before calling this
function.

------------------------------------------------------------------
   func ShutDown ();

Shuts your system down. This only works with APM BIOS version 1.1 or later.
NOTE THAT CACHES ARE *NOT* FLUSHED. You should flush the caches before calling this
function.

------------------------------------------------------------------
   func CtrlAltDel ();

This function has the same effect as performing a CtrlAltDel, this is, shooting int 19h.
NOTE THAT CACHES ARE *NOT* FLUSHED. You should flush the caches before calling this
function.

------------------------------------------------------------------
   func Suspend ();

This function suspends the system, taking it to a minimum power consume mode, until
you press a key. This only works with APM BIOS version 1.1 or later.

------------------------------------------------------------------
   func APMIsInstalled
        ret bool;

This function checks the existence of the APM-BIOS in your system, and updates the
version variables. Returns TRUE whenever the APM-BIOS is found.

------------------------------------------------------------------
   func APMGetVer
        ret Max, Min;

This function returns the Max.Min version of the APM-BIOS. Note that this version MUST
be updated first, by calling APMIsInstalled. Otherwise, the returned version is not
valid.


3.- LIMITATIONS
================

APMLib has been designed to work under DOS systems. Note the following limitations:

- DPMI server for DJGPP version is not included. Please, use that one from your system or search for CWSDPMI on simtel.net

- FlushAllCaches works with a limited list of the most popular caches, listed in
section 5.

- Reboot: If MF-II keyboard (AT keyboard) present, it uses an
optimised method. Otherwise, it performs the traditional one.

- ShutDown and Suspend: they only work with APM-BIOSes ver 1.1 or later.

- CtrlAltDel: not known limitations. It might not work if the Int 19h server is not
correctly installed.

- APMIsInstalled: not known limitations

- APMGetVer: APMIsInstalled MUST be called first.


4.- FUTURE PLANS
================

Current release is final, and there are not known bugs.

Future releases will be tested under:
- TurboC 2.02
- TurboPascal 5.5
Any feedback reported for these or other compilers will be greatly appreciated.

Other APM functions will be possibly added in the future, as well as ACPI support.

Support for other languages is a desirable option too, specially for those
languages spoken in the member countries of the European Community. If you
speak an unsupported language, and would like to contribute, please contact
the authors as specified in (6).


5.- ERROR MESSAGES
==================

The error code returned in the FlushAllCaches function is a bit field, each bit
corresponding to each of the caches/disk reset tried. Check the following table to
have a list of flushed caches and corresponding bits:

          Name                                   Bit(Weight)
Caches =========================================================
        CD-Blitz                                       0 (1)
        PC-Cache (*)                                   1 (2)
        Quick-Cache                                    2 (4)
        Super PC-Kwik (PC-Tools, Qualitas QCache,...)  3 (8)
        MS-SmartDrv.EXE (*)                            4 (16)
        MS-SmartDrv.SYS                                5 (32)
Reset disks ====================================================
        Reset Disk system                             15 (32768)
================================================================
(*) In this version, this cache will never fail


6.- CONTACTING AND REPORTING BUGS
=================================

You can contact the authors via e-mail:
Florian Xaver <dos.fire@aon.at> for the DJGPP version
Aitor Santamaria <aitor.sm@terra.es> for the rest

please, place APMLib somewhere in your subject line. Contacting the author will
help you:
- Know about latest release
- Try to solve your problems
- Get more information about APMLib
- Get more information about other programs available

There are currently no known bugs. If you want to submit a bug, please check
that it is a real bug, and if it is, then submit a mail to the author
stating:
- Information about your system, specially DOS system and version, APM-BIOS version
and all the caches used, with versions (if appliable)
- How your APMLib is installed
- A description of the problem as accurate as possible


7.- COPYRIGHT
=============

APMLib is a package to manage the power in your DOS
Copyright (C) 2000 - Aitor Santamaria
DJGPP Port and func amplib for C
Copyright (C) 2001 Florian Xaver


-------------------------------------------------------------
This package is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details (www.gnu.org)
-------------------------------------------------------------
