ACCESS Linux Platform employs the Hiker Application Framework's Volume Services to provide a simple way to deal with devices, plug-in cards, and other dynamically mounted media. Volume Services ensures that appropriate notifications are broadcast whenever mounted file systems (volumes) or devices are added or removed. It also provides a high-level API that simplifies common volume operations such as mounting and unmounting, renaming, and so forth.

Overview ^TOP^

Volume Services works in conjunction with udev. udev is a generic kernel device manager that runs as a daemon and monitors uevents that the kernel sends out (via netlink socket) when a new device is initialized or a device is removed from the system. When udev detects such an event, the following occurs:

1. udev creates a device node.
2. udev invokes a shell script that probes the volume and sends information about that volume to Volume Services.
3. Volume Services broadcasts the appropriate volume (or device) add or remove notification.

Various parts of ACCESS Linux Platform are registered for the notifications that are broadcast by Volume Services, and react accordingly. For instance:

• The CardInfo application interacts with the end user if a volume is mounted that needs to be formatted.
• The Media Cataloger scans newly mounted volumes for media files, adding them as appropriate to the catalog.
• The Bundle Manager looks through newly mounted volumes for applications and files.

Applications that work with data on removable media or that interact with devices that can be removed will want to register for these notifications as well. In particular, applications will want to note volume and/or device removed notifications, so that they don't attempt to access data or interact with a device that has been removed.

Notifications ^TOP^

Volume Services broadcasts the following notifications at the appropriate times:

ALP_NOTIFY_EVENT_VOLUME_ADDED

A card has been inserted and the volumes on it have been mounted.

ALP_NOTIFY_EVENT_VOLUME_REMOVED

A card with mounted volumes has been removed.

ALP_NOTIFY_EVENT_DEVICE_ADDED

A card has been inserted that is either blank or the file system on it was not recognized. This notification is broadcast whenever a removable storage object appears that is not mounted as a volume.

ALP_NOTIFY_EVENT_DEVICE_REMOVED

A card was removed that did not contain mounted file systems.

Each notification is accompanied by the UDI (Unique Device Identifier) of the added or removed device.

When a card containing mounted volumes is removed, Volume Services only broadcasts a "volume removed" notification. It does not broadcast a "device removed" notification. When a card that contains no mounted volumes is removed, only a "device removed" notification is broadcast.

Functionality Exposed by Volume Services ^TOP^

Volume Services exposes a small set of functions that can be used to manipulate and get information about removable volumes. Because most applications are only interested in noting when volumes are mounted and unmounted (which they do by registering for the appropriate notifications), the Volume Services functions are typically only used by a small set of applications: those interested in managing plug-in cards (such as CardInfo) and other special-purpose applications.

Manipulating Volumes ^TOP^

Explicit volume mounting and unmounting is done through the use of the alp_volumesvcs_mount() and alp_volumesvcs_unmount() functions. These functions cause the appropriate notifications to be broadcast when successful.

alp_volumesvcs_makefs() initializes a volume, creating a partition table with a single partition and putting a new file system on that partition on it. The newly initialized volume is then mounted. It is important to note that this function only initializes the volume with a single partition, and no function is provided that can create additional partitions. Although ACCESS Linux Platform supports removable media organized into multiple partitions, the media must have been formatted on a system that does such. Also note that if you use this function to initialize a device that currently contains multiple partitions, all data on all partitions is destroyed, and the device is reinitialized with a single partition. Finally, to get a list of filesystem types that can be used to format the volume, call alp_volumesvcs_fstypes(). Note that ACCESS Linux Platform may be able to mount preformatted filesystems of a type not included in the list returned from this function; the list you get back from alp_volumesvcs_fstypes() is simply the set of filesystems that can be used to format a volume on a given ACCESS Linux Platform device.

To rename a volume, call alp_volumesvcs_rename_volume(). This function can be called whether or not the specified volume is mounted; if necessary, the volume is unmounted before being renamed. Whether or not it was mounted prior to being renamed, the newly named volume is mounted when this function returns.

One final function, alp_volumesvcs_bind(), is handy when testing your volume manipulation code. This function mounts a directory as if it were a file system and generates a "volume added" notification. Unmounting the UDI associated with a bound directory will similarly cause a "volume removed" notification to be broadcast. (But note that the process of unmounting a bound directory does not cause the appropriate entry to be removed from the array of file system info blocks that is maintained by Volume Services. This entry will only be removed from the array when Volume Services is restarted—typically, when the ACCESS Linux Platform device is restarted.)

File System Info Blocks ^TOP^

Volume Services maintains an array of all pluggable devices. This array does not include the root file system and any other internal mounted file systems, such as /var or /sys. If no slot is present, the array will contain no elements. The array does include entries for empty slots—slots into which removable media (such as an SD card) could be inserted but at present is not.

While some of the information about a slot (such as its name or the path to the slot) can be obtained from Global Settings, Volume Services provides two functions that allow you to quickly and easily obtain a wealth of information about a slot and about a device that may be inserted into that slot. These functions return either all or one of the elements of the array of pluggable devices maintained by Volume Services.

You can obtain the complete set of elements by calling alp_volumesvcs_fsinfo_array().This function returns a pointer to a GArray, each element of which is an AlpVolumeSvcsFSinfo structure. This structure contains a great deal of information about the device, and, if it is mounted, about the volume. Included is information about the type of device, the volume label, a unique ID, and the amount of space both used and available. One structure element, fs_path, is particularly useful: it is a string containing a path to the volume's root (if the device's storage is accessible as a file system).

If you are looking for a particular entry, you have two options:

• You can obtain the entire array using alp_volumesvcs_fsinfo_array() and then search the array for the desired entry.
• You can obtain just the one entry corresponding to a supplied UDI, by calling alp_volumesvcs_fsinfo_for_udi(). The UDI is included as part of a "volume added" or "device added" notification.

Note that you must explicitly free the entries that you receive (and the GArray, if you used alp_volumesvcs_fsinfo_array()) once you are done with them. If you obtained a single entry from alp_volumesvcs_fsinfo_for_udi(), free it with alp_volumesvcs_fsinfo_free(). If you have an entire GArray of AlpVolumeSvcsFSinfo structures, you need to free each structure as well as the GArray itself. You can do this in one easy step by calling alp_volumesvcs_fsinfo_array_free().

The slot Field

The AlpVolumeSvcsFSinfo structure's slot field identifies the hardware location of a device. This field is particularly useful on devices that have more than one slot; it allows an application to distinguish between the slots. Each slot shows up as an entry in the array of AlpVolumeSvcsFSinfo structures, whether or not a device is inserted into that slot.

The slot field points to a character string that names the slot. This name is assigned by the device manufacturer and could be, for instance, "Expansion card". For an entry representing a directory mounted as a file system using alp_volumesvcs_bind(), the slot is set to the string "Internal".

AlpVolumeSvcsFSinfo Field Combinations

Depending upon whether or not a device is inserted into a slot, whether or not that device has a filesystem, and whether or not the filesystem is mounted, the udi, dev_path, and name fields in the AlpVolumeSvcsFSinfo structure are set to particular strings or to NULL. By examining the combination of these three fields, you can determine the status of a particular slot. Table 15.1, below, shows how to interpret the various combinations of udi, fs_path, and name fields.

Table 15.1  AlpVolumeSvcsFSinfo field combinations Ā