Move BVolume docs to the Haiku book

docs/user/storage/Volume.dox

@@ -0,0 +1,394 @@
+/*
+ * Copyright 2002-2013 Haiku Inc. All rights reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ *		Tyler Dauwalder
+ *		Vincent Dominguez
+ *		John Scipione, [email protected]
+ *		Ingo Weinhold, [email protected]
+ *
+ * Corresponds to:
+ *		headers/os/storage/Volume.h	hrev45306
+ *		src/kits/storage/Volume.cpp	hrev45306
+ */
+
+
+/*!
+	\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.
+*/
+
+
+/*!
+	\fn BVolume::BVolume()
+	\brief Creates an uninitialized BVolume object.
+
+	InitCheck() will return \c B_NO_INIT.
+
+	\see SetTo()
+*/
+
+
+/*!
+	\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.
+*/
+
+
+/*!
+	\fn BVolume::BVolume(const BVolume &volume)
+	\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.
+*/
+
+
+/*!
+	\fn BVolume::~BVolume()
+	\brief Destroys the object and frees all associated resources.
+*/
+
+
+/*!
+	\name Constructor helper methods
+*/
+
+
+//! @{
+
+
+/*!
+	\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.
+*/
+
+
+/*!
+	\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.
+	\return \c B_OK if the object was properly initialized, or an error code
+	        otherwise.
+*/
+
+
+/*!
+	\fn void BVolume::Unset()
+	\brief Brings the BVolume object to an uninitialized state.
+
+	InitCheck() will return \c B_NO_INIT.
+*/
+
+
+//! @}
+
+
+/*!
+	\name Volume information methods
+*/
+
+
+//! @{
+
+
+/*!
+	\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.
+*/
+
+
+/*!
+	\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.
+
+	\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.
+*/
+
+
+/*!
+	\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.
+*/
+
+
+/*!
+	\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.
+*/
+
+
+/*!
+	\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.
+*/
+
+
+//! @}
+
+
+/*!
+	\name Volume name methods
+*/
+
+
+//! @{
+
+
+/*!
+	\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.
+*/
+
+
+/*!
+	\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.
+*/
+
+
+//! @}
+
+
+/*!
+	\name Volume icon methods
+*/
+
+
+//! @{
+
+
+/*!
+	\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).
+
+	\param which The icon size to be retrieved: \c B_MINI_ICON for the mini or
+	       \c B_LARGE_ICON for the large icon.
+*/
+
+
+/*!
+	\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.
+*/
+
+
+//! @}
+
+
+/*!
+	\name Volume capability methods
+*/
+
+
+//! @{
+
+
+/*!
+	\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.
+*/
+
+
+/*!
+	\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.
+*/
+
+
+/*!
+	\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.
+*/
+
+
+/*!
+	\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.
+*/
+
+
+/*!
+	\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.
+*/
+
+
+/*!
+	\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.
+*/
+
+
+/*!
+	\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.
+*/
+
+
+//! @}
+
+
+/*!
+	\name Operator overload methods
+*/
+
+
+//! @{
+
+
+/*!
+	\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.
+*/
+
+
+/*!
+	\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.
+*/
+
+
+/*!
+	\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.
+*/
+
+
+//! @}

headers/os/storage/Volume.h

@@ -13,6 +13,7 @@
 #include <StorageDefs.h>
 #include <SupportDefs.h>
 
+
 class BDirectory;
 class BBitmap;
 
@@ -66,8 +67,12 @@ private:
 	virtual void			_TurnUpTheVolume8();
 
 			dev_t			fDevice;
+								// The device ID of the volume.
 			status_t		fCStatus;
+								// The initialization status of the object.
 			int32			_reserved[8];
+								// FBC
 };
 
+
 #endif	// _VOLUME_H

src/kits/storage/Volume.cpp

@@ -7,10 +7,6 @@
  *		Ingo Weinhold
  */
 
-/*!
-	\file Volume.h
-	BVolume implementation.
-*/
 
 #include <errno.h>
 #include <string.h>
@@ -28,50 +24,16 @@
 #include <fs_interface.h>
 
 
-/*!
+// Creates an uninitialized BVolume object.
-	\class BVolume
-	\brief Represents a disk volume
-
-	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 only exception is the method is SetName(), which
-	sets the name of the volume.
-
-	\author Vincent Dominguez
-	\author <a href='mailto:[email protected]'>Ingo Weinhold</a>
-
-	\version 0.0.0
-*/
-
-/*!	\var dev_t BVolume::fDevice
-	\brief The volume's device ID.
-*/
-
-/*!	\var dev_t BVolume::fCStatus
-	\brief The object's initialization status.
-*/
-
-// constructor
-/*!	\brief Creates an uninitialized BVolume.
-
-	InitCheck() will return \c B_NO_INIT.
-*/
 BVolume::BVolume()
 	: fDevice((dev_t)-1),
 	  fCStatus(B_NO_INIT)
 {
 }
 
-// constructor
-/*!	\brief Creates a BVolume and initializes it to the volume specified
-		   by the supplied device ID.
 
-	InitCheck() should be called to check whether the initialization was
+// Creates a BVolume and initializes it to the volume specified by the
-	successful.
+// supplied device ID.
-
-	\param device The device ID of the volume.
-*/
 BVolume::BVolume(dev_t device)
 	: fDevice((dev_t)-1),
 	  fCStatus(B_NO_INIT)
@@ -79,50 +41,31 @@ BVolume::BVolume(dev_t device)
 	SetTo(device);
 }
 
-// copy constructor
-/*!	\brief Creates a BVolume and makes it a clone of the supplied one.
 
-	Afterwards the object refers to the same device the supplied object
+// Creates a copy of the supplied BVolume object.
-	does. If the latter is not properly initialized, this object isn't
-	either.
-
-	\param volume The volume object to be cloned.
-*/
 BVolume::BVolume(const BVolume &volume)
 	: fDevice(volume.fDevice),
 	  fCStatus(volume.fCStatus)
 {
 }
 
-// destructor
-/*!	\brief Frees all resources associated with the object.
 
-	Does nothing.
+// Destroys the object and frees all associated resources.
-*/
 BVolume::~BVolume()
 {
 }
 
-// InitCheck
+
-/*!	\brief Returns the result of the last initialization.
+// Returns the initialization status.
-	\return
-	- \c B_OK: The object is properly initialized.
-	- an error code otherwise
-*/
 status_t
 BVolume::InitCheck(void) const
 {
 	return fCStatus;
 }
 
-// SetTo
+
-/*!	\brief Re-initializes the object to refer to the volume specified by
+// Initializes the object to refer to the volume specified by the supplied
-		   the supplied device ID.
+// device ID.
-	\param device The device ID of the volume.
-	\param
-	- \c B_OK: Everything went fine.
-	- an error code otherwise
-*/
 status_t
 BVolume::SetTo(dev_t device)
 {
@@ -143,9 +86,8 @@ BVolume::SetTo(dev_t device)
 	return fCStatus;
 }
 
-// Unset
+
-/*!	\brief Uninitialized the BVolume.
+// Brings the BVolume object to an uninitialized state.
-*/
 void
 BVolume::Unset()
 {
@@ -153,27 +95,17 @@ BVolume::Unset()
 	fCStatus = B_NO_INIT;
 }
 
-// Device
+
-/*!	\brief Returns the device ID of the volume the object refers to.
+// 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 is not properly initialized.
-*/
 dev_t
 BVolume::Device() const
 {
 	return fDevice;
 }
 
-// GetRootDirectory
+
-/*!	\brief Returns the root directory of the volume referred to by the object.
+// Writes the root directory of the volume referred to by this object into
-	\param directory A pointer to a pre-allocated BDirectory to be initialized
+// directory.
-		   to the volume's root directory.
-	\return
-	- \c B_OK: Everything went fine.
-	- \c B_BAD_VALUE: \c NULL \a directory or the object is not properly
-	  initialized.
-	- another error code
-*/
 status_t
 BVolume::GetRootDirectory(BDirectory *directory) const
 {
@@ -193,13 +125,8 @@ BVolume::GetRootDirectory(BDirectory *directory) const
 	return error;
 }
 
-// Capacity
+
-/*!	\brief Returns the volume's total storage capacity.
+// Returns the total storage capacity of the volume.
-	\return
-	- The volume's total storage capacity (in bytes), when the object is
-	  properly initialized.
-	- \c B_BAD_VALUE otherwise.
-*/
 off_t
 BVolume::Capacity() const
 {
@@ -212,14 +139,8 @@ BVolume::Capacity() const
 	return (error == B_OK ? info.total_blocks * info.block_size : error);
 }
 
-// FreeBytes
+
-/*!	\brief Returns the amount of storage that's currently unused on the
+// Returns the amount of unused space on the volume (in bytes).
-		   volume (in bytes).
-	\return
-	- The amount of storage that's currently unused on the volume (in bytes),
-	  when the object is properly initialized.
-	- \c B_BAD_VALUE otherwise.
-*/
 off_t
 BVolume::FreeBytes() const
 {
@@ -233,13 +154,7 @@ BVolume::FreeBytes() const
 }
 
 
-/*!	\brief Returns the size of one block (in bytes). It depends on the
+// Returns the size of one block (in bytes).
-		underlying file system what this means exactly.
-	\return
-	- The block size in bytes.
-	- \c B_NO_INIT if the volume is not initialized.
-	- Other errors forwarded from the file system.
-*/
 off_t
 BVolume::BlockSize() const
 {
@@ -256,20 +171,7 @@ BVolume::BlockSize() const
 }
 
 
-// GetName
+// Copies the name of the volume into the provided buffer.
-/*!	\brief Returns the name of the volume.
-
-	The name of the volume is copied 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 shall be written.
-	\return
-	- \c B_OK: Everything went fine.
-	- \c B_BAD_VALUE: \c NULL \a name or the object is not properly
-	  initialized.
-	- another error code
-*/
 status_t
 BVolume::GetName(char *name) const
 {
@@ -285,16 +187,8 @@ BVolume::GetName(char *name) const
 	return error;
 }
 
-// SetName
+
-/*!	\brief Sets the name of the volume referred to by this object.
+// Sets the name of the volume.
-	\param name The volume's new name. Must not be longer than
-		   \c B_FILE_NAME_LENGTH (including the terminating null).
-	\return
-	- \c B_OK: Everything went fine.
-	- \c B_BAD_VALUE: \c NULL \a name or the object is not properly
-	  initialized.
-	- another error code
-*/
 status_t
 BVolume::SetName(const char *name)
 {
@@ -319,7 +213,7 @@ BVolume::SetName(const char *name)
 
 	// change the name of the mount point
 
-	// R5 implementation checks, if an entry with the volume's old name
+	// 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
@@ -346,14 +240,8 @@ BVolume::SetName(const char *name)
 	return error;
 }
 
-// GetIcon
+
-/*!	\brief Returns the icon of the volume.
+// Writes the volume's icon into icon.
-	\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).
-	\param which Specifies the size of the icon to be retrieved:
-		   \c B_MINI_ICON for the mini and \c B_LARGE_ICON for the large icon.
-*/
 status_t
 BVolume::GetIcon(BBitmap *icon, icon_size which) const
 {
@@ -388,10 +276,7 @@ BVolume::GetIcon(uint8** _data, size_t* _size, type_code* _type) const
 }
 
 
-/*!	\brief Returns whether the volume is removable.
+// Returns whether or not the volume is removable.
-	\return \c true, when the object is properly initialized and the
-	referred to volume is removable, \c false otherwise.
-*/
 bool
 BVolume::IsRemovable() const
 {
@@ -404,11 +289,8 @@ BVolume::IsRemovable() const
 	return (error == B_OK && (info.flags & B_FS_IS_REMOVABLE));
 }
 
-// IsReadOnly
+
-/*!	\brief Returns whether the volume is read only.
+// Returns whether or not the volume is read-only.
-	\return \c true, when the object is properly initialized and the
-	referred to volume is read only, \c false otherwise.
-*/
 bool
 BVolume::IsReadOnly(void) const
 {
@@ -421,11 +303,8 @@ BVolume::IsReadOnly(void) const
 	return (error == B_OK && (info.flags & B_FS_IS_READONLY));
 }
 
-// IsPersistent
+
-/*!	\brief Returns whether the volume is persistent.
+// Returns whether or not the volume is persistent.
-	\return \c true, when the object is properly initialized and the
-	referred to volume is persistent, \c false otherwise.
-*/
 bool
 BVolume::IsPersistent(void) const
 {
@@ -438,11 +317,8 @@ BVolume::IsPersistent(void) const
 	return (error == B_OK && (info.flags & B_FS_IS_PERSISTENT));
 }
 
-// IsShared
+
-/*!	\brief Returns whether the volume is shared.
+// Returns whether or not the volume is shared.
-	\return \c true, when the object is properly initialized and the
-	referred to volume is shared, \c false otherwise.
-*/
 bool
 BVolume::IsShared(void) const
 {
@@ -455,11 +331,8 @@ BVolume::IsShared(void) const
 	return (error == B_OK && (info.flags & B_FS_IS_SHARED));
 }
 
-// KnowsMime
+
-/*!	\brief Returns whether the volume supports MIME types.
+// Returns whether or not the volume supports MIME-types.
-	\return \c true, when the object is properly initialized and the
-	referred to volume supports MIME types, \c false otherwise.
-*/
 bool
 BVolume::KnowsMime(void) const
 {
@@ -472,11 +345,8 @@ BVolume::KnowsMime(void) const
 	return (error == B_OK && (info.flags & B_FS_HAS_MIME));
 }
 
-// KnowsAttr
+
-/*!	\brief Returns whether the volume supports attributes.
+// Returns whether or not the volume supports attributes.
-	\return \c true, when the object is properly initialized and the
-	referred to volume supports attributes, \c false otherwise.
-*/
 bool
 BVolume::KnowsAttr(void) const
 {
@@ -489,11 +359,8 @@ BVolume::KnowsAttr(void) const
 	return (error == B_OK && (info.flags & B_FS_HAS_ATTR));
 }
 
-// KnowsQuery
+
-/*!	\brief Returns whether the volume supports queries.
+// Returns whether or not the volume supports queries.
-	\return \c true, when the object is properly initialized and the
-	referred to volume supports queries, \c false otherwise.
-*/
 bool
 BVolume::KnowsQuery(void) const
 {
@@ -506,16 +373,9 @@ BVolume::KnowsQuery(void) const
 	return (error == B_OK && (info.flags & B_FS_HAS_QUERY));
 }
 
-// ==
-/*!	\brief Returns whether two BVolume objects are equal.
 
-	Two volume objects are said to be equal, if they either are both
+// Returns whether or not the supplied BVolume object is a equal
-	uninitialized, or both are initialized and refer to the same volume.
+// to this object.
-
-	\param volume The object to be compared with.
-	\result \c true, if this object and the supplied one are equal, \c false
-			otherwise.
-*/
 bool
 BVolume::operator==(const BVolume &volume) const
 {
@@ -523,30 +383,16 @@ BVolume::operator==(const BVolume &volume) const
 			|| fDevice == volume.fDevice);
 }
 
-// !=
+// Returns whether or not the supplied BVolume object is NOT equal
-/*!	\brief Returns whether two BVolume objects are unequal.
+// to this object.
-
-	Two volume objects are said to be equal, if they either are both
-	uninitialized, or both are initialized and refer to the same volume.
-
-	\param volume The object to be compared with.
-	\result \c true, if this object and the supplied one are unequal, \c false
-			otherwise.
-*/
 bool
 BVolume::operator!=(const BVolume &volume) const
 {
 	return !(*this == volume);
 }
 
-// =
-/*!	\brief Assigns another BVolume object to this one.
 
-	This object is made an exact clone of the supplied one.
+// Assigns the supplied BVolume object to this volume.
-
-	\param volume The volume from which shall be assigned.
-	\return A reference to this object.
-*/
 BVolume&
 BVolume::operator=(const BVolume &volume)
 {