SMS Guide: 4.2 Receiving an SMS Message: Receiving an SMS Message

GEOS SDK TechDocs

4.1 SM Receive and the Mailbox Library

When the inbox receives a message that it determines is destined for a specific application, the mailbox will contact that application's process class with MSG_META_MAILBOX_NOTIFY_MESSAGE_AVAILABLE . This message passes a token identifer of the SMS message.

If you wish your application to handle an SMS message, you will need to write a message handler for MSG_META_MAILBOX_NOTIFY_MESSAGE_AVAILABLE . It should perform the following steps:

1. Call MailboxAcknowledgeReceipt() to inform the mailbox that we're handling the message. Pass the token identifer of the SMS message that was passed with MSG_META_MAILBOX_NOTIFY_MESSAGE_AVAILABLE . (See Acknowledging Receipt of the Message .)
2. Retrieve the VM reference to the message with MailboxGetBodyRef() . (See Retrieving the Text from the VM Block .)
3. Lock down the VM block and retrieve a pointer to the text.
4. Copy the text to a local buffer.
5. Unlock the VM block.
6. Call MailboxDoneWithBody() to instruct the mailbox to release the VM reference to the text. (See Cleaning Up .)
7. Call Mailbox DeleteMessage() , passing the token referring to this message.

These specific steps are described in more detail below:

Acknowledging Receipt of the Message

MailboxAcknowledgeMessageReceipt()

When your application receives an SMS message with MSG_META_MAILBOX_NOTIFY_MESSAGE_AVAILABLE , your first order of business should be informing the mailbox that you have the message. To do this, send the mailbox MailboxAcknowledgeMessageReceipt() , passing it the message token.

Code Display 3-6 Acknowledging Receipt of an SMS Message

/*
 * Each application which wishes to receive SMS messages should create a 
 * MSG_META_MAILBOX_NOTIFY_MESSAGE_AVAILABLE handler in the app's main prcoess
 * class.
 */

@method MyProcessClass, MSG_META_MAILBOX_NOTIFY_MESSAGE_AVAILABLE {

    /*
     * First we inform the mailbox that we've received the message. We pass the 
     * `msg' token that was passed to this message in the first place.
     */

    MailboxAcknowledgeMessageReceipt(msg);

    /* To be continued ... */

Retrieving the Text from the VM Block

MailboxGetBodyRef()

As we indicated in Storing the Text Within a VM File , it is convenient for the SMS message itself to be wrapped in a small VMChain structure. In the following section, we assume that is indeed what was done on the sending end.

Use MailboxGetBodyRef() to retrieve this reference to the actual text. Pass the message token, a pointer to a buffer to store the body reference, and the length of that buffer.

Code Display 3-7 Retrieving the Text

    MailboxError 			errorCode;
    VMAppTreeRef			vmRef;
    word 			refSize;
    MemHandle			handleToText;
    TCHAR			smsText[FOAM_MAX_SMS_TEXT_SIZE+1];
    char			*ptrToText;

    /* 
     * First, retrieve the reference to the body of the SMS text from the mailbox 
     * library. Place that reference into our vmRef variable.
     */

    refSize = sizeof(VMTreeAppRef);
    errorCode = MailboxGetBodyRef(msg, &vmRef, &refSize);

    if (errorCode == ME_SUCCESS) {

	/*
	 * Lock the block and retrieve a pointer to the SMS text.
	 */
	ptrToText = (char *) VMLock(vmRef.VMTAR_vmFile,
				 VMCHAIN_GET_VM_BLOCK(vmRef.VMTAR_vmChain),
				 &handleToText);

	/*
	 * Advance the pointer beyond the carriage return to get beyond the 
	 * prefix. 
	 */

	while ( *ptrToText != `\r')
	    ptrToText++;

	/* Advance over the `\r' ...*/
	    ptrToText++;

	strcpy(smsText, ptrToText);

	VMUnlock(handleToText);

	/* To be continued ... */

Cleaning Up

MailboxDoneWithBody(), MailboxDeleteMessage()

Finally, we need to notify the mailbox that it can delete both the text of the message (and the reference to that text) and the message itself. To perform each of these steps, call MailboxDoneWithBody() and MailboxDeleteMessage() .

Code Display 3-8 Cleaning Up the Mailbox

	/* Now remove the external text and the reference to that text. */

	MailboxDoneWithBody(msg, &vmRef, refSize)

	/* 
	 * Finally, delete the "message" including the message token and any 
	 * information included with it.
	 */

	MailboxDeleteMessage(msg);

    }

}

GEOS SDK TechDocs

4.1 SM Receive and the Mailbox Library