docs/user/storage/VolumeRoster.dox

   1 /*
   2  * Copyright 2002-2014 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       hrev47402
  12  *              src/kits/storage/VolumeRoster.cpp       hrev47402
  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         \since BeOS R3
  36 */
  37
  38
  39 /*!
  40         \fn BVolumeRoster::BVolumeRoster()
  41         \brief Creates a BVolumeRoster object. The object is ready to be used.
  42
  43         \since BeOS R3
  44 */
  45
  46
  47 /*!
  48         \fn BVolumeRoster::~BVolumeRoster()
  49         \brief Deletes the volume roster and frees all associated resources.
  50
  51         If a watch was activated (by StartWatching()), it is deactivated.
  52
  53         \since BeOS R3
  54 */
  55
  56
  57
  58 /*!
  59         \fn status_t BVolumeRoster::GetNextVolume(BVolume *volume)
  60         \brief Fills out the passed in BVolume object with the next available
  61                volume.
  62
  63         \param volume A pointer to a pre-allocated BVolume object to be
  64                initialized to the next available volume.
  65
  66         \return A status code.
  67         \retval B_OK Everything went fine.
  68         \retval B_BAD_VALUE The last volume in the list was already returned.
  69
  70         \since BeOS R3
  71 */
  72
  73
  74 /*!
  75         \fn void BVolumeRoster::Rewind()
  76         \brief Rewinds the list of available volumes back to the first item.
  77
  78         The next call to GetNextVolume() will return the first available volume.
  79
  80         \since BeOS R3
  81 */
  82
  83
  84 /*!
  85         \fn status_t BVolumeRoster::GetBootVolume(BVolume *volume)
  86         \brief Fills out the passed in BVolume object with the boot volume.
  87
  88         Currently, this method looks for the volume that is mounted at "/boot".
  89         The only way to fool the system into thinking that there is not a boot
  90         volume is to rename "/boot" -- but, please refrain from doing this.
  91
  92         \param volume A pointer to a pre-allocated BVolume to be initialized to
  93                refer to the boot volume.
  94
  95         \return A status code, \c B_OK if everything went fine or an error code
  96                 otherwise.
  97
  98         \since BeOS R3
  99 */
 100
 101
 102 /*!
 103         \fn status_t BVolumeRoster::StartWatching(BMessenger messenger)
 104         \brief Starts watching the available volumes for changes.
 105
 106         Notifications are sent to the specified target whenever a volume is
 107         mounted or unmounted. The format of the notification messages is
 108         described under watch_node(). Actually BVolumeRoster just provides a
 109         more convenient interface for it.
 110
 111         If StartWatching() has been called before with another target and no
 112         StopWatching() since, StopWatching() is called first, so that the former
 113         target won't receive any notifications anymore.
 114
 115         When the object is destroyed all watching ends as well.
 116
 117         \param messenger The target which the notification messages are sent.
 118
 119         \return A status code.
 120         \retval B_OK Everything went fine.
 121         \retval B_BAD_VALUE The supplied BMessenger was invalid.
 122         \retval B_NO_MEMORY There was insufficient memory to carry out this
 123                 operation.
 124
 125         \see watch_node()
 126
 127         \since BeOS R3
 128 */
 129
 130
 131 /*!
 132         \fn void BVolumeRoster::StopWatching()
 133         \brief Stops watching volumes initiated by StartWatching().
 134
 135         \see stop_watching()
 136
 137         \since BeOS R3
 138 */
 139
 140
 141 /*!
 142         \fn BMessenger BVolumeRoster::Messenger() const
 143         \brief Returns the messenger currently watching the volume list.
 144
 145         \return A messenger to the target currently watching the volume list, or
 146                 an invalid messenger if not watching.
 147
 148         \since BeOS R3
 149 */