DOCERR: Get/SetCommEventMask Functions Documented Incorrectly

The information in this article applies to:

• Microsoft Windows Software Development Kit (SDK) for Windows versions 3.0 and 3.1

SUMMARY

The descriptions in the Microsoft Windows SDK "Reference Volume 1" of GetCommEventMask() and SetCommEventMask() fail to make clear the correct use of these routines and their usefulness. This article provides additional documentation for these important communications functions.

MORE INFORMATION

Some background information is in order. In a communications context, the "event word" is a word of memory the bits of which specify the events that have occurred. An "event mask" is a word-sized parameter to a function. The bits of the event mask specify the bits in the event word that are affected by a given function call.

WORD GetCommEventMask(nCid, nEvtMask)

The description for the GetCommEventMask() function, on page 4-162 of the SDK reference, reads as follows:

   This function retrieves the value of the current event mask, and
   then clears the mask.

   This function retrieves the value of the current event word, and
   then clears those bits in the event word that are specified by the
   nEvtMask parameter.

Note: The GetCommEventMask() API will return the entire current event word regardless of the value of nEvtMask.

WORD FAR * SetCommEventMask(nCid, nEvtMask)

The description for the SetCommEventMask() API, on page 4-373 of the SDK reference, reads as follows:

   This function enables and retrieves the event mask of the
   communications device specified by the nCid parameter. The bits of
   the nEvtMask parameter define which events are to be enabled. The
   return value points to the current state of the event mask.

   This function enables the event mask of the communications device
   specified by the nCid parameter. The bits of the nEvtMask parameter
   define which events are to be enabled. The return value points to
   the current state of the event word.