Legacy Document

Inside Macintosh: Files /

Chapter 4 - Alias Manager / Using the Alias Manager

Resolving Alias Records

The Alias Manager provides two functions that you can use to resolve alias records:

• the high-level function ResolveAlias, which performs a fast search and identifies only one target
• the low-level function MatchAlias, which can perform a fast search, an exhaustive search, or both and which can return a list of target candidates

In general, when you want to identify only the single most likely target of an alias record, you call ResolveAlias. You call MatchAlias when you want your program
to control the search.

Identifying a Single Target

To resolve an alias record, you usually call the ResolveAlias function. This function performs a fast search (described earlier in "Fast Searches" on page 4-7) and exits after it identifies one target. The ResolveAlias function compares some key information about the identified target with the information stored in the alias record. If any of the information is different, ResolveAlias automatically updates the record.

Note

Like all other Alias Manager functions, ResolveAlias updates the record only in memory. Your application is responsible for updating alias records stored on disk when appropriate.

In the dictionary example illustrated in Figure 4-1 on page 4-6, the application calls ResolveAlias with a relative path specification when the user runs the spelling checker on a document with a customized dictionary. If you provide a relative starting point, ResolveAlias performs the relative search first.

The ResolveAlias function reports, in the wasChanged parameter, whether it updated the alias record. After ResolveAlias runs, the value of wasChanged is TRUE if the record was updated and FALSE if it was not. If you are storing the alias record, check the value of wasChanged (as well as the function's result code) to see whether to update the stored record after resolving an alias.

If ResolveAlias can't resolve the alias record, it returns a nonzero result code. A result code of fnfErr signals that ResolveAlias has found the correct volume and parent directory but not the target file or folder. In this case, ResolveAlias constructs a valid FSSpec record that describes the target. You can use this record to explore possible solutions to the resolution failure. You can, for example, pass the FSSpec record to the File Manager function FSpCreate to create a replacement for a missing file.

Identifying Multiple Targets

The MatchAlias function is a low-level routine that gives your application control over the search algorithms.

You can control

• whether to attempt an automatic mounting of unmounted volumes
• whether to search on more than one volume
• whether to perform a fast search, an exhaustive search, or both
• what the order of the absolute and relative searches in a fast search should be
• whether to pursue search strategies that require interaction with the user (such as asking for a password while mounting an AppleShare volume)

You can also specify a maximum number of candidates that MatchAlias can identify. For details about controlling a search with the MatchAlias function, see its description beginning on page 4-20.

You can supply an optional filter function that MatchAlias calls

• each time it identifies a possible match
• when three seconds have elapsed without a match

The filter function determines whether each candidate is added to the list of possible targets. It can also terminate the search. See "Filtering Possible Targets" on page 4-25
for a description of the filter function.

The MatchAlias function returns, in an array of file system specification records, all candidates that it identifies.