diff --git a/docs/user/storage/NodeMonitor.dox b/docs/user/storage/NodeMonitor.dox new file mode 100644 index 0000000000..ecda7896d6 --- /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@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. +*/ + + +/*! + \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 B_WATCH_ATTR: 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 B_WATCH_ATTR: 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 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. + + \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 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. + + \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 e6065a71c9..cb66f15fc6 100644 --- a/headers/os/storage/NodeMonitor.h +++ b/headers/os/storage/NodeMonitor.h @@ -9,11 +9,10 @@ #include -/* 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 791a4f6d80..48c8cf1336 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) {