[haiku-commits] haiku: hrev45258 - docs/user/storage src/kits/storage headers/os/storage
- From: jscipione@xxxxxxxxx
- To: haiku-commits@xxxxxxxxxxxxx
- Date: Sat, 9 Feb 2013 02:40:15 +0100 (CET)
hrev45258 adds 1 changeset to branch 'master'
old head: 66d07bdfce49a76325f42d9d4b7374f520c47cb5
new head: fc9827011d04d5f203964499e9b823b395d63aaa
overview: http://cgit.haiku-os.org/haiku/log/?qt=range&q=fc98270+%5E66d07bd
----------------------------------------------------------------------------
fc98270: Moved NodeMonitor docs to Haiku Book.
[ John Scipione <jscipione@xxxxxxxxx> ]
----------------------------------------------------------------------------
Revision: hrev45258
Commit: fc9827011d04d5f203964499e9b823b395d63aaa
URL: http://cgit.haiku-os.org/haiku/commit/?id=fc98270
Author: John Scipione <jscipione@xxxxxxxxx>
Date: Sat Feb 9 01:39:35 2013 UTC
----------------------------------------------------------------------------
3 files changed, 413 insertions(+), 90 deletions(-)
docs/user/storage/NodeMonitor.dox | 392 ++++++++++++++++++++++++++++++++++
headers/os/storage/NodeMonitor.h | 31 ++-
src/kits/storage/NodeMonitor.cpp | 80 +------
----------------------------------------------------------------------------
diff --git a/docs/user/storage/NodeMonitor.dox
b/docs/user/storage/NodeMonitor.dox
new file mode 100644
index 0000000..ecda789
--- /dev/null
+++ b/docs/user/storage/NodeMonitor.dox
@@ -0,0 +1,392 @@
+/*
+ * Copyright 2013 Haiku Inc. All rights reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ * Axel Dörfler, axeld@xxxxxxxxxxxxxxxx
+ * John Scipione, jscipione@xxxxxxxxx
+ * Ingo Weinhold, bonefish@xxxxxxxxxxxx
+ * Clemens Zeidler, haiku@xxxxxxxxxxxxxxxxxx
+ *
+ * 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.
+*/
+
+
+/*!
+ \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.
+
+ Flag for watch_node(). Subscribe to watching when a file is written to.
+*/
+
+
+/*!
+ \def B_ENTRY_CREATED
+
+ \c B_NODE_MONITOR notification message "opcode", entry created.
+*/
+
+
+/*!
+ \def B_ENTRY_REMOVED
+
+ \c B_NODE_MONITOR notification message "opcode", entry removed.
+*/
+
+
+/*!
+ \def B_ENTRY_MOVED
+
+ \c B_NODE_MONITOR notification message "opcode", entry moved.
+*/
+
+
+/*!
+ \def B_STAT_CHANGED
+
+ \c B_NODE_MONITOR notification message "opcode", stat changed.
+*/
+
+
+/*!
+ \def B_ATTR_CHANGED
+
+ \c B_NODE_MONITOR notification message "opcode", attribute changed.
+*/
+
+
+/*!
+ \def B_DEVICE_MOUNTED
+
+ \c B_NODE_MONITOR notification message "opcode", device mounted.
+*/
+
+
+/*!
+ \def B_DEVICE_UNMOUNTED
+
+ \c B_NODE_MONITOR notification message "opcode", device unmounted.
+*/
+
+
+/*!
+ \def B_ATTR_CREATED
+
+ \c B_ATTR_CHANGED notification message "cause", attribute created.
+ (Haiku only)
+*/
+
+
+/*!
+ \def B_ATTR_REMOVED
+
+ \c B_ATTR_CHANGED notification message "cause", attribute removed.
+ (Haiku only)
+*/
+
+
+/*!
+ \var B_STAT_MODE
+
+ \c B_STAT_CHANGED notification messages "fields" flag, mode changed.
+*/
+
+
+/*!
+ \var B_STAT_UID
+
+ \c B_STAT_CHANGED notification messages "fields" flag, UID changed.
+*/
+
+
+/*!
+ \var B_STAT_GID
+
+ \c B_STAT_CHANGED notification messages "fields" flag, GID changed.
+*/
+
+
+/*!
+ \var B_STAT_SIZE
+
+ \c B_STAT_CHANGED notification messages "fields" flag, stat size
changed.
+*/
+
+
+/*!
+ \var B_STAT_ACCESS_TIME
+
+ \c B_STAT_CHANGED notification messages "fields" flag, access time
+ changed.
+*/
+
+
+/*!
+ \var B_STAT_MODIFICATION_TIME
+
+ \c B_STAT_CHANGED notification messages "fields" flag, modification time
+ changed.
+*/
+
+
+/*!
+ \var B_STAT_CREATION_TIME
+
+ \c B_STAT_CHANGED notification messages "fields" flag, creation time
+ changed.
+*/
+
+
+/*!
+ \var B_STAT_CHANGE_TIME
+
+ \c B_STAT_CHANGED notification messages "fields" flag, time information
+ changed.
+*/
+
+
+/*!
+ \var B_STAT_INTERIM_UPDATE
+
+ \internal Implementation detail. Not in Be Book.
+
+ \c B_STAT_CHANGED notification messages "fields" flag, 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 Messenger referring to the target. Must be valid.
+
+ \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 exlusive, 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.
+
+ \param target Messenger referring to the target. Must be valid.
+
+ \return \c B_OK if everything went fine, an error code otherwise.
+*/
+
+
+/*!
+ \fn status_t stop_watching(const BHandler *handler, const BLooper
*looper)
+ \brief Unsubscribes \a target from node and mount monitoring.
+
+ \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.
+*/
diff --git a/headers/os/storage/NodeMonitor.h b/headers/os/storage/NodeMonitor.h
index e6065a7..cb66f15 100644
--- a/headers/os/storage/NodeMonitor.h
+++ b/headers/os/storage/NodeMonitor.h
@@ -9,11 +9,10 @@
#include <StorageDefs.h>
-/* Flags for the watch_node() call.
- *
- * Note that B_WATCH_MOUNT is NOT included in B_WATCH_ALL.
- * You may prefer to use BVolumeRoster for volume watching.
- */
+// Flags for the watch_node() call.
+
+// Note that B_WATCH_MOUNT is NOT included in B_WATCH_ALL.
+// You may prefer to use BVolumeRoster for volume watching.
enum {
B_STOP_WATCHING = 0x0000,
@@ -28,11 +27,10 @@ enum {
};
-/* The "opcode" field of the B_NODE_MONITOR notification message you get.
- *
- * The presence and meaning of the other fields in that message specifying what
- * exactly caused the notification depend on this value.
- */
+// The "opcode" field of the B_NODE_MONITOR notification message you get.
+
+// The presence and meaning of the other fields in that message specifying what
+// exactly caused the notification depend on this value.
#define B_ENTRY_CREATED 1
#define B_ENTRY_REMOVED 2
@@ -67,11 +65,10 @@ enum {
};
-/* C++ callable Prototypes
- *
- * Since you are not able to parse BMessages from plain C, there is no
- * API exported.
- */
+// C++ callable Prototypes
+
+// Since you are not able to parse BMessages from plain C, there is no
+// API exported.
#if defined(__cplusplus) && !defined(_KERNEL_MODE)
@@ -95,6 +92,6 @@ extern status_t watch_node(const node_ref *node, uint32 flags,
extern status_t stop_watching(BMessenger target);
extern status_t stop_watching(const BHandler *handler, const BLooper *looper =
NULL);
-#endif /* __cplusplus && !_KERNEL_MODE */
+#endif // __cplusplus && !_KERNEL_MODE
-#endif /* _NODE_MONITOR_H*/
+#endif // _NODE_MONITOR_H
diff --git a/src/kits/storage/NodeMonitor.cpp b/src/kits/storage/NodeMonitor.cpp
index 791a4f6..48c8cf1 100644
--- a/src/kits/storage/NodeMonitor.cpp
+++ b/src/kits/storage/NodeMonitor.cpp
@@ -22,19 +22,7 @@
// TODO: Tests!
-// watch_volume
-/*! \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 \c B_WATCH_ATTR: The target is subscribed to
- watching the specified aspects of any node on the volume.
-
- \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 \c B_OK, if everything went fine, another error code otherwise.
-*/
+// Subscribes a target to watch node changes on a volume.
status_t
watch_volume(dev_t volume, uint32 flags, BMessenger target)
{
@@ -58,29 +46,7 @@ watch_volume(dev_t volume, uint32 flags, const BHandler
*handler,
}
-// watch_node
-/*! \brief Subscribes a target to node and/or mount watching, or
unsubscribes
- it from node watching.
-
- Depending of \a flags the action performed by this function varies:
- - \a flags is \c 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 \c B_WATCH_DIRECTORY: The target is subscribed to
- watching the specified aspects of the node. \a node must not be \c
NULL
- in this case.
-
- Note, that the latter two cases are not mutual exlusive, 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 Messenger referring to the target. Must be valid.
- \return \c B_OK, if everything went fine, another error code otherwise.
-*/
+// Subscribes or unsubscribes a target to node and/or mount watching.
status_t
watch_node(const node_ref *node, uint32 flags, BMessenger target)
{
@@ -122,32 +88,9 @@ watch_node(const node_ref *node, uint32 flags, BMessenger
target)
return B_OK;
}
-// watch_node
-/*! \brief Subscribes a target to node and/or mount watching, or
unsubscribes
- it from node watching.
-
- Depending of \a flags the action performed by this function varies:
- - \a flags is \c 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 \c B_WATCH_DIRECTORY: The target is subscribed to
- watching the specified aspects of the node. \a node must not be \c
NULL
- in this case.
-
- Note, that the latter two cases are not mutual exlusive, 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, another error code otherwise.
-*/
+
+// Subscribes or unsubscribes a handler or looper to node and/or mount
+// watching.
status_t
watch_node(const node_ref *node, uint32 flags, const BHandler *handler,
const BLooper *looper)
@@ -156,10 +99,7 @@ watch_node(const node_ref *node, uint32 flags, const
BHandler *handler,
}
-/*! \brief Unsubscribes a target from node and mount monitoring.
- \param target Messenger referring to the target. Must be valid.
- \return \c B_OK, if everything went fine, another error code otherwise.
-*/
+// Unsubscribes a target from node and mount monitoring.
status_t
stop_watching(BMessenger target)
{
@@ -174,13 +114,7 @@ stop_watching(BMessenger target)
}
-/*! \brief Unsubscribes a target from node and mount monitoring.
- \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, another error code otherwise.
-*/
+// Unsubscribes a target from node and mount monitoring.
status_t
stop_watching(const BHandler *handler, const BLooper *looper)
{
Other related posts:
- » [haiku-commits] haiku: hrev45258 - docs/user/storage src/kits/storage headers/os/storage - jscipione
