Technical Q&A QA1491

Volumes Not Showing Up On The Desktop

Q: I'm writing a custom file system (VFS plug-in). I can mount my volume just fine at the BSD level, but its icon doesn't show up on the desktop. How can I make my file system's volumes show up on the desktop?

A: If you're developing a local file system (using the terminology from Technical Q&A QA1242, 'Developing for VFS'), you need to create a file system bundle and install it in /System/Library/Filesystems. The file system bundle format is not formally documented (r. 3524590), but you can look at Sample Code Project 'MFSLives' for an example. For a local file system, a valid file system bundle (including the embedded utility and mount tools) is sufficient for the system to probe and mount your file system, and for your volumes to automatically appear on the desktop.

This is, however, not sufficient for a network file system. A network file system must have a file system bundle (this allows the Finder to show the correct localized name in the Format field of the Get Info window), but that's not sufficient for your volumes to show up on the desktop automatically. For a network file system, the user typically does some explicit operation to mount a volume. For the built-in network file systems (AppleShare, SMB, and so on), the users mounts a volume using the Connect to Server dialog in the Finder, or by browsing /Network. There is currently no way for third party network file systems to integrate into these standard locations. See Technical Q&A QA1387, 'Integrating With The Connect to Server Dialog' for the details.

If you follow the advice from that document and create your own mounting application, your volumes will still not show up on the desktop. You must explicitly notify the sytem when you mount a new volume. The mechanism for doing this is documented below.

In this context a cluster file system works the same way as a network file system.

New Volume Mount Notification

When you mount a new network volume, you must tell the system about it. You do this by calling the DiskArbitration routine DiskArbDiskAppearedWithMountpointPing_auto. This routine isn't part of the standard DiskArbitration framework headers, so you have to declare your own prototype for it. The correct prototype is shown in Listing 1.

Listing 1: DiskArbDiskAppearedWithMountpointPing_auto prototype

extern kern_return_t DiskArbDiskAppearedWithMountpointPing_auto(
    char *   disk,
    unsigned flags,
    char *   mountpoint
) __attribute__((weak_import));

enum {
    kDiskArbDiskAppearedEjectableMask              = 1 << 1,
    kDiskArbDiskAppearedNetworkDiskMask            = 1 << 3
};

The parameters to this routine are:

• disk is the device on which the disk is mounted. In the case of a network volume, you can use any unique string. However, it must match the f_mntfromname value returned by statfs for your volume.

• flags must be kDiskArbDiskAppearedEjectableMask | kDiskArbDiskAppearedNetworkDiskMask.

• mountpoint is an absolute path to the directory on which the volume is mounted. Typically this is a unique subdirectory that you create within /Volumes.

This routine is part of the old (pre-Mac OS X 10.3), private, DiskArbitration framework interface. When we introduced a new, public DiskArbitration interface in Mac OS X 10.3, we didn't introduce a replacement for this routine because, in the long term, DiskArbitration will automatically learn about new network volumes by way of a kernel notification. So, ultimately, you won't need to call this routine for your volume to appear on the desktop. For that reason, we strongly recommend that you weak link against this symbol and, if it's not present, just don't call it.

Finally, because you're calling the old, private DiskArbitration framework interface, you have to explicitly initialize that interface. You do this by calling DiskArbInit, the prototype of which is given in Listing 2. If you fail to do this, it's likely that DiskArbDiskAppearedWithMountpointPing_auto will fail with an error code of 5 (KERN_FAILURE).

Listing 2: DiskArbInit prototype

extern kern_return_t DiskArbInit(void) __attribute__((weak_import));

As with DiskArbDiskAppearedWithMountpointPing_auto, you should weak link to this routine and not call it if it's not present.

Back to Top 

Document Revision History

Posted: 2006-12-20