ReadFile
Description:
Read received data (packet) from ARCNET controller.
By default the driver does not complete ReadFile() request until the ARCNET data packet was received. But it also possible to
set the timeout for ReadFile() to force the request completion on timeout. So if application set a the read timeout
with IOCTL_FARC_SET_READ_TIMEOUT to set to any non-zero value
the ReadFile() request will be completed with:
Syntax:
Parameters:
Parameter | Description |
hDev | A handle to the device obtained by CreateFile. For asynchronous read operations, hDev must be a handle that is opened with the FILE_FLAG_OVERLAPPED flag by the CreateFile function |
lpBuffer | A pointer to the buffer that receives the data read from a device. This buffer must remain valid for the duration of the read operation. The caller must not use this buffer until the read operation is completed. Note: It is recommended to use the buffer with maximal ARCNET packet length 514 bytes. |
nNumberOfBytesToRead | The maximum number of bytes to be read. Note: It is recommended to specify the maximal ARCNET packet length (514 bytes). |
lpNumberOfBytesRead | A pointer to the variable that receives the number of bytes read. |
lpOverlapped | A pointer to an OVERLAPPED structure is required if the hFile parameter was opened with FILE_FLAG_OVERLAPPED, otherwise it can be NULL. If hDev is opened with FILE_FLAG_OVERLAPPED, the lpOverlapped parameter must point to a valid and unique OVERLAPPED structure, otherwise the function can incorrectly report that the read operation is complete. |
Return Value:
If the function succeeds, the return value is nonzero (TRUE).
If the function fails, or is completing asynchronously, the return value is zero (FALSE).
To get extended error information, call the GetLastError() function.
Possible errors (see also Error codes ):
E_FARC_INVALID_HANDLE
E_FARC_READ_TIMEOUT
E_FARC_BAD_PACKET_SIZE
E_FARC_EXCESSIVE_RECON
E_FARC_NOT_INITED
E_FARC_INITIALIZING
E_FARC_USAGE_EXPIRED
E_FARC_PENDING
E_FARC_ABORT
Format of ARCNET Packet:
If ReadFile()-request returns successfully, the it contains an ARCNET packet in following format
item | size | note |
Node-ID of transmitter(SID) | 1 byte | node-id of the transmitter |
Node-ID of receiver(DID) | 1 byte | 0, if packet is broadcast message, otherwise node-id of the receiver |
Reserved | 4 byte | not yet in use, ignore |
Data | 1-253 byteor 257-508 byte | transferred raw data |
Notes:
1)ReadFile() returns the number of bytes returned in the receive buffer,
not the number of data bytes! If you want to get the number of received data bytes, subtract 6.
2) The controller must be initalized with IOCTL_FARC_INIT,
otherwise ReadFile()-request will alway fail with E_FARC_NOT_INITED.
Example:
Note, that the following example is only a fragment. It is recommended,
that the driver is opened in asynchronous mode and a IOCTL_FARC_INIT was successful performed.
Recommendations:
Have in mind, that the controller is capable of receiving 2 packets. It is good practice, to have 2 ReadFiles() requests permanently running to prevent data loss. Please note that those 2 requests must be always started from same thread.
See also:
DeviceIoControl()
IOCTL_FARC_INIT
IOCTL_FARC_SET_READ_TIMEOUT
IOCTL_FARC_GET_READ_TIMEOUT