SetupComm
The SetupComm
function initializes the communications parameters for a specified
communications device.
BOOL SetupComm(
|
HANDLE hFile, |
// handle of
communications device |
|
DWORD dwInQueue, |
// size of input
buffer |
|
DWORD dwOutQueue |
// size of output
buffer |
|
); |
|
Parameters
hFile
Identifies
the communications device. The CreateFile function returns this handle.
dwInQueue
Specifies the
recommended size, in bytes, of the device s internal input buffer.
dwOutQueue
Specifies the
recommended size, in bytes, of the device s internal output buffer.
Return Values
If the
function succeeds, the return value is nonzero.
If the function
fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
After a
process uses the CreateFile function to open a handle to a
communications device, it can call SetupComm to set the communications
parameters for the device. If it does not set them, the device uses the default
parameters when the first call to another communications function occurs.
The dwInQueue
and dwOutQueue parameters specify the recommended sizes for the internal
buffers used by the driver for the specified device. For example, YMODEM
protocol packets are slightly larger than 1024 bytes. Therefore, a recommended
buffer size might be 1200 bytes for YMODEM communications. For Ethernet-based
communications, a recommended buffer size might be 1600 bytes, which is
slightly larger than a single Ethernet frame.
The device
driver receives the recommended buffer sizes, but is free to use any input and
output (I/O) buffering scheme, as long as it provides reasonable performance
and data is not lost due to overrun (except under extreme circumstances). For
example, the function can succeed even though the driver does not allocate a
buffer, as long as some other portion of the operating system provides
equivalent functionality.
If the device
driver determines that the recommended buffer sizes involve transfers beyond
its ability to handle, the function can fail.
See Also