Instead, we can us some other undocumented APIs to get a pointer directly to the receive buffer.

First we call SerReceiveCheck to get a total count of the received chars. Then, instead of calling SerReceive (or SerReceive10), we call SerReceiveWindowOpen. This gets us a pointer to a contiguous block of characters, and the length of that block. This is a pointer directly into the receive ISR's buffer. Because it's a circular buffer, the received characters might wrap around -- some at the end of the physical buffer, then next at the beginning again. In this case, we'll get a pointer to the group at the end of the buffer (the next chars to read in). We'll need to call SerReceiveWindowOpen a second time to get the wrapped part of the buffer.

We call SerReceiveWindowOpen to get the pointer to and length of data. We do as we wish with the data, then call SerReceiveWindowClose, telling it how many characters we actually used. Then, if we didn't get all the characters indicated in the call to SerReceiveCheck, we'll call SerReceiveWindowOpen and SerReceiveWindowClose a second time.

Finally, we want to tell the serial ISR to call our callback again, so we call SerPrimeWakeupHandler.

Note that there might be more characters than we ask for (the "prime count") when we process our special keyDownEvent -- this example just processes all that are there.

Conclusion
This article shows you how to use a callback for serial receive. As I mentioned, there's a bit of risk because it's undocumented, but it's been used by other applications and discussed occasionally on the developer mailing list and newsgroups.

Because they use APIs that aren't in the original Pilot 1000 and 5000, applicationss which use these techniques should check the Palm OS version number. The standard samples do this. In the interest of simplicity, and because of laziness, fighting the flu and impending deadlines, I didn't put the version checking into this sample application. It didn't crash on my Pilot 1000, but it didn't work either -- certainly it can't be expected to always fail gracefully.

Alan Jay Weiner writes software for PalmPilots. His email address is alan@ajw.com.