docs/user/storage/Volume.dox

   1 /*
   2  * Copyright 2002-2014 Haiku, Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Authors:
   6  *              Tyler Dauwalder
   7  *              Vincent Dominguez
   8  *              John Scipione, jscipione@gmail.com
   9  *              Ingo Weinhold, bonefish@users.sf.net
  10  *
  11  * Corresponds to:
  12  *              headers/os/storage/Volume.h     hrev47402
  13  *              src/kits/storage/Volume.cpp     hrev47402
  14  */
  15
  16
  17 /*!
  18         \file Volume.h
  19         \ingroup storage
  20         \ingroup libbe
  21         \brief Provides the BVolume class.
  22 */
  23
  24
  25 /*!
  26         \class BVolume
  27         \ingroup storage
  28         \ingroup libbe
  29         \brief Provides an interface for querying information about a volume.
  30
  31         The class is a simple wrapper for a \c dev_t and the function
  32         fs_stat_dev(). The sole exception is the SetName() method which
  33         sets the name of the volume.
  34
  35         \since BeOS R3
  36 */
  37
  38
  39 /*!
  40         \fn BVolume::BVolume()
  41         \brief Creates an uninitialized BVolume object.
  42
  43         InitCheck() will return \c B_NO_INIT.
  44
  45         \see SetTo()
  46
  47         \since BeOS R3
  48 */
  49
  50
  51 /*!
  52         \fn BVolume::BVolume(dev_t device)
  53         \brief Creates a BVolume and initializes it to the volume specified
  54                by the supplied device ID.
  55
  56         InitCheck() should be called afterwards to check if initialization was
  57         successful.
  58
  59         \param device The device ID of the volume.
  60
  61         \since BeOS R3
  62 */
  63
  64
  65 /*!
  66         \fn BVolume::BVolume(const BVolume& volume)
  67         \brief Creates a copy of the supplied BVolume object.
  68
  69         Afterwards the object refers to the same device the supplied object
  70         does. If the latter is not properly initialized, this result isn't
  71         either.
  72
  73         \param volume The volume object to be copied.
  74
  75         \since BeOS R3
  76 */
  77
  78
  79 /*!
  80         \fn BVolume::~BVolume()
  81         \brief Destroys the object and frees all associated resources.
  82
  83         \since BeOS R3
  84 */
  85
  86
  87 /*!
  88         \name Constructor Helpers
  89 */
  90
  91
  92 //! @{
  93
  94
  95 /*!
  96         \fn status_t BVolume::InitCheck(void) const
  97         \brief Returns the initialization status.
  98
  99         \return \c B_OK if the object was properly initialized, or an error code
 100                 otherwise.
 101
 102         \since BeOS R3
 103 */
 104
 105
 106 /*!
 107         \fn status_t BVolume::SetTo(dev_t device)
 108         \brief Initializes the object to refer to the volume specified by
 109                the supplied device ID.
 110
 111         \param device The device ID of the volume to set.
 112
 113         \return \c B_OK if the object was properly initialized, or an error code
 114                 otherwise.
 115
 116         \since BeOS R3
 117 */
 118
 119
 120 /*!
 121         \fn void BVolume::Unset()
 122         \brief Brings the BVolume object to an uninitialized state.
 123
 124         InitCheck() will return \c B_NO_INIT.
 125
 126         \since BeOS R3
 127 */
 128
 129
 130 //! @}
 131
 132
 133 /*!
 134         \name Volume Information
 135 */
 136
 137
 138 //! @{
 139
 140
 141 /*!
 142         \fn dev_t BVolume::Device() const
 143         \brief Returns the device ID of the volume the object refers to.
 144
 145         \return Returns the device ID of the volume the object refers to
 146                 or -1 if the object was not properly initialized.
 147
 148         \since BeOS R3
 149 */
 150
 151
 152 /*!
 153         \fn status_t BVolume::GetRootDirectory(BDirectory *directory) const
 154         \brief Writes the root directory of the volume referred to by this
 155                object into \a directory.
 156
 157         \param directory A pointer to a pre-allocated BDirectory to be initialized
 158                to the volume's root directory.
 159
 160         \return A status code.
 161         \retval B_OK Everything went fine.
 162         \retval B_BAD_VALUE \a directory was \c NULL or the object was not properly
 163                 initialized.
 164
 165         \since BeOS R3
 166 */
 167
 168
 169 /*!
 170         \fn off_t BVolume::Capacity() const
 171         \brief Returns the total storage capacity of the volume.
 172
 173         \return The volume's total storage capacity (in bytes), or \c B_BAD_VALUE
 174                 if the object is not properly initialized.
 175
 176         \see FreeBytes()
 177
 178         \since BeOS R3
 179 */
 180
 181
 182 /*!
 183         \fn off_t BVolume::FreeBytes() const
 184         \brief Returns the amount of unused space on the volume (in bytes).
 185
 186         \return The amount of unused space on the volume (in bytes), or
 187                 \c B_BAD_VALUE if the object is not properly initialized.
 188
 189         \since BeOS R3
 190 */
 191
 192
 193 /*!
 194         \fn off_t BVolume::BlockSize() const
 195         \brief Returns the size of one block (in bytes). The meaning of this
 196                depends on the underlying file system.
 197
 198         \return The block size in bytes, \c B_NO_INIT if the volume is not
 199                 initialized or other errors forwarded from the file system.
 200
 201         \since Haiku R1
 202 */
 203
 204
 205 //! @}
 206
 207
 208 /*!
 209         \name Volume Name
 210 */
 211
 212
 213 //! @{
 214
 215
 216 /*!
 217         \fn status_t BVolume::GetName(char* name) const
 218         \brief Writes the volume's name into the provided buffer.
 219
 220         \param name A pointer to a pre-allocated character buffer of size
 221                \c B_FILE_NAME_LENGTH or larger into which the name of the
 222                volume is written.
 223
 224         \return A status code.
 225         \retval B_OK Everything went fine.
 226         \retval B_BAD_VALUE \a name was \c NULL or the object was not properly
 227                 initialized.
 228
 229         \see SetName()
 230
 231         \since BeOS R3
 232 */
 233
 234
 235 /*!
 236         \fn status_t BVolume::SetName(const char *name)
 237         \brief Sets the volume's name to \a name.
 238
 239         \note The R5 implementation checks if an entry with the volume's old name
 240               exists in the root directory and renames that entry, if it is indeed
 241               the mount point of the volume (or a link referring to it). In all
 242               other cases, nothing is done (even if the mount point is named like
 243               the volume, but lives in a different directory). We follow suit for
 244               the time being.
 245
 246         \warning If the volume name is set to "boot" this method tries to rename
 247                  it to /boot, but is prevented by the kernel.
 248
 249         \param name The new name of the volume, must not be longer than
 250                    \c B_FILE_NAME_LENGTH (including the terminating \c NULL).
 251
 252         \return A status code.
 253         \retval B_OK Everything went fine.
 254         \retval B_BAD_VALUE \a name was \c NULL or the object was not properly
 255                 initialized.
 256
 257         \since Haiku R1
 258 */
 259
 260
 261 //! @}
 262
 263
 264 /*!
 265         \name Volume Icon
 266 */
 267
 268
 269 //! @{
 270
 271
 272 /*!
 273         \fn status_t BVolume::GetIcon(BBitmap *icon, icon_size which) const
 274         \brief Writes the volume's icon into the supplied BBitmap.
 275
 276         \param icon A pointer to a pre-allocated BBitmap of the correct dimension
 277                to store the requested icon (16x16 for the mini and 32x32 for the
 278                large icon).
 279
 280         \param which The icon size to be retrieved: \c B_MINI_ICON for the mini or
 281                \c B_LARGE_ICON for the large icon.
 282
 283         \since BeOS R4
 284 */
 285
 286
 287 /*!
 288         \fn status_t BVolume::GetIcon(uint8** _data, size_t* _size,
 289                 type_code* _type) const
 290         \brief Writes the volume's icon data into the supplied \c uint8 array.
 291
 292         \param _data A pointer to a pointer to a pre-allocated \c uint8 array of
 293                the correct size to store the requested icon.
 294         \param _size The size of the retrieved icon (in bytes).
 295         \param _type The type code of the retrieve icon.
 296
 297         \returns A status code.
 298         \retval B_OK Everything went fine.
 299         \retval B_NO_INIT Object was not properly initialized.
 300
 301         \see fs_stat_dev() for more return codes.
 302         \see get_device_icon() for more return codes.
 303
 304         \since Haiku R1
 305 */
 306
 307
 308 //! @}
 309
 310
 311 /*!
 312         \name Volume Capabilities
 313 */
 314
 315
 316 //! @{
 317
 318
 319 /*!
 320         \fn bool BVolume::IsRemovable() const
 321         \brief Returns whether or not the volume is removable.
 322
 323         \return \c true, if the volume was properly initialized and is removable,
 324                 \c false otherwise.
 325
 326         \since BeOS R3
 327 */
 328
 329
 330 /*!
 331         \fn bool BVolume::IsReadOnly(void) const
 332         \brief Returns whether or not the volume is read-only.
 333
 334         \return \c true, if the volume was properly initialized and is read-only,
 335                 \c false otherwise.
 336
 337         \since BeOS R3
 338 */
 339
 340
 341 /*!
 342         \fn bool BVolume::IsPersistent(void) const
 343         \brief Returns whether or not the volume is persistent.
 344
 345         \return \c true, if the volume was properly initialized and is persistent,
 346                \c false otherwise.
 347
 348         \since BeOS R3
 349 */
 350
 351
 352 /*!
 353         \fn bool BVolume::IsShared(void) const
 354         \brief Returns whether or not the volume is shared.
 355
 356         return \c true, if the volume was properly initialized and is shared,
 357                \c false otherwise.
 358
 359         \since BeOS R3
 360 */
 361
 362
 363 /*!
 364         \fn bool BVolume::KnowsMime(void) const
 365         \brief Returns whether or not the volume supports MIME-types.
 366
 367         \return \c true, if the volume was properly initialized and supports
 368                 MIME-types, \c false otherwise.
 369
 370         \since BeOS R3
 371 */
 372
 373
 374 /*!
 375         \fn bool BVolume::KnowsAttr(void) const
 376         \brief Returns whether or not the volume supports attributes.
 377
 378         \return \c true, if the volume was properly initialized and supports
 379                 attributes, \c false otherwise.
 380
 381         \since BeOS R3
 382 */
 383
 384
 385 /*!
 386         \fn bool BVolume::KnowsQuery(void) const
 387         \brief Returns whether or not the volume supports queries.
 388
 389         \return \c true, if the volume was properly initialized and supports
 390                 queries, \c false otherwise.
 391
 392         \since BeOS R3
 393 */
 394
 395
 396 //! @}
 397
 398
 399 /*!
 400         \name Operators
 401 */
 402
 403
 404 //! @{
 405
 406
 407 /*!
 408         \fn bool BVolume::operator==(const BVolume &volume) const
 409         \brief Returns whether or not the supplied BVolume object is equal to this
 410                object.
 411
 412         Two volume objects are said to be equal if they are both uninitialized,
 413         or they are both initialized and refer to the same volume.
 414
 415         \param volume The volume to be tested for equality.
 416
 417         \return \c true, if the objects are equal, \c false otherwise.
 418
 419         \since BeOS R3
 420 */
 421
 422
 423 /*!
 424         \fn bool BVolume::operator!=(const BVolume &volume) const
 425         \brief Returns whether or not the supplied BVolume object is NOT equal to
 426                this object.
 427
 428         Two volume objects are said to be unequal if one is initialized and the
 429         other is not or if they are both initialized and refer to the different
 430         volumes.
 431
 432         \param volume The volume to be tested for inequality.
 433
 434         \return \c true, if the objects and unequal, \c false otherwise.
 435
 436         \since BeOS R3
 437 */
 438
 439
 440 /*!
 441         \fn BVolume& BVolume::operator=(const BVolume &volume)
 442         \brief Assigns the supplied BVolume object to this volume, this object is
 443                made to be an exact clone of the supplied one.
 444
 445         \param volume The volume to be assigned.
 446
 447         \return A reference to this object.
 448
 449         \since BeOS R3
 450 */
 451
 452
 453 //! @}