Framework | CoreServices/CoreServices.h |
Declared in | Aliases.h |
The Alias Manager creates and resolves alias records, which are data structures that describe file system objects (files, directories, and volumes.) An alias record contains a "fingerprint" of a file system object. You can store the alias record instead of a file system reference, and use the Alias Manager to find the object again when it's needed. The Alias Manager contains algorithms for locating objects that have been moved, renamed, copied, or restored from backup.
The exact makeup of an alias record depends on the file system in which the object resides. The Alias Manager takes advantage of persistent object ids, creation dates, file types, creator codes and the like if they are available. By default, an object at the location stored in the alias record will be considered a stronger match than an object with the same file id in a different location. (You can alter this behavior by passing flags to the functions that resolve the alias.)
The Alias Manager supports two types of alias records. The standard alias contains as much information as the Alias Manager can gather from the underlying file system. The minimal alias only stores a subset of the information in a standard alias record. A minimal alias may be used when the object is unlikely to move, the reference is to be short-lived, or space is a critical issue (the exact space savings depends on the underlying file system format.) The standard alias is the preferred format because it is more robust.
The Finder supports the creation and use of alias files that contain alias records. Currently, Mac OS X does not provide a way for other applications to create these alias files. The Alias Manager can identify and resolve Finder alias files, but it cannot create them.
FSNewAlias
FSNewAliasUnicode
FSNewAliasFromPath
FSNewAliasMinimal
FSNewAliasMinimalUnicode
FSUpdateAlias
FSCopyAliasInfo
FSMatchAliasBulk
FSResolveAlias
FSResolveAliasWithMountFlags
FSMatchAlias
Deprecated in Mac OS X v10.5
FSMatchAliasNoUI
Deprecated in Mac OS X v10.5
Alias Manager functions that use the FSSpec
data type have been deprecated. Instead, you should use the equivalent FSRef
–based functions, which include support for features such as unicode and long filenames. For more information on FSSpec
and FSRef
types, see File Manager Reference.
GetAliasInfo
Deprecated in Mac OS X v10.3
FollowFinderAlias
Deprecated in Mac OS X v10.5
MatchAliasNoUI
Deprecated in Mac OS X v10.5
ResolveAliasFileWithMountFlags
Deprecated in Mac OS X v10.5
IsAliasFile
Deprecated in Mac OS X v10.4
MatchAlias
Deprecated in Mac OS X v10.4
NewAlias
Deprecated in Mac OS X v10.4
NewAliasMinimal
Deprecated in Mac OS X v10.4
NewAliasMinimalFromFullPath
Deprecated in Mac OS X v10.4
ResolveAlias
Deprecated in Mac OS X v10.4
ResolveAliasFile
Deprecated in Mac OS X v10.4
ResolveAliasFileWithMountFlagsNoUI
Deprecated in Mac OS X v10.4
ResolveAliasWithMountFlags
Deprecated in Mac OS X v10.4
UpdateAlias
Deprecated in Mac OS X v10.4
Disposes of a universal procedure pointer (UPP) to an alias filtering callback function.
void DisposeAliasFilterUPP ( AliasFilterUPP userUPP );
The UPP to dispose of.
See AliasFilterProcPtr
for more information on alias filtering callback functions.
Aliases.h
Returns information from an alias handle.
OSStatus FSCopyAliasInfo ( AliasHandle inAlias, HFSUniStr255 *targetName, HFSUniStr255 *volumeName, CFStringRef *pathString, FSAliasInfoBitmap *whichInfo, FSAliasInfo *info );
A handle to the alias record from which to get information.
A pointer to a string that, on return, contains the name of the target item. Pass NULL
if you do not want this information returned.
A pointer to a string that, on return, contains the name of the volume the target resides on. Pass NULL
if you do not want this information returned.
A pointer a CFString that, on return, contains the POSIX path to the target. Pass NULL
if you do not want this information returned.
A pointer to a variable of type FSAliasInfoBitmap
. On return, this field indicates which fields in the alias information block, specified in the info
parameter, contain valid data. See “Alias Information Masks” for a description of the values that may be returned here. This parameter may be NULL
.
A pointer to a structure of type FSAliasInfo
. On return, this structure contains information about the alias. Pass NULL
if you do not want this information returned.
A result code.
This function returns the requested information from the alias handle passed in the inAlias parameter. The information is gathered only from the alias record, so it may not match what is on disk. No disk input/output is performed.
The FSCopyAliasInfo
function adds support for unicode filenames and filenames longer than 32 bytes. It replaces the GetAliasInfo
function.
Aliases.h
Resolves an alias record obtained from a Finder alias file.
OSErr FSFollowFinderAlias ( FSRef *fromFile, AliasHandle alias, Boolean logon, FSRef *target, Boolean *wasChanged );
A pointer to the file to use for a first attempt at a relative resolution; pass a pointer to the alias file's FSRef
for this parameter.
A handle to the alias record taken from the alias file's resources.
If true
, the Alias Manager attempts to mount a volume if necessary to complete the resolution of the alias.
A pointer to an FSRef
structure. On return, this FSRef
refers to the target found by the resolution.
A pointer to a Boolean value. FSFollowFinderAlias
sets this value to true
if it has updated the alias record.
A result code.
Aliases.h
Determines whether a file system object is an alias file, a data file, or a folder.
OSErr FSIsAliasFile ( const FSRef *fileRef, Boolean *aliasFileFlag, Boolean *folderFlag );
A pointer to the file system object to test.
A pointer to a Boolean variable. On return, a value of TRUE
indicates that the object specified in the fileRef parameter is an alias file. A value of FALSE
indicates that the object is not an alias file.
A pointer to a Boolean variable. On return, a value of TRUE
indicates that the object specified in the fileRef parameter is a folder. A value of FALSE
indicates that the object is a file.
A result code.
Table 1 summarizes the information that this function provides about the object specified in the fileRef
parameter:
Alias flag |
Folder flag |
Object kind |
---|---|---|
T |
F |
Alias file |
F |
F |
Data file |
F |
T |
Folder |
Note that if fileRef
is an alias file, this function does not provide any information about the object to which the alias refers. To find out whether this object is a file or a folder, you can use FSResolveAliasFile
.
Aliases.h
Identifies a list of possible matches for an alias.
OSStatus FSMatchAliasBulk ( const FSRef *fromFile, unsigned long rulesMask, AliasHandle inAlias, short *aliasCount, FSRef *aliasList, Boolean *needsUpdate, FSAliasFilterProcPtr aliasFilter, void *yourDataPtr );
A pointer to the starting point for a relative search. You may pass NULL
if you do not want this function to perform a relative search. By default, this function performs a relative search only if the absolute search does not find a match. If you want to perform the relative search first, you should pass kARMSearchRelFirst
in the rulesMask
parameter.
A set of rules to guide the resolution. Pass the sum of all of the rules you want to invoke. For a description of the values you can use in this parameter, see “Matching Constants.”
A handle to the alias record to be resolved.
On input, a pointer to the maximum number of possible matches to return. On output, the actual number of matches returned.
A pointer to an array of FSRef
structures. On output, this array holds the results of the search, a list of possible candidates.
A pointer to a Boolean flag that, on output, indicates whether the alias record needs to be updated. For more information about this parameter, see the Discussion.
An optional application-defined filter function. The Alias Manager calls your filter function each time it identifies a possible match or 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 FSAliasFilterProcPtr
for a description of the filter function.
A pointer to data to be passed to the filter function, or NULL
. The yourDataPtr
parameter can point to any data your application might need in the filter function.
A result code. If the Alias Manager finds the specified volume and parent directory but fails to find the target file or directory in that location, the return value is fnfErr
and the elements in the aliasList
parameter are not valid.
After it identifies a target, this function compares some key information about the target with the same information in the record. If the information does not match, this function sets the needsUpdate flag to true
. This 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 in the rulesMask parameter but the target is identified through either an absolute search or an exhaustive search. Otherwise, this function sets the needsUpdate flag to false
. This function always sets the needsUpdate flag to false
when resolving an alias created by FSNewAliasMinimal
. To update the alias record to reflect the final results of the resolution, use the function FSUpdateAlias
.
Aliases.h
Creates a new alias record, given a target file or directory.
OSErr FSNewAlias ( const FSRef *fromFile, const FSRef *target, AliasHandle *inAlias );
A pointer to the starting point for a relative search. You may pass NULL
if you do not need relative search information in the alias record. The files or directories specified in the fromFile and target parameters must reside on the same volume.
A pointer to the target file or directory of the alias.
A pointer to an alias handle. On return, this handle refers to the newly created alias record. If the function fails to create an alias record, it sets inAlias to NULL
.
A result code. If the specified target is valid, this function creates an alias record for the target and returns noErr
. Any other return value indicates that this function did not create an alias record.
The FSNewAlias
function creates an alias record that describes the specified target. It allocates the storage, fills in the record, and puts a record handle to that storage in the inAlias parameter. FSNewAlias
records the full pathname of the target and a collection of other information relevant to locating the target, verifying the target, and mounting the target’s volume, if necessary. You can have FSNewAlias
store relative search information as well by supplying a starting point for a relative search.
Aliases.h
Creates a new alias record, given the pathname of the target file or directory.
OSErr FSNewAliasFromPath ( const char *fromFilePath, const char *targetPath, OptionBits flags, AliasHandle *inAlias, Boolean *isDirectory );
A C string that specifies the starting point for a relative search. The string should contain a UTF-8 pathname. You may pass NULL
if you do not need relative search information in the alias record.
A C string that contains the full UTF-8 pathname of the target object.
Reserved for future use. Currently, you should pass 0.
A pointer to an alias handle. On output, this handle refers to the newly created alias record.
A pointer to a Boolean value. On input, if the target does not exist, set the value to true
if the target is a directory or false
if it is not. (Pass NULL
if you are not sure whether the target is a directory.) On output, if the target exists, the value is true
if the target is a directory, false
if it is not.
A result code. For more information, see the Discussion.
If the specified target exists, this function creates an alias record for the target and returns noErr
. If the parent directory specified in the target pathname exists but the target itself does not exist, this function creates an alias record for the target and returns fnfErr
. Any other return value indicates that this function did not create an alias record.
Aliases.h
Creates a new minimal alias record, given a target file or directory.
OSErr FSNewAliasMinimal ( const FSRef *target, AliasHandle *inAlias );
A pointer to the target of the alias record.
A pointer to an alias handle. On return, this handle refers to the newly created alias record. If the function fails to create an alias record, it sets inAlias
to NULL
.
A result code. If the specified target is valid, this function creates an alias record for the target and returns noErr
. Any other return value indicates that this function did not create an alias record.
The FSNewAliasMinimal
function creates an alias record that contains only the minimum information necessary to describe the target. The FSNewAliasMinimal
function uses the standard alias record data structure, but it fills in only parts of the record.
The FSResolveAlias
function never updates a minimal alias record.
Aliases.h
Creates a minimal alias, given the Unicode name and parent directory of the target.
OSErr FSNewAliasMinimalUnicode ( const FSRef *targetParentRef, UniCharCount targetNameLength, const UniChar *targetName, AliasHandle *inAlias, Boolean *isDirectory );
A pointer to the parent directory of the target.
The number of Unicode characters in the target's name.
A pointer to the Unicode name of the target.
A pointer to an alias handle. On return, this handle refers to the newly created alias record.
A pointer to a Boolean value. On input, if the target does not exist, set the value to true
if the target is a directory or false
if it is not. (Pass NULL
if you are not sure whether the target is a directory.) On output, if the target exists, the value is true
if the target is a directory, false
if it is not.
A result code. For more information, see the Discussion.
If the specified target exists, this function creates an alias record for the target and returns noErr
. If the parent directory exists but the target itself does not exist, this function creates an alias record for the target and returns fnfErr
. Any other return value indicates that this function did not create an alias record.
Aliases.h
Creates a new alias record, given the Unicode name and parent directory of the target.
OSErr FSNewAliasUnicode ( const FSRef *fromFile, const FSRef *targetParentRef, UniCharCount targetNameLength, const UniChar *targetName, AliasHandle *inAlias, Boolean *isDirectory );
A pointer to the starting point for a relative search. You may pass NULL
if you do not need relative search information in the alias record.
A pointer to the parent directory of the target.
The number of Unicode characters in the target's name.
A pointer to the Unicode name of the target.
A pointer to an alias handle. On return, this handler refers to the newly created alias record.
A pointer to a Boolean value. On input, if the target does not exist, set the value to true
if the target is a directory or false
if it is not. (Pass NULL
if you are not sure whether the target is a directory.) On output, if the target exists, the value is true
if the target is a directory, false
if it is not.
A result code. For more information, see the Discussion.
If the specified target exists, this function creates an alias record for the target and returns noErr
. If the parent directory exists but the target itself does not exist, this function creates an alias record for the target and returns fnfErr
. Any other return value indicates that this function did not create an alias record.
Aliases.h
Returns an FSRef
to the single most likely target of an alias record.
OSErr FSResolveAlias ( const FSRef *fromFile, AliasHandle alias, FSRef *target, Boolean *wasChanged );
A pointer to the starting point for a relative search. If you pass NULL
in this parameter, FSResolveAlias
performs only an absolute search. If you pass a pointer to a valid FSRef
in the fromFile
parameter, FSResolveAlias
performs a relative search for the target, followed by an absolute search only if the relative search fails. If you want to perform an absolute search followed by a relative search, you should use the function FSMatchAliasBulk
.
A handle to the alias record to be resolved and, if necessary, updated.
A pointer to an FSRef
. On successful return, this FSRef
describes the target of the alias record. This parameter must point to a valid FSRef
structure.
A pointer to a Boolean value indicating, on return, whether the alias record in the alias parameter was updated because it contained some outdated information about the target. If it updates the alias record, FSResolveAlias
sets the wasChanged
parameter to true
. Otherwise, it sets it to false
. (FSResolveAlias
never updates a minimal alias, so it never sets wasChanged
to true
when resolving a minimal alias.
A result code. When it finds the specified volume and parent directory but fails to find the target file or directory in that location, FSResolveAlias
returns fnfErr
. Note that the FSRef
in the alias
parameter is not valid in this case.
The FSResolveAlias
function performs a fast search for the target of the alias. If the resolution is successful, FSResolveAlias
returns (in the target parameter) the FSRef
for the target file system object, updates the alias record if necessary, and reports (through the wasChanged parameter) whether the record was updated. If the target is on an unmounted AppleShare volume, FSResolveAlias
automatically mounts the volume. If the target is on an unmounted ejectable volume, FSResolveAlias
asks the user to insert the volume. The FSResolveAlias
function exits after it finds one acceptable target.
After it identifies a target, FSResolveAlias
compares some key information about the target with the information in the alias record. If the information differs, FSResolveAlias
updates the record to match the target.
The FSResolveAlias
function displays the standard dialogs when it needs input from the user, such as a name and password for mounting a remote volume. The user can cancel the resolution through these dialogs.
Aliases.h
Resolves an alias contained in an alias file.
OSErr FSResolveAliasFile ( FSRef *theRef, Boolean resolveAliasChains, Boolean *targetIsFolder, Boolean *wasAliased );
A pointer to the alias file you plan to open. If the function completes successfully, this FSRef
describes to the file or the directory referred to by the alias file.
A Boolean value. Set this parameter to TRUE
if you want FSResolveAliasFile
to resolve all aliases in a chain (for example, an alias file that refers to an alias file and so on), stopping only when it reaches the target file. Set this parameter to FALSE
if you want to resolve only one alias file, even if the target is another alias file.
A pointer to a Boolean value. The FSResolveAliasFile
function returns TRUE
in this parameter if the FSRef
in the parameter theRef
points to a directory or a volume; otherwise, FSResolveAliasFile
returns FALSE
in this parameter.
A pointer to a Boolean value. The FSResolveAliasFile
function returns TRUE
in this parameter if the FSRef
in the parameter theRef
points to an alias; otherwise, FSResolveAliasFile
returns FALSE
in this parameter.
A result code. When it finds the specified volume and parent directory but fails to find the target file or directory in that location, FSResolveAliasFile
returns fnfErr
.
If your application bypasses the Finder when manipulating documents, it should check for and resolve aliases itself by using the FSResolveAliasFile
function.
The FSResolveAliasFile
function first checks the catalog file for the file or directory specified in the parameter theRef to determine whether it is an alias and whether it is a file or a directory. If the object is not an alias, FSResolveAliasFile
leaves theRef unchanged, sets the targetIsFolder parameter to TRUE
for a directory or volume and FALSE
for a file, sets wasAliased to FALSE
, and returns noErr
. If the object is an alias, FSResolveAliasFile
resolves it, places the target in the parameter theRef, and sets the wasAliased flag to TRUE
.
If FSResolveAliasFile
receives an error code while resolving an alias, it leaves the input parameters as they are and exits, returning an error code. FSResolveAliasFile
can return any Resource Manager or File Manager errors.
Aliases.h
Resolves an alias contained in an alias file.
OSErr FSResolveAliasFileWithMountFlags ( FSRef *theRef, Boolean resolveAliasChains, Boolean *targetIsFolder, Boolean *wasAliased, unsigned long mountFlags );
A pointer to the alias file you plan to open. If the function completes successfully, this FSRef
describes the file or the directory referred to by the alias file.
A Boolean value. Set this parameter to TRUE
if you want FSResolveAliasFileWithMountFlags
to resolve all aliases in a chain (for example, an alias file that refers to an alias file and so on), stopping only when it reaches the target file. Set this parameter to FALSE
if you want to resolve only one alias file, even if the target is another alias file.
A pointer to a Boolean value. The FSResolveAliasFileWithMountFlags
function returns TRUE
in this parameter if the FSRef
in the parameter theRef
points to a directory or a volume; otherwise, FSResolveAliasFileWithMountFlags
returns FALSE
in this parameter.
A pointer to a Boolean value. The FSResolveAliasFileWithMountFlags
function returns TRUE
in this parameter if the FSRef
in the parameter theRef
points to an alias; otherwise, FSResolveAliasFileWithMountFlags
returns FALSE
in this parameter.
Options controlling how the alias file is resolved. See “Volume Mount Options” for a description of the values you can use here. Set this parameter to kResolveAliasFileNoUI
to prevent any user interaction, including disk switch alerts, while the alias is being resolved.
A result code.
The function FSResolveAliasFileWithMountFlags
is identical to FSResolveAliasFile
with the exception that it provides the mountFlags parameter, allowing callers additional control over how the alias file is resolved.
Aliases.h
Returns an FSRef
to the target of an alias.
OSErr FSResolveAliasWithMountFlags ( const FSRef *fromFile, AliasHandle inAlias, FSRef *target, Boolean *wasChanged, unsigned long mountFlags );
A pointer to the starting point for a relative search. If you pass NULL
in this parameter, FSResolveAliasWithMountFlags
performs an absolute search. If you pass a pointer to a valid FSRef
in the fromFile
parameter, FSResolveAliasWithMountFlags
performs a relative search for the target, followed by an absolute search only if the relative search fails. If you want to perform an absolute search followed by a relative search, you should use the function FSMatchAliasBulk
.
A handle to the alias record to be resolved and, if necessary, updated.
A pointer to an FSRef
structure. On successful return, this FSRef
refers to the target of the alias record. This parameter must point to a valid FSRef
structure.
A pointer to a Boolean value indicating, on return, whether the alias record to be resolved was updated because it contained some outdated information about the target. If it updates the alias record, FSResolveAliasWithMountFlags
sets the wasChanged
parameter to true
. Otherwise, it sets it to false
. (FSResolveAliasWithMountFlags
never updates a minimal alias, so it never sets wasChanged
to true
when resolving a minimal alias.
Options controlling how the alias is resolved. See “Volume Mount Options” for a description of the values you can use here. Set this parameter to kResolveAliasFileNoUI
to prevent any user interaction while the alias is being resolved.
A result code.
The function FSResolveAliasWithMountFlags
is identical to FSResolveAlias
with the exception that it provides the mountFlags
parameter, allowing callers additional control over how the alias is resolved.
Aliases.h
Updates an alias record for a specified target.
OSErr FSUpdateAlias ( const FSRef *fromFile, const FSRef *target, AliasHandle alias, Boolean *wasChanged );
A pointer to the starting point for a relative search. You may pass NULL
if you do not need relative search information in the alias record. The two files or directories specified in the fromFile
and target
parameters must reside on the same volume.
A pointer to the target of the alias record.
A handle to the alias record to be updated.
A pointer to a Boolean value that, on output, indicates whether the newly constructed alias record is different from the old one. If the new record is exactly the same as the old one, the value is false
. Otherwise, the value is true
. Check this parameter to determine whether you need to save an updated record.
A result code.
This function rebuilds the entire alias record and fills it in as the FSNewAlias
function would. The FSUpdateAlias
function always creates a complete alias record. When you use FSUpdateAlias
to update a minimal alias record, you convert the minimal record to a complete record.
Aliases.h
Gets the size of an alias record referenced by a handle.
Size GetAliasSize ( AliasHandle alias );
A handle to the alias record from which to get the information.
The size of the alias record.
The returned size is smaller than the size returned by the function GetHandleSize
if any custom data is added. This routine is thread safe.
Aliases.h
Gets the size of an alias record referenced by a pointer.
Size GetAliasSizeFromPtr ( const AliasRecord *alias );
A pointer to the alias record from which to get the information.
The size of the alias record.
This routine is thread safe.
Aliases.h
Gets the user type for an alias record referenced by a handle.
OSType GetAliasUserType ( AliasHandle alias );
A handle to the alias record from which to get the user type.
The user type associated with the alias.
This routine is thread safe.
Aliases.h
Gets the user type for the alias record referenced by a pointer.
OSType GetAliasUserTypeFromPtr ( const AliasRecord *alias );
A pointer to the alias record from which to get the user type.
The user type associated with the alias.
This routine is thread safe.
Aliases.h
Calls your alias filtering callback function.
Boolean InvokeAliasFilterUPP ( CInfoPBPtr cpbPtr, Boolean *quitFlag, Ptr myDataPtr, AliasFilterUPP userUPP );
You should not need to use the function InvokeAliasFilterUPP
, as the system calls your alias filtering callback for you.
Aliases.h
Creates a new universal procedure pointer (UPP) to an alias filtering callback function.
AliasFilterUPP NewAliasFilterUPP ( AliasFilterProcPtr userRoutine );
A pointer to your alias filtering callback function. For more information, see AliasFilterProcPtr
.
On return, a UPP to the alias filtering callback function.
Aliases.h
Sets the user type for an alias record referenced by a handle.
void SetAliasUserType ( AliasHandle alias, OSType userType );
A handle to the alias record for which to set the user type.
The user type associated with the alias.
This routine is thread safe.
Aliases.h
Sets the user type for the alias record referenced by a pointer.
void SetAliasUserTypeWithPtr ( AliasPtr alias, OSType userType );
A pointer to the alias record for which to set the user type.
The user type associated with the alias.
This routine is thread safe.
Aliases.h
Defines a pointer to an alias filtering callback function that filters out possible targets identified by the FSMatchAlias
function.
typedef Boolean (*AliasFilterProcPtr) ( CInfoPBPtr cpbPtr, Boolean * quitFlag, Ptr myDataPtr );
If you name your function MyAliasFilterCallback
, you would declare it like this:
Boolean MyAliasFilterCallback ( CInfoPBPtr cpbPtr, Boolean * quitFlag, Ptr myDataPtr );
A pointer to a catalog information parameter block. When your function is called, the cpbPtr
parameter points to the catalog information parameter block of the possible match (returned by the File Manager function PBGetCatInfo
).
On exit, set this to true
if you want to terminate the search.
A pointer to any customized data that your application passed when it called FSMatchAlias
. This parameter allows your filter function to access any data that your application has set up on its own.
Your function should return true
to indicate that the possible match is to be discarded, or false
to indicate that the possible match is to be added to the list of possible targets.
You can write your own filter function to examine possible targets identified by the FSMatchAlias
function. The FSMatchAlias
function calls your filter function each time it identifies a possible match.
Aliases.h
Defines a pointer to an alias filtering callback function that filters out possible targets identified by the FSMatchAliasBulk
function.
typedef Boolean (*FSAliasFilterProcPtr) ( FSRef *ref, Boolean *quitFlag, Ptr myDataPtr );
If you name your function MyFSAliasFilterCallback
, you would declare it like this:
Boolean MyAliasFilterCallback ( FSRef *ref, Boolean *quitFlag, Ptr myDataPtr );
A pointer to a file system object. When your function is called, the ref parameter points to the possible match.
On output, set this Boolean flag to true
if you want to terminate the search.
A pointer to any customized data that your application passed when it called FSMatchAliasBulk
. This parameter allows your filter function to access any data that your application has set up on its own.
Your function should return true
to indicate that the possible match is to be discarded, or false
to indicate that the possible match is to be added to the list of possible targets.
You can write your own filter function to examine possible targets identified by the FSMatchAliasBulk
function. The FSMatchAliasBulk
function calls your filter function each time it identifies a possible match.
Aliases.h
Defines the alias record information type used in the index parameter of GetAliasInfo
.
typedef short AliasInfoType;
Aliases.h
Defines a universal procedure pointer (UPP) to an alias filtering function.
typedef AliasFilterProcPtr AliasFilterUPP;
See AliasFilterProcPtr
for more information on alias filtering functions.
Aliases.h
Defines an alias record.
struct AliasRecord { OSType userType; unsigned short aliasSize; }; typedef struct AliasRecord AliasRecord; typedef AliasRecord * AliasPtr; typedef AliasPtr * AliasHandle;
userType
A 4-byte field that can contain application-specific data. When an alias record is created, this field contains 0. Your application can use this field for its own purposes.
aliasSize
The size, in bytes, assigned to the alias record at the time of its creation or updating. This is the total size of the record, including the userType
and aliasSize
fields, as well as the variable-length data that is private to the Alias Manager.
The Alias Manager uses alias records to store information that allows it to locate an object in the file system.
Aliases.h
Defines an information block passed to the FSCopyAliasInfo
function.
struct FSAliasInfo { UTCDateTime volumeCreateDate; UTCDateTime targetCreateDate; OSType fileType; OSType fileCreator; UInt32 parentDirID; UInt32 nodeID; UInt16 filesystemID; UInt16 signature; Boolean volumeIsBootVolume; Boolean volumeIsAutomounted; Boolean volumeIsEjectable; Boolean volumeHasPersistentFileIDs; Boolean isDirectory; }; typedef struct FSAliasInfo FSAliasInfo; typedef FSAliasInfo * FSAliasInfoPtr;
volumeCreateDate
The creation date of the volume on which the alias target resides.
targetCreateDate
The creation date of the alias target.
fileType
The file type of the target.
fileCreator
The creator code of the target.
parentDirID
The directory ID of the target’s parent directory.
nodeID
The ID of the file or directory that is the alias target.
filesystemID
The filesystem ID.
signature
The volume signature of the volume on which the target resides.
volumeIsBootVolume
A Boolean value indicating whether the volume is the boot volume.
volumeIsAutomounted
A Boolean value indicating whether the volume is automounted.
volumeIsEjectable
A Boolean value indicating whether the volume is ejectable.
volumeHasPersistentFileIDs
A Boolean value indicating whether the volume has persistent file ID’s.
isDirectory
A Boolean value indicating whether the alias target is a directory.
Aliases.h
Returned by the FSCopyAliasInfo
function to indicate which fields of the alias information structure contain valid data.
typedef UInt32 FSAliasInfoBitmap; enum { kFSAliasInfoNone = 0x00000000, kFSAliasInfoVolumeCreateDate = 0x00000001, kFSAliasInfoTargetCreateDate = 0x00000002, kFSAliasInfoFinderInfo = 0x00000004, kFSAliasInfoIsDirectory = 0x00000008, kFSAliasInfoIDs = 0x00000010, kFSAliasInfoFSInfo = 0x00000020, kFSAliasInfoVolumeFlags = 0x00000040 };
kFSAliasInfoNone
None of the alias information is valid.
Available in Mac OS X v10.2 and later.
Declared in Aliases.h
.
kFSAliasInfoVolumeCreateDate
The volume creation date in the volumeCreateDate
field is valid.
Available in Mac OS X v10.2 and later.
Declared in Aliases.h
.
kFSAliasInfoTargetCreateDate
The creation date of the alias target, in the targetCreateDate
field, is valid.
Available in Mac OS X v10.2 and later.
Declared in Aliases.h
.
kFSAliasInfoFinderInfo
The file type and creator information, in the fileType
and fileCreator
fields, is valid.
Available in Mac OS X v10.2 and later.
Declared in Aliases.h
.
kFSAliasInfoIsDirectory
The information in the isDirectory
field is valid.
Available in Mac OS X v10.2 and later.
Declared in Aliases.h
.
kFSAliasInfoIDs
The parent directory ID and alias target ID, in the parentDirID
and nodeID
fields, are valid.
Available in Mac OS X v10.2 and later.
Declared in Aliases.h
.
kFSAliasInfoFSInfo
The filesystem ID and signature, in the filesystemID
and signature
fields, are valid.
Available in Mac OS X v10.2 and later.
Declared in Aliases.h
.
kFSAliasInfoVolumeFlags
The volume information, in the volumeIsBootVolume
, volumeIsAutomounted
, volumeIsEjectable
, and volumeHasPersistentFileIDs
fields, is valid.
Available in Mac OS X v10.2 and later.
Declared in Aliases.h
.
Specify how an alias should be resolved.
enum { kResolveAliasFileNoUI = 0x00000001, kResolveAliasTryFileIDFirst = 0x00000002 };
kResolveAliasFileNoUI
The Alias Manager should resolve the alias without presenting a user interface.
Available in Mac OS X v10.0 and later.
Declared in Aliases.h
.
kResolveAliasTryFileIDFirst
The Alias Manager should search for the alias target using file IDs before searching using the path.
Available in Mac OS X v10.2 and later.
Declared in Aliases.h
.
The FSResolveAliasWithMountFlags
, FSResolveAliasFileWithMountFlags
, ResolveAliasWithMountFlags
, ResolveAliasFileWithMountFlags
, and ResolveAliasFileWithMountFlagsNoUI
functions take these constants in the mountFlags
parameter, allowing you to specify how the alias should be resolved.
Specify the matching criteria for the alias matching functions.
enum { kARMMountVol = 0x00000001, kARMNoUI = 0x00000002, kARMMultVols = 0x00000008, kARMSearch = 0x00000100, kARMSearchMore = 0x00000200, kARMSearchRelFirst = 0x00000400, kARMTryFileIDFirst = 0x00000800 };
kARMMountVol
Automatically try to mount the target’s volume if it is not mounted.
Available in Mac OS X v10.0 and later.
Declared in Aliases.h
.
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.
Available in Mac OS X v10.0 and later.
Declared in Aliases.h
.
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.
Available in Mac OS X v10.0 and later.
Declared in Aliases.h
.
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 NULL
and the list of matches is not full.
Available in Mac OS X v10.0 and later.
Declared in Aliases.h
.
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.
Available in Mac OS X v10.0 and later.
Declared in Aliases.h
.
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.
Available in Mac OS X v10.0 and later.
Declared in Aliases.h
.
kARMTryFileIDFirst
Perform a search using the file ID of the target before searching using the path.
Available in Mac OS X v10.2 and later.
Declared in Aliases.h
.
The FSMatchAlias
, FSMatchAliasNoUI
, MatchAliasNoUI
and MatchAlias
functions use these constants to specify the matching criteria by passing a sum of these constants in the rulesMask parameter. You must specify at least one of the last three parameters: kARMSearch
, kARMSearchMore
, and kARMSearchRelFirst
.
Specifies the file type of an alias resource file.
enum { rAliasType = 'alis' };
The GetAliasInfo
function uses these constants in the index
parameter.
enum { asiZoneName = -3, asiServerName = -2, asiVolumeName = -1, asiAliasName = 0, asiParentName = 1 };
asiZoneName
If the record represents a target on an AppleShare volume, retrieve the server’s zone name. Otherwise, return an empty string.
Available in Mac OS X v10.0 and later.
Declared in Aliases.h
.
asiServerName
If the record represents a target on an AppleShare volume, retrieve the server name. Otherwise, return an empty string.
Available in Mac OS X v10.0 and later.
Declared in Aliases.h
.
asiVolumeName
Return the name of the volume on which the target resides.
Available in Mac OS X v10.0 and later.
Declared in Aliases.h
.
asiAliasName
Return the name of the target.
Available in Mac OS X v10.0 and later.
Declared in Aliases.h
.
asiParentName
Return the name of the parent directory of the target of the record. If the target is a volume, return the volume name.
Available in Mac OS X v10.0 and later.
Declared in Aliases.h
.
You can check for version and feature availability information by using the Alias Manager selectors defined in the Gestalt Manager. For more information, see Gestalt Manager Reference.
© 2003, 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-12-05)