This article is from the Programming VCOMM FAQ, by firstname.lastname@example.org (Taed Nelson) with numerous contributions by others.
There needs to be a better description (like that found in the TAPI
documentation for its structures, which uses a chart format) of which fields
are read and written by VCOMM, and which should be read and written by the
port driver. And also a complete description of what each field is used for
by VCOMM and the port driver.
10.9.1: Notification fields
The fields for support notification such as lpClientEventNotify,
lpClientReadNotify, lpClientWriteNotify etc. are defined in the _PortData
structure. But serial driver doesn't use it and defines similar additional
fields inside _PortInformation structure. Why?
Is it possible to use the fields within the port driver? Serial.vxd keeps its
own copy of the data, but does not update _PortData. Does VCOMM copy this
information into _PortData when it passes the SetCallback functions down to
the port driver?
In all cases, the rules of using those fields must be documented.
This field is not described.
It seems that every time a character is received (including echo characters
and response codes from "virtual modems"), this field should be updated with
the result of Get_Last_Updated_System_Time. (See also
This seems to allow VCOMM to perform timeouts using the entries in the
COMMTIMEOUTS structure. This is also undocumented.
[See also "CommTimeouts".]
There are many more fields in VCOMM.H than are described in COMM.DOC.
Serial.vxd makes use of some of these "extra" error values, such as
IE_HARDWARE. Additionally, COMM.DOC defines two that are not in VCOMM.H:
IE_CHARWAITING and IE_TIMEOUT.
The descriptions of IE_DEFAULT differ significantly between COMM.DOC and
VCOMM.H. The first states "some general error occurred", while the second
defines an "error in default params". It seems that SERIAL.VXD uses it more
as a catch-all error condition, rather than referring specifically to the
passed parameters of a function.
Should this field be updated with the value 0 when a function returns
successfully? The wording of the Vcomm documentation is unclear as to whether
it should contain the last actual error, or just the last return value.
Serial.vxd writes a 0 much of the time, but often does not.