The Mailbox Library: 7.1 Examples of Mailbox Usage: An Incoming Pager Email Message

7.2 Sending and Receiving an Address Book Page

In this example, we consider a device that's receiving an Email message. The message was generated by some central server, which need not have been running any variety of GEOS, as long as the message conformed to the transport driver's expectations for the message format.

Arrival of The Message

The message is received via a wireless pager card that's plugged into the device. The transport driver for the card, which was loaded when the card was inserted, periodically polls the card to see if new messages have arrived. On the next poll, it finds that there is indeed a new message. It extracts enough of the message to determine it's something for the Email application to see.

Armed with that, it calls the Mailbox library to register a message, specifying:

The destination is the Email application (whose token it knows, in the same way it knows the message is for the Email application).
The transport mechanism is LOCAL (i.e. the message is destined for an application on this machine).
The user should be notified of the arrival of the message, when appropriate. (The priority may be extracted from the pager card's data structure, allowing some Email to be treated as urgent, while other is treated as junk mail)
The user should not be asked whether the message should be delivered when the connection is available (i.e. when the application is loaded). That is, when the application is loaded, the message will automatically be presented.
The delivery-verb of choice is "Read"; this is used when presenting the message to the user.
The storage format token is that for the data driver located on the pager card's file-system.
The data format is one the Email application expects. Note that in this case, the pager card data driver will end up converting from the format in which the message is stored on the card to a VM- or file-based format of some sort. In effect, the data driver is pretending the data are stored in the format appropriate to the data format token the pager driver has claimed they're in, when in fact they're in a very different format within the card's own memory.
The address of the data (a reference to the data on the card). This address is specific to the passed data driver. When registering a message, you must know the type of address the data driver you're specifying expects (and, of course, provide an address of data in that format).
The message data are not volatile, as far as the pager driver is concerned. (Data are volatile if they are in danger of deletion as soon as the Mailbox library returns from the store-message call. The indication of volatility is passed to the data driver so it knows if it should copy the data to a safer location.)
The subject line, which it has extracted from the message.
A starting time-bound of the current time. This allows the message to be delivered immediately, if the Email application is currently loaded.
An ending time-bound of one day from now. When the ending bound time is reached, the application will automatically be loaded and the message presented. The choice of an ending bound is peculiar to the card and what the driver writer thinks is a reasonable deadline for the user to view the message. It may also be intuited from something in the Email message itself, such as a special header in the message.

If the card will delete the message after a certain time, the pager driver will want to set an ending time-bound well before that deletion is scheduled to occur. If the card may delete the message after a while to free up space, as happens in the EMBARC card, the driver may well want to set an ending time-bound of, say, one day from when the message was received. The driver could also set the ending bound to match the starting bound, thus forcing the Email application to be loaded. The final choice, of course, is to set no ending bound.

For its part, the Mailbox library will load the data driver and call it, passing the data address the library was given and allowing the driver to copy the data (if required) and return its own version of the "opaque" data. (The message body is "opaque" to the Mailbox library, in that it never looks into this data for information; instead, it passes the data to the various drivers and applications, which may interpret and manipulate the data.) For example, the file data driver might well copy the file, whose name was passed, into a spool directory for safekeeping, returning the shorter name back to the Mailbox library as the opaque data to store with the message. The rest of the data will be copied into the message descriptor, after checking to make sure it's reasonable, and the descriptor will be placed at the head of the inbox queue.

Assuming the message is given standard First-Class priority and that the Email application isn't currently running in the foreground, the Mailbox library will catch the existence of the new message at its next (user-settable) check interval and will notify the user of its arrival. If the message has a higher priority, the user may be notified immediately, and may be forced to deal with the message immediately, as well. If the Email application is the foreground application, and has told the system it will take care of notifications itself, the message is immediately given to the application, which will presumably notify the user in its own way.

Delivery of The Message

When the delivery box is presented to the user, the user can decide how to proceed with the message.

If the user says to send it, the Mailbox library will establish an IACP connection to the application that is to receive the message and send it an appropriate notification. When the application acknowledges receipt of the message, the message is removed from the Mailbox library's "inbox" and any list displaying the message is updated appropriately.

In essence, the Mailbox library will use IACP to send a MSG_META_MAILBOX_NOTIFY_MESSAGE_AVAILABLE to the application object, passing the token for the message.

Using the message token, the application calls the Mailbox library to acknowledge receipt of the message. This acknowledgment will remove the message from the inbox, but will not delete the message descriptor.

The application will then call the Mailbox library back to fetch the body of the message, its subject, time stamp, etc. When the user deletes the message, the Email application will notify the library that it is done with the message. This call will cause the message data and the message descriptor to both be deleted.

GEOS SDK TechDocs |

7 Examples of Mailbox Usage | Next:

7.2 Sending and Receiving an Address Book Page