# The Storage Kit: BVolumeRoster

Derived from: none

Declared in: be/storage/VolumeRoster.h

Library: libbe.so

## Overview

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.

## Constructor and Destructor

### BVolumeRoster()

          BVolumeRoster(void)

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 ~BVolumeRoster()

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

## Member Functions

### GetBootVolume()

          status_t GetBootVolume(BVolume *boot_vol)

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

(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.)

RETURN CODES

- `B_NO_ERROR`. The boot volume was successfully retrieved.
- `B_ENTRY_NOT_FOUND`. The boot volume wasn't found.

### GetNextVolume(), Rewind()

          status_t GetNextVolume(BVolume *volume)
          void Rewind(void)

`GetNextVolume()` 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.

`Rewind()` rewinds the volume list such that the next `GetNextVolume()` will return the first element in the list.

RETURN CODES

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

### StartWatching(), StopWatching(), Messenger()

          status_t StartWatching(BMessenger messenger = be_app_messenger)
          void StopWatching(void)
          BMessenger Messenger(void) const

These functions start and stop 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...

- `StopWatching()`. 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.

- `Messenger()` returns a copy of the BMessenger object that was set in the previous `StartWatching()` 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 Storage Kit: The Node Monitor section of this chapter.

RETURN CODES

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

The Be Book, in lovely HTML, for BeOS Release 3.

Copyright © 1998 Be, Inc. All rights reserved.

Last modified March 26, 1998.