Alias Manager

The Alias Manager is the part of the Operating System that helps you to locate specified files, directories, or volumes at a later time. It stores certain information about the target object in an alias record. When you later want the Alias Manager to find the target, you pass it the alias record and other information regarding the type of search to perform. Sometimes, the Alias Manager can find the original file. In other cases, the Alias Manager builds a list of potential matches and allows you (or the user) to select the desired file.

The Alias Manager creates and resolves (that is, finds the targets of) alias records. In general, you should use the Alias Manager to create an alias record whenever you find yourself storing a specific file description, such as filename and parent directory ID. The Alias Manager stores this information and more in the alias record, and it also provides a set of search strategies for resolving the record later. You can use the Alias Manager to create, resolve, and (if necessary) update alias records. You can also obtain information about the target of an alias record without actually resolving the alias record.

The Alias Manager can track files and directories across volumes. If the target of an alias record is on an unmounted AppleShare volume, the Alias Manager automatically mounts the volume when it resolves the alias. If the target object is on an unmounted ejectable volume, the Alias Manager prompts the user to insert the volume.

When the Alias Manager creates an alias record, it allocates the storage, fills in the record, and returns a handle to it. Your application is responsible for storing the record and retrieving it when needed.

Alias Records

An alias record is a data structure that describes a file, directory, or volume. The record contains

  • location information, such as name and parent directory ID
  • verification information, such as creation date, file type, and creator
  • volume mounting information (that is, server and zone), if applicable

By storing alias records, you can allow your users to create a robust connection to a file— that is, a connection that can survive the moving or renaming of the target file. The Finder introduced in system software version 7.0, for example, stores alias records in aliases created by the user to represent other files or folders. The Edition Manager uses alias records to support data sharing among separate documents.

An alias record is a reliable way to identify a file system object when your application is communicating with a process that might be running on a different machine.

The creation of an alias record has no effect on the target of the record, except to establish a file ID reference for the target file if one did not previously exist.

The alias record contains only two fields of public information available to your application. The bulk of the record is managed privately by the Alias Manager.

Your application can store, in the userType field, its own signature or any other data that fits into 4 bytes. When the Alias Manager creates an alias record, it stores 0 in that field.

The Alias Manager stores, in the aliasSize field, the size assigned to the record at the time of its creation. Knowing the starting size allows you to store and retrieve data of your own at the end of the record. An alias record is typically 200 to 300 bytes long.

Search Strategies

Some of the key features of the Alias Manager are the search strategies built into the alias-resolution functions. The search strategies are designed to find the original target of an alias record, even if the target has been moved, renamed, copied, or restored from backup. Which strategy you use to resolve a particular alias record usually depends on a number of factors, including whether you are willing to sacrifice time to find as many potential targets as possible and whether the target is known to be in a particular volume. This section describes the available search strategies.

You can request either a relative or an absolute search. If you request an absolute search, you can specify whether the search should be either fast or exhaustive. (A relative search is always a fast search.) As you can see, there are three general search strategies available to your application for resolving alias records:

  • relative search (always fast)
  • absolute fast search
  • absolute exhaustive search

The following sections describe these search strategies.

Relative Searches

During a relative search, the Alias Manager starts in a specified directory and searches for the target of an alias record by ascending the file system hierarchy to a predetermined common parent of the target and the starting directory and then descending the hierarchy from that common parent.

Suppose, for example, that you are writing a word-processing application that allows the user to build a customized, supplemental dictionary for each document. You might create the dictionary as a separate document in the same directory as the document it serves. In this case, the common parent of the document and the dictionary file (that is, the lowest-level directory that appears in the pathnames of both) is simply the directory containing both files.

To resolve an alias record using a relative search, the Alias Manager needs several pieces of information, which are recorded in the alias record at the time you create it. The Alias Manager needs a relative path, that is, a path to the target from another file or directory on the same volume. (Relative paths don’t work across volumes.) To record a relative path, the Alias Manager saves the distances from the target and the starting file or directory to their common parent. The Alias Manager can later use those distances in conjunction with the full pathname to conduct a relative search.

When resolving the alias record by using a relative path, the Alias Manager looks at the directory at the specified distance above the starting file or directory. The Alias Manager then constructs a partial pathname by extracting one field of the absolute pathname for each step from the target to the common parent.

Absolute Searches

In contrast to a relative search, an absolute search always begins at the root directory of the file system hierarchy and always descends the hierarchy. The first step in any absolute search is to identify the volume on which the target resides. When conducting a volume search, the Alias Manager considers the volume’s name, its creation date (which acts almost as a unique identifier for a volume), and its type (for example, a hard disk, a 3.5-inch floppy disk, or an AppleShare volume).

The Alias Manager first looks for a volume that matches all three criteria: name, creation date, and type. The search succeeds if the volume is mounted and if its name and creation date have not changed since the record was created. If the search fails, the Alias Manager attempts to match by creation date and type only. This step locates volumes that have been renamed. Finally, the Alias Manager attempts to match by volume name and type only.

If the target is on an unmounted AppleShare volume, the Alias Manager attempts to mount the volume. It presents a name and password dialog box if appropriate. If the target is on an unmounted ejectable volume, the Alias Manager displays a dialog box prompting the user to insert the volume. Your application can suppress the automatic mounting, as explained in the description of the MatchAlias function.

In some circumstances, a relative search identifies the correct target when an absolute search cannot. For example, suppose the user of your word-processing application creates a working copy of a document and dictionary by copying the entire folder Sample to another disk. The user later updates the original document and dictionary by copying the folder from the working disk. All of the underlying file and directory identifications change, but the filenames and relative path remain the same. When the user later runs the spelling checker on the document, a relative-path search finds the correct target dictionary.

Fast Searches

A fast search employs an algorithm designed to find the target of an alias record quickly. Depending on how you invoke it, the fast-search algorithm starts with either a relative search or an absolute search. The Alias Manager can perform a relative fast search whether or not it has identified the target volume, but it cannot perform an absolute fast search unless the volume has been identified.

During an absolute fast search, the Alias Manager first searches by file ID (if the target is a file) or directory ID (if the target is a directory). (File IDs and directory IDs are described in the chapter “File Manager” in this book.) Even if a file has been renamed or moved on a volume, the Alias Manager can find it quickly through its file ID.

If the search by file ID or directory ID fails, the Alias Manager searches by name in the original parent directory. This search locates the target if its file or directory ID has changed but it still exists by the same name in the parent directory (for example, if the target was restored from a backup). The Alias Manager compares file numbers of files found by name in the correct parent directory. If the file numbers do not match, the file is treated as a possible match—that is, it is put on the list of candidates—and the search continues. If the target is not found by name in the parent directory, the Alias Manager looks for a file by file number in the parent directory. A file with the same file number but a different name replaces a file with the same name but a different file number in the list of matches.

If the search by file ID or directory ID fails and if the Alias Manager cannot find the original parent directory, it searches for the target by full pathname. This search succeeds if the target resides in the same location on the volume but the directory ID of its parent directory has changed (for example, if the entire parent directory was restored from a backup).

If the search by full pathname fails, the Alias Manager attempts to find the file by tracing partial pathnames up through all parent directories, using parent directory IDs instead of directory names. For example, consider this full pathname:

MyDisk:Fruits:Tropical:Ackees

If the search by full pathname fails, Alias Manager first looks for the partial pathname “:Ackees” in the directory with the ID that the directory “MyDisk:Fruits:Tropical” had when the alias record was created. If that search fails, it looks for “:Tropical:Ackees” in the directory with the ID that “MyDisk:Fruits” had, and so on.

If you do not ask for a search by relative path first but do provide a starting point for a relative search, and if the alias record contains relative path information, the Alias Manager performs a relative search after the absolute search. The relative search succeeds if the relative path is the same as when the record was created and if the names of the target and its intervening parent directories have not changed.

Exhaustive Searches

An exhaustive search uses an algorithm that scans an entire volume to look for possible matches. The Alias Manager typically performs an exhaustive search by calling the File Manager function PBCatSearch, searching for files or directories with a matching creation date, creator, and type.

The PBCatSearch function is available only on volumes that support the HFS routines and only on systems running system software version 7.0 and later. When PBCatSearch is not available, an exhaustive search of the entire volume is performed by making a series of indexed File Manager calls, searching for objects with matching creation date, type, creator, or file number.

See Also