1/* 2 * Copyright 2002-2013 Haiku Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Vincent Dominguez 7 * John Scipione, jscipione@gmail.com 8 * Ingo Weinhold, bonefish@users.sf.net 9 * 10 * Corresponds to: 11 * headers/os/storage/VolumeRoster.h hrev45306 12 * src/kits/storage/VolumeRoster.cpp hrev45306 13 */ 14 15 16/*! 17 \file VolumeRoster.h 18 \ingroup storage 19 \ingroup libbe 20 \brief Provides the BVolumeRoster class. 21*/ 22 23 24/*! 25 \class BVolumeRoster 26 \ingroup storage 27 \ingroup libbe 28 \brief Provides an interface for iterating through available volumes 29 and watching for mounting/unmounting. 30 31 This class wraps the next_dev() function for iterating through the 32 list of available volumes and watch_node()/stop_watching() for 33 watching volumes. 34*/ 35 36 37/*! 38 \fn BVolumeRoster::BVolumeRoster() 39 \brief Creates a BVolumeRoster object. The object is ready to be used. 40*/ 41 42 43/*! 44 \fn BVolumeRoster::~BVolumeRoster() 45 \brief Deletes the volume roster and frees all associated resources. 46 47 If a watch was activated (by StartWatching()), it is deactivated. 48*/ 49 50 51 52/*! 53 \fn status_t BVolumeRoster::GetNextVolume(BVolume *volume) 54 \brief Fills out the passed in BVolume object with the next available 55 volume. 56 57 \param volume A pointer to a pre-allocated BVolume object to be 58 initialized to the next available volume. 59 60 \return A status code. 61 \retval B_OK Everything went fine. 62 \retval B_BAD_VALUE The last volume in the list was already returned. 63*/ 64 65 66/*! 67 \fn void BVolumeRoster::Rewind() 68 \brief Rewinds the list of available volumes back to the first item. 69 70 The next call to GetNextVolume() will return the first available volume. 71*/ 72 73 74/*! 75 \fn status_t BVolumeRoster::GetBootVolume(BVolume *volume) 76 \brief Fills out the passed in BVolume object with the boot volume. 77 78 Currently, this method looks for the volume that is mounted at "/boot". 79 The only way to fool the system into thinking that there is not a boot 80 volume is to rename "/boot" -- but, please refrain from doing this. 81 82 \param volume A pointer to a pre-allocated BVolume to be initialized to 83 refer to the boot volume. 84 85 \return A status code, \c B_OK if everything went fine or an error code 86 otherwise. 87*/ 88 89 90/*! 91 \fn status_t BVolumeRoster::StartWatching(BMessenger messenger) 92 \brief Starts watching the available volumes for changes. 93 94 Notifications are sent to the specified target whenever a volume is 95 mounted or unmounted. The format of the notification messages is 96 described under watch_node(). Actually BVolumeRoster just provides a 97 more convenient interface for it. 98 99 If StartWatching() has been called before with another target and no 100 StopWatching() since, StopWatching() is called first, so that the former 101 target won't receive any notifications anymore. 102 103 When the object is destroyed all watching ends as well. 104 105 \param messenger The target which the notification messages are sent. 106 107 \return A status code. 108 \retval B_OK Everything went fine. 109 \retval B_BAD_VALUE The supplied BMessenger was invalid. 110 \retval B_NO_MEMORY There was insufficient memory to carry out this 111 operation. 112 113 \see watch_node() 114*/ 115 116 117/*! 118 \fn void BVolumeRoster::StopWatching() 119 \brief Stops watching volumes initiated by StartWatching(). 120 121 \see stop_watching() 122*/ 123 124 125/*! 126 \fn BMessenger BVolumeRoster::Messenger() const 127 \brief Returns the messenger currently watching the volume list. 128 129 \return A messenger to the target currently watching the volume list, or 130 an invalid messenger if not watching. 131*/ 132