All Databases Inside Mac - Basic Toolbox

MatchAlias

Identify a list of possible matches

#include <Aliases.h> Alias Manager

OSErr MatchAlias( fromFile, rulesMask, alias, aliasCount, aliasList,

needsUpdate, aliasFilter, yourDataPtr);

FSSpec * fromFile ; the starting point for a relative path

unsigned long rulesMask ; a set of rules to guide the resolution

AliasHandle alias ; a handle to the AliasRecord to be resolved

short * aliasCount ; maximum number of possible matches

FSSpecArrayPtr aliasList ; points to the array that holds the search

results

Boolean *needsUpdate ; a signal to your application

AliasFilterProcPtr aliasFilter ; points to a filter function

Ptr yourDataPtr ; points to data your application might need

returns Error Code; 0=no error

You use the MatchAlias function to identify a list of possible matches and

pass the list through an optional selection filter. The filter can pass more than

one possible match.

fromFile represents 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 (FSSpec )record that describes the

starting point for the search.

rulesMask specifies a set of rules to guide the resolution. Pass the sum of all of

the rules you want to invoke. (See below for a list of constants and

their descriptions.)

alias is a handle to the AliasRecord to be resolved.

aliasCount is the address of a short. 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 to

create a replacement for a missing file with the File Manager

function FSpCreate.

aliasList points to the array that holds the results of the search.

needsUpdate 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

MatchAlias 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

a direct search or an exhaustive search. Otherwise, MatchAlias 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 AliasRecord to

reflect the final results of the resolution, call UpdateAlias .

aliasFilter 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 the Notes

sectionbelow for a description of the filter function

yourDataPtr can point to any data that your application might need in the filter

function. Use the myDataPtr parameter to pass global or local data to

your filter function

Returns: an operating system Error Code.

noErr (0) No error

nsvErr (-35) The volume is not mounted

fnfErr (-43) Target not found, but volume and parent directory

found; if aliasCount is 1, target parameter contains a

valid FSSpec record

paramErr (-50) Target, alias, or both are NIL, or the AliasRecord

is corrupt

usrCanceledErr (-128) The user canceled the operation

Notes: MatchAlias resolves the AliasRecord specified by the alias parameter,

following the rules specified by the rulesMask parameter, and returns a

list of possible candidates in the structure specified by the aliasList

parameter. MatchAlias places the number of candidates identified in the

aliasCount parameter.

The constants and their descriptions for the rulesMask paramater are as

follows:

Constant Description

kARMSearch Perform a fast search for the alias target.

If kARMSearchRelFirst is not set, perform a direct search

first, followed by a relative search only if 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.

PBCatSearch 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 one or both of kARMSearch

and kARMSearchRelFirst, MatchAlias performs the fast

search first.

kARMSearchRelFirst If kARMSearch is also set, perform a relative search before

the direct search. (If kARMSearch is also set and the target

is found through the direct 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.

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

mounted.

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 AliasRecord. 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 AliasRecord created by

NewAliasMinimalFromFullpath, MatchAlias ignores

this flag.

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.

You must specify at least one of the first three parameters:

kARMSearch, kARMSearchMore, and kARMSearchRelFirst.

You must specify at least one of the first three constants: kARMSearch,

kARMSearchMore, and kARMSearchRelFirst.

You can write your own filter function to examine possible targets

identified by the MatchAlias function. MatchAlias calls your filter

function each time it identifies a possible match and when three seconds

have elapsed without a match. The filter function takes three parameters

and returns a Boolean value. It should look like this:

Boolean MyMatchAliasFilter (CInfoPBPtr cpbPtr, Boolean *quitFlag, Ptr

myDataPtr)

{

if (cpbPtr == NIL)

// Terminate search?

//*quitFlag = TRUE;

else

// Do your examination of possible targets here

}

The cbPtr parameter points to the catalog information parameter block

record (as returned by the File Manager function PBGetCatInfo) of the

possible match. MatchAlias sets this parameter to NIL if it is calling your

function to give it a periodic change to terminate search. (Do not use this

parameter without checking for NIL.

Set the quitFlag parameter to terminate the search.

The myDataPtr parameter points to any customized data that your

application passed when it called MatchAlias. This parameter allows you

to access any data that your application has set up on its own.

The Boolean return value determines whether the possible match is

discarded (TRUE) or added to the possible list of targets (FALSE).

Referenced by (8):