The Mailbox Library: 6.2 Application Responsibilities: Sending a Message

| Up: GEOS SDK TechDocs | Up | Prev: 6.1 Providing a User-Interface | Next: 6.3 Receiving and Processing Messages

A user will generally send a message by using the application's MailboxSendControl object. This object lets the user send the selected material in the application. It lets the user select such things as the message's destination, transmission time, subject line, etc.

Once the user has selected the message, the MailboxSendControl sends the message MSG_META_MAILBOX_CREATE_MESSAGE to its output object (generally the application object). This message instructs the object to create an appropriate message.

When the application has been notified that it should create a message, it should then determine what data type the message will need. It does this by sending MSG_MAILBOX_SEND_CONTROL_CHOOSE_FORMAT to its MailboxSendControl. It can find out other information about the message to be sent by sending other messages to the MailboxSendControl.

The MailboxSendControl informs the application what data type it should use. The application must determine what data to send (generally the current selection); it then assembles this data into the format requested by the send control object. Finally, it registers the message by sending MSG_MAILBOX_SEND_CONTROL_REGISTER_MESSAGE to its MailboxSendControl. This message instructs the MailboxSendControl to register the message with the Mailbox library.

MSG_META_MAILBOX_CREATE_MESSAGE()

MetaMailboxMessage void MSG_META_MAILBOX_CREATE_MESSAGE(
        optr		sendControl,
        word		transHandle);

This message informs the output of a MailboxSendControl that it should create the body of the message. It is the obligation of that object to notify the controller that it has accomplished this task with MSG_MAILBOX_SEND_CONTROL_REGISTER_MESSAGE.

MSG_MAILBOX_SEND_CONTROL_REGISTER_MESSAGE

MailboxMessage 	MSG_MAILBOX_SEND_CONTROL_REGISTER_MESSAGE(
        word		TransID,
        MailboxStorage		bodyStorage,
        MailboxDataFormat		bodyFormat,
        const void *		bodyRef,
        unsigned word		bodyRefLen,
        MailboxMessageFlags		flags,
        const char *		subject,
        const GeodeToken *		destApp)

When an application wishes to send a message, it does this by registering a message with the Mailbox library. The Mailbox library then loads the appropriate data and transport drivers to actually deliver the message. The application registers a message by sending MSG_MAILBOX_SEND_CONTROL_REGISTER_MESSAGE to its MailboxSendControl object.

Source: The recipient of MSG_META_MAILBOX_CREATE_MESSAGE. Generally sent by the Application object.

Destination: The application's MailboxSendControl.

Parameters: TransID This is the token the MailboxSendControl passed with its MSG_META_MAILBOX_CREATE_MESSAGE .

bodyStorage
The 32-bit token (of type MailboxStorage ) identifying the data driver which should be used. (The message will be passed in a format appropriate to that data driver.)
bodyFormat
The 32-bit token (of type MailboxDataFormat ) identifying the kind of data in the message body. Each format token implies a particular storage type.
bodyRef
A pointer to the beginning of a data block. This block instructs the data driver where the message body is. (Each data driver may have its own conventions for interpreting the data in this block.)
bodyRefLen
The number of bytes at *bodyRef .
flags
A word of MailboxMessageFlags .
subject
A pointer to a null-terminated string containing the subject or summary line describing the message. (The string may contain newline characters.)
destApp
the GeodeToken of the application which will receive the message (on whichever machine receives the message). If this is a generic token, the recipient machine's Mailbox library will automatically convert it to the token of whichever application will actually receive the message.

Interception: If you define a subclass of the MailboxSendControl, you may wish to intercept this message to add functionality.

MSG_META_MAILBOX_MESSAGE_REGISTERED

MetaMailboxMessage void MSG_META_MAILBOX_MESSAGE_REGISTERED(
        MemHamdle		args);

This message is sent by the MailboxSendControl once it has attempted (via MailboxRegisterMessage() ) to register the message. The controller may call MailboxDoneWithVMFile() (or any other cleanup procedures) in response to this message. <

| Up: GEOS SDK TechDocs | Up | Prev: 6.1 Providing a User-Interface | Next: 6.3 Receiving and Processing Messages