haiku/docs/user/storage/NodeMonitor.dox

/*
 * Copyright 2003-2014 Haiku, Inc. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 *		Axel Dörfler, axeld@pinc-software.de
 *		John Scipione, jscipione@gmail.com
 *		Ingo Weinhold, bonefish@users.sf.net
 *		Clemens Zeidler, haiku@clemens-zeidler.de
 *
 * Corresponds to:
 *		headers/os/storage/NodeMonitor.h	hrev47403
 *		src/kits/storage/NodeMonitor.cpp	hrev47403
 */


/*!
	\file NodeMonitor.h
	\ingroup storage
	\ingroup libbe
	\brief 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.
*/


//// Flags for the watch_node() call.


/*!
	\var B_STOP_WATCHING
	\brief Unsubscribe from watching a node.

	Flag for watch_node().

	\attention \c B_STOP_WATCHING does not apply to volume watching, you must
	           call stop_watching() instead.

	\since BeOS R3
*/


/*!
	\var B_WATCH_NAME
	\brief Subscribe to watching for change to the name of a node.

	Flag for watch_volume() and watch_node().

	\since BeOS R3
*/


/*!
	\var B_WATCH_STAT
	\brief Subscribe to watching for changes to the stat information of a node.

	Flag for watch_volume() and watch_node().

	\since BeOS R3
*/


/*!
	\var B_WATCH_ATTR
	\brief Subscribe to watching for changes to the attributes of a node.

	Flag for watch_volume() and watch_node().

	\since BeOS R3
*/


/*!
	\var B_WATCH_DIRECTORY
	\brief Subscribe to watching for changes to the contents of a directory.

	Flag for watch_node().

	\since BeOS R3
*/


/*!
	\var B_WATCH_ALL
	\brief Flag for watch_node().

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

	\since BeOS R3
*/


/*!
	\var B_WATCH_MOUNT
	\brief  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
*/


/*!
	\var B_WATCH_INTERIM_STAT
	\brief 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 \c B_WATCH_INTERIM_STAT flag.

	\internal Implementation detail, not in Be Book.

	\since Haiku R1
*/


// The "opcode" field of the B_NODE_MONITOR notification message you get.


/*!
	\def B_ENTRY_CREATED
	\brief \c B_NODE_MONITOR notification message "opcode" is set when entry is
	       created.

	\since BeOS R3
*/


/*!
	\def B_ENTRY_REMOVED
	\brief \c B_NODE_MONITOR notification message "opcode" is set when entry is
	       removed.

	\since BeOS R3
*/


/*!
	\def B_ENTRY_MOVED
	\brief \c B_NODE_MONITOR notification message "opcode" is set when entry is
	       moved.

	\since BeOS R3
*/


/*!
	\def B_STAT_CHANGED
	\brief \c B_NODE_MONITOR notification message "opcode" set when stat info
	       changes.

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

	\since BeOS R3
*/


/*!
	\def B_ATTR_CHANGED
	\brief \c B_NODE_MONITOR notification message "opcode" set when attribute
	       changes.

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

	\since BeOS R3
*/


/*!
	\def B_DEVICE_MOUNTED
	\brief \c B_NODE_MONITOR notification message "opcode" set when device is
	       mounted.

	\since BeOS R3
*/


/*!
	\def B_DEVICE_UNMOUNTED
	\brief \c B_NODE_MONITOR notification message "opcode" set when device is
	       unmounted.

	\since BeOS R3
*/


// More specific info in the "cause" field of B_ATTR_CHANGED notification
// messages.


/*!
	\def B_ATTR_CREATED
	\brief \c B_ATTR_CHANGED notification message "cause" set when attribute is
	       created.

	\since Haiku R1
*/


/*!
	\def B_ATTR_REMOVED
	\brief \c B_ATTR_CHANGED notification message "cause" set when attribute is
	       removed.

	\since Haiku R1
*/


// More specific info in the "fields" field of B_STAT_CHANGED notification
// messages, specifying what parts of the stat data have actually been
// changed.


/*!
	\var B_STAT_MODE
	\brief Set when stat mode changes.

	\c B_STAT_CHANGED notification messages "fields" flag.

	\since Haiku R1
*/


/*!
	\var B_STAT_UID
	\brief Set when UID changes.

	\c B_STAT_CHANGED notification messages "fields" flag.

	\since Haiku R1
*/


/*!
	\var B_STAT_GID
	\brief Set when GID changes.

	\c B_STAT_CHANGED notification messages "fields" flag.

	\since Haiku R1
*/


/*!
	\var B_STAT_SIZE
	\brief Set when stat size changes.

	\c B_STAT_CHANGED notification messages "fields" flag.

	\since Haiku R1
*/


/*!
	\var B_STAT_ACCESS_TIME
	\brief Set when access time changes.

	\c B_STAT_CHANGED notification messages "fields" flag.

	\since Haiku R1
*/


/*!
	\var B_STAT_MODIFICATION_TIME
	\brief Set when modification time changes.

	\c B_STAT_CHANGED notification messages "fields" flag.

	\since Haiku R1
*/


/*!
	\var B_STAT_CREATION_TIME
	\brief Set when creation time changes.

	\c B_STAT_CHANGED notification messages "fields" flag.

	\since Haiku R1
*/


/*!
	\var B_STAT_CHANGE_TIME
	\brief Set when access, modification or creation time changes.

	\c B_STAT_CHANGED notification messages "fields" flag.

	\since Haiku R1
*/


/*!
	\var B_STAT_INTERIM_UPDATE
	\brief Set when file is written to.

	\internal Implementation detail, not in Be Book.

	\c B_STAT_CHANGED notification messages "fields" flag.

	\since Haiku R1
*/


/*!
	\fn status_t watch_volume(dev_t volume, uint32 flags, BMessenger target)
	\brief Subscribes \a target to watch node changes on \a volume.

	Depending of \a flags the action performed by this function varies:
	- \a flags contains at least one of \c B_WATCH_NAME, \c B_WATCH_STAT,
	  or <tt>B_WATCH_ATTR</tt>: The target is subscribed to watching the specified
	  aspects of any node on the volume.

	\a flags may include:
	- \c B_WATCH_NAME
	- \c B_WATCH_STAT
	- \c B_WATCH_ATTR

	\c B_WATCH_VOLUME flag is assumed.

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

	\return A status code.
	\retval B_OK Everything went fine.
	\retval B_BAD_VALUE \a flags did not include one of \c B_WATCH_NAME,
	        \c B_WATCH_STAT, or \c B_WATCH_ATTR.

	\since Haiku R1
*/


/*!
	\fn status_t watch_volume(dev_t volume, uint32 flags,
		const BHandler* handler, const BLooper* looper)
	\brief Subscribes \a handler or \a looper to watch node changes on
	       \a volume.

	Depending of \a flags the action performed by this function varies:
	- \a flags contains at least one of \c B_WATCH_NAME, \c B_WATCH_STAT,
	  or <tt>B_WATCH_ATTR</tt>: The target is subscribed to watching the specified
	  aspects of any node on the volume.

	\a flags may include:
	- \c B_WATCH_NAME
	- \c B_WATCH_STAT
	- \c B_WATCH_ATTR

	\c B_WATCH_VOLUME flag is assumed.

	\param volume dev_t referring to the volume to be watched.
	\param flags Flags indicating the actions to be performed.
	\param handler The target \a handler. May be \c NULL, if \a looper is not
	       \c NULL. Then the preferred handler of the looper is targeted.
	\param looper The target \a looper. May be \c NULL, if \a handler is not
	       \c NULL. Then the handler's looper is the target looper.

	\return A status code.
	\retval B_OK Everything went fine.
	\retval B_BAD_VALUE \a flags did not include one of \c B_WATCH_NAME,
	        \c B_WATCH_STAT, or \c B_WATCH_ATTR.

	\since Haiku R1
*/


/*!
	\fn status_t watch_node(const node_ref* node, uint32 flags,
		BMessenger target)
	\brief Subscribes or unsubscribes \a target to node and/or mount watching.

	Depending of \a flags the action performed by this function varies:
	- \a flags is 0: The target is unsubscribed from watching the node.
	  \a node must not be \c NULL in this case.
	- \a flags contains \c B_WATCH_MOUNT: The target is subscribed to mount
	  watching.
	- \a flags contains at least one of \c B_WATCH_NAME, \c B_WATCH_STAT,
	  \c B_WATCH_ATTR, or <tt>B_WATCH_DIRECTORY</tt>: The target is subscribed to
	  watching the specified aspects of the node. \a node must not be \c NULL
	  in this case.

	\a flags may include:
	- \c B_STOP_WATCHING

	or one or more of the following:
	- \c B_WATCH_NAME
	- \c B_WATCH_STAT
	- \c B_WATCH_ATTR
	- \c B_WATCH_DIRECTORY
	- \c B_WATCH_ALL
	- \c 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.

	\param node node_ref referring to the node to be watched. May be \c NULL,
	       if only mount watching is requested.
	\param flags Flags indicating the actions to be performed.
	\param target BMessenger object referring to the \a target.

	\return \c B_OK if everything went fine, an error code otherwise.

	\since BeOS R3
*/


/*!
	\fn status_t watch_node(const node_ref* node, uint32 flags,
		const BHandler* handler, const BLooper* looper)
	\brief Subscribes or unsubscribes \a handler or \a looper to node and/or
	       mount watching.

	Depending of \a flags the action performed by this function varies:
	- \a flags is 0: The target is unsubscribed from watching the node.
	  \a node must not be \c NULL in this case.
	- \a flags contains \c B_WATCH_MOUNT: The target is subscribed to mount
	  watching.
	- \a flags contains at least one of \c B_WATCH_NAME, \c B_WATCH_STAT,
	  \c B_WATCH_ATTR, or <tt>B_WATCH_DIRECTORY</tt>: The target is subscribed to
	  watching the specified aspects of the node. \a node must not be \c NULL
	  in this case.

	\a flags may include:
	- \c B_STOP_WATCHING

	or one or more of the following:
	- \c B_WATCH_NAME
	- \c B_WATCH_STAT
	- \c B_WATCH_ATTR
	- \c B_WATCH_DIRECTORY
	- \c B_WATCH_ALL
	- \c 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.

	\param node node_ref referring to the node to be watched. May be \c NULL,
	       if only mount watching is requested.
	\param flags Flags indicating the actions to be performed.
	\param handler The target handler. May be \c NULL, if \a looper is not
	       \c NULL. Then the preferred handler of the looper is targeted.
	\param looper The target looper. May be \c NULL, if \a handler is not
	       \c NULL. Then the handler's looper is the target looper.

	\return \c B_OK if everything went fine, an error code otherwise.

	\since BeOS R3
*/


/*!
	\fn status_t stop_watching(BMessenger target)
	\brief Unsubscribes \a 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.

	\param target BMessenger object referring to the \a target.

	\return A status code.
	\retval B_OK Stopped sending notification messages to the \a target.
	\retval B_BAD_VALUE \a target was invalid.
	\retval B_ENTRY_NOT_FOUND Node not found.

	\since BeOS R3
*/


/*!
	\fn status_t stop_watching(const BHandler* handler, const BLooper* looper)
	\brief Unsubscribes \a handler or \a 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.

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

	\return A status code.
	\retval B_OK Stopped sending notification messages to the target.
	\retval B_BAD_VALUE Target from \a handler or \a looper was invalid.
	\retval B_ENTRY_NOT_FOUND Node not found.

	\since BeOS R3
*/