AN197 Silicon_Laboratories, AN197 Datasheet - Page 5

• Manufacturer Part Number: AN197
• Description: Serial Communications Guide FOR THE Cp210x
• Manufacturer: Silicon_Laboratories

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)
{
{
}
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()
createevent.asp).
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
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.
bool success= false;
OVERLAPPEDo= {0};
o.hEvent = CreateEvent(NULL, FALSE, FALSE, NULL);
if (!ReadFile(handle, data, length, dwRead, &o))
}
else
CloseHandle(o.hEvent);
return success;
if (GetLastError() == ERROR_IO_PENDING)
success = true;
if (WaitForSingleObject(o.hEvent, timeout) == WAIT_OBJECT_0)
GetOverlappedResult(handle, &o, dwRead, FALSE);
success = true;
is
located
at
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dllproc/base/
Rev. 0.6
http://msdn.microsoft.com/library/
AN197
5