watch_node() tells the Node Monitor to…

• …start paying attention to the node specified by the node_ref argument. If you're watching for volumes (only), nref can be NULL. The easiest way to get a node_ref is to invoke BStatable::GetNodeRef() on any BEntry or BNode object.

• The flags argument lists the changes that you want the Monitor to pay attention to. See below for details.

• The target of the change notification messages is specified either as a BMessenger, or as a BHandler / BLooper pair. (The target specification follows the BInvoker::SetTarget() protocol; see the BInvoker class for details.) The notification shows up as a BMessage in the target's MessageReceived() function.

Note

You can't tell the Node Monitor to send its notifications to another application. Currently, the BMessenger that you specify must identify a target in the caller's team.

Jumping ahead a bit, here's a sample function that tells the Node Monitor to watch for name and attribute changes to a given entry. The Monitor's notifications will be sent to the application's main loop:

status_t WatchThis(BEntry *entry)
{
   node_ref nref;
   entry->GetNodeRef(&nref);
   return (watch_node(&nref,
            B_WATCH_NAME | B_WATCH_ATTR,
            be_app_messenger));
}

Monitor Flags

watch_node()'s flags argument is a combination of the following

Constant	Description
B_WATCH_NAME	Watches for name changes. This includes moving the node to a different directory, or removing the node altogether.
B_WATCH_STAT	Watches for any change to the node's stat structure. This includes changes to the size, modification date, owner, and so on. See "The stat Structure" in the BStatable class for a description of what's in the stat structure.
B_WATCH_ATTR	Watches for changes to any of the node's attributes. This includes adding and removing attributes.
B_WATCH_DIRECTORY	Only applies to nodes that are directories. The flag tells the Monitor to watch for changes (new entries, entry deletions, entries being renamed) to the directory. (You can apply the other flags to a directory, as well). It's not an error to set B_WATCH_DIRECTORY on a node that isn't a directory—but it doesn't do anything for you.
B_WATCH_ALL.	This is a convenience that combines all the above.
B_WATCH_MOUNT	Watches for volumes being mounted and unmounted. As mentioned above, the nref argument isn't needed (it can be NULL) if all you're doing is watching volumes. B_WATCH_MOUNT isn't included in B_WATCH_ALL.

There's one other constant, which lives in a class by itself:

Constant	Description
B_STOP_WATCHING	Tells the Node Monitor to stop watching the nref argument.

You can't combine B_STOP_WATCHING with any of the others in an attempt to stop watching a specific category of changes. For example, if you call…

watch_node(&nref, B_WATCH_STAT, be_app_messenger);
watch_node(&nref, B_WATCH_ATTR, be_app_messenger);

…and then call…

watch_node(&nref, B_STOP_WATCHING, be_app_messenger);

…both of the previous Monitor calls are stopped.

Warning

B_STOP_WATCHING does not apply to volume watching. The only way to stop monitoring volume un/mounts is to call stop_watching().

watch_node(&nref,
    B_WATCH_NAME | B_WATCH_ATTR,
    be_app_messenger);

Tells the Node Monitor to stop sending notifications to the target described by the arguments. All the Node Monitor "slots" that were allocated to the target are freed. Keep in mind that are only 4096 slots for the entire system.

A completely new entry was created in a monitored directory. (This doesn't include entries that are moved into this directory from some other directory—see B_ENTRY_MOVED.)

You get this notification if you applied B_WATCH_DIRECTORY to the directory in which the entry was created. The message's fields are:

void MyTarget::MessageReceived(BMessage *msg)
{
   int32 opcode;
   dev_t device;
   ino_t directory;
   ino_t node;
   const char *name;

   if (msg->what == B_NODE_MONITOR) {
      if (msg->FindInt32("opcode", &opcode) == B_OK) {
         switch (opcode) {
            case B_ENTRY_CREATED:
               msg->FindInt32("device", &device);
               msg->FindInt64("directory", &directory);
               msg->FindInt64("node", &node);
               msg->FindString("name", &name);
               break;
            ...

entry_ref ref;
const char *name;
...
msg->FindInt32("device", &ref.device);
msg->FindInt64("directory", &ref.directory);
msg->FindString("name", &name);
ref.set_name(name);

node_ref nref;
status_t err;

...
msg->FindInt32("device", &nref.device);
msg->FindInt64("node", &nref.node);

err = watch_node(&nref, B_WATCH_ALL, be_app_messenger);

node_ref nref;
BDirectory dir;
status_t err;

...
msg->FindInt32("device", &nref.device);
msg->FindInt64("directory", &nref.node);
err = dir.SetTo(&nref);

A node was removed (deleted) from a directory.

You get this if you applied B_WATCH_NAME on the node itself, or B_WATCH_DIRECTORY on the directory that the node lived in. The message's fields are:

Note

Since this message is telling you that the node was removed, the "node" value will be invalid. The node number can be useful (and sometimes necessary) for comparison with cached node numbers (as demonstrated below).

Parsing the message is the same as for B_ENTRY_CREATED, but without the name field. See "Parsing and Tricks," above.

Note that the B_ENTRY_REMOVED message is sent as soon as the node's entry is "unlinked" from its directory. The node itself may linger for while after that. Follow this logic:

• When a file (regardless of flavor) is removed, the entry for that file is immediately removed ("unlinked") from the file hierarchy, and the Node Monitor message is immediately sent—even if you have an object that has opened the file's node.

• The node isn't actually destroyed until the last open object (to that node) is destroyed. (In POSIX speak, the node is destroyed when the last file descriptor to the node is closed.)

• Until the node is destroyed, the open objects (file descriptors) can still access the node's data.

You can take advantage of this to warn a user that a file is going to go away, or to make a backup, or whatever. For example, let's say you have an application that lets the user open files; each time a file is opened, your OpenFile() function creates a BFile object and starts the Node Monitor running:

status_t YourApp::OpenFile(const char *pathname)
{
   BFile *file;
   node_ref nref;
   status_t err;

   file = new BFile(pathname, B_READ_WRITE);
   if ((err=file->InitCheck()) != B_OK)
      return err;

   file->GetNodeRef(&nref);
   err = watch_node(&nref, B_WATCH_NAME, be_app_messenger);

   if (err != B_OK) {
      delete file;
      return err;
   }

   /* We've got the file and we're monitoring it; now we cache
   * the BFile by adding it to a BList (data member).
   * function. There's a race condition between the
   * watch_node() call above and the following AddItem().
   */
   return ((FileList->AddItem((void *)file)) ? B_OK : B_ERROR);

}

Now we receive a Node Monitor message telling us the node has been removed. We stuff the device and node fields into a node_ref and pass them to a (fictitious) AlertUser() function:

void YourApp::MessageReceived(BMessage *msg)
{
   int32 opcode;
   node_ref nref;

   if (msg->what == B_NODE_MONITOR) {
      if (msg->FindInt32("opcode", &opcode) == B_OK) {
         switch (opcode) {
            case B_ENTRY_REMOVED:
               msg->FindInt32("device", &nref.device);
               msg->FindInt64("node", &nref.node);
               GoodbyeFile(nref);
   ...
}

The implementation of GoodbyeFile() (which we won't show here) would walk down the BFile list looking for a node_ref that matches the argument:

void YourApp::GoodbyeFile(node_ref nref)
{
   BFile *filePtr;
   int32 ktr = 0;
   node_ref cref;

   while ((*filePtr = (BFile *)FileList->ItemAt(ktr++))) {
      filePtr->GetNodeRef(&cref);
      if (nref == cref) {
         /* We found it. Now we do whatever
         * we need to do.
         */
      }
   }
}

If a match is found, your app could then do whatever it needs to do. Remember—the node's data is still valid until your BFile is destroyed or re-initialized.

A node was moved from one directory to a different directory.

You get this if you applied B_WATCH_NAME on the node itself, or B_WATCH_DIRECTORY on either of the directories. The message's fields are:

Note

Moving a node does not change its ino_t number.

Parsing the message is much the same as for B_ENTRY_CREATED, modulo the directory field changes. See "Parsing and Tricks"

Moving a node doesn't affect the objects that hold the node open. They (the objects) can continue to read and write data from the node.

A field in the node's stat structure changed (this doesn't include the stat structure disappearing because the node was deleted).

You get this if you applied B_WATCH_STAT on the node itself. The message's fields are:

The stat structure is described in "The stat Structure" in the BStatable class. The fields that you can change are:

• Owner (st_uid), group (st_gid), and permissions (low four bytes of st_mode).

• Creation (st_ctime), modification (st_mtime), and access times (st_atime; currently unused).

• The size of the node's data (st_size). The measurement doesn't include attributes.

A couple of important points:

• The B_STAT_CHANGED message doesn't give you enough information to construct an object from which you can get a stat structure. In other words, you can't play the same games that were described in "Parsing and Tricks."

• The message also doesn't tell you which stat field changed.

In most uses of the B_STAT_CHANGED message, you have to cache the objects that you're monitoring so you can compare their node_refs to the message fields (an example of this is given in B_ENTRY_REMOVED). Furthermore, you may want to cache the objects' stat structures so you can figure out which field changed.

An attribute of the node changed.

You get this if you applied B_WATCH_ATTR on the node itself. The message's fields are:

Attributes are key/value pairs that can be "attached" to any file (regardless of flavor). They're described in the BNode class.

As with B_STAT_CHANGED messages, you may not be able to use the B_ATTR_CHANGED information directly. Instead, you have to cache references to the (BNode) objects that you're monitoring so you can compare their node_refs to the message fields (an example of this is given in B_ENTRY_REMOVED).

A file system device (in other words, a volume) was mounted.

You get this if you passed B_WATCH_MOUNT to watch_node(). The message's fields are:

Obviously, there's no node involved, here, so the first argument to the watch_node() call can be NULL:

watch_node(NULL, B_WATCH_MOUNT, be_app_messenger);

Unlike with the other "watch flags," the only way to stop the mount-watching is to call stop_watching().

A file system device (in other words, a volume) was unmounted.

You get this if you passed B_WATCH_MOUNT to watch_node(). The message's fields are:

Be careful with the device number: dev_ts are quickly recycled. You should only need this number if you're keeping a list of the dev_ts of all mounted disks and you want to remove the dev_t for this recently-unmounted volume (keeping in mind that a device mounted message bearing this dev_t may arrive in the meantime).