haiku/docs/user/storage/Volume.dox

454 lines
9.3 KiB
Plaintext
Raw Normal View History

2013-02-22 05:15:53 +04:00
/*
* Copyright 2002-2014 Haiku, Inc. All rights reserved.
2013-02-22 05:15:53 +04:00
* Distributed under the terms of the MIT License.
*
* Authors:
* Tyler Dauwalder
* Vincent Dominguez
* John Scipione, jscipione@gmail.com
* Ingo Weinhold, bonefish@users.sf.net
*
* Corresponds to:
* headers/os/storage/Volume.h hrev47402
* src/kits/storage/Volume.cpp hrev47402
2013-02-22 05:15:53 +04:00
*/
/*!
\file Volume.h
\ingroup storage
\ingroup libbe
\brief Provides the BVolume class.
*/
/*!
\class BVolume
\ingroup storage
\ingroup libbe
\brief Provides an interface for querying information about a volume.
The class is a simple wrapper for a \c dev_t and the function
fs_stat_dev(). The sole exception is the SetName() method which
sets the name of the volume.
\since BeOS R3
2013-02-22 05:15:53 +04:00
*/
/*!
\fn BVolume::BVolume()
\brief Creates an uninitialized BVolume object.
InitCheck() will return \c B_NO_INIT.
\see SetTo()
\since BeOS R3
2013-02-22 05:15:53 +04:00
*/
/*!
\fn BVolume::BVolume(dev_t device)
\brief Creates a BVolume and initializes it to the volume specified
by the supplied device ID.
InitCheck() should be called afterwards to check if initialization was
successful.
\param device The device ID of the volume.
\since BeOS R3
2013-02-22 05:15:53 +04:00
*/
/*!
\fn BVolume::BVolume(const BVolume& volume)
2013-02-22 05:15:53 +04:00
\brief Creates a copy of the supplied BVolume object.
Afterwards the object refers to the same device the supplied object
does. If the latter is not properly initialized, this result isn't
either.
\param volume The volume object to be copied.
\since BeOS R3
2013-02-22 05:15:53 +04:00
*/
/*!
\fn BVolume::~BVolume()
\brief Destroys the object and frees all associated resources.
\since BeOS R3
2013-02-22 05:15:53 +04:00
*/
/*!
\name Constructor Helpers
2013-02-22 05:15:53 +04:00
*/
//! @{
/*!
\fn status_t BVolume::InitCheck(void) const
\brief Returns the initialization status.
\return \c B_OK if the object was properly initialized, or an error code
otherwise.
\since BeOS R3
2013-02-22 05:15:53 +04:00
*/
/*!
\fn status_t BVolume::SetTo(dev_t device)
\brief Initializes the object to refer to the volume specified by
the supplied device ID.
\param device The device ID of the volume to set.
2013-02-22 05:15:53 +04:00
\return \c B_OK if the object was properly initialized, or an error code
otherwise.
\since BeOS R3
2013-02-22 05:15:53 +04:00
*/
/*!
\fn void BVolume::Unset()
\brief Brings the BVolume object to an uninitialized state.
InitCheck() will return \c B_NO_INIT.
\since BeOS R3
2013-02-22 05:15:53 +04:00
*/
//! @}
/*!
\name Volume Information
2013-02-22 05:15:53 +04:00
*/
//! @{
/*!
\fn dev_t BVolume::Device() const
\brief Returns the device ID of the volume the object refers to.
\return Returns the device ID of the volume the object refers to
or -1 if the object was not properly initialized.
\since BeOS R3
2013-02-22 05:15:53 +04:00
*/
/*!
\fn status_t BVolume::GetRootDirectory(BDirectory *directory) const
\brief Writes the root directory of the volume referred to by this
object into \a directory.
\param directory A pointer to a pre-allocated BDirectory to be initialized
to the volume's root directory.
2013-02-22 05:15:53 +04:00
\return A status code.
\retval B_OK Everything went fine.
\retval B_BAD_VALUE \a directory was \c NULL or the object was not properly
initialized.
\since BeOS R3
2013-02-22 05:15:53 +04:00
*/
/*!
\fn off_t BVolume::Capacity() const
\brief Returns the total storage capacity of the volume.
\return The volume's total storage capacity (in bytes), or \c B_BAD_VALUE
if the object is not properly initialized.
\see FreeBytes()
\since BeOS R3
2013-02-22 05:15:53 +04:00
*/
/*!
\fn off_t BVolume::FreeBytes() const
\brief Returns the amount of unused space on the volume (in bytes).
\return The amount of unused space on the volume (in bytes), or
\c B_BAD_VALUE if the object is not properly initialized.
\since BeOS R3
2013-02-22 05:15:53 +04:00
*/
/*!
\fn off_t BVolume::BlockSize() const
\brief Returns the size of one block (in bytes). The meaning of this
depends on the underlying file system.
\return The block size in bytes, \c B_NO_INIT if the volume is not
initialized or other errors forwarded from the file system.
\since Haiku R1
2013-02-22 05:15:53 +04:00
*/
//! @}
/*!
\name Volume Name
2013-02-22 05:15:53 +04:00
*/
//! @{
/*!
\fn status_t BVolume::GetName(char* name) const
\brief Writes the volume's name into the provided buffer.
\param name A pointer to a pre-allocated character buffer of size
\c B_FILE_NAME_LENGTH or larger into which the name of the
volume is written.
\return A status code.
\retval B_OK Everything went fine.
\retval B_BAD_VALUE \a name was \c NULL or the object was not properly
initialized.
\see SetName()
\since BeOS R3
2013-02-22 05:15:53 +04:00
*/
/*!
\fn status_t BVolume::SetName(const char *name)
\brief Sets the volume's name to \a name.
\note The R5 implementation checks if an entry with the volume's old name
exists in the root directory and renames that entry, if it is indeed
the mount point of the volume (or a link referring to it). In all
other cases, nothing is done (even if the mount point is named like
the volume, but lives in a different directory). We follow suit for
the time being.
\warning If the volume name is set to "boot" this method tries to rename
it to /boot, but is prevented by the kernel.
\param name The new name of the volume, must not be longer than
\c B_FILE_NAME_LENGTH (including the terminating \c NULL).
\return A status code.
\retval B_OK Everything went fine.
\retval B_BAD_VALUE \a name was \c NULL or the object was not properly
initialized.
\since Haiku R1
2013-02-22 05:15:53 +04:00
*/
//! @}
/*!
\name Volume Icon
2013-02-22 05:15:53 +04:00
*/
//! @{
/*!
\fn status_t BVolume::GetIcon(BBitmap *icon, icon_size which) const
\brief Writes the volume's icon into the supplied BBitmap.
\param icon A pointer to a pre-allocated BBitmap of the correct dimension
to store the requested icon (16x16 for the mini and 32x32 for the
large icon).
2013-02-22 05:15:53 +04:00
\param which The icon size to be retrieved: \c B_MINI_ICON for the mini or
\c B_LARGE_ICON for the large icon.
\since BeOS R4
2013-02-22 05:15:53 +04:00
*/
/*!
\fn status_t BVolume::GetIcon(uint8** _data, size_t* _size,
type_code* _type) const
\brief Writes the volume's icon data into the supplied \c uint8 array.
\param _data A pointer to a pointer to a pre-allocated \c uint8 array of
the correct size to store the requested icon.
\param _size The size of the retrieved icon (in bytes).
\param _type The type code of the retrieve icon.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT Object was not properly initialized.
\see fs_stat_dev() for more return codes.
\see get_device_icon() for more return codes.
\since Haiku R1
2013-02-22 05:15:53 +04:00
*/
//! @}
/*!
\name Volume Capabilities
2013-02-22 05:15:53 +04:00
*/
//! @{
/*!
\fn bool BVolume::IsRemovable() const
\brief Returns whether or not the volume is removable.
\return \c true, if the volume was properly initialized and is removable,
\c false otherwise.
\since BeOS R3
2013-02-22 05:15:53 +04:00
*/
/*!
\fn bool BVolume::IsReadOnly(void) const
\brief Returns whether or not the volume is read-only.
\return \c true, if the volume was properly initialized and is read-only,
\c false otherwise.
\since BeOS R3
2013-02-22 05:15:53 +04:00
*/
/*!
\fn bool BVolume::IsPersistent(void) const
\brief Returns whether or not the volume is persistent.
\return \c true, if the volume was properly initialized and is persistent,
\c false otherwise.
\since BeOS R3
2013-02-22 05:15:53 +04:00
*/
/*!
\fn bool BVolume::IsShared(void) const
\brief Returns whether or not the volume is shared.
return \c true, if the volume was properly initialized and is shared,
\c false otherwise.
\since BeOS R3
2013-02-22 05:15:53 +04:00
*/
/*!
\fn bool BVolume::KnowsMime(void) const
\brief Returns whether or not the volume supports MIME-types.
\return \c true, if the volume was properly initialized and supports
MIME-types, \c false otherwise.
\since BeOS R3
2013-02-22 05:15:53 +04:00
*/
/*!
\fn bool BVolume::KnowsAttr(void) const
\brief Returns whether or not the volume supports attributes.
\return \c true, if the volume was properly initialized and supports
attributes, \c false otherwise.
\since BeOS R3
2013-02-22 05:15:53 +04:00
*/
/*!
\fn bool BVolume::KnowsQuery(void) const
\brief Returns whether or not the volume supports queries.
\return \c true, if the volume was properly initialized and supports
queries, \c false otherwise.
\since BeOS R3
2013-02-22 05:15:53 +04:00
*/
//! @}
/*!
\name Operators
2013-02-22 05:15:53 +04:00
*/
//! @{
/*!
\fn bool BVolume::operator==(const BVolume &volume) const
\brief Returns whether or not the supplied BVolume object is equal to this
object.
Two volume objects are said to be equal if they are both uninitialized,
or they are both initialized and refer to the same volume.
\param volume The volume to be tested for equality.
\return \c true, if the objects are equal, \c false otherwise.
\since BeOS R3
2013-02-22 05:15:53 +04:00
*/
/*!
\fn bool BVolume::operator!=(const BVolume &volume) const
\brief Returns whether or not the supplied BVolume object is NOT equal to
this object.
Two volume objects are said to be unequal if one is initialized and the
other is not or if they are both initialized and refer to the different
volumes.
\param volume The volume to be tested for inequality.
\return \c true, if the objects and unequal, \c false otherwise.
\since BeOS R3
2013-02-22 05:15:53 +04:00
*/
/*!
\fn BVolume& BVolume::operator=(const BVolume &volume)
\brief Assigns the supplied BVolume object to this volume, this object is
made to be an exact clone of the supplied one.
\param volume The volume to be assigned.
\return A reference to this object.
\since BeOS R3
2013-02-22 05:15:53 +04:00
*/
//! @}