The Mailbox Library: 3 Mailbox Structures & Utilities

MailboxGetVMFile(), MailboxMessageFlags, MailboxMessagePriority, MailboxDeliveryVerb

There are a few data types that are used at various parts of the message-transmission and reception process. There are also a few concepts related to these types that need to be discussed first.

First of all, we need to distinguish between two basic data types: data format types , and data storage types .

Every message has two data tokens associated with it. One is the data format type, and the other is the data storage type. The data storage type describes the gross structure of the message data. Every data driver can accept one data storage type. For example, the GEOS system includes data drivers for messages whose bodies are stored in VM trees, and messages whose bodies are stored in byte-files. The data driver is not concerned with the message on a lower level. If you send a message in a VM tree, the data drivers at both machines will make sure that the message arives in a valid VM tree (which may mean fixing up the VM handles that make up the links in the tree), but they won't care about the data inside the blocks of the tree.

On a higherlevel, every message has its own data format type. This type describes how the data is actually stored in the underlying structure. For example, a message might be stored as a GString in a VM chain. In this case, the message's data storage type would be "VM tree" (a VM chain is a special kind of VM tree), and the data format type would be "VM Gstring".

Every data format type implies a particular data storage type; all messages with data format type a will necessarily use data storage type x . The converse, however, is not necessarily true. For example, all messages with data format type "VM GString" have data storage type "VM tree"; as do all messages with data format "VM composite".

When an application passes a message to a data driver, it may designate the message body as either "volatile" or "non-volatile". If the data is marked "volatile", the application may alter or destroy the data as soon as it has registered the message. That is, when the application registers the message, the appropriate Data Driver copies all the message's information out of the passed message before execution returns to the application. You should pass "volatile" if, for example, you are passing a pointer to a VM file used by the application.

If you designate the data as non-volatile , you are not allowed to alter or delete the data in the message. If you ask it to, the data driver will take care of freeing the storage used for the message when it is done with it. Every data driver has its own conventions about what applications should do with non-volatile messages after sending them.

For example, if you send a message through the VM tree data driver, you should write non-volatile messages to a special VM file created by the routine MailboxGetVMFile() . This routine is passed a single argument, the number of blocks you expect to allocate in the VM block. The routine returns the handle of a VM file. You can write the message in this file, and register the message (designated "non-volatile"). The data driver will then take care of freeing the file's storage when the message has been safely delivered.

Each message is associated with a set of MailboxMessageFlags . These are a byte-length record. This record has the following flags:

MMF_BODY_DATA_VOLATILE: As discussed above, this flag indicates that the data in the message must be copied immediately, as it is subject to change or freeing without further notice.
MMF_SEND_WITHOUT_QUERY: This flag indicates that the message should be sent without asking the user for permission.
MMF_PRIORITY: This is a member of the MailboxMessagePriority enumerated type, discussed below.
MMF_VERB: This is a member of the MailboxDeliveryVerb enumerated type, discussed below.

Every message can be assigned a priority. This priority is represented by a member of the MailboxMessagePriority enumerated type. The priority affects how the Mailbox library will handle the message at both the sending and the receiving end. This type has the following values:

MMF_EMERGENCY: The recipient user should be notified immediately, and not allowed to do anything before he or she receives the message.
MMP_URGENT: The user should be notified immediately, and told there is an urgent message awaiting. The user does not, however, have to read the message right away.
MMP_FIRST_CLASS: The user should be notified on the next periodic check of the Inbox. There are no other constraints on when the user should read the message.
MMP_THIRD_CLASS: The Inbox should not notify the user of the message's arrival; instead, the appropriate application should notify the user, if appropriate. For outgoing messages, the user must explicitly request that the message be sent; it will not happen automatically once a connection is made.

Every message has a "delivery verb" associated with it. This is useful in notifying the user of the message's arrival. Each delivery verb is represented by a member of the MailboxDeliveryVerb enumerated type. This type has the following members:

MDV_DELIVER: This is the default verb.
MDV_VIEW: The message is some sort of image that can be viewed, e.g. a received fax.
MDV_PLAY: The message is some kind of continuous message with a definite starting point and ending point, e.g. a voice recording or MPEG movie.
MDV_ACCEPT: Another generic verb.
MDV_READ: The message is mainly textual, and can be read (e.g. an old-fashioned EMail message).
MDV_FILE: The message is, or contains, one or more units that should be stored in a document that can contain many such units (e.g. an address-book card).

GEOS SDK TechDocs |

2 Inbox/Outbox Structure | Next:

4 Data Formats