diff --git a/docs/user/storage/VolumeRoster.dox b/docs/user/storage/VolumeRoster.dox new file mode 100644 index 0000000000..e29bfba5c4 --- /dev/null +++ b/docs/user/storage/VolumeRoster.dox @@ -0,0 +1,131 @@ +/* + * Copyright 2002-2013 Haiku Inc. All rights reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * Vincent Dominguez + * John Scipione, jscipione@gmail.com + * Ingo Weinhold, bonefish@users.sf.net + * + * Corresponds to: + * headers/os/storage/VolumeRoster.h hrev45306 + * src/kits/storage/VolumeRoster.cpp hrev45306 + */ + + +/*! + \file VolumeRoster.h + \ingroup storage + \ingroup libbe + \brief Provides the BVolumeRoster class. +*/ + + +/*! + \class BVolumeRoster + \ingroup storage + \ingroup libbe + \brief Provides an interface for iterating through available volumes + and watching for mounting/unmounting. + + This class wraps the next_dev() function for iterating through the + list of available volumes and watch_node()/stop_watching() for + watching volumes. +*/ + + +/*! + \fn BVolumeRoster::BVolumeRoster() + \brief Creates a BVolumeRoster object. The object is ready to be used. +*/ + + +/*! + \fn BVolumeRoster::~BVolumeRoster() + \brief Deletes the volume roster and frees all associated resources. + + If a watch was activated (by StartWatching()), it is deactivated. +*/ + + + +/*! + \fn status_t BVolumeRoster::GetNextVolume(BVolume *volume) + \brief Fills out the passed in BVolume object with the next available + volume. + + \param volume A pointer to a pre-allocated BVolume object to be + initialized to the next available volume. + + \return A status code. + \retval B_OK Everything went fine. + \retval B_BAD_VALUE The last volume in the list was already returned. +*/ + + +/*! + \fn void BVolumeRoster::Rewind() + \brief Rewinds the list of available volumes back to the first item. + + The next call to GetNextVolume() will return the first available volume. +*/ + + +/*! + \fn status_t BVolumeRoster::GetBootVolume(BVolume *volume) + \brief Fills out the passed in BVolume object with the boot volume. + + Currently, this method looks for the volume that is mounted at "/boot". + The only way to fool the system into thinking that there is not a boot + volume is to rename "/boot" -- but, please refrain from doing this. + + \param volume A pointer to a pre-allocated BVolume to be initialized to + refer to the boot volume. + + \return A status code, \c B_OK if everything went fine or an error code + otherwise. +*/ + + +/*! + \fn status_t BVolumeRoster::StartWatching(BMessenger messenger) + \brief Starts watching the available volumes for changes. + + Notifications are sent to the specified target whenever a volume is + mounted or unmounted. The format of the notification messages is + described under watch_node(). Actually BVolumeRoster just provides a + more convenient interface for it. + + If StartWatching() has been called before with another target and no + StopWatching() since, StopWatching() is called first, so that the former + target won't receive any notifications anymore. + + When the object is destroyed all watching ends as well. + + \param messenger The target which the notification messages are sent. + + \return A status code. + \retval B_OK Everything went fine. + \retval B_BAD_VALUE The supplied BMessenger was invalid. + \retval B_NO_MEMORY There was insufficient memory to carry out this + operation. + + \see watch_node() +*/ + + +/*! + \fn void BVolumeRoster::StopWatching() + \brief Stops watching volumes initiated by StartWatching(). + + \see stop_watching() +*/ + + +/*! + \fn BMessenger BVolumeRoster::Messenger() const + \brief Returns the messenger currently watching the volume list. + + \return A messenger to the target currently watching the volume list, or + an invalid messenger if not watching. +*/ diff --git a/headers/os/storage/VolumeRoster.h b/headers/os/storage/VolumeRoster.h index 235c06bc78..2f245144f8 100644 --- a/headers/os/storage/VolumeRoster.h +++ b/headers/os/storage/VolumeRoster.h @@ -36,8 +36,16 @@ private: private: int32 fCookie; + // The iteration cookie for next_dev() + // Initialized to 0 BMessenger* fTarget; + // BMessenger referring to the target to + // which the watching notification + // messages are sent. The object is + // allocated and owned by the roster, + // or NULL if not watching. uint32 _reserved[3]; + // FBC }; diff --git a/src/kits/storage/VolumeRoster.cpp b/src/kits/storage/VolumeRoster.cpp index a04bdcd952..3149ab523f 100644 --- a/src/kits/storage/VolumeRoster.cpp +++ b/src/kits/storage/VolumeRoster.cpp @@ -6,10 +6,7 @@ // // Description: BVolumeRoster class // ---------------------------------------------------------------------- -/*! - \file VolumeRoster.cpp - BVolumeRoster implementation. -*/ + #include #include @@ -21,71 +18,32 @@ #include #include + static const char kBootVolumePath[] = "/boot"; using namespace std; + #ifdef USE_OPENBEOS_NAMESPACE namespace OpenBeOS { #endif -/*! - \class BVolumeRoster - \brief A roster of all volumes available in the system - - Provides an interface for iterating through the volumes available in - the system and watching volume mounting/unmounting. - The class wraps the next_dev() function for iterating through the - volume list and the watch_node()/stop_watching() for the watching - features. - - \author Vincent Dominguez - \author Ingo Weinhold - - \version 0.0.0 -*/ - -/*! \var dev_t BVolumeRoster::fCookie - \brief The iteration cookie for next_dev(). Initialized with 0. -*/ - -/*! \var dev_t BVolumeRoster::fTarget - \brief BMessenger referring to the target to which the watching - notification messages are sent. - - The object is allocated and owned by the roster. \c NULL, if not watching. -*/ - -// constructor -/*! \brief Creates a new BVolumeRoster. - - The object is ready to be used. -*/ BVolumeRoster::BVolumeRoster() : fCookie(0), fTarget(NULL) { } -// destructor -/*! \brief Frees all resources associated with this object. - If a watching was activated on (StartWatching()), it is deactived. -*/ +// Deletes the volume roster and frees all associated resources. BVolumeRoster::~BVolumeRoster() { StopWatching(); } -// GetNextVolume -/*! \brief Returns the next volume in the list of available volumes. - \param volume A pointer to a pre-allocated BVolume to be initialized to - refer to the next volume in the list of available volumes. - \return - - \c B_OK: Everything went fine. - - \c B_BAD_VALUE: The last volume in the list has already been returned. -*/ + +// Fills out the passed in BVolume object with the next available volume. status_t BVolumeRoster::GetNextVolume(BVolume *volume) { @@ -104,29 +62,16 @@ BVolumeRoster::GetNextVolume(BVolume *volume) return error; } -// Rewind -/*! \brief Rewinds the list of available volumes such that the next call to - GetNextVolume() will return the first element in the list. -*/ + +// Rewinds the list of available volumes back to the first item. void BVolumeRoster::Rewind() { fCookie = 0; } -// GetBootVolume -/*! \brief Returns the boot volume. - Currently, this function looks for the volume that is mounted at "/boot". - The only way to fool the system into thinking that there is not a boot - volume is to rename "/boot" -- but, please refrain from doing so...(:o( - - \param volume A pointer to a pre-allocated BVolume to be initialized to - refer to the boot volume. - \return - - \c B_OK: Everything went fine. - - an error code otherwise -*/ +// Fills out the passed in BVolume object with the boot volume. status_t BVolumeRoster::GetBootVolume(BVolume *volume) { @@ -145,27 +90,8 @@ BVolumeRoster::GetBootVolume(BVolume *volume) return error; } -// StartWatching -/*! \brief Starts watching the list of volumes available in the system. - Notifications are sent to the specified target whenever a volume is - mounted or unmounted. The format of the notification messages is - described under watch_node(). Actually BVolumeRoster just provides a - more convenient interface for it. - - If StartWatching() has been called before with another target and no - StopWatching() since, StopWatching() is called first, so that the former - target won't receive any notifications anymore. - - When the object is destroyed all watching has an end as well. - - \param messenger The target to which the notification messages shall be - sent. - \return - - \c B_OK: Everything went fine. - - \c B_BAD_VALUE: The supplied BMessenger is invalid. - - \c B_NO_MEMORY: Insufficient memory to carry out this operation. -*/ +// Starts watching the available volumes for changes. status_t BVolumeRoster::StartWatching(BMessenger messenger) { @@ -188,9 +114,8 @@ BVolumeRoster::StartWatching(BMessenger messenger) return error; } -// StopWatching -/*! \brief Stops volume watching initiated with StartWatching() before. -*/ + +// Stops watching volumes initiated by StartWatching(). void BVolumeRoster::StopWatching() { @@ -201,22 +126,20 @@ BVolumeRoster::StopWatching() } } -// Messenger -/*! \brief Returns a messenger to the target currently watching the volume - list. - \return A messenger to the target currently watching the volume list, or - an invalid messenger, if noone is currently watching. -*/ + +// Returns the messenger currently watching the volume list. BMessenger BVolumeRoster::Messenger() const { return (fTarget ? *fTarget : BMessenger()); } + // FBC void BVolumeRoster::_SeveredVRoster1() {} void BVolumeRoster::_SeveredVRoster2() {} + #ifdef USE_OPENBEOS_NAMESPACE } #endif