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 \retval B_NAME_TOO_LONG \a name was >= \c B_FILE_NAME_LENGTH. 257 258 \since BeOS R4 259*/ 260 261 262//! @} 263 264 265/*! 266 \name Volume Icon 267*/ 268 269 270//! @{ 271 272 273/*! 274 \fn status_t BVolume::GetIcon(BBitmap *icon, icon_size which) const 275 \brief Writes the volume's icon into the supplied BBitmap. 276 277 \param icon A pointer to a pre-allocated BBitmap of the correct dimension 278 to store the requested icon (16x16 for the mini and 32x32 for the 279 large icon). 280 281 \param which The icon size to be retrieved: \c B_MINI_ICON for the mini or 282 \c B_LARGE_ICON for the large icon. 283 284 \since BeOS R4 285*/ 286 287 288/*! 289 \fn status_t BVolume::GetIcon(uint8** _data, size_t* _size, 290 type_code* _type) const 291 \brief Writes the volume's icon data into the supplied \c uint8 array. 292 293 \param _data A pointer to a pointer to a pre-allocated \c uint8 array of 294 the correct size to store the requested icon. 295 \param _size The size of the retrieved icon (in bytes). 296 \param _type The type code of the retrieve icon. 297 298 \returns A status code. 299 \retval B_OK Everything went fine. 300 \retval B_NO_INIT Object was not properly initialized. 301 302 \see fs_stat_dev() for more return codes. 303 \see get_device_icon() for more return codes. 304 305 \since Haiku R1 306*/ 307 308 309//! @} 310 311 312/*! 313 \name Volume Capabilities 314*/ 315 316 317//! @{ 318 319 320/*! 321 \fn bool BVolume::IsRemovable() const 322 \brief Returns whether or not the volume is removable. 323 324 \return \c true, if the volume was properly initialized and is removable, 325 \c false otherwise. 326 327 \since BeOS R3 328*/ 329 330 331/*! 332 \fn bool BVolume::IsReadOnly(void) const 333 \brief Returns whether or not the volume is read-only. 334 335 \return \c true, if the volume was properly initialized and is read-only, 336 \c false otherwise. 337 338 \since BeOS R3 339*/ 340 341 342/*! 343 \fn bool BVolume::IsPersistent(void) const 344 \brief Returns whether or not the volume is persistent. 345 346 \return \c true, if the volume was properly initialized and is persistent, 347 \c false otherwise. 348 349 \since BeOS R3 350*/ 351 352 353/*! 354 \fn bool BVolume::IsShared(void) const 355 \brief Returns whether or not the volume is shared. 356 357 return \c true, if the volume was properly initialized and is shared, 358 \c false otherwise. 359 360 \since BeOS R3 361*/ 362 363 364/*! 365 \fn bool BVolume::KnowsMime(void) const 366 \brief Returns whether or not the volume supports MIME-types. 367 368 \return \c true, if the volume was properly initialized and supports 369 MIME-types, \c false otherwise. 370 371 \since BeOS R3 372*/ 373 374 375/*! 376 \fn bool BVolume::KnowsAttr(void) const 377 \brief Returns whether or not the volume supports attributes. 378 379 \return \c true, if the volume was properly initialized and supports 380 attributes, \c false otherwise. 381 382 \since BeOS R3 383*/ 384 385 386/*! 387 \fn bool BVolume::KnowsQuery(void) const 388 \brief Returns whether or not the volume supports queries. 389 390 \return \c true, if the volume was properly initialized and supports 391 queries, \c false otherwise. 392 393 \since BeOS R3 394*/ 395 396 397//! @} 398 399 400/*! 401 \name Operators 402*/ 403 404 405//! @{ 406 407 408/*! 409 \fn bool BVolume::operator==(const BVolume &volume) const 410 \brief Returns whether or not the supplied BVolume object is equal to this 411 object. 412 413 Two volume objects are said to be equal if they are both uninitialized, 414 or they are both initialized and refer to the same volume. 415 416 \param volume The volume to be tested for equality. 417 418 \return \c true, if the objects are equal, \c false otherwise. 419 420 \since BeOS R3 421*/ 422 423 424/*! 425 \fn bool BVolume::operator!=(const BVolume &volume) const 426 \brief Returns whether or not the supplied BVolume object is NOT equal to 427 this object. 428 429 Two volume objects are said to be unequal if one is initialized and the 430 other is not or if they are both initialized and refer to the different 431 volumes. 432 433 \param volume The volume to be tested for inequality. 434 435 \return \c true, if the objects and unequal, \c false otherwise. 436 437 \since BeOS R3 438*/ 439 440 441/*! 442 \fn BVolume& BVolume::operator=(const BVolume &volume) 443 \brief Assigns the supplied BVolume object to this volume, this object is 444 made to be an exact clone of the supplied one. 445 446 \param volume The volume to be assigned. 447 448 \return A reference to this object. 449 450 \since BeOS R3 451*/ 452 453 454//! @} 455