VCOMM requests that a port driver carry out specific operations by calling port driver functions — that is, callback functions provided by the port driver. Most port driver functions correspond to specific VCOMM services. A port driver may support a subset of the port driver functions. The following sections briefly describe the various port driver functions.
To open the port, VCOMM calls the PortOpen function for the port driver that best supports the device. If successful, the PortOpen function returns the address of a _PORTINFORMATION structure. This address is used to identify the open port in all subsequent calls to port driver functions. The first field of the _PORTINFORMATION structure must be a _PORTDATA structure, but additional fields can be defined by the port driver. The _PORTDATA structure contains information about an open communications device that is used by VCOMM, the port driver, or both. It includes a pointer to the port driver's _PORTFUNCTIONS structure, that contains the addresses of all the port driver functions except Enumerator, Inquire, and PortOpen.
To close a communications port, VCOMM calls the port driver's PortClose function.
See also PortClose, _PORTDATA, _PORTFUNCTIONS, _PORTINFORMATION, PortOpen
When a port driver opens a communications port, it initializes it using a default configuration. A port's configuration is defined by its device control block, a _DCB structure. To enable a client to get and set the current configuration, a port driver provides the PortGetCommState and PortSetCommState functions.
The communications settings supported by a communications device are defined by a _COMMPROP structure. To enable a client to determine the available configuration settings, you must provide the PortGetProperties function.
A port driver initializes a port's receive and transmit queues to default sizes it specifies. To enable a client to override these, the port driver must provide the PortSetup function.
See also _COMMPROP, _DCB, PortGetCommState, PortGetProperties, PortSetCommState, PortSetup
To enable communications output, a port driver should provide a PortWrite function. For port drivers that use a transmit queue, the PortWrite function writes to the queue and returns immediately; an interrupt service routine actually sends the data. For port drivers that do not use a transmit queue, the PortWrite function sends the data and then returns. To enable a VCOMM client to resume transmission after a communications error, a port driver should provide a PortClearError function.
A port driver's PortTransmitChar function sends a high-priority character, such as an event character, ahead of any characters in the transmit queue. Typically, the port driver does not send the character immediately, but stores it in a special one-character buffer. The function can fail (return FALSE) if a character specified in a previous call is still waiting to be sent.
To enable communications input, a port driver should provide a PortRead function. For output-only devices, such as LPT ports, the PortRead function should simply return TRUE (success), and indicate zero bytes read. For port drivers that use a receive queue, the PortRead function should retrieve data from the receive queue and return immediately; an interrupt service routine actually reads data into the receive queue. The amount of data retrieved from the queue may be less than the amount requested. For port drivers that do not use a receive queue, the PortRead function actually reads data from the device. The amount of data read is less than the amount requested only if a read time-out occurs, in which case the return value is FALSE.
A port driver's PortGetQueueStatus function retrieves the status of the receive and transmit queues. A port driver's PortPurge function discards the contents of the transmit or receive queue.
See also PortClearError, PortGetQueueStatus, PortPurge, PortRead, PortTransmitChar, PortWrite
VCOMM clients can request that they be notified when communications events occur or when queue thresholds reach specified limits. In addition, VCOMM clients can enable or disable specific events and specify the location of the event variable.
To support event notification, a port driver provides the PortEnableNotification function. This function registers a callback function that the port driver calls when enabled events occur. Enabled events are specified by a 32-bit variable called the event mask. A port driver's PortSetEventMask and PortGetEventMask functions set and retrieve the event mask, and may also specify the location of the event variable. The PortSetModemStatusShadow function may also set the event mask.
To support queue threshold notifications, a port driver provides the PortSetReadCallback and PortSetWriteCallback functions. These functions set the notification thresholds for the receive and transmit queues, respectively, and register callback functions that the port driver calls when these thresholds are reached.
The PortEscapeFunction function enables port drivers to define extended functions. A set of common extended functions is defined in VCOMM.INC in the Windows 95 DDK. By defining additional extended functions, a port driver can expose capabilities of a device that are not otherwise defined by the communications API. Extended functions can be used in conjunction with driver-defined events to facilitate two-way message passing between a VCOMM client and a port driver.
See also _PORTDATA, PortEnableNotification, PortEscapeFunction, PortGetEventMask, PortSetEventMask, PortSetModemStatusShadow, PortSetReadCallback, PortSetWriteCallback, _VCOMM_GetModemStatus