VCOMM client VxD services enable VxDs to use any communications resource for which a port driver is installed. VCOMM provides services for opening and closing a communications resource, configuring a port, reading from and writing to a communications resource, processing communications events, and calling a port driver's extended functions. The following topics describe the VCOMM client VxD services.
VxDs use the VCOMM client VxD services for a variety of reasons. Following are some examples of VCOMM client VxDs:
Because creating a private VxD ties your application to Windows 95, you should do so only if necessary. Microsoft(r) Win32(r) applications are scheduled regularly enough to meet the timing requirements of most protocols, such as those for file transfer.
Before performing any other operations on a communications resource, a client VxD must call the _VCOMM_OpenComm service to open the resource. This service initializes the communications device and the port driver associated with it, and returns a communications handle that is used in subsequent calls to VCOMM client VxD services.
The _VCOMM_CloseComm service closes a communications resource. If the transmit queue is not empty, the close property of the port determines whether the remaining data is sent before the port is closed: if it is PORTCLOSE_WAIT, the service does not close the port and does not return until the characters in the transmit queue have been sent; if it is PORTCLOSE_FLUSH, the service discards the data in the transmit queue and closes the port immediately. You can query and set the close property using the _VCOMM_EscapeCommFunction service.
Client VxDs must close any communications resources they open. A VxD that opens a communications resource for use in a virtual machine (VM) must process the VM_Not_Executeable event so that it can close the resource if the VM terminates.
See also _VCOMM_CloseComm, _VCOMM_EscapeCommFunction, _VCOMM_OpenComm
You can use VCOMM services to configure a communications resource and initialize its receive and transmit queues. The _DCB (device control block) structure specifies the configuration settings for a communications resource - for example, the baud rate, the number of data bits per byte, and the number of stop bits per byte. Additional fields specify parity, handshaking options, and special characters used for handshaking or for signaling events.
When you open a communications resource, the port driver initializes it using a default configuration. You can determine the current configuration by calling the _VCOMM_GetCommState service, that fills in a _DCB structure. Before configuring the communications resource, you can determine which settings it supports by calling the _VCOMM_GetCommProperties service; this service fills in a _COMMPROP structure. To configure the communications resource, call the _VCOMM_SetCommState service.
To initialize the receive and transmit queues for a communications resource, call the _VCOMM_SetupComm service. The previous state of the receive queue is returned in the specified _QSB structure. If you do not call this service, the port driver uses default queues. The _COMMPROP structure specifies the default and maximum sizes of the receive and transmit queues. Note that port drivers for some devices, such as LPT ports, do not use queues.
See also _COMMPROP, _DCB, _QSB, _VCOMM_GetCommProperties, _VCOMM_GetCommState, _VCOMM_SetCommState, _VCOMM_SetupComm
To write to a communications resource, call the _VCOMM_WriteComm service. This service writes the specified data to the transmit queue and returns immediately. Always check both the return value of this service and the number of bytes written. If there is insufficient space in the transmit queue, the number of bytes written is less than the number requested - yet the return value is TRUE. In this case, call the _VCOMM_ClearCommError service to detect and reset any communications errors that may have occurred.
For communications devices that do not use transmit queues, such as LPT ports, _VCOMM_WriteComm actually writes the data to the device before returning. If a write time-out occurs, the number of bytes written is less than the number requested and the return value is FALSE.
To send high-priority characters, such as event characters, you can use the _VCOMM_TransmitCommChar service. This service sends a single character ahead of any data in the transmit queue. Until the hardware is ready to send the character, most port drivers store it in a special one-character buffer. If a character specified in a previous call to this service is still waiting to be sent, the service returns FALSE.
To read from a communications resource, call the _VCOMM_ReadComm service. This service reads the specified amount of data from the receive queue and returns immediately. Always check both the return value of this service and the number of bytes read. If the receive queue does not contain enough data, the number of bytes read is less than the number requested - yet the return value is TRUE. If the number of bytes read is zero, call _VCOMM_ClearCommError to detect and reset any communications errors that may have occurred.
For output-only devices, such as LPT ports, _VCOMM_ReadComm returns TRUE with zero bytes read. For other communications devices that do not uses receive queues, _VCOMM_ReadComm actually reads the data from the device before returning. If a read time-out occurs, the number of bytes read is less than the number requested and the return value is FALSE.
You can check the status of the transmit and receive queues by calling the _VCOMM_GetCommQueueStatus service; this service fills in a _COMSTAT structure. You can discard the contents of the transmit or receive queue by calling the _VCOMM_PurgeComm service.
See also _COMSTAT, _VCOMM_ClearCommError, _VCOMM_GetCommQueueStatus, _VCOMM_PurgeComm, _VCOMM_ReadComm, _VCOMM_TransmitCommChar, _VCOMM_WriteComm
A VCOMM client can receive notifications when communications events occur or when the receive and transmit queues pass specified thresholds. To receive notifications for events, call the _VCOMM_EnableCommNotification service. To receive notifications when queue thresholds are reached, call the _VCOMM_SetReadCallback and _VCOMM_SetWriteCallback services. All three services register client-defined callback functions with the port driver. For information about the callback functions, see the description of the CommNotifyProc function.
You receive notifications for communications events only if the events are enabled. To enable events, call the _VCOMM_SetCommEventMask service; this service specifies the event mask and, optionally, the address of the event variable. The event mask is a 32-bit variable that specifies the combination of enabled events. The event variable is a 32-bit variable that specifies the enabled events that were detected; the port driver updates the event variable at interrupt time when events occur. To determine which enabled events have occurred, call the _VCOMM_GetCommEventMask service; this service retrieves the detected events and clears the corresponding bits in the event variable.
If a hardware handshaking signal causes a notification, the parameters for CommNotifyProc identify the signal that changed but not the current state of the signal. To determine the current state of the clear to send (CTS), data set ready (DSR), receive line signal detect (RLSD), and ring signals, call the _VCOMM_GetModemStatus service.
See also CommNotifyProc, _VCOMM_EnableCommNotification, _VCOMM_GetCommEventMask, _VCOMM_GetModemStatus, _VCOMM_SetCommEventMask, _VCOMM_SetReadCallback, _VCOMM_SetWriteCallback
You can use the _VCOMM_EscapeCommFunction service to direct the port driver to carry out an extended function. Constants defined in VCOMM.INC identify several extended functions that can be used - for example, to get or set the close property, set or clear hardware handshaking lines, or reset an LPT port. Individual port drivers may support only a subset of the extended functions defined in VCOMM.INC.
To expose unique features of a communications device, port drivers can define driver-specific extended functions not in VCOMM.INC.
See also _VCOMM_EscapeCommFunction