TCAP API (Application Programming Interface) Information
Copyright(c) 1998 Tim Kannel

The information in this file is rather technical; knowing it
is not necessary for normal use of TCAP. This information
will not be useful to anyone that is not a programmer.
However, I would like to know if anyone does use this information.

Disclaimer
----------
    The author of TCAP is not liable for any damage caused by
  use of the program or this API. Due to the nature of the program
  (a TSR/background utility) your system could potentially become unstable,
  so use with caution.

Contents
--------
 - Miscellaneous information
 - API specification

TCAP has an interface available to applications that can be
used to determine if TCAP is running, and, if it is running,
whether TCAP is currently capturing console I/O. Capturing
can also be turned on or off.

A C/C++ wrapper to the assembly-language API is provided in
TCAP.H and TCAP.C.

The API is implemented through the multiplex interrupt, interrupt 2Fh.
In general, AH contains TCAP's ID number and AL contains
a function code. The ID number is determined using the first function.
Registers not used to return values are not modified.

"Command" specifically refers to a command or program run with the
/C command-line option, not commands or programs run during a
general capture session (running TCAP without the /C command-line option).

Tip: If your program runs TCAP to capture text from another program
  (using the /C command-line option) TCAP may or may not be running before
  and after the other program executes. Make sure that TCAP is running (see
  the first API function) before using any of the other API functions from
  the primary program.

Note: This API is only supported in versions 3.0+
  A method for detecting whether the full API is available is
  described in the notes for the first function (which is available
  under any version).


API Specification
-----------------

Determining if TCAP is installed (TCAP installation check)
  Input:  AH = multiplex ID (see notes)
          AL = 0
  Output: AH = 0 or multiplex ID (see notes)
          AL = 0FFh
          ES:DI = pointer to signature string (see notes)

  Notes:  AL = 0FFh is the primary indicator that TCAP is installed.
          However, since TCAP does not use a predefined ID value, as
          described below, the signature string should also be verified.

          The signature string is
               0 1 2 TCAP 2 1 0
          without the spaces. The numbers are integers, not ASCII characters.
          As a C-style string it's "\0\1\2TCAP\2\1\0".  C/C++ programmers
          should realize that this string can not be compared with
          strcmp() because of the embedded zeros; use (a far version of)
          memcmp(). (Similar restrictions may apply to other
          languages, of course.)

          The multiplex ID is determined by TCAP when it is installed.
          The ID will be in the range 128 <= ID <= 255.  To determine
          if TCAP is installed, each number in that range must be
          tested until the desired output is generated. If the
          indicated output does not appear for any ID value in the allowed
          range then TCAP is not installed.

          This mechanism for installation-checking is used by many other
          programs, some of which use ID values in that range. Therefore,
          the value of AL is not sufficient to determine that TCAP is the
          program which is responding. This is why it is necessary to
          check the signature string.

          The value of AH upon return will be 0 for a version of
          TCAP that supports this interface (3.0+); AH is unchanged
          under previous versions. Unless you know your program will
          only be used with version 3.0+, the program should check AH before
          calling any of the other functions.

          Be sure to save the ID number if your program plans on calling
          any of the other functions. (And don't rely on the ID number
          being present in AH after calling this function!)

Getting TCAP's version number
  Input:  AH = multiplex ID
          AL = 1
  Output: AH = major version number
          AL = minor version number
          BX = capabilities flags

  Notes:  The current version, version 3.1, returns 0301h in AX.
          Note that minor version numbers are a single digit in the
          lower half of the lower byte.

          The value returned in BX is currently defined as follows:
             Bit(s)     Meaning (if the bit(s) are nonzero)
             0          supports /overwrite and /append command-line options
             1          supports and uses long filenames for the capture file
             2-15       not used,reserved for future use (these bits are zero)

          Bit 0 is always set as of version 3.1.

          Bit 1 was always zero prior to version 3.1, its value under
          version 3.1 (or later) is variable: if the operating system does
          not support long filenames then the bit is zero, otherwise this
          bit MAY be set to one. The bit will be set if TCAP was able to
          successfully open or create the capture file using the
          long filename functions, otherwise the bit will be clear.
          This bit does not apply to executable filenames used with the
          /C command.

Finding out whether TCAP is currently capturing console I/O
(Get Capture Flag)
  Input:  AH = multiplex ID
          AL = 2
  Output: AX = capture flag

  Notes:  If the flag is zero then capturing is disabled; any nonzero value
          indicates that capturing is enabled.

Setting the state of the console I/O capturing
(Set Capture Flag)
  Input:  AH = multiplex ID
          AL = 3
          BX = new value for capture flag
  Output: none (capture flag is set to the indicated value)

  Notes:  If the flag is zero then capturing is disabled; any nonzero value
          indicates that capturing is enabled.

          This function also attempts to flush the capture buffer.

Getting the number of bytes remaining in TCAP's buffer
  Input:  AH = multiplex ID
          AL = 4
  Output: AX = number of bytes waiting to be flushed

  Notes:  Function 5 can be used to flush the buffer (see below).

Flushing the capture buffer
  Input:  AH = multiplex ID
          AL = 5
  Output: AX = bytes remaining to be flushed

  Notes:  The return value will usually be zero, indicating that
          the buffer was successfully written to disk. However,
          certain conditions may prevent the flush from occurring.

Get Overflow Status
  Input:  AH = multiplex ID
          AL = 6
  Output: AX = primary overflow status
          BX = overflow status of last command

  Notes:  Overflow status refers to whether bytes were lost during
          the capture as a result of not being able to flush the
          buffer when necessary. The primary overflow status is the
          current overflow status. The overflow status of the last
          command refers to the overflow status from the last time
          a command or program was run with the /C option. If no
          commands have been run this value will be zero. The primary
          overflow status is saved and reset before running a command
          with the /C option; it is restored when the commmand completes.

          On a related note, the errorlevel returned by TCAP when an
          overflow occurred is 255. (That's as of version 3.0, previous
          versions returned a different value). The value of this overflow
          indicator is subject to change in future versions.

          Forced Overflow Conditions

          The use of the /C option to run a command or program
          changes the current capture file (unless the appropriate
          option is used to prevent the change). The change occurs
          both before and after running the command (the change after
          restores the previous filename). Before both filename changes
          TCAP attempts to flush its buffer to prevent buffered text from
          being written to the wrong file. If the flush fails the
          current contents are discarded and an overflow condition is
          forced. This event, however, should be very rare, if not
          impossible. These explicit flushes occur regardless of whether
          the filename actually changed.
