Since they're not part of the official documentation, there's a bit of risk in using them, as they may change in future Palm devices. Of course, that can happen (and has!) with the documented APIs also.

Indeed, several of the APIs we'll use are listed as "for system use only." Nevertheless, they are the only means to accomplish the callback-driven receive. They've been mentioned several times on the developer mailing list and while their use hasn't been encouraged, it hasn't been discouraged either.

Looking at the SerialMgr.h header file, you'll see prototypes and definitions for the serial APIs I described in December. But there's a few additional APIs. These include:

• SerSleep
• SerWake
• SerReceiveISP
• SerReceiveWindowOpen
• SerReceiveWindowClose
• SerSetWakeupHandler
• SerPrimeWakeupHandler

Additionally, there's a typedef to define the SerWakeupHandler prototype:

We'll use the wakeup handler to set a callback when characters are received, and the receive window APIs to actually get the characters from the serial port's receive buffer.

Note that these are only available in Palm OS 2 and above. Because of this, any program that uses these will not work on an original Pilot 1000 or Pilot 5000.

How the Wakeup Handler works
As I described in December's column, most programs simply poll the serial port every now and then to see if there are any characters received.

In this version of SerialEcho we'll use SerSetWakeupHandler to tell the low-level serial routines to call us when characters come in the serial port.

When the program starts, it'll set up the callback then go into the standard event loop. While there's nothing coming in the serial port the machine just waits in low-power idle mode. As soon as characters come in, the callback gets called (directly from the low-level interrupt service routine) and it posts an event to wake up the normal event loop. It returns to the ISR (interrupt service routine) which completes its work and things continue on as normal. The event just posted gets returned to your event loop. You process it and get the received characters and do what you want with them. Once you're done, you return to the event loop and go idle again -- until the next character comes in the serial port.

Let's look at what we need to handle all this.

Initialize the Wakeup Handler
First we need to tell the serial routines to call our callback routine when characters come in. After opening the serial port using the standard SerOpen call, you call SerSetWakeupHandler, giving it the address of the callback routine and a reference number. When the callback is executed, the reference number is passed to it. This allows a single callback to be used for multiple ports; each would have its own reference number. Normally the reference number isn't needed -- after all, there's only one serial port so you know where things are coming from and what should happen. However, if a future device were to have more than one port, or you want to pass information to the callback routine for whatever reason, you could store the information in a structure and pass a pointer to that structure as the reference number. Or it could be an index into a table. For the example here, we don't need it so I just set the reference number to zero.