880e147bd9
* Add a note to stop_watching() about the asynchronous nature of node monitoring and its consequences. * Also update the breif description and parameters of stop_watching(). * Detail the return values of stop_watching() a bit better. * Add a note (an \attention actually) to B_STOP_WATCHING flag. * Fix a spelling mistake and other minor fixes.
431 lines
11 KiB
Plaintext
431 lines
11 KiB
Plaintext
/*
|
|
* Copyright 2003-2013 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 hrev45253
|
|
* src/kits/storage/NodeMonitor.cpp hrev45253
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var B_STOP_WATCHING
|
|
|
|
Flag for watch_node(). Unsubscribe from watching a node.
|
|
|
|
\attention \c B_STOP_WATCHING does not apply to volume watching, you must
|
|
call stop_watching() instead.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var B_WATCH_NAME
|
|
|
|
Flag for watch_volume() and watch_node(). Subscribe to watching for
|
|
change to the name of a node.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var B_WATCH_STAT
|
|
|
|
Flag for watch_volume() and watch_node(). Subscribe to watching for
|
|
changes to the stat information of a node.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var B_WATCH_ATTR
|
|
|
|
Flag for watch_volume() and watch_node(). Subscribe to watching for
|
|
changes to the attributes of a node.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var B_WATCH_DIRECTORY
|
|
|
|
Flag for watch_node(). Subscribe to watching for changes to the contents
|
|
of a directory.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var B_WATCH_ALL
|
|
|
|
Flag for watch_node(). Subscribe to watching for changes to all
|
|
information of a node except \c B_WATCH_MOUNT.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var B_WATCH_MOUNT
|
|
|
|
Flag for watch_node(). Subscribe to watching for when a volume is mounted
|
|
or unmounted. You may prefer to use BVolumeRoster for volume watching
|
|
instead.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var B_WATCH_INTERIM_STAT
|
|
|
|
\internal Implementation detail. Not in Be Book.
|
|
|
|
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.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\def B_ENTRY_CREATED
|
|
|
|
\c B_NODE_MONITOR notification message "opcode" is set when entry is
|
|
created.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\def B_ENTRY_REMOVED
|
|
|
|
\c B_NODE_MONITOR notification message "opcode" is set when entry is
|
|
removed.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\def B_ENTRY_MOVED
|
|
|
|
\c B_NODE_MONITOR notification message "opcode" is set when entry is
|
|
moved.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\def B_STAT_CHANGED
|
|
|
|
\c B_NODE_MONITOR notification message "opcode" set when stat info
|
|
changes. More information can be found in the "fields" field.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\def B_ATTR_CHANGED
|
|
|
|
\c B_NODE_MONITOR notification message "opcode" set when attribute
|
|
changes. More information can be found in the "cause" field.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\def B_DEVICE_MOUNTED
|
|
|
|
\c B_NODE_MONITOR notification message "opcode" set when device is
|
|
mounted.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\def B_DEVICE_UNMOUNTED
|
|
|
|
\c B_NODE_MONITOR notification message "opcode" set when device is
|
|
unmounted.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\def B_ATTR_CREATED
|
|
|
|
\c B_ATTR_CHANGED notification message "cause" set when attribute is
|
|
created. (Haiku only)
|
|
*/
|
|
|
|
|
|
/*!
|
|
\def B_ATTR_REMOVED
|
|
|
|
\c B_ATTR_CHANGED notification message "cause" set when attribute is
|
|
removed. (Haiku only)
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var B_STAT_MODE
|
|
|
|
\c B_STAT_CHANGED notification messages "fields" flag set when stat mode
|
|
changes.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var B_STAT_UID
|
|
|
|
\c B_STAT_CHANGED notification messages "fields" flag set when UID
|
|
changes.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var B_STAT_GID
|
|
|
|
\c B_STAT_CHANGED notification messages "fields" flag set when GID
|
|
changes.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var B_STAT_SIZE
|
|
|
|
\c B_STAT_CHANGED notification messages "fields" flag set when stat size
|
|
changes.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var B_STAT_ACCESS_TIME
|
|
|
|
\c B_STAT_CHANGED notification messages "fields" flag set when access time
|
|
changes.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var B_STAT_MODIFICATION_TIME
|
|
|
|
\c B_STAT_CHANGED notification messages "fields" flag set when
|
|
modification time changes.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var B_STAT_CREATION_TIME
|
|
|
|
\c B_STAT_CHANGED notification messages "fields" flag set when creation
|
|
time changes.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var B_STAT_CHANGE_TIME
|
|
|
|
\c B_STAT_CHANGED notification messages "fields" flag set when access,
|
|
modification or creation time changes.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var B_STAT_INTERIM_UPDATE
|
|
|
|
\internal Implementation detail. Not in Be Book.
|
|
|
|
\c B_STAT_CHANGED notification messages "fields" flag set when file is
|
|
written to.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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.
|
|
*/
|