hrev45315 adds 3 changesets to branch 'master' old head: 7f562d441c47fcfc89221b612ed5493f196bfcea new head: bcd9244e4a74bea401bf234eb2e715e324931dbc overview: http://cgit.haiku-os.org/haiku/log/?qt=range&q=bcd9244+%5E7f562d4 ---------------------------------------------------------------------------- 7635a30: SymLink.h not Symlink.h 9d5f531: Move BVolume docs to the Haiku book bcd9244: Fix BCountry::GetName() method that was showing in BVolume::GetName() [ John Scipione <jscipione@xxxxxxxxx> ] ---------------------------------------------------------------------------- 5 files changed, 457 insertions(+), 207 deletions(-) docs/user/locale/Country.dox | 13 +- docs/user/storage/SymLink.dox | 6 +- docs/user/storage/Volume.dox | 394 ++++++++++++++++++++++++++++++++++++++ headers/os/storage/Volume.h | 5 + src/kits/storage/Volume.cpp | 246 +++++------------------- ############################################################################ Commit: 7635a303a293bc569cd6542a5fcc1266cb6aa472 URL: http://cgit.haiku-os.org/haiku/commit/?id=7635a30 Author: John Scipione <jscipione@xxxxxxxxx> Date: Fri Feb 22 01:14:58 2013 UTC SymLink.h not Symlink.h ---------------------------------------------------------------------------- diff --git a/docs/user/storage/SymLink.dox b/docs/user/storage/SymLink.dox index ca2ff05..847ea47 100644 --- a/docs/user/storage/SymLink.dox +++ b/docs/user/storage/SymLink.dox @@ -8,13 +8,13 @@ * Ingo Weinhold, bonefish@xxxxxxxxxxxx * * Corresponds to: - * headers/os/storage/Symlink.h hrev45306 - * src/kits/storage/Symlink.cpp hrev45306 + * headers/os/storage/SymLink.h hrev45306 + * src/kits/storage/SymLink.cpp hrev45306 */ /*! - \file Symlink.h + \file SymLink.h \ingroup storage \ingroup libbe \brief Provides the BSymLink class. ############################################################################ Commit: 9d5f5318a5648a58945bd6eb221493ddf39e70e5 URL: http://cgit.haiku-os.org/haiku/commit/?id=9d5f531 Author: John Scipione <jscipione@xxxxxxxxx> Date: Fri Feb 22 01:15:53 2013 UTC Move BVolume docs to the Haiku book ---------------------------------------------------------------------------- diff --git a/docs/user/storage/Volume.dox b/docs/user/storage/Volume.dox new file mode 100644 index 0000000..f2a483c --- /dev/null +++ b/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, jscipione@xxxxxxxxx + * Ingo Weinhold, bonefish@xxxxxxxxxxxx + * + * 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. +*/ + + +//! @} diff --git a/headers/os/storage/Volume.h b/headers/os/storage/Volume.h index 01cb793..1d53f7b 100644 --- a/headers/os/storage/Volume.h +++ b/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 diff --git a/src/kits/storage/Volume.cpp b/src/kits/storage/Volume.cpp index 2c05719..48cd4e3 100644 --- a/src/kits/storage/Volume.cpp +++ b/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> -/*! - \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:bonefish@xxxxxxxxxxxx'>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. -*/ +// Creates an uninitialized BVolume object. 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 - successful. - - \param device The device ID of the volume. -*/ +// Creates a BVolume and initializes it to the volume specified by the +// supplied device ID. 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 - does. If the latter is not properly initialized, this object isn't - either. - \param volume The volume object to be cloned. -*/ +// Creates a copy of the supplied BVolume object. 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. - \return - - \c B_OK: The object is properly initialized. - - an error code otherwise -*/ + +// Returns the initialization status. status_t BVolume::InitCheck(void) const { return fCStatus; } -// SetTo -/*! \brief Re-initializes the object to refer to the volume specified by - the supplied device ID. - \param device The device ID of the volume. - \param - - \c B_OK: Everything went fine. - - an error code otherwise -*/ + +// Initializes the object to refer to the volume specified by the supplied +// device ID. 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. - \return Returns the device ID of the volume the object refers to - or -1, if the object is not properly initialized. -*/ + +// Returns the device ID of the volume the object refers to. dev_t BVolume::Device() const { return fDevice; } -// GetRootDirectory -/*! \brief Returns the root directory of the volume referred to by the object. - \param directory A pointer to a pre-allocated BDirectory to be initialized - 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 -*/ + +// Writes the root directory of the volume referred to by this object into +// directory. 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. - \return - - The volume's total storage capacity (in bytes), when the object is - properly initialized. - - \c B_BAD_VALUE otherwise. -*/ + +// Returns the total storage capacity of the volume. 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 - 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. -*/ + +// Returns the amount of unused space on the volume (in bytes). 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 - 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. -*/ +// Returns the size of one block (in bytes). off_t BVolume::BlockSize() const { @@ -256,20 +171,7 @@ BVolume::BlockSize() const } -// GetName -/*! \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 -*/ +// Copies the name of the volume into the provided buffer. 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. - \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 -*/ + +// Sets the name of the volume. 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. - \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. -*/ + +// Writes the volume's icon into 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. - \return \c true, when the object is properly initialized and the - referred to volume is removable, \c false otherwise. -*/ +// Returns whether or not the volume is removable. 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. - \return \c true, when the object is properly initialized and the - referred to volume is read only, \c false otherwise. -*/ + +// Returns whether or not the volume is read-only. 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. - \return \c true, when the object is properly initialized and the - referred to volume is persistent, \c false otherwise. -*/ + +// Returns whether or not the volume is persistent. 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. - \return \c true, when the object is properly initialized and the - referred to volume is shared, \c false otherwise. -*/ + +// Returns whether or not the volume is shared. 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. - \return \c true, when the object is properly initialized and the - referred to volume supports MIME types, \c false otherwise. -*/ + +// Returns whether or not the volume supports MIME-types. 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. - \return \c true, when the object is properly initialized and the - referred to volume supports attributes, \c false otherwise. -*/ + +// Returns whether or not the volume supports attributes. 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. - \return \c true, when the object is properly initialized and the - referred to volume supports queries, \c false otherwise. -*/ + +// Returns whether or not the volume supports queries. 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 - 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 equal, \c false - otherwise. -*/ +// Returns whether or not the supplied BVolume object is a equal +// to this object. bool BVolume::operator==(const BVolume &volume) const { @@ -523,30 +383,16 @@ BVolume::operator==(const BVolume &volume) const || fDevice == volume.fDevice); } -// != -/*! \brief Returns whether two BVolume objects are unequal. - - 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. -*/ +// Returns whether or not the supplied BVolume object is NOT equal +// to this object. 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. - \param volume The volume from which shall be assigned. - \return A reference to this object. -*/ +// Assigns the supplied BVolume object to this volume. BVolume& BVolume::operator=(const BVolume &volume) { ############################################################################ Revision: hrev45315 Commit: bcd9244e4a74bea401bf234eb2e715e324931dbc URL: http://cgit.haiku-os.org/haiku/commit/?id=bcd9244 Author: John Scipione <jscipione@xxxxxxxxx> Date: Fri Feb 22 01:16:34 2013 UTC Fix BCountry::GetName() method that was showing in BVolume::GetName() ---------------------------------------------------------------------------- diff --git a/docs/user/locale/Country.dox b/docs/user/locale/Country.dox index 1e2438a..1b64b64 100644 --- a/docs/user/locale/Country.dox +++ b/docs/user/locale/Country.dox @@ -64,11 +64,16 @@ /*! - \fn bool BCountry::GetName(BString& name) const - \brief Get the name of the country. + \fn status_t BCountry::GetName(BString& name, + const BLanguage* displayLanguage = NULL) const + \brief Writes the country's name into the supplied BString. - Fills in the name parameter with the name of the country in the - language set by the user's locale. + \param name A reference to a BString to write the country name to. + \param displayLanguage The language to use when writing the name. Can be + \c NULL to use the language set by the user's locale. + + \returns A status code, B_OK if everything went fine, or an error code + otherwise. */