Next we call SerPrimeWakeupHandler to tell when to call the callback. This sets the number of characters to receive after which the callback will be called. In the example, I want to process characters even if only one comes in, so I set to call me after the first character.

If you were reading in fixed-length blocks, you could set the "prime count" to the size of the block -- then you'd know you have received at least a full block when your handler is called.

The Wakeup Handler Awakens
When the "prime count" number of characters has been received, the serial port's ISR (interrupt service routine) will call your wakeup handler callback. It will disable further callbacks so you needn't worry about reentrancy (you will need to re-enable the handler again later). It calls your handler with a single argument -- the reference number that you set in SerSetWakeupHandler. If you had multiple serial ports and used the same callback handler for all of them, you'd use this number to distinguish between the ports.

Warning: note that you're operating in an interrupt-routine context! You can do very little at this time! In fact, the only Palm OS API that's safe is to call is EvtEnqueueKey. No other APIs are interrupt-safe.

EvtEnqueueKey inserts a "key down" event into the event queue. It could enqueue a normal key (as such things as the Fitaly or Jot keyboards do) or it could use a special command key (such as lowBatteryChr, menuChr or ronamaticChr), as some of the Palm internal routines do. We'll use a special command key like the OS does, but we'll define our own. As it turns out, all the special keys that Palm uses have a "virtual key" of zero, so we can simply use a different virtual key code. In the example, I use an ASCII code of 'S', a virtual key of 0x01, and the commandKeyMask modifier.

After calling EvtEnqueueKey, the wakeup handler returns to the serial ISR.

The Event Loop Awakens
The key down event that we just posted causes the event loop to wake up -- with a keyDownEvent, naturally.

We could let the event be handled as a normal key-down event; typically this is in the form handler. But I wanted to be sure that the normal OS routines never see our special command key -- just in case they (or a future machine) would misinterpret it. So I created a special event handler, SerialHandleEvent. This looks for key-down events with our custom key. When it finds one, it processes the received serial characters. The event loop calls SerialHandleEvent before it calls any of the other handlers.

Getting the Received Characters
In December's version, we used SerReceiveCheck and SerReceive10 (the Palm OS version 1.0 compatible API) to get the characters that came in the serial port.

There's an anomaly with the wakeup handler -- it seems to break SerReceive and SerReceive10; neither works properly when a wakeup handler is set. Because the wakeup handler is undocumented, I don't know if this is intentional or not -- I just know they haven't worked when I've tried them.