In file include/NodeMonitorHelpers.h:

class NodeMonitor : private BMessenger

The Node Monitor is a service that lets you ask to be notified of certain file system changes

Inheritance:

NodeMonitor


Public Methods

NodeMonitor(const BStatable &toWatch)
Begins watching the given file system node
virtual ~NodeMonitor()
Stops watching the node that this monitor represents
status_t InitCheck()
Returns the result of constructing the node monitor

Public

File system utility functions
These are utility functions to make common storage kit conversions easier than before, particularly as they relate to node monitors
static entry_ref GetEntryRef(node_ref &from_directory, const char *name)
This is a utility function that obtains an entry_ref for a name in a directory node
static BEntry GetEntry(node_ref &from_directory, const char *name)
This is a utility function that obtains a BEntry for a name in the given directory node
static BDirectory GetDirectory(node_ref &directory_ref)
This is a utility function that converts a directory node_ref to a BDirectory object

Protected Fields

node_ref mTargetEntry
The node_ref that is being watched by this object
const BStatable* mWatched
The BStatable that is being watched by this object

Protected Methods

virtual void EntryDeleted(node_ref &fromDirectory)
This hook function is called when the node is deleted from the file system
virtual void EntryMoved(node_ref &from_directory, node_ref &to_directory, const char *newName)
This hook function is called when the node is moved to a new directory and/or gets a new name
virtual void StatChanged()
This hook function is called when certain parts of the stat structure have changed
virtual void AttributeChanged(const char *which)
This hook function is called when an attribute has been added, rewritten, or deleted

Documentation

The Node Monitor is a service that lets you ask to be notified of certain file system changes. You can ask to be told when a change is made to... The hook functions in this class are by default implemented to do nothing. The lone exception is NodeMonitor::EntryDeleted, which is implemented to simply turn off monitoring for the node since it is now deleted from the file system.

Hook functions must not block. Learn to use inter-thread communication and semaphores. It's easy.

NodeMonitor(const BStatable &toWatch)
Begins watching the given file system node. The notification functions in this class will be called when the given changes occur to the node. You should override only those notifications you're interested in getting.

Remember that BStatable is the ancestor to both BNode and BEntry (which is, in turn, the ancestor of BFile, BDirectory, and BSymLink. If you have an entry_ref, reassure yourself that it is not abstract (BEntry::Exists), and then you can turn it into a BStatable derivative. If you are working from a BNode only, ensure that it's properly initialized by calling InitCheck() before building a NodeMonitor on it.

Parameters:
towatch - The entity to begin observing.

virtual ~NodeMonitor()
Stops watching the node that this monitor represents

File system utility functions
These are utility functions to make common storage kit conversions easier than before, particularly as they relate to node monitors. If the conversion you want to make is not supported here, you should make certain that you have read and understead the storage kit's introduction, and understand the difference between a node and an entry.

static entry_ref GetEntryRef(node_ref &from_directory, const char *name)
This is a utility function that obtains an entry_ref for a name in a directory node.

Keep in mind that the reference may or may not be abstract. That's up to you to find out. Refer to the Storage Kit documentation for the definition of abstract.

See Also:
GetEntry

static BEntry GetEntry(node_ref &from_directory, const char *name)
This is a utility function that obtains a BEntry for a name in the given directory node. If the corresponding entry is for a symbolic link, it is not traversed. There are at least two ways this function can go wrong:
  1. First from_directory may be invalid. This would be the case if the directory node has been deleted from the file system. This will cause an invalid entry_ref.
  2. The given "name" may not exist in the directory. This will cause the entry_ref to come out abstract, which is different from invalid. refer to a file that does not exist in a directory that does.
To test for these conditions, you may wish to try the following code:
BDirectory directory;
BEntry entry;
directory = NodeMonitorHelpers::GetDirectory(dir_node_ref);
if (directory.InitCheck() == B_NO_ERROR) {
directory.Lock();

BEntry entry = NodeMonitorHelpers::GetEntry(dir_node_ref, name)));
if (entry.Exists()) {
}

directory.Unlock();
}
Returns:
The BEntry that represents the given name in the given directory.
Parameters:
directory_node - The node_ref that is known to point to a valid directory.
name - The name of the file inside the directory.

static BDirectory GetDirectory(node_ref &directory_ref)
This is a utility function that converts a directory node_ref to a BDirectory object. Note that ordinarily is is not possible to turn a node_ref into an entry_ref.

In various node monitor hook functions, a parameter is passed in that is a node_ref to a directory. For subtle reasons in the storage kit, you are allowed to turn a directory node_ref into its corresponding entry.

Note that the directory object may not be valid if the directory that contains the node_ref has not been locked. You should test it (with BDirectory::InitCheck) to make sure.

Returns:
The BDirectory object, configured for the node reference.
Parameters:
directory_ref - The node_ref that is known to point to a valid directory.

status_t InitCheck()
Returns the result of constructing the node monitor

virtual void EntryDeleted(node_ref &fromDirectory)
This hook function is called when the node is deleted from the file system. Note that, by the time this function is called, the node has already been removed, and the node_ref in this class is not guaranteed to be valid any more.

However, you can guarnatee that the node remains valid by keeping BFile objects around that point to the nodes you are interested in. Refer to the Storage Kit's documentation on the node monitor system for an example. Note that this will keep the node valid, but any entries that to the node are rendered abstract (if the node was a file) or invalid (if the node was a directory).

Note: It is a valid operation to delete this from this hook function, once you've dealt with the disappearance of this node. This is the default behaviour unless you override the destructor.

Parameters:
fromDirectory - The directory that the node that is being monitored is removed from.

virtual void EntryMoved(node_ref &from_directory, node_ref &to_directory, const char *newName)
This hook function is called when the node is moved to a new directory and/or gets a new name. If the file has simply been renamed in place, from_directory == to_directory.

virtual void StatChanged()
This hook function is called when certain parts of the stat structure have changed. The stat structure is described in "The stat Structure" in the BStatable class. If you are really interested in this, you will probably want to keep track of the parts of the stat structure you're interested in watching change.

Recall that few parts of stat can change:

  • 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.
See Also:
BStatable

virtual void AttributeChanged(const char *which)
This hook function is called when an attribute has been added, rewritten, or deleted
Parameters:
which - The name of the attribute which was added, rewritten, or deleted.
See Also:
Attribute

node_ref mTargetEntry
The node_ref that is being watched by this object. It should be equal to the result of mWatched->GetNodeRef().

const BStatable* mWatched
The BStatable that is being watched by this object. It's up to you to remember if it was a directory, file, or symlink; you can also use the dynamic_cast<> operator.


Direct child classes:
PathMonitor
DirectoryMonitor
Author:
Stephen van Egmond wrote the C++ classes Dominic Giampaolo wrote the node monitor

alphabetic index hierarchy of classes


this page has been generated automatically by doc++

(c)opyright by Malte Zöckler, Roland Wunderling
contact: doc++@zib.de