In the BeOS Preview Release 2, the default alpha arguments to SetHighColor(), SetLowColor(), and SetViewColor() in View.h were changed from 0 to 255. We also changed the value of the constant B_TRANSPARENT_32_BIT. These changes were made in long-range preparation (i.e., not for Release 3, and not yet included in plans for any subsequent release) for alpha channel support in the App Server and the Kits. This means a number of things for you:

• You don't have to worry about B_TRANSPARENT_32_BIT. It's a symbol, so the change in value should be transparent (pun intended) from a source compatibility standpoint. We've added some filters in the aforementioned calls that look for the old value, just to be extra safe.

• You should worry, however, if you have data (or, less likely, code) that hard-codes the old B_TRANSPARENT_32_BIT value and you stuff that data directly into a BBitmap. The solution here is...use the new value! (Duh.)

• You should inspect your code for uninitialized alpha values. You don't have to do this immediately since we currently ignore the value of the alpha component, but it's a good habit to get into.

Here's some suspicious code:

// alpha component omitted!
rgb_color foo = {255, 255, 255};

If you don't want foo to be transparent (an alpha of 0), you should do the following:

// explicitly set it to 255
rgb_color foo = {255, 255, 255, 255};

Here are some other common cases that I found while rummaging through the Interface Kit:

{
  rgb_color foo;

  if (blah)
    // this is good
    foo = ViewColor();
  else
    // bad, alpha isn't being set...
    foo.red = foo.green = foo.blue = 123;
}

{
  // explicitly setting alpha to 0!
  SetHighColor(80, 80, 80, 0);
  ...
}

If you're writing an app that uses signals, or a library that uses signals, or a library that may be used by an app that uses signals, watch out for B_INTERRUPTED. Functions such as acquire_sem() will return an error code of B_INTERRUPTED when they are "unblocked" by a signal.

The following code is unsafe:

// theSem is a valid sem_id
acquire_sem(theSem);

Do this (or something like it) instead:

// loop until we acquire the semaphore
while (acquire_sem(theSem) == B_INTERRUPTED);

Here's a list of functions that you want to protect from B_INTERRUPTED:

• acquire_sem()

• acquire_sem_etc()

• port_buffer_size()

• read()

• write()

• read_port()

• read_port_etc()

• write_port()

• write_port_etc()

• wait_for_thread()

Speaking of error codes, did you know that BLooper::PostMessage() returns an error? Or, to put it another way, did you know that PostMessage() can fail, even if all BLoopers and BHandlers involved are valid?

A BLooper's port capacity is set to 100 (B_LOOPER_PORT_DEFAULT_CAPACITY) by default. This is also true of BWindow (BWindow inherits from BLooper). If a Looper's message queue is inundated with BMessages, its port fills up. Since a BLooper with a full port can no longer accept messages, that's one way a call to PostMessage() can fail.

There are a number of ways to deal with this situation:

• Look at PostMessage()'s return value. Handle errors gracefully.

• Don't do any super time-consuming things in MessageReceived(). Spawn a thread if you have to. This reduces the likelihood of a BLooper's port filling up.

• Use a BMessenger.

BMessengers are cool. The following code snippets are functionally equivalent:

status_t err1 = myLooper->PostMessage(kMyCommandConstant);

BMessenger messenger(myLooper);
status_t err2 = messenger.SendMessage(kMyCommandConstant);

The difference is that the BMessenger version guarantees that your message will be delivered, regardless of the state of the recipient's port. It does this by blocking on the full port until there is room. Keep in mind, this blocking can lead to other issues such as deadlock, but that's been covered in other articles, for example: Issue 1-#25

Let's write a simple C function to create and send an e-mail, which we'll cleverly call "sendmail".

status_t sendmail(char *to,
                  char *subject,
                  char *from,
                  char *replyto,
                  char *content,
                  char *enclosure_path) {
  BMailMessage *message;
  status_t err;

Our sendmail() function lets us specify the To, Subject, From, and Reply-to header fields, as well as the message content and one enclosure, specified by pathname.

  message = new BMailMessage();
  if (!message) {
    // Couldn't allocate memory for the message
    return B_ERROR;
  }

First, we create a new BMailMessage object. If we can't create it, we just return B_ERROR immediately, since there's really no point in going on.

The To and Subject header fields are mandatory for any e-mail message, and the Mail Kit doesn't know how to create them for you automatically, so you need to set them up:

  err = message->AddHeaderField(B_MAIL_TO, to);
  err |= message->AddHeaderField(B_MAIL_SUBJECT, subject);

Notice that we're ORing the result codes of the AddHeaderField() calls together. In this example program, we don't care *what* error occurred, but only whether or not an error occurred at all. By ORing all the results together, we obtain a mega-result that's B_OK (which happens to be zero) if and only if no errors occurred at all.

Of course, you could be more programmatically correct and handle each error individually with alerts, but this saves some space for the purposes of this article without disposing of error-handling entirely.

The From and Reply-to fields can be automatically filled in by the Mail Kit if you don't specify them. So if the caller specifies NULL for these two fields, we don't bother to set them up.

  if (from) {
    err |= message->AddHeaderField(B_MAIL_FROM, from);
  }
  if (replyto) {
    err |= message->AddHeaderField(B_MAIL_REPLY, replyto);
  }

Then we add the message body by calling AddContent():

  err |= message->AddContent(content, strlen(content));

And, if the enclosure_path parameter is non-NULL, we add the enclosure to the message:

  if (enclosure_path) {
    err |= message->AddEnclosure(enclosure_path);
  }

Finally, if no errors have occurred, we send the message by calling Send(). The first parameter to Send() is a boolean that specifies whether the message should be sent immediately (true) or queued to be sent the next time the mail daemon is scheduled to run (false). In this case, we want the message to be sent immediately, so we specify true.

  if (err == B_OK) {
    err = message->Send(true);  // Send now
  }

Now it's time to clean up. We delete the message object and return B_ERROR if an error occurred or B_OK if everything went well:

  delete message;
  if (err) {
    return B_ERROR;
  }
  return B_OK;
}

Now you can send a message by calling sendmail():

status_t error = sendmail("foo@bar.com",
                          "Subject",
                          "sheppy@be.com",
                          "sheppy@bar.com",
                          "This is the message body.",
                          "/boot/home/file.zip");

This will send, to foo@bar.com, the message "This is the message body." with the file /boot/home/file.zip attached. The From will be listed as sheppy@be.com, and the Reply-to will be sheppy@bar.com.

You could also do:

status_t error = sendmail("foo@bar.com",
                          "Subject",
                          NULL,
                          NULL,
                          "Body",
                          NULL);

This sends a message to foo@bar.com with a subject "Subject" and the body "Body." There's no enclosure, and the Mail Kit automatically sets From and Reply-to to the addresses configured in the E-mail preferences application.

Read the E-mail.h header file to see what other header fields you can add to your messages.

When e-mail arrives, the mail daemon creates a new file to contain the message and adds the appropriate attributes to the file. These attributes contain things like the subject, from, to, and other fields. With these attributes firmly in place, you can query the file system to look for e-mail files based on the values of these fields.

Let's create a sample program that lists the subjects and senders of all unread messages. We'll call it listmessages(). You should already be familiar with queries and attributes. If you're not, have a look at the BQuery and BNode sections in the Storage Kit chapter of the "Be Book."

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

New messages are stored by the mail daemon on the user's boot disk, so we begin by using the volume roster to identify the boot disk and set our query to search on that disk:

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

The next thing we do is set up our query. We want to search for new mail messages, so our search predicate is "MAIL:status = New". See the E-mail.h header file for a list of the mail message attributes.

If an error occurs while trying to establish the predicate for the query, we bail out:

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

Then we run the query. If an error occurs, we print an appropriate message and give up:

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

Now it's time to loop through the files in the query's result set. We'll use BQuery::GetNextRef() to iterate through them. For each entry, we set up a BNode so we can use BNode's attribute functions to read the file's attributes. Again, as good programmers, we gracefully cope with errors:

  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;
    }

Next, we read the From attribute. This attribute's name is given by the constant B_MAIL_ATTR_FROM. We use a 256-byte buffer, preinitialized to an empty string, and call BNode::ReadAttr() to read the attribute into the buffer.

To facilitate formatting our display, we chop off the From string at 20 characters, then print the message number and the From attribute to the screen:

    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);

Our loop ends by reading the Subject attribute (B_MAIL_ATTR_SUBJECT), truncating it to 40 characters, and printing it as well:

    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: %s\n", buf);
  }

To add a little panache, we round things out by displaying the total number of new messages. If we didn't find any new messages, we say so:

  if (message_count) {
    beep();    // The postman beeps once
    printf("%d new messages.\n", message_count);
    beep();    // The postman beeps twice
  }
  else {
    printf("No new messages.\n");
  }

The output from this function looks something like this. The "<she" is the beginning of my e-mail address, chopped off by our 20-character truncation of the From attribute:

  1 From: "Eric Shepherd" <she   Sub: Newsletter test
  2 From: "Eric Shepherd" <she   Sub: re: BeOS programming
2 new messages.

Consider this: In the while loop, you obtain an entry_ref for every new e-mail on the user's system. Instead of listing out the subject and sender's names, you could just as easily open up the file and show the contents in a window. You're well on your way to having an e-mail reader without even breaking a sweat (and we all know how expensive it is to replace broken sweat).

I'm sure you've all heard the "chicken-and-egg" paradox, which has it that developers won't do applications for the BeOS before there is an installed customer base, and customers won't install the BeOS until there are applications.

Well, I'm pleased to say that our "egg" days are over and we're hatching. At our Macworld Expo booth in January, several software companies will demonstrate compelling applications that let you do things you cannot do on Mac or Windows, that out-perform Mac and Windows apps, and that generally prove the BeOS is a superior platform for media applications.

There are more applications coming. I can't give you specifics, except to say that it's time to change the way you think about the BeOS. As we expand into the Intel world there will no longer be any basis for the criticism "but they have no apps." (I don't yet know what criticism will take its place, but it won't be that.) The Intel port represents a big change in how we see the BeOS, and we need to adjust our brains around it.

But please don't replace "I don't think I'll develop an app for the BeOS because there aren't any apps" with "I don't want to develop for the BeOS because someone is probably already doing the app I want to do." The BeOS running on Intel offers a huge opportunity—and you have a head start. The field is wide open for you to write your dream application with minimal competition.

The BeOS has always been a separate operating system, even if it happened to run on the Macintosh. More and more, you'll see us listed as an independent platform alongside Mac, Windows, Unix, Linux, DOS, etc...

Some of us have been working with the BeOS for so long that we don't remember the experience of discovering it for the first time. Seeing and using the BeOS for the first time is one of those defining moments, paradigm shifts, flash realizations, spiritual transformations...

I saw this again as I watched someone here give his first demo last Friday. He was a little nervous and awkward, looking at his script, hesititant, but his confidence was sustained by a guy in the audience who kept shouting, "MY GOD!" and "OH MY GOD!!!" every time he showed another BeOS feature.

The BeOS is the equivalent of a fiber-optic infrastructure upon which your media applications are built, bringing a quantum increase in performance. Mac and Windows are old copper wire systems. Mac and Windows are vinyl and the BeOS is CD.

Sure, there's a lot of support out there for copper wire systems, just like there was a huge inventory of vinyl recordings. Hundreds of manufacturers build things like insulators and transformers for telephone poles, wire cutters, connector boards...plus lots of electricians, etc...

Because fiber is new technology there is not that kind of support structure in place yet. (The infrastructure is coming for the BeOS because YOU are going to develop products and drivers and make a lot of money—right?)

But this isn't like Beta vs. VHS, where both are acceptable so either one can win. This is fiber vs. copper and it is a matter of spreading the word, getting the awareness out there. It is a question of "when," not "if." From now on media apps must be on the BeOS to be competitive. The BeOS *is* the Media OS.