The Storage Kit: BVolume

The Storage Kit Table of Contents | The Storage Kit Index

# BVolume

Derived from: none

Declared in: be/storage/Volume.h

Library: libbe.so

###### Summary

The BVolume class lets you ask questions about specific "volumes," where a volume is any independent file system. Most applications are usually only interested in "persistent" volumes, such as hard disks, floppies, or CD-ROMs, but you can also create BVolumes to virtual file systems, such as /pipe. Here's what a BVolume knows:

- The volume's name, device ID, and "root directory."

- Its storage capacity, and the currently available storage.

- If the volume is on a media that's removable.

- If the volume's storage is persistent (as opposed to the ephemeral storage you get with virtual file systems).

- If the volume is accessed through the network.

- If the file system uses MIME as file types, if it responds to queries, and if it knows about attributes.

### Initializing a BVolume

There are two ways to initialize a BVolume:

- You can initialize it directly using a device ID (`dev_t`) that you pass to the BVolume constructor or `SetTo()` function. You can get a device ID from the device field of an `entry_ref` or `node_ref` structure. This method is useful if you have a file and you want to know which volume it lives on.

- If you want to iterate over all the mounted volumes, you can ask a BVolumeRoster object to get you the "next" volume (`BVolumeRoster::GetNextVolume()`). You can also ask the BVolumeRoster for the "boot" volume. This is the volume that was used to boot the computer.

### Mount and Unmount

A BVolume object can't tell you directly whether the device that it represents is still mounted. If you want to ask, you can call a `status_t`-returning BVolume function; if the function returns `B_BAD_VALUE`, the device is no longer mounted.

Furthermore, you can't ask a BVolume to unmount itself. If you want to be told when devices are mounted and unmounted, you have to ask the Node Monitor to help you. Call `watch_node()` thus:

       watch_node(NULL, B_WATCH_MOUNT, messenger);

messenger is a BMessenger object that acts as the target of subsequent mount and unmount notifications. See "The Node Monitor" section of this chapter for details.

## Constructor and Destructor

### BVolume()

`BVolume(`void`) `
`BVolume(`BVolume &volume`) `
`BVolume(dev_t` device`) `

Creates a new BVolume object and initializes it according to the argument. The status of the initialization is recorded by the `InitCheck()` function.

- The default constructor does nothing and sets `InitCheck()` to `B_NO_INIT`.

- The device constructor sets the BVolume to point to the volume represented by the argument. See the `SetTo()` function for status codes.

- The copy constructor sets the object to point to the same device as does the argument.

### ~BVolume

`~BVolume() `

Destroys the BVolume object.

## Member Functions

### Capacity() , FreeBytes()

`off_t` `Capacity(`void`)` const
`off_t` `FreeBytes(`void`)` const

Returns the volume's total storage capacity and the amount of storage that's currently unused. Both measurements are in bytes.

### Device()

`dev_t` `Device(`void`)` const

Returns the object's `dev_t` number.

### GetIcon()

`status_t` `GetIcon(` BBitmap *icon, `icon_size` which`)` const

Returns the volume's icon in icon. which specifies the icon to retrieve, either `B_MINI_ICON` (16x16) or `B_LARGE_ICON` (32x32).

See also: `get_device_icon()`

### GetName()

`status_t` `GetName(`char *buffer`)` const

Copies the name of the volume into buffer.

### GetRootDirectory()

`status_t` `GetRootDirectory(` BDirectory *dir`)` const

Initializes dir (which must be allocated) to refer to the volume's "root directory." The root directory stands at the "root" of the volume's file hierarchy. Note that this isn't necessarily the root of the entire file hierarchy.

### InitCheck()

`status_t` `InitCheck(`void`)` const

Returns the status of the last initialization (from either the constructor or `SetTo()`).

### IsPersistent() , IsRemovable() , IsReadOnly() , IsShared()

bool `IsPersistent(`void`)` const
bool `IsRemovable(`void`)` const
bool `IsReadOnly(`void`)` const
bool `IsShared(`void`)` const

These functions answer media-related questions about the volume:

- `IsPersistent()`. Is the storage persistent (such as on a floppy or hard disk)?

- `IsRemovable()`. Can the media be removed?

- `IsReadOnly()`. Can it be read but not written to?

- `IsShared()`. Is it accessed through the network (as opposed to being directly connected to this computer)?

### KnowsAttr() , KnowsMime() , KnowsQuery()

bool `KnowsAttr(`void`)` const
bool `KnowsMime(`void`)` const
bool `KnowsQuery(`void`)` const

These functions answer questions about the file system on the volume:

- `KnowsAttr()`. Do its files accept attributes?

- `KnowsMime()`. Does it use MIME to type files?

- `KnowsQuery()`. Can it respond to queries?

### SetTo() , Unset()

`status_t` `SetTo(dev_t` dev`) `
void `Unset(`void`) `

`SetTo()` initializes the BVolume object to represent the volume (device) identified by the argument.

`Unset()` uninitializes the BVolume.

## Operators

### = (assignment)

BVolume& operator `= (`const BEntry &volume`) `

In the expression

       BVolume a = b;

BVolume a is initialized to refer to the same volume as b. To gauge the success of the assignment, you should call `InitCheck()` immediately afterwards. Assigning a BVolume to itself is safe.

Assigning from an uninitialized BVolume is "successful": The assigned-to BVolume will also be uninitialized (`B_NO_INIT`).

### == , != (comparison)

bool operator `== (`const BVolume &volume`)` const
bool operator `!= (`const BVolume &volume`)` const

Two BVolume objects are said to be equal if they refer to the same volume, or if they're both uninitialized.

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