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