BVolumeRoster Class Reference

#include <VolumeRoster.h>

List of all members.

Detailed Description

The BVolumeRoster class keeps track of the volumes that are mounted in the file system hierarchy.

: It lets you know about volumes in two ways:

It lists the volumes that are currently mounted. You can step through the list through iterative calls to the GetNextVolume() function.

It lets you know when new volumes are mounted, and when existing volumes are unmounted. (See StartWatching().)

: How you create your BVolumeRoster object depends on what you're going to do with it:

If you simply want to step through the volume list, then creating a BVolumeRoster on the stack is sufficient.

However, if you want to watch for volumes being mounted and unmounted, then you must keep your BVolumeRoster object around. The watching stops when the object is deleted.

: A single BVolumeRoster object can perform both functions: You can use it to step through the volume list at the same time that it's watching volumes.

Public Member Functions

BVolumeRoster ()

virtual ~BVolumeRoster ()

status_t GetNextVolume (BVolume *vol)

void Rewind ()

status_t GetBootVolume (BVolume *vol)

status_t StartWatching (BMessenger msngr=be_app_messenger)

void StopWatching (void)

BMessenger Messenger (void) const

Constructor & Destructor Documentation

BVolumeRoster ( )

Creates a new BVolumeRoster object. You don't have to "initialize" the object before using it (as you do with most other Storage Kit classes). You can call GetNextVolume() (or whatever) immediately after constructing.

~BVolumeRoster ( ) [virtual]

Destroys the object. If this BVolumeRoster object was watching volumes, the watch is called off.

Member Function Documentation

status_t GetBootVolume ( BVolume * vol )

Initializes vol to refer to the "boot volume." This is the volume that was used to boot the computer. vol must be allocated before you pass it in. If the boot volume can't be found, the argument is uninitialized.

Parameters:

vol BVolume object

Returns:
B_NO_ERROR. The boot volume was successfully retrieved.
B_ENTRY_NOT_FOUND. The boot volume wasn't found.
(Currently, this function looks for the volume that's mounted at /boot. The only way to fool the system into thinking that there isn't a boot volume is to rename /boot - not a smart thing to do.)

status_t GetNextVolume ( BVolume * vol )

Retrieves the "next" volume from the volume list and uses it to initialize the argument (which must be allocated). When the function return B_BAD_VALUE, you've reached the end of the list.

Parameters:

vol BVolume object

Returns:
B_NO_ERROR. The next volume was successfully retrieved.
B_BAD_VALUE. You've reached the end of the volume list.

BMessenger Messenger ( void ) const

Returns:
A copy of the BMessenger object that was set in the previous StartWatching() call.

void Rewind ( void )

Rewinds the volume list such that the next GetNextVolume() will return the first element in the list.

status_t StartWatching ( BMessenger msngr = be_app_messenger )

This function start the BVolumeRoster's volume-watching facility. (This is actually just a convenient cover for the Node Monitor.)
StartWatching() registers a request for notifications of volume mounts and unmounts. The notifications are sent (as BMessages) to the BHandler/BLooper pair specified by the argument. There are separate messages for mounting and unmounting; their formats are described below. The caller retains possession of the BHandler/BLooper that the BMessenger represents. The volume watching continues until this BVolumeRoster object is destroyed, or until you call...
There are separate notifications (BMessages) for volume-mounted and volume- unmounted events. See the B_DEVICE_MOUNTED and B_DEVICE_UNMOUNTED descriptions in The Node Monitor section.

Parameters:

msngr BMessenger object

Returns:
B_NO_ERROR. The volume-watcher was successfully started or stopped.
B_BAD_VALUE. Poorly formed BMessenger.
B_NO_MEMORY. Couldn't allocate resources.

void StopWatching ( void )

These functions stop the BVolumeRoster's volume-watching facility. (This is actually just a convenient cover for the Node Monitor.)
This function tells the volume-watcher to stop watching. In other words, notifications of volume mounts and unmounts are no longer sent to the BVolumeRoster's target.


Public Member Functions
	BVolumeRoster ()
virtual	~BVolumeRoster ()
status_t	GetNextVolume (BVolume *vol)
void	Rewind ()
status_t	GetBootVolume (BVolume *vol)
status_t	StartWatching (BMessenger msngr=be_app_messenger)
void	StopWatching (void)
BMessenger	Messenger (void) const