Alias Manager Reference

Framework	CoreServices/CoreServices.h
Declared in	Aliases.h

Overview

The Alias Manager enables the creation and resolution of alias records, which are data structures that describe files, directories, and volumes in the file system. 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, 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.

Functions by Task

Creating and Updating Alias Records

Getting Alias Size

Getting and Setting Alias User Types

Resolving and Reading Alias Records

Working With Finder Alias Files

Working With Universal Procedure Pointers to Alias Manager Callbacks

Deprecated Functions

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.

Callbacks

AliasFilterProcPtr

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
);

Parameters

cpbPtr: 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).
quitFlag: On exit, set this to true if you want to terminate the search.
myDataPtr: 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.

Return Value

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.

Discussion

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.

Availability

Available in OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Aliases.h

FSAliasFilterProcPtr

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
);

Parameters

ref: A pointer to a file system object. When your function is called, the ref parameter points to the possible match.
quitFlag: On output, set this Boolean flag to true if you want to terminate the search.
myDataPtr: 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.

Return Value

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.

Discussion

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.

Availability

Available in OS X v10.5 and later.

Declared In

Aliases.h

Data Types

AliasInfoType

Defines the alias record information type used in the index parameter of GetAliasInfo.

typedef short AliasInfoType;

Availability

Available in OS X v10.0 and later.

Declared In

Aliases.h

AliasFilterUPP

Defines a universal procedure pointer (UPP) to an alias filtering function.

typedef AliasFilterProcPtr AliasFilterUPP;

Discussion

See FSAliasFilterProcPtr for more information on alias filtering functions.

Availability

Available in OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Aliases.h

AliasRecord

Defines an alias record.

struct AliasRecord {
   OSType userType;
   unsigned short aliasSize;
};
typedef struct AliasRecord              AliasRecord;
   typedef AliasRecord *                   AliasPtr;
   typedef AliasPtr *                      AliasHandle;

Fields

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.

Discussion

The Alias Manager uses alias records to store information that allows it to locate an object in the file system.

Availability

Available in OS X v10.0 and later.

Declared In

Aliases.h

FSAliasInfo

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;

Fields

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.

Availability

Available in OS X v10.2 and later.

Declared In

Aliases.h

Constants

Alias Information Masks

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
};

Constants

kFSAliasInfoNone

None of the alias information is valid.

Available in OS X v10.2 and later.

Declared in Aliases.h.

kFSAliasInfoVolumeCreateDate

The volume creation date in the volumeCreateDate field is valid.

Available in 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 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 OS X v10.2 and later.

Declared in Aliases.h.

kFSAliasInfoIsDirectory

The information in the isDirectory field is valid.

Available in 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 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 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 OS X v10.2 and later.

Declared in Aliases.h.

Volume Mount Options

Specify how an alias should be resolved.

enum {
   kResolveAliasFileNoUI = 0x00000001,
   kResolveAliasTryFileIDFirst = 0x00000002
};

Constants

kResolveAliasFileNoUI

The Alias Manager should resolve the alias without presenting a user interface.

Available in 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 OS X v10.2 and later.

Declared in Aliases.h.

Discussion

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.

Matching Constants

Specify the matching criteria for the alias matching functions.

enum {
   kARMMountVol = 0x00000001,
   kARMNoUI = 0x00000002,
   kARMMultVols = 0x00000008,
   kARMSearch = 0x00000100,
   kARMSearchMore = 0x00000200,
   kARMSearchRelFirst = 0x00000400,
   kARMTryFileIDFirst = 0x00000800
};

Constants

kARMMountVol

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

Available in 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 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 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 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 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 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 OS X v10.2 and later.

Declared in Aliases.h.

Discussion

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.

Alias Resource Type

Specifies the file type of an alias resource file.

enum {
   rAliasType = 'alis'
};

Information Type Constants

The GetAliasInfo function uses these constants in the index parameter.

enum {
   asiZoneName = -3,
   asiServerName = -2,
   asiVolumeName = -1,
   asiAliasName = 0,
   asiParentName = 1
};

Constants

asiZoneName

If the record represents a target on an AppleShare volume, retrieve the server’s zone name. Otherwise, return an empty string.

Available in 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 OS X v10.0 and later.

Declared in Aliases.h.

asiVolumeName

Return the name of the volume on which the target resides.

Available in OS X v10.0 and later.

Declared in Aliases.h.

asiAliasName

Return the name of the target.

Available in 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 OS X v10.0 and later.

Declared in Aliases.h.

Gestalt Constants

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.

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.