AN197

Rev. 0.6

5

4.2. Reading Data

There are several things that need to happen in a read, so it is a good idea to create a function for the reads to be

called whenever a read must occur. Here is an example of a read function:

bool ReadData(HANDLE handle, BYTE* data, DWORD length, DWORD* dwRead, UINT timeout)

{

bool success= false;

OVERLAPPEDo= {0};

o.hEvent = CreateEvent(NULL, FALSE, FALSE, NULL);

if (!ReadFile(handle, data, length, dwRead, &o))

{

if (GetLastError() == ERROR_IO_PENDING)

if (WaitForSingleObject(o.hEvent, timeout) == WAIT_OBJECT_0)

success = true;

GetOverlappedResult(handle, &o, dwRead, FALSE);

}

else

success = true;

CloseHandle(o.hEvent);

return success;

}

The parameters passed in to this function are the handle to an open COM port, a pointer to an array of bytes that

will be read, the number if bytes that are in the array, a pointer to a variable to store and return the number of bytes

read, and a timeout value.

Two local variables are declared at the beginning of the function: a bool named success that will store the success

of the read (this is initialized to false, and only set true when the read succeeds), and an overlapped object o which

is passed to the ReadFile() function and alerts if the transfer is complete or not (this is always initialized to {0}

before the hEvent is assigned). Creating an event with the CreateEvent(NULL, FALSE, FALSE, NULL) function

sets the hEvent property of o to prepare it to be passed to the ReadFile() function (more information on

CreateEvent()

is

located

at

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dllproc/base/

Next, the ReadFile() function is called with the handle, data, length of the data, and variable to store the amount of

data that was written (more information on the ReadFile() function is located at http://msdn.microsoft.com/library/

default.asp?url=/library/en-us/fileio/base/readfile.asp). If this function returns successfully then a non-zero value is

returned. If the function fails, then it will return 0. The if statement will determine if the write succeeded and if it

didn't, the last error is retrieved to see if there really was an error or the write just wasn't finished. If

ERROR_IO_PENDING is returned then object o is then waited on until either the write finishes or fails (if

something other than ERROR_IO_PENDING is returned by the GetLastError() function, then there is the possibility

of surprise removal; see section 8. "Application Design Notes" for comments on surprise removal). When the wait

is over, the result is obtained so that the amount of bytes read is updated. The success variable will then be

assigned with the appropriate value, and the handle of o.hEvent is closed. Finally, the function returns the success

of the read, which will be true if the read successfully completed.