Legacy Document

Inside Macintosh: Files /

Chapter 4 - Alias Manager / Alias Manager Reference

Alias Manager Routines / Resolving and Reading Alias Records

MatchAlias

You use the MatchAlias function to identify a list of possible matches and pass the list through an optional selection filter. The filter can return more than one possible match.

FUNCTION MatchAlias (fromFile: FSSpecPtr; rulesMask: LongInt;
                     alias: AliasHandle; VAR aliasCount: Integer;
                     aliasList: FSSpecArrayPtr; 
                     VAR needsUpdate: Boolean; 
                     aliasFilter: AliasFilterProcPtr;
                     yourDataPtr: UNIV Ptr): OSErr;

fromFile

The starting point for a relative search. If you do not want MatchAlias to perform a relative search, set fromFile to NIL. If you want MatchAlias to perform a relative search, pass a pointer to a file system specification record that describes the starting point for the search.

rulesMask

A set of rules to guide the resolution. Pass the sum of all of the rules you want to invoke.

alias

A handle to the alias record to be resolved.

aliasCount

On input, the maximum number of possible matches to return. On output, the actual number of matches returned.

aliasList

A pointer to the array that holds the results of the search.

needsUpdate

A Boolean flag that indicates whether the alias record to be resolved needs to be updated.

aliasFilter

An application-defined filter function.

yourDataPtr

A pointer to data to be passed to the filter function.

DESCRIPTION

The MatchAlias function resolves the alias record specified by the alias parameter, following the rules specified by the rulesMask parameter. Then it returns, in the structure specified by the aliasList parameter, a list of possible candidates. The MatchAlias function places, in the aliasCount parameter, the number of
candidates identified.

You specify the matching criteria by passing a sum of these constants in the
rulesMask parameter.

CONST
   kARMMountVol         =  $00000001;{mount volume automatically}
   kARMNoUI             =  $00000002;{suppress user interface}
   kARMMultVols         =  $00000008;{search on multiple volumes}
   kARMSearch           =  $00000100;{do a fast search}
   kARMSearchMore       =  $00000200;{do an exhaustive search}
   kARMSearchRelFirst   =  $00000400;{do a relative search first}

Constant descriptions

kARMMountVol

Automatically try to mount the target's volume if it is not
mounted.

kARMNoUI

Stop if a search requires user interaction, such as a password dialog box when mounting a remote volume. If user interaction is needed and kARMNoUI is in effect, the search fails.

kARMMultVols

Search all mounted volumes. The search begins with the volume on which the target resided when the record was created. When you specify a fast search of all mounted volumes, MatchAlias performs a formal fast search only on the volume described in the alias record. On all other volumes it looks for the target by ID or by name in the directory with the specified parent directory ID. When you specify an exhaustive search of multiple volumes, MatchAlias performs the same search on all volumes. When resolving an alias record created by NewAliasMinimalFromFullPath, MatchAlias ignores this flag.

kARMSearch

Perform a fast search for the alias target. If kARMSearchRelFirst is not set, perform an absolute search first, followed by a relative search only if the value of the fromFile parameter is not NIL and the list of matches is not full.

kARMSearchMore

Perform an exhaustive search for the alias target. On HFS volumes, the exhaustive search uses the File Manager function PBCatSearch to identify candidates with matching creation date, type, and creator. The PBCatSearch function is available only on HFS volumes and only on systems running version 7.0 or later. On MFS volumes or HFS volumes that do not support PBCatSearch, the exhaustive search makes a series of indexed calls to File Manager functions, using the same search criteria. If you set kARMSearchMore and either or both of kARMSearch and kARMSearchRelFirst, MatchAlias performs the fast search first.

kARMSearchRelFirst

If kARMSearch is also set, perform a relative search before the absolute search. (If kARMSearch is also set and the target is found through the absolute search, MatchAlias sets the needsUpdate flag to TRUE.) If neither kARMSearch nor kARMSearchMore is set, perform only a relative search. If kARMSearch is not set but kARMSearchMore is set, perform a relative search followed by an exhaustive search.

You must specify at least one of the last three parameters: kARMSearch, kARMSearchMore, and kARMSearchRelFirst.

Your application can specify a maximum number of possible matches by setting the aliasCount parameter. MatchAlias changes the aliasCount parameter to the
actual number of candidates identified. If MatchAlias finds the parent directory on the correct volume but does not find the target, it sets the aliasCount parameter to 1, puts the file system specification record for the target in the results list, and returns fnfErr. The FSSpec record is valid, although the object it describes does not exist. This information is intended as a "hint" that lets you explore possible solutions to the resolution failure. You can, for example, use the FSSpec record and the File Manager function FSpCreate to create a replacement for a missing file.

The needsUpdate flag is a signal to your application that the record might need to be updated. After it identifies a target, MatchAlias compares some key information about the target with the same information in the record. If the information does not match, MatchAlias sets the needsUpdate flag to TRUE. The key information is

• the name of the target
• the directory ID of the target's parent
• the file ID or directory ID of the target
• the name and creation date of the volume on which the target resides

The MatchAlias function also sets the needsUpdate flag to TRUE if it identifies a list of possible matches rather than a single match or if kARMsearchRelFirst is set but the target is identified through either an absolute search or an exhaustive search. Otherwise, the MatchAlias function sets the needsUpdate flag to FALSE. MatchAlias always sets the needsUpdate flag to FALSE when resolving an alias created by NewAliasMinimal. If you want to update the alias record to reflect the final
results of the resolution, call UpdateAlias.

The aliasFilter parameter points to a filter function supplied by your application. The Alias Manager executes this function each time it identifies a possible match and after the search has continued for three seconds without a match. Your filter function returns a Boolean value that determines whether the possible match is discarded (TRUE) or added to the list of possible targets (FALSE). It can also terminate the search by setting the variable parameter quitFlag. See "Filtering Possible Targets" on page 4-25 for a description of the filter function.

The yourDataPtr parameter can point to any data that your application might need in the filter function.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for MatchAlias are

Trap macro	Selector
_AliasDispatch	$0005

RESULT CODES

noErr	0	No error
nsvErr	-35	The volume is not mounted
fnfErr	-43	Target not found, but volume and parent directory found
paramErr	-50	The value of the target or alias parameter, or both, is NIL, or the alias record is corrupt
usrCanceledErr	-128	The user canceled the operation