From 7c2e411db98056d1c6b965a792ab574040974c23 Mon Sep 17 00:00:00 2001 From: Ingo Weinhold Date: Sat, 1 Feb 2003 18:13:13 +0000 Subject: [PATCH] Small changes to the interface. Some fixes. And documentation added. git-svn-id: file:///srv/svn/repos/haiku/trunk/current@2616 a95241bf-73f2-0310-859d-f6bbb57e9c96 --- src/kits/storage/DiskDevice.cpp | 167 ++++++++++++++- src/kits/storage/DiskDeviceRoster.cpp | 179 ++++++++++++++++ src/kits/storage/DiskDeviceVisitor.cpp | 51 +++++ src/kits/storage/Partition.cpp | 283 +++++++++++++++++++++++-- src/kits/storage/Session.cpp | 196 +++++++++++++++-- 5 files changed, 839 insertions(+), 37 deletions(-) diff --git a/src/kits/storage/DiskDevice.cpp b/src/kits/storage/DiskDevice.cpp index 2148d5accb..1ca4a12d04 100644 --- a/src/kits/storage/DiskDevice.cpp +++ b/src/kits/storage/DiskDevice.cpp @@ -5,17 +5,48 @@ #include +/*! \class BDiskDevice + \brief A BDiskDevice object represents a storage device. +*/ + // constructor +/*! \brief Creates an uninitialized BDiskDevice object. +*/ BDiskDevice::BDiskDevice() { } // destructor +/*! \brief Frees all resources associated with this object. +*/ BDiskDevice::~BDiskDevice() { } +// Size +/*! \brief Returns the size of the device. + \return The size of the device in bytes. +*/ +off_t +BDiskDevice::Size() const +{ + return 0; // not implemented +} + +// BlockSize +/*! \brief Returns the block size of the device. + \return The block size of the device in bytes. +*/ +int32 +BDiskDevice::BlockSize() const +{ + return 0; // not implemented +} + // CountSessions +/*! \brief Returns the number of sessions on this device. + \return The number of sessions on this device. +*/ int32 BDiskDevice::CountSessions() const { @@ -23,6 +54,11 @@ BDiskDevice::CountSessions() const } // SessionAt +/*! \brief Returns a contained session by index. + \param index The index of the session to be returned. + \return The session with the requested index, or \c NULL, if \a index + is out of range. +*/ BSession * BDiskDevice::SessionAt(int32 index) const { @@ -30,20 +66,19 @@ BDiskDevice::SessionAt(int32 index) const } // CountPartitions +/*! \brief Returns the number of partitions on this device. + \return The number of partitions on this device. +*/ int32 BDiskDevice::CountPartitions() const { return 0; // not implemented } -// BlockSize -int32 -BDiskDevice::BlockSize() const -{ - return 0; // not implemented -} - // DevicePath +/*! \brief Returns the path to the device. + \return The path to the device. +*/ const char * BDiskDevice::DevicePath() const { @@ -51,18 +86,47 @@ BDiskDevice::DevicePath() const } // GetName +/*! \brief Returns a human readable name for the device. + + The method tries to interpret the device path, which it can do only for + floppy, IDE and SCSI devices, for others the device path is returned. + + \param name Pointer to a pre-allocated BString to be set to the device + name. + \param includeBusID \c true, if the bus ID shall be included in the name + to be returned. + \param includeLUN \c true, if the LUN shall be included in the name + to be returned. + \return A human readable name for the device. +*/ void BDiskDevice::GetName(BString *name, bool includeBusID, bool includeLUN) const { } // GetName +/*! \brief Returns a human readable name for the device. + + The method tries to interpret the device path, which it can do only for + floppy, IDE and SCSI devices, for others the device path is returned. + + \param name Pointer to a pre-allocated char buffer into which the device + name shall be copied. + \param includeBusID \c true, if the bus ID shall be included in the name + to be returned. + \param includeLUN \c true, if the LUN shall be included in the name + to be returned. + \return A human readable name for the device. +*/ void BDiskDevice::GetName(char *name, bool includeBusID, bool includeLUN) const { } // IsReadOnly +/*! \brief Returns whether the device is read-only. + \return \c true, if the device is read-only, \c false otherwise. +*/ bool BDiskDevice::IsReadOnly() const { @@ -70,6 +134,9 @@ BDiskDevice::IsReadOnly() const } // IsRemovable +/*! \brief Returns whether the device media are removable. + \return \c true, if the device media are removable, \c false otherwise. +*/ bool BDiskDevice::IsRemovable() const { @@ -77,6 +144,9 @@ BDiskDevice::IsRemovable() const } // HasMedia +/*! \brief Returns whether the device contains a media. + \return \c true, if the device contains a media, \c false otherwise. +*/ bool BDiskDevice::HasMedia() const { @@ -84,6 +154,9 @@ BDiskDevice::HasMedia() const } // IsFloppy +/*! \brief Returns whether the device is a floppy device. + \return \c true, if the device is a floppy device, \c false otherwise. +*/ bool BDiskDevice::IsFloppy() const { @@ -91,6 +164,22 @@ BDiskDevice::IsFloppy() const } // Type +/*! \brief Returns the type of the device. + + The type may be one of the following (note, that not all types make sense + for storage device, but they are listed anyway): + - \c B_DISK: Hard disks, floppy disks, etc. + - \c B_TAPE: Tape drives. + - \c B_PRINTER: Printers. + - \c B_CPU: CPU devices. + - \c B_WORM: Write-once, read-many devives. + - \c B_CD: CD ROMs. + - \c B_SCANNER: Scanners. + - \c B_OPTICAL: Optical devices. + - \c B_JUKEBOX: Jukeboxes. + - \c B_NETWORK: Network devices. + \return The type of the device. +*/ uint8 BDiskDevice::Type() const { @@ -98,6 +187,15 @@ BDiskDevice::Type() const } // UniqueID +/*! \brief Returns a unique identifier for this device. + + The ID is not persistent, i.e. in general won't be the same after + rebooting. + + \see BDiskDeviceRoster::GetDeviceWithID(). + + \return A unique identifier for this device. +*/ int32 BDiskDevice::UniqueID() const { @@ -105,6 +203,14 @@ BDiskDevice::UniqueID() const } // Eject +/*! \brief Eject the device's media. + + The device media must, of course, be removable, and the device must + support ejecting the media. + + \return \c B_OK, if the media are ejected successfully, another error code + otherwise. +*/ status_t BDiskDevice::Eject() { @@ -112,6 +218,9 @@ BDiskDevice::Eject() } // LowLevelFormat +/*! \brief Low level formats the device. + \return \c B_OK, if everything went fine, another error code otherwise. +*/ status_t BDiskDevice::LowLevelFormat() { @@ -119,6 +228,15 @@ BDiskDevice::LowLevelFormat() } // Update +/*! \brief Updates the object to reflect the latest changes to the device. + + Note, that subobjects (BSessions, BPartitions) may be deleted during this + operation. It is also possible, that the device doesn't exist anymore -- + e.g. if it is hot-pluggable. Then an error is returned and the object is + uninitialized. + + \return \c B_OK, if the update went fine, another error code otherwise. +*/ status_t BDiskDevice::Update() { @@ -126,6 +244,16 @@ BDiskDevice::Update() } // VisitEachSession +/*! \brief Iterates through the device's sessions. + + The supplied visitor's Visit(BSession*) is invoked for each session. + If Visit() returns \c true, the iteration is terminated and the BSession + object just visited is returned. + + \param visitor The visitor. + \return The BSession object at which the iteration was terminated, or + \c NULL, if the iteration has not been terminated. +*/ BSession * BDiskDevice::VisitEachSession(BDiskDeviceVisitor *visitor) { @@ -133,6 +261,16 @@ BDiskDevice::VisitEachSession(BDiskDeviceVisitor *visitor) } // VisitEachPartition +/*! \brief Iterates through the device's partitions. + + The supplied visitor's Visit(BPartition*) is invoked for each partition. + If Visit() returns \c true, the iteration is terminated and the BPartition + object just visited is returned. + + \param visitor The visitor. + \return The BPartition object at which the iteration was terminated, or + \c NULL, if the iteration has not been terminated. +*/ BPartition * BDiskDevice::VisitEachPartition(BDiskDeviceVisitor *visitor) { @@ -140,6 +278,17 @@ BDiskDevice::VisitEachPartition(BDiskDeviceVisitor *visitor) } // Traverse +/*! \brief Pre-order traverses the tree of the spanned by the BDiskDevice and + its subobjects. + + The supplied visitor's Visit() is invoked for the device object itself, + for each session and for each partition. + If Visit() returns \c true, the iteration is terminated and this method + returns \c true as well. + + \param visitor The visitor. + \return \c true, if the iteration was terminated, \c false otherwise. +*/ bool BDiskDevice::Traverse(BDiskDeviceVisitor *visitor) { @@ -147,11 +296,15 @@ BDiskDevice::Traverse(BDiskDeviceVisitor *visitor) } // copy constructor +/*! \brief Privatized copy constructor to avoid usage. +*/ BDiskDevice::BDiskDevice(const BDiskDevice &) { } // = +/*! \brief Privatized assignment operator to avoid usage. +*/ BDiskDevice & BDiskDevice::operator=(const BDiskDevice &) { diff --git a/src/kits/storage/DiskDeviceRoster.cpp b/src/kits/storage/DiskDeviceRoster.cpp index 35d9308368..57a6ac8d95 100644 --- a/src/kits/storage/DiskDeviceRoster.cpp +++ b/src/kits/storage/DiskDeviceRoster.cpp @@ -5,17 +5,38 @@ #include +/*! \class BDiskDeviceRoster + \brief An interface for iterating through the disk devices known to the + system and for a notification mechanism provided to listen to their + changes. +*/ + // constructor +/*! \brief Creates a BDiskDeviceRoster object. + + The object is ready to be used after construction. +*/ BDiskDeviceRoster::BDiskDeviceRoster() { } // destructor +/*! \brief Frees all resources associated with the object. +*/ BDiskDeviceRoster::~BDiskDeviceRoster() { } // GetNextDevice +/*! \brief Returns the next BDiskDevice. + \param device Pointer to a pre-allocated BDiskDevice to be initialized to + represent the next device. + \return + - \c B_OK: Everything went fine. + - \c B_ENTRY_NOT_FOUND: The end of the list of devices had already been + reached. + - another error code +*/ status_t BDiskDeviceRoster::GetNextDevice(BDiskDevice *device) { @@ -23,6 +44,9 @@ BDiskDeviceRoster::GetNextDevice(BDiskDevice *device) } // Rewind +/*! \brief Rewinds the device list iterator. + \return \c B_OK, if everything went fine, another error code otherwise. +*/ status_t BDiskDeviceRoster::Rewind() { @@ -30,6 +54,18 @@ BDiskDeviceRoster::Rewind() } // VisitEachDevice +/*! \brief Iterates through the all devices. + + The supplied visitor's Visit(BDiskDevice*) is invoked for each device. + If Visit() returns \c true, the iteration is terminated and this method + returns \c true. If supplied, \a device is set to the concerned device. + + \param visitor The visitor. + \param device Pointer to a pre-allocated BDiskDevice to be initialized + to the device at which the iteration was terminated. + May be \c NULL. + \return \c true, if the iteration was terminated, \c false otherwise. +*/ bool BDiskDeviceRoster::VisitEachDevice(BDiskDeviceVisitor *visitor, BDiskDevice *device) @@ -38,6 +74,22 @@ BDiskDeviceRoster::VisitEachDevice(BDiskDeviceVisitor *visitor, } // VisitEachPartition +/*! \brief Iterates through the all devices' partitions. + + The supplied visitor's Visit(BPartition*) is invoked for each partition. + If Visit() returns \c true, the iteration is terminated and this method + returns \c true. If supplied, \a device is set to the concerned device + and in \a partition the pointer to the partition object is returned. + + \param visitor The visitor. + \param device Pointer to a pre-allocated BDiskDevice to be initialized + to the device at which the iteration was terminated. + May be \c NULL. + \param partition Pointer to a pre-allocated BPartition pointer to be set + to the partition at which the iteration was terminated. + May be \c NULL. + \return \c true, if the iteration was terminated, \c false otherwise. +*/ bool BDiskDeviceRoster::VisitEachPartition(BDiskDeviceVisitor *visitor, BDiskDevice *device, @@ -47,6 +99,17 @@ BDiskDeviceRoster::VisitEachPartition(BDiskDeviceVisitor *visitor, } // Traverse +/*! \brief Pre-order traverses the tree of the spanned by the BDiskDevices and + their subobjects. + + The supplied visitor's Visit() is invoked for each device, for each + session and for each partition. + If Visit() returns \c true, the iteration is terminated and this method + returns \c true as well. + + \param visitor The visitor. + \return \c true, if the iteration was terminated, \c false otherwise. +*/ bool BDiskDeviceRoster::Traverse(BDiskDeviceVisitor *visitor) { @@ -54,6 +117,23 @@ BDiskDeviceRoster::Traverse(BDiskDeviceVisitor *visitor) } // VisitEachMountedPartition +/*! \brief Iterates through the all devices' partitions that are mounted. + + The supplied visitor's Visit(BPartition*) is invoked for each mounted + partition. + If Visit() returns \c true, the iteration is terminated and this method + returns \c true. If supplied, \a device is set to the concerned device + and in \a partition the pointer to the partition object is returned. + + \param visitor The visitor. + \param device Pointer to a pre-allocated BDiskDevice to be initialized + to the device at which the iteration was terminated. + May be \c NULL. + \param partition Pointer to a pre-allocated BPartition pointer to be set + to the partition at which the iteration was terminated. + May be \c NULL. + \return \c true, if the iteration was terminated, \c false otherwise. +*/ bool BDiskDeviceRoster::VisitEachMountedPartition(BDiskDeviceVisitor *visitor, BDiskDevice *device, @@ -63,6 +143,23 @@ BDiskDeviceRoster::VisitEachMountedPartition(BDiskDeviceVisitor *visitor, } // VisitEachMountablePartition +/*! \brief Iterates through the all devices' partitions that are mountable. + + The supplied visitor's Visit(BPartition*) is invoked for each mountable + partition. + If Visit() returns \c true, the iteration is terminated and this method + returns \c true. If supplied, \a device is set to the concerned device + and in \a partition the pointer to the partition object is returned. + + \param visitor The visitor. + \param device Pointer to a pre-allocated BDiskDevice to be initialized + to the device at which the iteration was terminated. + May be \c NULL. + \param partition Pointer to a pre-allocated BPartition pointer to be set + to the partition at which the iteration was terminated. + May be \c NULL. + \return \c true, if the iteration was terminated, \c false otherwise. +*/ bool BDiskDeviceRoster::VisitEachMountablePartition(BDiskDeviceVisitor *visitor, BDiskDevice *device, @@ -72,6 +169,23 @@ BDiskDeviceRoster::VisitEachMountablePartition(BDiskDeviceVisitor *visitor, } // VisitEachInitializablePartition +/*! \brief Iterates through the all devices' partitions that are initializable. + + The supplied visitor's Visit(BPartition*) is invoked for each + initializable partition. + If Visit() returns \c true, the iteration is terminated and this method + returns \c true. If supplied, \a device is set to the concerned device + and in \a partition the pointer to the partition object is returned. + + \param visitor The visitor. + \param device Pointer to a pre-allocated BDiskDevice to be initialized + to the device at which the iteration was terminated. + May be \c NULL. + \param partition Pointer to a pre-allocated BPartition pointer to be set + to the partition at which the iteration was terminated. + May be \c NULL. + \return \c true, if the iteration was terminated, \c false otherwise. +*/ bool BDiskDeviceRoster::VisitEachInitializablePartition(BDiskDeviceVisitor *visitor, BDiskDevice *device, @@ -81,6 +195,18 @@ BDiskDeviceRoster::VisitEachInitializablePartition(BDiskDeviceVisitor *visitor, } // GetDeviceWithID +/*! \brief Returns a BDiskDevice for a given ID. + + The supplied \a device is initialized to the device identified by \a id. + + \param id The ID of the device to be retrieved. + \param device Pointer to a pre-allocated BDiskDevice to be initialized + to the device identified by \a id. + \return + - \c B_OK: Everything went fine. + - \c B_ENTRY_NOT_FOUND: A device with ID \a id could not be found. + - other error codes +*/ status_t BDiskDeviceRoster::GetDeviceWithID(int32 id, BDiskDevice *device) const { @@ -88,6 +214,22 @@ BDiskDeviceRoster::GetDeviceWithID(int32 id, BDiskDevice *device) const } // GetSessionWithID +/*! \brief Returns a BSession for a given ID. + + The supplied \a device is initialized to the device the session identified + by \a id resides on, and \a session is set to point to the respective + BSession. + + \param id The ID of the session to be retrieved. + \param device Pointer to a pre-allocated BDiskDevice to be initialized + to the device the session identified by \a id resides on. + \param session Pointer to a pre-allocated BSession pointer to be set to + the session identified by \a id. + \return + - \c B_OK: Everything went fine. + - \c B_ENTRY_NOT_FOUND: A session with ID \a id could not be found. + - other error codes +*/ status_t BDiskDeviceRoster::GetSessionWithID(int32 id, BDiskDevice *device, BSession **session) const @@ -96,6 +238,22 @@ BDiskDeviceRoster::GetSessionWithID(int32 id, BDiskDevice *device, } // GetPartitionWithID +/*! \brief Returns a BPartition for a given ID. + + The supplied \a device is initialized to the device the partition + identified by \a id resides on, and \a partition is set to point to the + respective BPartition. + + \param id The ID of the partition to be retrieved. + \param device Pointer to a pre-allocated BDiskDevice to be initialized + to the device the partition identified by \a id resides on. + \param partition Pointer to a pre-allocated BPartition pointer to be set + to the partition identified by \a id. + \return + - \c B_OK: Everything went fine. + - \c B_ENTRY_NOT_FOUND: A partition with ID \a id could not be found. + - other error codes +*/ status_t BDiskDeviceRoster::GetPartitionWithID(int32 id, BDiskDevice *device, BPartition **partition) const @@ -103,6 +261,21 @@ BDiskDeviceRoster::GetPartitionWithID(int32 id, BDiskDevice *device, } // StartWatching +/*! \brief Adds a target to the list of targets to be notified on disk device + events. + + \todo List the event mask flags, the events and describe the layout of the + notification message. + + If \a target is already listening to events, this method replaces the + former event mask with \a eventMask. + + \param target A BMessenger identifying the target to which the events + shall be sent. + \param eventMask A mask specifying on which events the target shall be + notified. + \return \c B_OK, if everything went fine, another error code otherwise. +*/ status_t BDiskDeviceRoster::StartWatching(BMessenger target, uint32 eventMask) { @@ -110,6 +283,12 @@ BDiskDeviceRoster::StartWatching(BMessenger target, uint32 eventMask) } // StopWatching +/*! \brief Remove a target from the list of targets to be notified on disk + device events. + \param target A BMessenger identifying the target to which notfication + message shall not longer be sent. + \return \c B_OK, if everything went fine, another error code otherwise. +*/ status_t BDiskDeviceRoster::StopWatching(BMessenger target) { diff --git a/src/kits/storage/DiskDeviceVisitor.cpp b/src/kits/storage/DiskDeviceVisitor.cpp index 23f4d07a55..e1754f7171 100644 --- a/src/kits/storage/DiskDeviceVisitor.cpp +++ b/src/kits/storage/DiskDeviceVisitor.cpp @@ -5,17 +5,46 @@ #include +/*! \class BDiskDeviceVisitor + \brief Base class of visitors used for BDiskDevice, BSession and + BPartition iteration. + + BDiskDeviceRoster, BDiskDevice and BSession provide iteration methods, + that work together with an instance of a derived class of + BDiskDeviceVisitor. For each encountered BDiskDevice, BSession and + BPartition the respective Visit() method is invoked. The return value + of that method specifies whether the iteration shall be terminated at + that point. +*/ + // constructor +/*! \brief Creates a new disk device visitor. +*/ BDiskDeviceVisitor::BDiskDeviceVisitor() { } // destructor +/*! \brief Free all resources associated with this object. + + Does nothing. +*/ BDiskDeviceVisitor::~BDiskDeviceVisitor() { } // Visit +/*! \brief Invoked when a BDiskDevice is visited. + + If the method returns \c true, the iteration is terminated at this point, + on \c false continued. + + Overridden by derived classes. + This class' version does nothing and it returns \c false. + + \return \c true, if the iteration shall be terminated at this point, + \c false otherwise. +*/ bool BDiskDeviceVisitor::Visit(BDiskDevice *device) { @@ -23,6 +52,17 @@ BDiskDeviceVisitor::Visit(BDiskDevice *device) } // Visit +/*! \brief Invoked when a BSession is visited. + + If the method returns \c true, the iteration is terminated at this point, + on \c false continued. + + Overridden by derived classes. + This class' version does nothing and it returns \c false. + + \return \c true, if the iteration shall be terminated at this point, + \c false otherwise. +*/ bool BDiskDeviceVisitor::Visit(BSession *device) { @@ -30,6 +70,17 @@ BDiskDeviceVisitor::Visit(BSession *device) } // Visit +/*! \brief Invoked when a BPartition is visited. + + If the method returns \c true, the iteration is terminated at this point, + on \c false continued. + + Overridden by derived classes. + This class' version does nothing and it returns \c false. + + \return \c true, if the iteration shall be terminated at this point, + \c false otherwise. +*/ bool BDiskDeviceVisitor::Visit(BPartition *device) { diff --git a/src/kits/storage/Partition.cpp b/src/kits/storage/Partition.cpp index e39eba4e9d..010ea4aec3 100644 --- a/src/kits/storage/Partition.cpp +++ b/src/kits/storage/Partition.cpp @@ -5,17 +5,20 @@ #include -// constructor -BPartition::BPartition() -{ -} +/*! \class BPartition + \brief A BPartition object represent a partition and provides a lot of + methods to retrieve information about it and some to manipulate it. -// destructor -BPartition::~BPartition() -{ -} + Not all BPartitions represent actual on-disk partitions. Some exist only + to make all devices fit smoothly into the framework (e.g. for floppies, + \see IsVirtual()), others represents merely partition slots + (\see IsEmpty()). +*/ // Session +/*! \brief Returns the session this partition resides on. + \return The session this partition resides on. +*/ BSession * BPartition::Session() const { @@ -23,6 +26,9 @@ BPartition::Session() const } // Device +/*! \brief Returns the device this partition resides on. + \return The device this partition resides on. +*/ BDiskDevice * BPartition::Device() const { @@ -30,6 +36,11 @@ BPartition::Device() const } // Offset +/*! \brief Returns the partition's offset relative to the beginning of the + device it resides on. + \return The partition's offset in bytes relative to the beginning of the + device it resides on. +*/ off_t BPartition::Offset() const { @@ -37,6 +48,9 @@ BPartition::Offset() const } // Size +/*! \brief Returns the size of the partition. + \return The size of the partition in bytes. +*/ off_t BPartition::Size() const { @@ -44,6 +58,9 @@ BPartition::Size() const } // BlockSize +/*! \brief Returns the block size of the device. + \return The block size of the device in bytes. +*/ int32 BPartition::BlockSize() const { @@ -51,6 +68,10 @@ BPartition::BlockSize() const } // Index +/*! \brief Returns the index of the partition in its session's list of + partitions. + \return The index of the partition in its session's list of partitions. +*/ int32 BPartition::Index() const { @@ -58,6 +79,19 @@ BPartition::Index() const } // Flags +/*! \brief Returns the flags for this partitions. + + The partition flags are a bitwise combination of: + - \c B_HIDDEN_PARTITION: The partition can not contain a file system. + - \c B_VIRTUAL_PARTITION: There exists no on-disk partition this object + represents. E.g. for floppies there will be a BPartition object spanning + the whole floppy disk. + - \c B_EMPTY_PARTITION: The partition represents no physical partition, + but merely an empty slot. This mainly used to keep the indexing of + partitions more persistent. This flag implies also \c B_HIDDEN_PARTITION. + + \return The flags for this partition. +*/ uint32 BPartition::Flags() const { @@ -65,6 +99,11 @@ BPartition::Flags() const } // IsHidden +/*! \brief Returns whether the partition can contain a file system. + \see Flags(). + \return \c true, if the partition can't contain a file system, \c false + otherwise. +*/ bool BPartition::IsHidden() const { @@ -72,6 +111,11 @@ BPartition::IsHidden() const } // IsVirtual +/*! \brief Returns whether the object doesn't represents an on-disk partition. + \see Flags(). + \return \c true, if the object doesn't represent an on-disk partition, + \c false otherwise. +*/ bool BPartition::IsVirtual() const { @@ -79,13 +123,37 @@ BPartition::IsVirtual() const } // IsEmpty +/*! \brief Returns whether the partition is empty. + \see Flags(). + \return \c true, if the partition is empty, \c false otherwise. +*/ bool BPartition::IsEmpty() const { return false; // not implemented } +// ContainsFileSystem +/*! \brief Returns whether the partition contains a file system recognized by + the system. + \return \c true, if the partition contains a file system recognized by + the system, \c false otherwise. +*/ +bool +BPartition::ContainsFileSystem() const +{ + return false; // not implemented +} + // Name +/*! \brief Returns the name of the partition. + + Note, that not all partitioning system support names. The method returns + \c NULL, if the partition doesn't have a name. + + \return The name of the partition, or \c NULL, if the partitioning system + does not support names. +*/ const char * BPartition::Name() const { @@ -93,6 +161,9 @@ BPartition::Name() const } // Type +/*! \brief Returns a human readable string for the type of the partition. + \return A human readable string for the type of the partition. +*/ const char * BPartition::Type() const { @@ -100,6 +171,15 @@ BPartition::Type() const } // FileSystemShortName +/*! \brief Returns a short string identifying the file system on the partition. + + If the partition doesn't contain a recognized file system + (\see ContainsFileSystem()), \c NULL is returned. + + \return A short string identifying the file system on the partition, + or \c NULL, if the partition doesn't contain a recognized file + system. +*/ const char * BPartition::FileSystemShortName() const { @@ -107,6 +187,15 @@ BPartition::FileSystemShortName() const } // FileSystemLongName +/*! \brief Returns a longer description of the file system on the partition. + + If the partition doesn't contain a recognized file system + (\see ContainsFileSystem()), \c NULL is returned. + + \return A longer description of the file system on the partition, + or \c NULL, if the partition doesn't contain a recognized file + system. +*/ const char * BPartition::FileSystemLongName() const { @@ -114,6 +203,14 @@ BPartition::FileSystemLongName() const } // VolumeName +/*! \brief Returns the name of the volume. + + If the partition doesn't contain a recognized file system + (\see ContainsFileSystem()), \c NULL is returned. + + \return The name of the volume, or \c NULL, if the partition doesn't + contain a recognized file system. +*/ const char * BPartition::VolumeName() const { @@ -121,20 +218,47 @@ BPartition::VolumeName() const } // FileSystemFlags +/*! \brief Returns the file system flags for the volume. + + If the partition doesn't contain a recognized file system + (\see ContainsFileSystem()), the return value is undefined. + + Note, that, if the volume is mounted, the returned flags are identical + with the ones fs_stat_dev() reports. If not mounted they describe merely + the file system's capabilities. E.g. if the file system supports + writing and the device is not read-only, the B_FS_IS_READONLY is not set, + but it will be set, when the volume is mounted read-only. The same applies + to other capabilities that can be disabled at mount time. + + \return The file system flags of the volume, if the partition contains + a recognized file system. +*/ uint32 BPartition::FileSystemFlags() const { - return NULL; // not implemented + return 0; // not implemented } // IsMounted +/*! \brief Returns whether the volume is mounted. + \return \c true, if the volume is mounted, \c false otherwise. +*/ bool BPartition::IsMounted() const { - return NULL; // not implemented + return false; // not implemented } // UniqueID +/*! \brief Returns a unique identifier for this partition. + + The ID is not persistent, i.e. in general won't be the same after + rebooting. + + \see BDiskDeviceRoster::GetPartitionWithID(). + + \return A unique identifier for this partition. +*/ int32 BPartition::UniqueID() const { @@ -142,6 +266,15 @@ BPartition::UniqueID() const } // GetVolume +/*! \brief Returns a BVolume for the partition. + + The can succeed only, if the partition is mounted. + + \param volume Pointer to a pre-allocated BVolume, to be initialized to + represent the volume. + \return \c B_OK, if the volume is mounted and the parameter could be set + accordingly, another error code otherwise. +*/ status_t BPartition::GetVolume(BVolume *volume) const { @@ -149,6 +282,18 @@ BPartition::GetVolume(BVolume *volume) const } // GetIcon +/*! \brief Returns an icon for this partition. + + Note, that currently there are only per-device icons, i.e. the method + returns the same icon for each partition of a device. But this may change + in the future. + + \param icon Pointer to a pre-allocated BBitmap to be set to the icon of + the partition. + \param which Size of the icon to be retrieved. Can be \c B_MINI_ICON or + \c B_LARGE_ICON. + \return \c B_OK, if everything went fine, another error code otherwise. +*/ status_t BPartition::GetIcon(BBitmap *icon, icon_size which) const { @@ -156,13 +301,29 @@ BPartition::GetIcon(BBitmap *icon, icon_size which) const } // Mount +/*! \brief Mounts the volume. + + The volume can only be mounted, if the partition contains a recognized + file system (\see ContainsFileSystem()) and it is not already mounted. + + \param mountFlags Currently only \c B_MOUNT_READ_ONLY is defined, which + forces the volume to be mounted read-only. + \param parameters File system specific mount parameters. + \return \c B_OK, if everything went fine, another error code otherwise. +*/ status_t -BPartition::Mount(uint32 mountflags, const char *parameters) +BPartition::Mount(uint32 mountFlags, const char *parameters) { return B_ERROR; // not implemented } // Unmount +/*! \brief Unmounts the volume. + + The volume can of course only be unmounted, if it currently is mounted. + + \return \c B_OK, if everything went fine, another error code otherwise. +*/ status_t BPartition::Unmount() { @@ -170,43 +331,133 @@ BPartition::Unmount() } // GetInitializationParameters +/*! \brief Asks the user to set the parameters for initializing this partition. + + A dialog window will be opened, centered at \a dialogCenter, asking the + user for setting the parameters to be used for initializing this partition + with the file system specified by \a fileSystem. + + The method does not return until the user has confirmed or cancelled the + dialog. In the latter case \a cancelled is set to \c true, otherwise to + \c false. + + \param fileSystem The file system the parameters shall be asked for. + \param volumeName The volume name set by the user. + \param parameters Pointer to a pre-allocated BString to be set to the + parameters the user has specified. + \param dialogCenter The point at which to center the dialog. If omitted, + the dialog is displayed centered to the screen. + \param cancelled Pointer to a pre-allocated bool to be set to \c true, if + the dialog has been cancelled by the user, or to \c false + otherwise. May be \c NULL. + \return + - \c B_OK: The parameters have been retrieved successfully. + - \c B_ERROR: Either the dialog has been cancelled -- then \a cancelled + is set accordingly -- or some other error occured. + - another error code +*/ status_t BPartition::GetInitializationParameters(const char *fileSystem, - BPoint dialogCenter, + BString *volumeName, BString *parameters, - bool *cancelled); + BPoint dialogCenter, + bool *cancelled) { return B_ERROR; // not implemented } // Initialize +/*! \brief Initializes the partition according to the supplied parameters. + \param fileSystem The file system to be used for initialization. + \param volumeName The new volume name. + \param parameters File system specific parameters. + \return + - \c B_OK: Everything went fine. + - another error code, if an error occured +*/ status_t -BPartition::Initialize(const char *fileSystem, const char *parameters) +BPartition::Initialize(const char *fileSystem, const char *volumeName, + const char *parameters) { return B_ERROR; // not implemented } // Initialize +/*! \brief Initializes the partition after asking the user for the respective + parameters. + + A dialog window will be opened, centered at \a dialogCenter, asking the + user for setting the parameters to be used for initializing this partition + with the file system specified by \a fileSystem. + + The method does not return until the user has either confirmed the dialog + and the initialization is done, or the dialog has been cancelled. In the + latter case \a cancelled is set to \c true, otherwise to \c false. + + \param fileSystem The file system to be used for the initialization. + \param dialogCenter The point at which to center the dialog. If omitted, + the dialog is displayed centered to the screen. + \param cancelled Pointer to a pre-allocated bool to be set to \c true, if + the dialog has been cancelled by the user, or to \c false + otherwise. May be \c NULL. + \return + - \c B_OK: The parameters have been retrieved successfully and the + initialization went fine, too. + - \c B_ERROR: Either the dialog has been cancelled -- then \a cancelled + is set accordingly -- or some other error occured. + - another error code +*/ status_t BPartition::Initialize(const char *fileSystem, BPoint dialogCenter, - bool *cancelled); + bool *cancelled) { return B_ERROR; // not implemented } // GetFileSystemList +/*! \brief Returns a list of all file systems that can be used for + initialization. + + The names of the file systems are added as BString objects to the + supplied list. The caller takes over ownership of the return BString + objects and is responsible for deleteing them. + + Any of returned names can be passed to Initialize(). + + \param list Pointer to a pre-allocated BObjectList the names of the + file systems shall be added to. + \return \c B_OK, if everything went fine, another error code otherwise. +*/ status_t -BPartition::GetFileSystemList(BObjectList *list) +BPartition::GetFileSystemList(BObjectList *list) { return B_ERROR; // not implemented } // constructor +/*! \brief Creates an uninitialized BPartition object. +*/ +BPartition::BPartition() +{ +} + +// constructor +/*! \brief Privatized copy constructor to avoid usage. +*/ BPartition::BPartition(const BPartition &) { } +// destructor +/*! \brief Frees all resources associated with this object. +*/ +BPartition::~BPartition() +{ +} + // = +/*! \brief Privatized assignment operator to avoid usage. +*/ BPartition & BPartition::operator=(const BPartition &) { diff --git a/src/kits/storage/Session.cpp b/src/kits/storage/Session.cpp index f34aa92f71..88a90569f3 100644 --- a/src/kits/storage/Session.cpp +++ b/src/kits/storage/Session.cpp @@ -5,19 +5,24 @@ #include -const char *B_INTEL_PARTITION_STYLE = "intel"; +/*! \class BSession + \brief A BSession object represent a session and provides a lot of + methods to retrieve information about it and some to manipulate it. -// constructor -BSession::BSession() -{ -} + Not all BSession represent actual on-disk sessions. Some exist only + to make all devices fit smoothly into the framework (e.g. for hard and + floppy, \see IsVirtual()). +*/ -// destructor -BSession::~BSession() -{ -} + +/*! \brief Name of the DOS/Intel partitioning system. +*/ +const char *B_INTEL_PARTITIONING = "intel"; // Device +/*! \brief Returns the device this session resides on. + \return The device this session resides on. +*/ BDiskDevice * BSession::Device() const { @@ -25,6 +30,11 @@ BSession::Device() const } // Offset +/*! \brief Returns the session's offset relative to the beginning of the + device it resides on. + \return The session's offset in bytes relative to the beginning of the + device it resides on. +*/ off_t BSession::Offset() const { @@ -32,6 +42,9 @@ BSession::Offset() const } // Size +/*! \brief Returns the size of the session. + \return The size of the session in bytes. +*/ off_t BSession::Size() const { @@ -39,6 +52,9 @@ BSession::Size() const } // CountPartitions +/*! \brief Returns the number of partitions on this session. + \return The number of partitions on this session. +*/ int32 BSession::CountPartitions() const { @@ -46,6 +62,11 @@ BSession::CountPartitions() const } // PartitionAt +/*! \brief Returns a contained partition by index. + \param index The index of the partition to be returned. + \return The partition with the requested index, or \c NULL, if \a index + is out of range. +*/ BPartition * BSession::PartitionAt(int32 index) const { @@ -53,6 +74,9 @@ BSession::PartitionAt(int32 index) const } // Index +/*! \brief Returns the index of the session in its device's list of session. + \return The index of the session in its session's list of sessions. +*/ int32 BSession::Index() const { @@ -60,6 +84,16 @@ BSession::Index() const } // Flags +/*! \brief Returns the flags for this session. + + The session flags are a bitwise combination of: + - \c B_DATA_SESSION: The session is a non-audio session. + - \c B_VIRTUAL_SESSION: There exists no on-disk session this object + represents. E.g. for hard disks there will be a BSession object spanning + the whole disk. + + \return The flags for this partition. +*/ uint32 BSession::Flags() const { @@ -67,6 +101,9 @@ BSession::Flags() const } // IsAudio +/*! \brief Returns whether the session is an audio session. + \return \c true, if the session is an audio session, \c false otherwise. +*/ bool BSession::IsAudio() const { @@ -74,6 +111,9 @@ BSession::IsAudio() const } // IsData +/*! \brief Returns whether the session is a data (i.e. non-audio) session. + \return \c true, if the session is a data session, \c false otherwise. +*/ bool BSession::IsData() const { @@ -81,43 +121,108 @@ BSession::IsData() const } // IsVirtual +/*! \brief Returns whether the object doesn't represents an on-disk session. + \see Flags(). + \return \c true, if the object doesn't represent an on-disk session, + \c false otherwise. +*/ bool BSession::IsVirtual() const { return false; // not implemented } -// PartitionStyle +// PartitioningSystem +/*! \brief Returns the name of the partitioning system used for this session. + + If the session is a audio session or virtual (\see Flags()), the method + returns \c NULL, otherwise the name of the partitioning system used. + + \return The name of the partitioning system used for this session, if any. + \c NULL otherwise. +*/ const char * -BSession::PartitionStyle() const +BSession::PartitioningSystem() const { return NULL; // not implemented } // UniqueID +/*! \brief Returns a unique identifier for this session. + + The ID is not persistent, i.e. in general won't be the same after + rebooting. + + \see BDiskDeviceRoster::GetSessionWithID(). + + \return A unique identifier for this session. +*/ int32 BSession::UniqueID() const { return 0; // not implemented } -// EachPartition +// VisitEachPartition +/*! \brief Iterates through the session's partitions. + + The supplied visitor's Visit(BPartition*) is invoked for each partition. + If Visit() returns \c true, the iteration is terminated and the BPartition + object just visited is returned. + + \param visitor The visitor. + \return The BPartition object at which the iteration was terminated, or + \c NULL, if the iteration has not been terminated. +*/ BPartition * -BSession::EachPartition(BDiskDeviceVisitor *visitor) +BSession::VisitEachPartition(BDiskDeviceVisitor *visitor) { return NULL; // not implemented } // GetPartitioningParameters +/*! \brief Asks the user to set the parameters for partitioning this session. + + A dialog window will be opened, centered at \a dialogCenter, asking the + user for setting the parameters to be used for partitioning this session + with the partitioning system specified by \a partitioningSystem. + + The method does not return until the user has confirmed or cancelled the + dialog. In the latter case \a cancelled is set to \c true, otherwise to + \c false. + + \param partitioningSystem The partitioning system the parameters shall be + asked for. + \param parameters Pointer to a pre-allocated BString to be set to the + parameters the user has specified. + \param dialogCenter The point at which to center the dialog. If omitted, + the dialog is displayed centered to the screen. + \param cancelled Pointer to a pre-allocated bool to be set to \c true, if + the dialog has been cancelled by the user, or to \c false + otherwise. May be \c NULL. + \return + - \c B_OK: The parameters have been retrieved successfully. + - \c B_ERROR: Either the dialog has been cancelled -- then \a cancelled + is set accordingly -- or some other error occured. + - another error code +*/ status_t BSession::GetPartitioningParameters(const char *partitioningSystem, - BPoint dialogCenter, BString *parameters, + BString *parameters, BPoint dialogCenter, bool *cancelled) { return B_ERROR; // not implemented } // Partition +/*! \brief Partitions the session according to the supplied parameters. + \param partitioningSystem The partitioning system to be used for + partitioning. + \param parameters Partitioning system specific parameters. + \return + - \c B_OK: Everything went fine. + - another error code, if an error occured +*/ status_t BSession::Partition(const char *partitioningSystem, const char *parameters) { @@ -125,6 +230,31 @@ BSession::Partition(const char *partitioningSystem, const char *parameters) } // Partition +/*! \brief Partitions the session after asking the user for the respective + parameters. + + A dialog window will be opened, centered at \a dialogCenter, asking the + user for setting the parameters to be used for partitioning this session + with the partitioning system specified by \a partitioningSystem. + + The method does not return until the user has either confirmed the dialog + and the partitioning is done, or the dialog has been cancelled. In the + latter case \a cancelled is set to \c true, otherwise to \c false. + + \param partitioningSystem The partitioning system to be used for + partitioning. + \param dialogCenter The point at which to center the dialog. If omitted, + the dialog is displayed centered to the screen. + \param cancelled Pointer to a pre-allocated bool to be set to \c true, if + the dialog has been cancelled by the user, or to \c false + otherwise. May be \c NULL. + \return + - \c B_OK: The parameters have been retrieved successfully and the + partitioning went fine, too. + - \c B_ERROR: Either the dialog has been cancelled -- then \a cancelled + is set accordingly -- or some other error occured. + - another error code +*/ status_t BSession::Partition(const char *partitioningSystem, BPoint dialogCenter, bool *cancelled) @@ -132,12 +262,50 @@ BSession::Partition(const char *partitioningSystem, BPoint dialogCenter, return B_ERROR; // not implemented } +// GetPartitioningSystemList +/*! \brief Returns a list of all partitioning systems that can be used for + partitioning. + + The names of the partioning systems are added as BString objects to the + supplied list. The caller takes over ownership of the return BString + objects and is responsible for deleteing them. + + Any of returned names can be passed to Partition(). + + \param list Pointer to a pre-allocated BObjectList the names of the + partitioning systems shall be added to. + \return \c B_OK, if everything went fine, another error code otherwise. +*/ +status_t +BSession::GetPartitioningSystemList(BObjectList *list) +{ + return B_ERROR; // not implemented +} + +// constructor +/*! \brief Creates an uninitialized BSession object. +*/ +BSession::BSession() +{ +} + +// destructor +/*! \brief Frees all resources associated with this object. +*/ +BSession::~BSession() +{ +} + // copy constructor +/*! \brief Privatized copy constructor to avoid usage. +*/ BSession::BSession(const BSession &) { } // = +/*! \brief Privatized assignment operator to avoid usage. +*/ BSession & BSession::operator=(const BSession &) {