Every mail message is stored in an individual file with attached attributes that describe the message in detail; you can query the file system to obtain information about the sender, subject, and receiver of the message, among other things. See "Querying Mail Messages" below for more detailed information and an example program.

Every message the user writes is saved in a file until it's sent by the mail daemon (and may or may not be deleted after being sent). Likewise, messages that the mail daemon has retrieved are also stored in files on a local disk.

The process of sending a mail message works something like this:

• The user writes a new mail message and chooses the mail writing program's "Send" option.

• The mail writing program creates a BMailMessage object and configures it based on the user's inputs by setting the "To," "Subject," and other header fields appropriately, and by storing the message content into the BMailMessage.

• The program then calls the BMailMessage object's Send() function to tell the mail daemon to send the message.

• The mail daemon creates a disk file that contains the message. The message content is stored in the file itself, and attributes are created to contain the "To," "Subject," and other relevant header fields. See "Querying Mail Messages" for more information. The message's status attribute is set to "New".

• The next time the mail daemon's check_for_mail() function is called (either automatically or explicitly), the daemon sends the message via SMTP, then changes the message's status attribute to "Sent". This is done for all mail messages whose status is "Pending".

After sending outgoing messages, the mail daemon will also check to see if any incoming mail is waiting to be retrieved. If there is, it proceeds something like this:

• The mail daemon fetches the first message from the mail server via POP.

• The daemon creates a new mail message file, and the message is written into the file. The file contains the Internet headers, message content, and all enclosures (if any).

• The mail daemon scans the message and adds attributes to the message file for each of the header fields, as well as a couple of extra attributes. These are described in detail in "Querying Mail Messages" below.

• The daemon continues reading mail messages from the mail server until there aren't any left.

The Mail Kit takes full advantage of the BeOS attribute and query system. Each message received is parsed by the mail daemon and important information about it is converted into a defined collection of attributes attached to the file. This makes it extremely easy to create applications that search for messages meeting specific parameters. In an example to follow shortly, we'll create a program that lists all unread messages.

Once the mail daemon has received a message and saved it to disk, any application can query the file system to locate messages that meet certain parameters, then read the attributes and message content to present information about that message to the user.

The following attributes are provided by the Mail Kit:

The following attributes are indexed:

• B_MAIL_ATTR_NAME

• B_MAIL_ATTR_STATUS

• B_MAIL_ATTR_PRIORITY

• B_MAIL_ATTR_TO

• B_MAIL_ATTR_CC

• B_MAIL_ATTR_FROM

• B_MAIL_ATTR_SUBJECT

• B_MAIL_ATTR_REPLY

• B_MAIL_ATTR_WHEN

• B_MAIL_ATTR_FLAGS

The headers, the contents of the messag,e and the enclosures (in base-64 encoded form) can all be found in the file itself and can be read using a BFile object. See "The Storage Kit" in the for further information on reading files.

void main(void)
{
   BQuery query;
   BNode node;
   BVolume vol;
   BVolumeRoster vroster;
   entry_ref ref;
   char buf[256];
   int32 message_count = 0;

   vroster.GetBootVolume(&vol);
   query.SetVolume(&vol);

   if (query.SetPredicate("MAIL:status = New") != B_OK) {
      printf("Error: can't set query predicate.n");
      return;
   }

   if (query.Fetch() != B_OK) {
      printf("Error: new mail query failed.n");
      return;
   }

   while (query.GetNextRef(&ref) == B_OK) {
      message_count++;      // Increment message counter

      if (node.SetTo(&ref) != B_OK) {
         printf("Error: error scanning new messages.n");
         return;
      }

      buf[0] = '0';      // If error, use empty string
      node.ReadAttr(B_MAIL_ATTR_FROM, B_STRING_TYPE, 0,
                    buf, 255);
      buf[20] = '0';      // Truncate to 20 characters
      printf("%3d From: %-20s", message_count, buf);

      buf[0] = '0';      // If error, use empty string
      node.ReadAttr(B_MAIL_ATTR_SUBJECT, B_STRING_TYPE, 0, buf, 255);
      buf[40] = '0';      // Truncate to 40 characters
      printf(" Sub: %sn", buf);
   }

   if (message_count) {
      printf("%d new messages.n", message_count);
   }
   else {
      printf("No new messages.n");
   }
}

The mail daemon ensures, when it's first launched at system boot time, that the BeOS File Type database includes an entry for e-mail files. E-mail files have the MIME string "text/x-email", which is represented by the constant B_MAIL_TYPE.

The E-mail entry in the File Type database includes a list of the attributes on which you can search. You can look up this information using the BMimeType class's GetAttrInfo() function:

BMimeType mime;
BMessage message;

mime.SetTo(B_MAIL_TYPE);
mime.GetAttrInfo(&message);

After running this code, the message contains the description of the attributes available on e-mail files. The message has three useful arrays of items:

You can examine the items in each of these arrays in the message to get useful information about the attributes you can reference on the e-mail files. For example:

printf("Public name: %sn", FindString("attr:public_name", 1));
printf("Name: %sn", FindString("attr:name", 1));

This code will print the public name and the attribute name of the second attribute registered in the File Type database entry for e-mail files. In the current implementation of the Mail Kit, this would print:

Public name: Subject
Name: MAIL:subject

The number of (and order of) attributes in the database entry might change in the future—and that's where the File Type database comes in handy. If, a year from now, Be adds more attributes to e-mail files, your File Type database-savvy application won't have to be updated to support them.

At this time, the File Type database has attribute information records for each of the following attributes:

• B_MAIL_ATTR_NAME

• B_MAIL_ATTR_STATUS

• B_MAIL_ATTR_PRIORITY

• B_MAIL_ATTR_TO

• B_MAIL_ATTR_FROM

• B_MAIL_ATTR_SUBJECT

• B_MAIL_ATTR_REPLY

• B_MAIL_ATTR_WHEN

You can obtain information on these attributes, their formats, and their user-readable names by looping through the arrays in the message until the BMessage:Find…() function returns NULL or B_BAD_INDEX.

For more information on the BMimeType class and the File Type database, see BMimeType in The Storage Kit.