Macros | Enumerations | Functions
NodeMonitor.h File Reference

Provides functions and constants for monitoring changes to a node. More...

Macros

#define B_ATTR_CHANGED   5
 B_NODE_MONITOR notification message "opcode" set when attribute changes. More...
 
#define B_ATTR_CREATED   1
 B_ATTR_CHANGED notification message "cause" set when attribute is created. More...
 
#define B_ATTR_REMOVED   2
 B_ATTR_CHANGED notification message "cause" set when attribute is removed. More...
 
#define B_DEVICE_MOUNTED   6
 B_NODE_MONITOR notification message "opcode" set when device is mounted. More...
 
#define B_DEVICE_UNMOUNTED   7
 B_NODE_MONITOR notification message "opcode" set when device is unmounted. More...
 
#define B_ENTRY_CREATED   1
 B_NODE_MONITOR notification message "opcode" is set when entry is created. More...
 
#define B_ENTRY_MOVED   3
 B_NODE_MONITOR notification message "opcode" is set when entry is moved. More...
 
#define B_ENTRY_REMOVED   2
 B_NODE_MONITOR notification message "opcode" is set when entry is removed. More...
 
#define B_STAT_CHANGED   4
 B_NODE_MONITOR notification message "opcode" set when stat info changes. More...
 

Enumerations

enum  {
  B_STOP_WATCHING = 0x0000,
  B_WATCH_NAME = 0x0001,
  B_WATCH_STAT = 0x0002,
  B_WATCH_ATTR = 0x0004,
  B_WATCH_DIRECTORY = 0x0008,
  B_WATCH_ALL = 0x000f,
  B_WATCH_MOUNT = 0x0010,
  B_WATCH_INTERIM_STAT = 0x0020
}
 
enum  {
  B_STAT_MODE = 0x0001,
  B_STAT_UID = 0x0002,
  B_STAT_GID = 0x0004,
  B_STAT_SIZE = 0x0008,
  B_STAT_ACCESS_TIME = 0x0010,
  B_STAT_MODIFICATION_TIME = 0x0020,
  B_STAT_CREATION_TIME = 0x0040,
  B_STAT_CHANGE_TIME = 0x0080,
  B_STAT_INTERIM_UPDATE = 0x1000
}
 

Functions

status_t stop_watching (BMessenger target)
 Unsubscribes target from node and mount monitoring. More...
 
status_t stop_watching (const BHandler *handler, const BLooper *looper=NULL)
 Unsubscribes handler or looper target from node and mount monitoring. More...
 
status_t watch_node (const node_ref *node, uint32 flags, BMessenger target)
 Subscribes or unsubscribes target to node and/or mount watching. More...
 
status_t watch_node (const node_ref *node, uint32 flags, const BHandler *handler, const BLooper *looper=NULL)
 Subscribes or unsubscribes handler or looper to node and/or mount watching. More...
 
status_t watch_volume (dev_t volume, uint32 flags, BMessenger target)
 Subscribes target to watch node changes on volume. More...
 
status_t watch_volume (dev_t volume, uint32 flags, const BHandler *handler, const BLooper *looper=NULL)
 Subscribes handler or looper to watch node changes on volume. More...
 

Detailed Description

Provides functions and constants for monitoring changes to a node.

The are three main node monitoring functions are watch_volume(), watch_node(), and stop_watching().

Macro Definition Documentation

◆ B_ATTR_CHANGED

#define B_ATTR_CHANGED   5

B_NODE_MONITOR notification message "opcode" set when attribute changes.

More information can be found in the "cause" field.

Since
BeOS R3

◆ B_ATTR_CREATED

#define B_ATTR_CREATED   1

B_ATTR_CHANGED notification message "cause" set when attribute is created.

Since
Haiku R1

◆ B_ATTR_REMOVED

#define B_ATTR_REMOVED   2

B_ATTR_CHANGED notification message "cause" set when attribute is removed.

Since
Haiku R1

◆ B_DEVICE_MOUNTED

#define B_DEVICE_MOUNTED   6

B_NODE_MONITOR notification message "opcode" set when device is mounted.

Since
BeOS R3

◆ B_DEVICE_UNMOUNTED

#define B_DEVICE_UNMOUNTED   7

B_NODE_MONITOR notification message "opcode" set when device is unmounted.

Since
BeOS R3

◆ B_ENTRY_CREATED

#define B_ENTRY_CREATED   1

B_NODE_MONITOR notification message "opcode" is set when entry is created.

Since
BeOS R3

◆ B_ENTRY_MOVED

#define B_ENTRY_MOVED   3

B_NODE_MONITOR notification message "opcode" is set when entry is moved.

Since
BeOS R3

◆ B_ENTRY_REMOVED

#define B_ENTRY_REMOVED   2

B_NODE_MONITOR notification message "opcode" is set when entry is removed.

Since
BeOS R3

◆ B_STAT_CHANGED

#define B_STAT_CHANGED   4

B_NODE_MONITOR notification message "opcode" set when stat info changes.

More information can be found in the "fields" field.

Since
BeOS R3

Enumeration Type Documentation

◆ anonymous enum

anonymous enum
Enumerator
B_STOP_WATCHING 

Unsubscribe from watching a node.

Flag for watch_node().

Attention
B_STOP_WATCHING does not apply to volume watching, you must call stop_watching() instead.
Since
BeOS R3
B_WATCH_NAME 

Subscribe to watching for change to the name of a node.

Flag for watch_volume() and watch_node().

Since
BeOS R3
B_WATCH_STAT 

Subscribe to watching for changes to the stat information of a node.

Flag for watch_volume() and watch_node().

Since
BeOS R3
B_WATCH_ATTR 

Subscribe to watching for changes to the attributes of a node.

Flag for watch_volume() and watch_node().

Since
BeOS R3
B_WATCH_DIRECTORY 

Subscribe to watching for changes to the contents of a directory.

Flag for watch_node().

Since
BeOS R3
B_WATCH_ALL 

Flag for watch_node().

Subscribe to watching for changes to all information of a node except B_WATCH_MOUNT.

Since
BeOS R3
B_WATCH_MOUNT 

Subscribe to watching for when a volume is mounted or unmounted.

You may prefer to use BVolumeRoster for volume watching instead.

Flag for watch_node().

Since
BeOS R3
B_WATCH_INTERIM_STAT 

To avoid a flood of messages for small and frequent write operations on an open file the file system can limit the number of notifications and mark them with the B_WATCH_INTERIM_STAT flag.

◆ anonymous enum

anonymous enum
Enumerator
B_STAT_MODE 

Set when stat mode changes.

B_STAT_CHANGED notification messages "fields" flag.

Since
Haiku R1
B_STAT_UID 

Set when UID changes.

B_STAT_CHANGED notification messages "fields" flag.

Since
Haiku R1
B_STAT_GID 

Set when GID changes.

B_STAT_CHANGED notification messages "fields" flag.

Since
Haiku R1
B_STAT_SIZE 

Set when stat size changes.

B_STAT_CHANGED notification messages "fields" flag.

Since
Haiku R1
B_STAT_ACCESS_TIME 

Set when access time changes.

B_STAT_CHANGED notification messages "fields" flag.

Since
Haiku R1
B_STAT_MODIFICATION_TIME 

Set when modification time changes.

B_STAT_CHANGED notification messages "fields" flag.

Since
Haiku R1
B_STAT_CREATION_TIME 

Set when creation time changes.

B_STAT_CHANGED notification messages "fields" flag.

Since
Haiku R1
B_STAT_CHANGE_TIME 

Set when access, modification or creation time changes.

B_STAT_CHANGED notification messages "fields" flag.

Since
Haiku R1
B_STAT_INTERIM_UPDATE 

Set when file is written to.

Function Documentation

◆ stop_watching() [1/2]

status_t stop_watching ( BMessenger  target)

Unsubscribes target from node and mount monitoring.

You may still receive notification messages after calling stop_watching() because while node monitoring is asynchronous and all changes are atomic, message sending is not atomic so there is a lag time from when you stop monitoring and when the message is received in your message receiving thread. You can check the timestamp of the message to determine if it was sent after stop_watching() was called.

Parameters
targetBMessenger object referring to the target.
Returns
A status code.
Return values
B_OKStopped sending notification messages to the target.
B_BAD_VALUEtarget was invalid.
B_ENTRY_NOT_FOUNDNode not found.
Since
BeOS R3

◆ stop_watching() [2/2]

status_t stop_watching ( const BHandler handler,
const BLooper looper = NULL 
)

Unsubscribes handler or looper target from node and mount monitoring.

You may still receive notification messages after calling stop_watching() because while node monitoring is asynchronous and all changes are atomic, message sending is not atomic so there is a lag time from when you stop monitoring and when the message is received in your message receiving thread. You can check the timestamp of the message to determine if it was sent after stop_watching() was called.

Parameters
handlerThe target handler, may be NULL. If looper is not NULL then the looper's preferred handler is targeted.
looperThe target looper, may be NULL. If handler is not NULL then the handler's looper is targeted.
Returns
A status code.
Return values
B_OKStopped sending notification messages to the target.
B_BAD_VALUETarget from handler or looper was invalid.
B_ENTRY_NOT_FOUNDNode not found.
Since
BeOS R3

◆ watch_node() [1/2]

status_t watch_node ( const node_ref node,
uint32  flags,
BMessenger  target 
)

Subscribes or unsubscribes target to node and/or mount watching.

Depending of flags the action performed by this function varies:

  • flags is 0: The target is unsubscribed from watching the node. node must not be NULL in this case.
  • flags contains B_WATCH_MOUNT: The target is subscribed to mount watching.
  • flags contains at least one of B_WATCH_NAME, B_WATCH_STAT, B_WATCH_ATTR, or B_WATCH_DIRECTORY: The target is subscribed to watching the specified aspects of the node. node must not be NULL in this case.

flags may include:

  • B_STOP_WATCHING

or one or more of the following:

  • B_WATCH_NAME
  • B_WATCH_STAT
  • B_WATCH_ATTR
  • B_WATCH_DIRECTORY
  • B_WATCH_ALL
  • B_WATCH_MOUNT

Note that the latter two cases are not mutual exclusive, i.e. mount and node watching can be requested with a single call.

Parameters
nodenode_ref referring to the node to be watched. May be NULL, if only mount watching is requested.
flagsFlags indicating the actions to be performed.
targetBMessenger object referring to the target.
Returns
B_OK if everything went fine, an error code otherwise.
Since
BeOS R3

◆ watch_node() [2/2]

status_t watch_node ( const node_ref node,
uint32  flags,
const BHandler handler,
const BLooper looper = NULL 
)

Subscribes or unsubscribes handler or looper to node and/or mount watching.

Depending of flags the action performed by this function varies:

  • flags is 0: The target is unsubscribed from watching the node. node must not be NULL in this case.
  • flags contains B_WATCH_MOUNT: The target is subscribed to mount watching.
  • flags contains at least one of B_WATCH_NAME, B_WATCH_STAT, B_WATCH_ATTR, or B_WATCH_DIRECTORY: The target is subscribed to watching the specified aspects of the node. node must not be NULL in this case.

flags may include:

  • B_STOP_WATCHING

or one or more of the following:

  • B_WATCH_NAME
  • B_WATCH_STAT
  • B_WATCH_ATTR
  • B_WATCH_DIRECTORY
  • B_WATCH_ALL
  • B_WATCH_MOUNT

Note that the latter two cases are not mutual exclusive, i.e. mount and node watching can be requested with a single call.

Parameters
nodenode_ref referring to the node to be watched. May be NULL, if only mount watching is requested.
flagsFlags indicating the actions to be performed.
handlerThe target handler. May be NULL, if looper is not NULL. Then the preferred handler of the looper is targeted.
looperThe target looper. May be NULL, if handler is not NULL. Then the handler's looper is the target looper.
Returns
B_OK if everything went fine, an error code otherwise.
Since
BeOS R3

◆ watch_volume() [1/2]

status_t watch_volume ( dev_t  volume,
uint32  flags,
BMessenger  target 
)

Subscribes target to watch node changes on volume.

Depending of flags the action performed by this function varies:

  • flags contains at least one of B_WATCH_NAME, B_WATCH_STAT, or B_WATCH_ATTR: The target is subscribed to watching the specified aspects of any node on the volume.

flags may include:

  • B_WATCH_NAME
  • B_WATCH_STAT
  • B_WATCH_ATTR

B_WATCH_VOLUME flag is assumed.

Parameters
volumedev_t referring to the volume to be watched.
flagsFlags indicating the actions to be performed.
targetMessenger referring to the target. Must be valid.
Returns
A status code.
Return values
B_OKEverything went fine.
B_BAD_VALUEflags did not include one of B_WATCH_NAME, B_WATCH_STAT, or B_WATCH_ATTR.
Since
Haiku R1

◆ watch_volume() [2/2]

status_t watch_volume ( dev_t  volume,
uint32  flags,
const BHandler handler,
const BLooper looper = NULL 
)

Subscribes handler or looper to watch node changes on volume.

Depending of flags the action performed by this function varies:

  • flags contains at least one of B_WATCH_NAME, B_WATCH_STAT, or B_WATCH_ATTR: The target is subscribed to watching the specified aspects of any node on the volume.

flags may include:

  • B_WATCH_NAME
  • B_WATCH_STAT
  • B_WATCH_ATTR

B_WATCH_VOLUME flag is assumed.

Parameters
volumedev_t referring to the volume to be watched.
flagsFlags indicating the actions to be performed.
handlerThe target handler. May be NULL, if looper is not NULL. Then the preferred handler of the looper is targeted.
looperThe target looper. May be NULL, if handler is not NULL. Then the handler's looper is the target looper.
Returns
A status code.
Return values
B_OKEverything went fine.
B_BAD_VALUEflags did not include one of B_WATCH_NAME, B_WATCH_STAT, or B_WATCH_ATTR.
Since
Haiku R1