System Messages Introduction

This chapter lists and describes the messages that are defined by Be. This includes messages that are sent from the system to your application, messages that your application can create and send to other applications (and servers), and messages that are defined for their formats, but that you don't literally send anywhere (such as a clipboard message format).

Most messages are listed by their command constants (B_ABOUT_REQUESTED, B_QUIT_REQUESTED, etc.). Where the command constant isn't specific enough, the message is listed by some other field. For example, every Node Monitor message has the command constant B_NODE_MONITOR, and is further distinguished—and listed below—by its "opcode" field value (B_ENTRY_REMOVED, B_STAT_CHANGED, etc.). If a message doesn't have a defined command constant or other descriptive field, it's identified prosaically ("Clipboard Data", for example).

Reading a Message Description

Each message entry follows this format:

Purpose: Tells you whether the message is meant to be delivered ("Deliverable"), or if it's defined simply for its format ("Format"). A message can be both: It can be used as a deliverable by one part of the system, and used just for its format in another.

If the message is deliverable, it will describe the following:

Source: The sender of the message. An important point here is whether the message is sent by the system, by your app, or by both. If the "Source:" line doesn't mention that your app can send the message, then don't send it. Often the source is listed, vaguely, as "the system." This denotes that the message is sent by one of the basic servers (App Server or Input Server, mainly). Other sources (Node Monitor, Roster Monitor, MIME Monitor) are identified more precisely. In any case, the identity of the source is provided mainly so you know which ballpark you're in—the exact identity shouldn't matter to your code.
Target: The target of the message. This is the BHandler object that receives the message, and, if applicable, converts it to a hook function. For example, the target of a B_VIEW_MOVED message is the view's BWindow, not the BView itself (because the BView never actually sees the B_VIEW_MOVED message—it only sees the ViewMoved() hook function). The target is often either be_app or a BWindow object, but for some messages the target is declared by your app (the target of a BControl's invocation message, for example).
Hook: The hook function that the target invokes when the message is received. If this line is missing, the message doesn't map to a hook function.

This is followed by a brief description that tells you the circumstances under which the message is sent, and how your app is expected to behave when it receives the message. If the description doesn't say what your app is supposed to do, then it doesn't have to actively do anything, but it shouldn't interfere with the default mechanism.

After the description is a table that lists the message's Be-defined fields. If it doesn't have any fields, the table is excluded. If a field holds an array of data, the maximum size of the array, if known, is given in brackets after the field name:

"byte" [3]

In some cases, the array size is the value of some other field. Here, the size of the array in the "argv" field is given by the value of the "argc" field:

"argv" ["argc"]