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

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 ,   B_WATCH_CHILDREN = 0x0040 }
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.
status_t	stop_watching (const BHandler *handler, const BLooper *looper=NULL)
	Unsubscribes handler or looper target from node and mount monitoring.
status_t	watch_node (const node_ref *node, uint32 flags, BMessenger target)
	Subscribes or unsubscribes target to node and/or mount watching.
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.
status_t	watch_volume (dev_t volume, uint32 flags, BMessenger target)
	Subscribes target to watch node changes on volume.
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.

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().

• watch_volume() starts watching a volume and sends a message when a requested event occurs.
• watch_node() starts or stops watching a node, or watches for volumes to be mounted and unmounted, and sends a message when an event occurs.
• stop_watching() stops monitoring a node or volume and no longer sends messages.

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

target

BMessenger object referring to the target.

Returns

A status code.

Return values

B_OK	Stopped sending notification messages to the target.
B_BAD_VALUE	target was invalid.
B_ENTRY_NOT_FOUND	Node 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

handler	The target handler, may be NULL. If looper is not NULL then the looper's preferred handler is targeted.
looper	The target looper, may be NULL. If handler is not NULL then the handler's looper is targeted.

Returns

A status code.

Return values

B_OK	Stopped sending notification messages to the target.
B_BAD_VALUE	Target from handler or looper was invalid.
B_ENTRY_NOT_FOUND	Node 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

node	node_ref referring to the node to be watched. May be NULL, if only mount watching is requested.
flags	Flags indicating the actions to be performed.
target	BMessenger 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

node	node_ref referring to the node to be watched. May be NULL, if only mount watching is requested.
flags	Flags indicating the actions to be performed.
handler	The target handler. May be NULL, if looper is not NULL. Then the preferred handler of the looper is targeted.
looper	The 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

volume	dev_t referring to the volume to be watched.
flags	Flags indicating the actions to be performed.
target	Messenger referring to the target. Must be valid.

Returns

A status code.

Return values

B_OK	Everything went fine.
B_BAD_VALUE	flags 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

volume	dev_t referring to the volume to be watched.
flags	Flags indicating the actions to be performed.
handler	The target handler. May be NULL, if looper is not NULL. Then the preferred handler of the looper is targeted.
looper	The 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_OK	Everything went fine.
B_BAD_VALUE	flags did not include one of B_WATCH_NAME, B_WATCH_STAT, or B_WATCH_ATTR.

Since

Haiku R1