The Mailbox Library: 6.3 Application Responsibilities: Receiving and Processing Messages

| Up: GEOS SDK TechDocs | Up | Prev: 6.2 Sending a Message | Next: 7 Examples of Mailbox Usage 
MSG_META_MAILBOX_NOTIFY_MESSAGE_AVAILABLE, MailboxAcknowledgeMessageReceipt(), MailboxGetSubjectBlock(), MailboxGetSubjectLMem(), MailboxGetMessageFlags(), MailboxGetBodyFormat(), MailboxGetBodyRef(), MailboxDoneWithBody(), MailboxStealBody(), MailboxDeleteMessage()

An application that uses the Inbox/Outbox technology must be able to handle incoming messages, as well as generate outgoing ones.

The Mailbox holds incoming messages in its Inbox until an appropriate time to deliver them. For example, it may choose to wait until the user starts up the application, or until the delivery deadline is reached. In any event, when the Inbox library needs to deliver the message it sends MSG_META_MAILBOX_NOTIFY_MESSAGE_AVAILABLE to the application object of an appropriate application. This message has a single argument, a 32-bit MailboxMessage token which uniquely identifies the message.

If the application is going to handle the message, it must call the routine MailboxAcknowledgeMessageReceipt() . The routine is passed the MailboxMessage token for the message. (If you do not acknowledge the receipt of the message, your application will be bothered by repeated notifications.)

Once the application has been notified of an incoming message, it can call a number of routines to find out about the message. To find out the message's subject line, it should call either MailboxGetSubjectLMem() or MailboxGetSubjectBlock() . Both of these routines return the subject text for the message.

MailboxGetSubjectBlock() is passed a single parameter, namely the MailboxMessage token for the message. The routine allocates a global memory block, writes the subject line to that block (as a null-terminated string), and returns the handle of the block. If it fails, it returns zero and sets the thread's error value. (See ThreadGetError() .)

MailboxGetSubjectLMem() is very similar. It is passed two arguments: the MailboxMessage token for the message, and the global memory handle of an LMem heap. The routine allocates a chunk in that LMem heap, writes the subject line to that chunk (again, as a null-terminated string), and returns the chunk handle of that chunk. Again, if the routine is unable to comply, it returns zero and sets the thread's error value.

MailboxGetMessageFlags() is passed the MailboxMessage token for the message. It returns the MailboxMessageFlags for that message. It is often used to find the message's priority.

MailboxGetBodyFormat() is passed the MailboxMessage token for the message. It returns the MailboxDataFormat value for the message's body. The application can use this to decide if the message is written in a format the application can understand.

MailboxGetBodyRef() is used to actually retrieve the data for the message. The routine is passed the following arguments:

If the routine is successful, it returns true and writes a reference to the message body in the passed buffer. This reference is in the same format that would be passed to MailboxRegisterMessage() , i.e. it varies according to the data driver. If the routine is unsuccessful, it returns false and sets the thread's error value to an appropriate MailboxError value.

For every time the application successfully calls MailboxGetBodyRef() , it must call MailboxDoneWithBody() . This routine is passed three arguments:

The routine notifies the Mailbox library that the application is done with the message body for the time being. The mailbox library is thus free to close the file holding the data, or take some similar action. (The message body will not be destroyed; it will still be available for future calls to MailboxGetBodyRef() .)

An application can also get the message body by calling MailboxStealBody() . This is passed the same arguments, and returns the same values, as MailboxGetBodyRef() . However, if the routine is successful, the storage area containing the message body will be transferred to the ownership of the application, and the data driver will free any other storage it used to hold the message body. After a successful call to MailboxStealBody() , any future calls to MailboxGetBodyRef() or MailboxStealBody() will fail; as far as the Mailbox library is concerned, the message has no body any more. When the application is finished with the message, it must free the storage used for the message. In particular, if the data reside in a VM file, the application must call MailboxDoneWithVMFile() to notify the Mailbox library to free that file.

When an application is done processing a message, it must call MailboxDeleteMessage() . This routine is passed the MailboxMessage token for the message. It instructs the mailbox library to delete the message and any associated data. The MailboxMessage token becomes invalid after this routine returns.

| Up: GEOS SDK TechDocs | Up | Prev: 6.2 Sending a Message | Next: 7 Examples of Mailbox Usage