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//! @} 454