WriteFile

Description:
Send the data to other nodes in ARCNET networks.

Syntax:

BOOL WINAPI WriteFile( __in HANDLE hDev, __in LPCVOID lpBuffer, __in DWORD nNumberOfBytesToWrite, __out_opt LPDWORD lpNumberOfBytesWritten, __inout_opt LPOVERLAPPED lpOverlapped );

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 containing the data to be written to the 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.
nNumberOfBytesToWrite The number of bytes to be written to the device.
Note: This parameter specify the length of the ARCNET packet (see Format of ARCNET packet below).
lpNumberOfBytesWritten A pointer to the variable that receives the number of bytes written.
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_BAD_PACKET_SIZE
E_FARC_NO_LONG_PACKETS
E_FARC_BAD_SID
E_FARC_EXCESSIVE_RECON
E_FARC_NOT_INITED
E_FARC_NAK_TX
E_FARC_NO_RESPONSE
E_FARC_INITIALIZING
E_FARC_WRITE_DENIED
E_FARC_USAGE_EXPIRED
E_FARC_PENDING
E_FARC_ABORT

Format of ARCNET packet:

item size note
Node-ID of transmitter(SID) 1 byte  Should be the same as the node-id during initializing with IOCTL_FARC_INIT
Node-ID of receiver(DID)  1 byte  0, if packet is broadcast message otherwise node-id of the receiver
Userdefined Timeout  1 byte  Userdefined timeout: value * 100msIf the destination node responds with a NAK to the transmitting node (because receiver has no page free to receive any packets), the driver will try up to timeout milliseconds transmitting the packet to the destination node before it will return with E_FARC_NAK_TX. If set to 0, the driver will try a maximum of 4/128 times (respectively to z_four_naks in DCB).
Reserved  3 byte  Not yet in use and will not be transferred, must be set to 0
Data  1-253 byte or 257-508 byte If the application wants to transfer 254-256 bytes, it must split the data into two packets or fill up the buffer, so the buffer has a size of 257 or more bytes. This is because ARCNET is due to its protocol not capable of transferring packets with the size of 254-256 bytes.

Notes:

The controller must be initalized with IOCTL_FARC_INIT, otherwise WriteFile()-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.

OVERLAPPED overlapped; DWORD written, err; unsigned char packet[514]; BOOL ret; overlapped.Offset = 0; overlapped.OffsetHigh = 0; overlapped.hEvent = CreateEvent(NULL,TRUE,FALSE,NULL); ... packet[0] = 12; // our own node packet[1] = 0; // broadcast message packet[2] = 0; // user timeout disabled packet[3] = 0; packet[4] = 0; packet[5] = 0; packet[6] = 55; // data packet[7] = 20; // data length = 8; // 8 bytes in buffer handed to WriteFile ret = WriteFile(drvhandle, packet, length, &written, &overlapped); if (!ret) { err = GetLastError(); if (err == E_FARC_PENDING) { ret = GetOverlappedResult(drvhandle, &overlapped, &read, TRUE); if (!ret) { err = GetLastError(); switch (err) { case E_FARC_NAK_TX: // destination node responds with NAK break; case E_FARC_NO_RESPONSE: // destination node does not answer break; } } else { // OK, WriteFile finished } } else { // other error occured, perhaps wrong handle } }

See also:
DeviceIoControl()
IOCTL_FARC_INIT

Back to Programming Guide