The Storage Kit: BVolumeRoster

The Storage Kit Table of Contents | The Storage Kit Index

# BVolumeRoster

Derived from: none

Declared in: be/storage/VolumeRoster.h

Library: libbe.so

###### Summary

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 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 Storage Kit Table of Contents | The Storage Kit Index

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

Copyright © 2000 Be, Inc. All rights reserved..