OpenComm

2.x

int OpenComm(lpszDevControl, cbInQueue, cbOutQueue)
LPCSTR lpszDevControl;	/* address of device-control information	*/
UINT cbInQueue;	/* size of receiving queue	*/
UINT cbOutQueue;	/* size of transmission queue	*/

The OpenComm function opens a communications device.

Parameters

lpszDevControl

Points to a null-terminated string that specifies the device in the form COMn or LPTn, where n is the device number.

cbInQueue

Specifies the size, in bytes, of the receiving queue. This parameter is ignored for LPT devices.

cbOutQueue

Specifies the size, in bytes, of the transmission queue. This parameter is ignored for LPT devices.

Return Value

The return value identifies the open device if the function is successful. Otherwise, it is less than zero.

Errors

If the function fails, it may return one of the following error values:

Value

Meaning

IE_BADID	The device identifier is invalid or unsupported.
IE_BAUDRATE	The device's baud rate is unsupported.
IE_BYTESIZE	The specified byte size is invalid.
IE_DEFAULT	The default parameters are in error.
IE_HARDWARE	The hardware is not available (is locked by another device).
IE_MEMORY	The function cannot allocate the queues.
IE_NOPEN	The device is not open.
IE_OPEN	The device is already open.

If this function is called with both queue sizes set to zero, the return value is IE_OPEN if the device is already open or IE_MEMORY if the device is not open.

Comments

Windows allows COM ports 1 through 9 and LPT ports 1 through 3. If the device driver does not support a communications port number, the OpenComm function will fail.

The communications device is initialized to a default configuration. The SetCommState function should be used to initialize the device to alternate values.

The receiving and transmission queues are used by interrupt-driven device drivers. LPT ports are not interrupt driven—for these ports, the cbInQueue and cbOutQueue parameters are ignored and the queue size is set to zero.

Example

The following example uses the OpenComm function to open communications port 1:

idComDev = OpenComm("COM1", 1024, 128);
if (idComDev < 0) {
    ShowError(idComDev, "OpenComm");
    return 0;
}

err = BuildCommDCB("COM1:9600,n,8,1", &dcb);
if (err < 0) {
    ShowError(err, "BuildCommDCB");
    return 0;
}

err = SetCommState(&dcb);
if (err < 0) {
    ShowError(err, "SetCommState");
    return 0;
}