docs/user/storage/NodeMonitor.dox

   1 /*
   2  * Copyright 2003-2014 Haiku, Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Authors:
   6  *              Axel Dörfler, axeld@pinc-software.de
   7  *              John Scipione, jscipione@gmail.com
   8  *              Ingo Weinhold, bonefish@users.sf.net
   9  *              Clemens Zeidler, haiku@clemens-zeidler.de
  10  *
  11  * Corresponds to:
  12  *              headers/os/storage/NodeMonitor.h        hrev47403
  13  *              src/kits/storage/NodeMonitor.cpp        hrev47403
  14  */
  15
  16
  17 /*!
  18         \file NodeMonitor.h
  19         \ingroup storage
  20         \ingroup libbe
  21         \brief Provides functions and constants for monitoring changes to a node.
  22
  23         The are three main node monitoring functions are watch_volume(),
  24         watch_node(), and stop_watching().
  25         - watch_volume() starts watching a volume and sends a message
  26           when a requested event occurs.
  27         - watch_node() starts or stops watching a node, or watches for volumes
  28           to be mounted and unmounted, and sends a message when an event occurs.
  29         - stop_watching() stops monitoring a node or volume and no longer sends
  30           messages.
  31 */
  32
  33
  34 //// Flags for the watch_node() call.
  35
  36
  37 /*!
  38         \var B_STOP_WATCHING
  39         \brief Unsubscribe from watching a node.
  40
  41         Flag for watch_node().
  42
  43         \attention \c B_STOP_WATCHING does not apply to volume watching, you must
  44                    call stop_watching() instead.
  45
  46         \since BeOS R3
  47 */
  48
  49
  50 /*!
  51         \var B_WATCH_NAME
  52         \brief Subscribe to watching for change to the name of a node.
  53
  54         Flag for watch_volume() and watch_node().
  55
  56         \since BeOS R3
  57 */
  58
  59
  60 /*!
  61         \var B_WATCH_STAT
  62         \brief Subscribe to watching for changes to the stat information of a node.
  63
  64         Flag for watch_volume() and watch_node().
  65
  66         \since BeOS R3
  67 */
  68
  69
  70 /*!
  71         \var B_WATCH_ATTR
  72         \brief Subscribe to watching for changes to the attributes of a node.
  73
  74         Flag for watch_volume() and watch_node().
  75
  76         \since BeOS R3
  77 */
  78
  79
  80 /*!
  81         \var B_WATCH_DIRECTORY
  82         \brief Subscribe to watching for changes to the contents of a directory.
  83
  84         Flag for watch_node().
  85
  86         \since BeOS R3
  87 */
  88
  89
  90 /*!
  91         \var B_WATCH_ALL
  92         \brief Flag for watch_node().
  93
  94         Subscribe to watching for changes to all information of a node except
  95         \c B_WATCH_MOUNT.
  96
  97         \since BeOS R3
  98 */
  99
 100
 101 /*!
 102         \var B_WATCH_MOUNT
 103         \brief  Subscribe to watching for when a volume is mounted or unmounted.
 104
 105         You may prefer to use BVolumeRoster for volume watching instead.
 106
 107         Flag for watch_node().
 108
 109         \since BeOS R3
 110 */
 111
 112
 113 /*!
 114         \var B_WATCH_INTERIM_STAT
 115         \brief To avoid a flood of messages for small and frequent write operations
 116                on an open file the file system can limit the number of
 117                notifications and mark them with the \c B_WATCH_INTERIM_STAT flag.
 118
 119         \internal Implementation detail, not in Be Book.
 120
 121         \since Haiku R1
 122 */
 123
 124
 125 // The "opcode" field of the B_NODE_MONITOR notification message you get.
 126
 127
 128 /*!
 129         \def B_ENTRY_CREATED
 130         \brief \c B_NODE_MONITOR notification message "opcode" is set when entry is
 131                created.
 132
 133         \since BeOS R3
 134 */
 135
 136
 137 /*!
 138         \def B_ENTRY_REMOVED
 139         \brief \c B_NODE_MONITOR notification message "opcode" is set when entry is
 140                removed.
 141
 142         \since BeOS R3
 143 */
 144
 145
 146 /*!
 147         \def B_ENTRY_MOVED
 148         \brief \c B_NODE_MONITOR notification message "opcode" is set when entry is
 149                moved.
 150
 151         \since BeOS R3
 152 */
 153
 154
 155 /*!
 156         \def B_STAT_CHANGED
 157         \brief \c B_NODE_MONITOR notification message "opcode" set when stat info
 158                changes.
 159
 160         More information can be found in the "fields" field.
 161
 162         \since BeOS R3
 163 */
 164
 165
 166 /*!
 167         \def B_ATTR_CHANGED
 168         \brief \c B_NODE_MONITOR notification message "opcode" set when attribute
 169                changes.
 170
 171         More information can be found in the "cause" field.
 172
 173         \since BeOS R3
 174 */
 175
 176
 177 /*!
 178         \def B_DEVICE_MOUNTED
 179         \brief \c B_NODE_MONITOR notification message "opcode" set when device is
 180                mounted.
 181
 182         \since BeOS R3
 183 */
 184
 185
 186 /*!
 187         \def B_DEVICE_UNMOUNTED
 188         \brief \c B_NODE_MONITOR notification message "opcode" set when device is
 189                unmounted.
 190
 191         \since BeOS R3
 192 */
 193
 194
 195 // More specific info in the "cause" field of B_ATTR_CHANGED notification
 196 // messages.
 197
 198
 199 /*!
 200         \def B_ATTR_CREATED
 201         \brief \c B_ATTR_CHANGED notification message "cause" set when attribute is
 202                created.
 203
 204         \since Haiku R1
 205 */
 206
 207
 208 /*!
 209         \def B_ATTR_REMOVED
 210         \brief \c B_ATTR_CHANGED notification message "cause" set when attribute is
 211                removed.
 212
 213         \since Haiku R1
 214 */
 215
 216
 217 // More specific info in the "fields" field of B_STAT_CHANGED notification
 218 // messages, specifying what parts of the stat data have actually been
 219 // changed.
 220
 221
 222 /*!
 223         \var B_STAT_MODE
 224         \brief Set when stat mode changes.
 225
 226         \c B_STAT_CHANGED notification messages "fields" flag.
 227
 228         \since Haiku R1
 229 */
 230
 231
 232 /*!
 233         \var B_STAT_UID
 234         \brief Set when UID changes.
 235
 236         \c B_STAT_CHANGED notification messages "fields" flag.
 237
 238         \since Haiku R1
 239 */
 240
 241
 242 /*!
 243         \var B_STAT_GID
 244         \brief Set when GID changes.
 245
 246         \c B_STAT_CHANGED notification messages "fields" flag.
 247
 248         \since Haiku R1
 249 */
 250
 251
 252 /*!
 253         \var B_STAT_SIZE
 254         \brief Set when stat size changes.
 255
 256         \c B_STAT_CHANGED notification messages "fields" flag.
 257
 258         \since Haiku R1
 259 */
 260
 261
 262 /*!
 263         \var B_STAT_ACCESS_TIME
 264         \brief Set when access time changes.
 265
 266         \c B_STAT_CHANGED notification messages "fields" flag.
 267
 268         \since Haiku R1
 269 */
 270
 271
 272 /*!
 273         \var B_STAT_MODIFICATION_TIME
 274         \brief Set when modification time changes.
 275
 276         \c B_STAT_CHANGED notification messages "fields" flag.
 277
 278         \since Haiku R1
 279 */
 280
 281
 282 /*!
 283         \var B_STAT_CREATION_TIME
 284         \brief Set when creation time changes.
 285
 286         \c B_STAT_CHANGED notification messages "fields" flag.
 287
 288         \since Haiku R1
 289 */
 290
 291
 292 /*!
 293         \var B_STAT_CHANGE_TIME
 294         \brief Set when access, modification or creation time changes.
 295
 296         \c B_STAT_CHANGED notification messages "fields" flag.
 297
 298         \since Haiku R1
 299 */
 300
 301
 302 /*!
 303         \var B_STAT_INTERIM_UPDATE
 304         \brief Set when file is written to.
 305
 306         \internal Implementation detail, not in Be Book.
 307
 308         \c B_STAT_CHANGED notification messages "fields" flag.
 309
 310         \since Haiku R1
 311 */
 312
 313
 314 /*!
 315         \fn status_t watch_volume(dev_t volume, uint32 flags, BMessenger target)
 316         \brief Subscribes \a target to watch node changes on \a volume.
 317
 318         Depending of \a flags the action performed by this function varies:
 319         - \a flags contains at least one of \c B_WATCH_NAME, \c B_WATCH_STAT,
 320           or <tt>B_WATCH_ATTR</tt>: The target is subscribed to watching the specified
 321           aspects of any node on the volume.
 322
 323         \a flags may include:
 324         - \c B_WATCH_NAME
 325         - \c B_WATCH_STAT
 326         - \c B_WATCH_ATTR
 327
 328         \c B_WATCH_VOLUME flag is assumed.
 329
 330         \param volume dev_t referring to the volume to be watched.
 331         \param flags Flags indicating the actions to be performed.
 332         \param target Messenger referring to the target. Must be valid.
 333
 334         \return A status code.
 335         \retval B_OK Everything went fine.
 336         \retval B_BAD_VALUE \a flags did not include one of \c B_WATCH_NAME,
 337                 \c B_WATCH_STAT, or \c B_WATCH_ATTR.
 338
 339         \since Haiku R1
 340 */
 341
 342
 343 /*!
 344         \fn status_t watch_volume(dev_t volume, uint32 flags,
 345                 const BHandler* handler, const BLooper* looper)
 346         \brief Subscribes \a handler or \a looper to watch node changes on
 347                \a volume.
 348
 349         Depending of \a flags the action performed by this function varies:
 350         - \a flags contains at least one of \c B_WATCH_NAME, \c B_WATCH_STAT,
 351           or <tt>B_WATCH_ATTR</tt>: The target is subscribed to watching the specified
 352           aspects of any node on the volume.
 353
 354         \a flags may include:
 355         - \c B_WATCH_NAME
 356         - \c B_WATCH_STAT
 357         - \c B_WATCH_ATTR
 358
 359         \c B_WATCH_VOLUME flag is assumed.
 360
 361         \param volume dev_t referring to the volume to be watched.
 362         \param flags Flags indicating the actions to be performed.
 363         \param handler The target \a handler. May be \c NULL, if \a looper is not
 364                \c NULL. Then the preferred handler of the looper is targeted.
 365         \param looper The target \a looper. May be \c NULL, if \a handler is not
 366                \c NULL. Then the handler's looper is the target looper.
 367
 368         \return A status code.
 369         \retval B_OK Everything went fine.
 370         \retval B_BAD_VALUE \a flags did not include one of \c B_WATCH_NAME,
 371                 \c B_WATCH_STAT, or \c B_WATCH_ATTR.
 372
 373         \since Haiku R1
 374 */
 375
 376
 377 /*!
 378         \fn status_t watch_node(const node_ref* node, uint32 flags,
 379                 BMessenger target)
 380         \brief Subscribes or unsubscribes \a target to node and/or mount watching.
 381
 382         Depending of \a flags the action performed by this function varies:
 383         - \a flags is 0: The target is unsubscribed from watching the node.
 384           \a node must not be \c NULL in this case.
 385         - \a flags contains \c B_WATCH_MOUNT: The target is subscribed to mount
 386           watching.
 387         - \a flags contains at least one of \c B_WATCH_NAME, \c B_WATCH_STAT,
 388           \c B_WATCH_ATTR, or <tt>B_WATCH_DIRECTORY</tt>: The target is subscribed to
 389           watching the specified aspects of the node. \a node must not be \c NULL
 390           in this case.
 391
 392         \a flags may include:
 393         - \c B_STOP_WATCHING
 394
 395         or one or more of the following:
 396         - \c B_WATCH_NAME
 397         - \c B_WATCH_STAT
 398         - \c B_WATCH_ATTR
 399         - \c B_WATCH_DIRECTORY
 400         - \c B_WATCH_ALL
 401         - \c B_WATCH_MOUNT
 402
 403         Note that the latter two cases are not mutual exclusive, i.e. mount and
 404         node watching can be requested with a single call.
 405
 406         \param node node_ref referring to the node to be watched. May be \c NULL,
 407                if only mount watching is requested.
 408         \param flags Flags indicating the actions to be performed.
 409         \param target BMessenger object referring to the \a target.
 410
 411         \return \c B_OK if everything went fine, an error code otherwise.
 412
 413         \since BeOS R3
 414 */
 415
 416
 417 /*!
 418         \fn status_t watch_node(const node_ref* node, uint32 flags,
 419                 const BHandler* handler, const BLooper* looper)
 420         \brief Subscribes or unsubscribes \a handler or \a looper to node and/or
 421                mount watching.
 422
 423         Depending of \a flags the action performed by this function varies:
 424         - \a flags is 0: The target is unsubscribed from watching the node.
 425           \a node must not be \c NULL in this case.
 426         - \a flags contains \c B_WATCH_MOUNT: The target is subscribed to mount
 427           watching.
 428         - \a flags contains at least one of \c B_WATCH_NAME, \c B_WATCH_STAT,
 429           \c B_WATCH_ATTR, or <tt>B_WATCH_DIRECTORY</tt>: The target is subscribed to
 430           watching the specified aspects of the node. \a node must not be \c NULL
 431           in this case.
 432
 433         \a flags may include:
 434         - \c B_STOP_WATCHING
 435
 436         or one or more of the following:
 437         - \c B_WATCH_NAME
 438         - \c B_WATCH_STAT
 439         - \c B_WATCH_ATTR
 440         - \c B_WATCH_DIRECTORY
 441         - \c B_WATCH_ALL
 442         - \c B_WATCH_MOUNT
 443
 444         Note that the latter two cases are not mutual exclusive, i.e. mount and
 445         node watching can be requested with a single call.
 446
 447         \param node node_ref referring to the node to be watched. May be \c NULL,
 448                if only mount watching is requested.
 449         \param flags Flags indicating the actions to be performed.
 450         \param handler The target handler. May be \c NULL, if \a looper is not
 451                \c NULL. Then the preferred handler of the looper is targeted.
 452         \param looper The target looper. May be \c NULL, if \a handler is not
 453                \c NULL. Then the handler's looper is the target looper.
 454
 455         \return \c B_OK if everything went fine, an error code otherwise.
 456
 457         \since BeOS R3
 458 */
 459
 460
 461 /*!
 462         \fn status_t stop_watching(BMessenger target)
 463         \brief Unsubscribes \a target from node and mount monitoring.
 464
 465         You may still receive notification messages after calling stop_watching()
 466         because while node monitoring is asynchronous and all changes are atomic,
 467         message sending is not atomic so there is a lag time from when you
 468         stop monitoring and when the message is received in your message receiving
 469         thread. You can check the timestamp of the message to determine if
 470         it was sent after stop_watching() was called.
 471
 472         \param target BMessenger object referring to the \a target.
 473
 474         \return A status code.
 475         \retval B_OK Stopped sending notification messages to the \a target.
 476         \retval B_BAD_VALUE \a target was invalid.
 477         \retval B_ENTRY_NOT_FOUND Node not found.
 478
 479         \since BeOS R3
 480 */
 481
 482
 483 /*!
 484         \fn status_t stop_watching(const BHandler* handler, const BLooper* looper)
 485         \brief Unsubscribes \a handler or \a looper target from node and mount
 486                monitoring.
 487
 488         You may still receive notification messages after calling stop_watching()
 489         because while node monitoring is asynchronous and all changes are atomic,
 490         message sending is not atomic so there is a lag time from when you
 491         stop monitoring and when the message is received in your message receiving
 492         thread. You can check the timestamp of the message to determine if
 493         it was sent after stop_watching() was called.
 494
 495         \param handler The target handler, may be \c NULL. If \a looper is not
 496                \c NULL then the looper's preferred handler is targeted.
 497         \param looper The target looper, may be \c NULL. If \a handler is not
 498                \c NULL then the handler's looper is targeted.
 499
 500         \return A status code.
 501         \retval B_OK Stopped sending notification messages to the target.
 502         \retval B_BAD_VALUE Target from \a handler or \a looper was invalid.
 503         \retval B_ENTRY_NOT_FOUND Node not found.
 504
 505         \since BeOS R3
 506 */