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*/
507