Inside Macintosh: Files /

Chapter 4 - Alias Manager

Summary of the Alias Manager

Pascal Summary

Constants

CONST
   {Gestalt constants}
   gestaltAliasMgrAttr     = 'alis';      {Alias Mgr attributes selector}
   gestaltAliasMgrPresent  = 0;           {Alias Mgr is present}

   {resource type for saved alias records}
   rAliasType              = 'alis';

   {masks for alias resolution action rules used by MatchAlias}
   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}

   {index values for GetAliasInfo}
   asiZoneName             =  -3;         {get zone name}
   asiServerName           =  -2;         {get server name}
   asiVolumeName           =  -1;         {get volume name}
   asiAliasName            =  0;          {get target name}
   asiParentName           =  1;          {get parent directory name}

Data Types

TYPE AliasRecord     =                 {alias record}
   RECORD
      userType:   OSType;              {application's signature}
      aliasSize:  Integer;             {size of record when created}
      {variable-length private data}
   END;

   AliasPtr             =  ^AliasRecord;
   AliasHandle          =  ^AliasPtr;

   AliasInfoType        =  Integer;    {alias record information type}
   AliasFilterProcPtr   =  ProcPtr;    {application-defined routine}

Alias Manager Routines

Creating and Updating Alias Records

FUNCTION NewAlias	(fromFile: FSSpecPtr; target: FSSpec;
			VAR alias: AliasHandle): OSErr;
FUNCTION NewAliasMinimal(target: FSSpec; 
			VAR alias: AliasHandle): OSErr;
FUNCTION NewAliasMinimalFromFullPath
   			(fullPathLength: Integer; fullPath: Ptr; 
			zoneName: Str32; serverName: Str31; 
			VAR alias: AliasHandle): OSErr;
FUNCTION UpdateAlias	(fromFile: FSSpecPtr; target: FSSpec; 
			alias: AliasHandle; 
			VAR wasChanged: Boolean): OSErr;

Resolving and Reading Alias Records

FUNCTION ResolveAlias		(fromFile: FSSpecPtr; alias: AliasHandle; 
				VAR target: FSSpec; 
				VAR wasChanged: Boolean): OSErr;
FUNCTION MatchAlias		(fromFile: FSSpecPtr; rulesMask: LongInt; 
				alias: AliasHandle; VAR aliasCount: Integer; 
				aliasList: FSSpecArrayPtr; 
				VAR needsUpdate: Boolean; 
				aliasFilter: AliasFilterProcPtr; 
				yourDataPtr: UNIV Ptr): OSErr;
FUNCTION GetAliasInfo		(alias: AliasHandle; index: AliasInfoType; 
				VAR theString: Str63): OSErr;

Application-Defined Routine

FUNCTION MyMatchAliasFilter	(cpbPtr: CInfoPBPtr; VAR quitFlag: Boolean; 
				myDataPtr: Ptr): Boolean;

C Summary

Constants

/*Gestalt constants*/
#define gestaltAliasMgrAttr   'alis'      /*Alias Mgr attributes selector*/
#define gestaltAliasMgrPresent 0          /*Alias Mgr is present*/
/*resource type for saved alias records*/
#define rAliasType            'alis'
/*masks for alias resolution action rules used by MatchAlias*/
enum {kARMMountVol      = 0x00000001};    /*mount volume automatically*/
enum {kARMNoUI          = 0x00000002};    /*suppress user interface*/
enum {kARMMultVols      = 0x00000008};    /*search on multiple volumes*/
enum {kARMSearch        = 0x00000100};    /*do a fast search*/
enum {kARMSearchMore    = 0x00000200};    /*do an exhaustive search*/
enum {kARMSearchRelFirt = 0x00000400};    /*do a relative search first*/
/*index values for GetAliasInfo*/
enum {asiZoneName       = -3};            /*get zone name*/
enum {asiServerName     = -2};            /*get server name*/
enum {asiVolumeName     = -1};            /*get volume name*/
enum {asiAliasName      = 0};             /*get target name*/
enum {asiParentName     = 1};             /*get parent directory name*/

Data Types

typedef struct {                          /*alias record*/
      OSType            userType;         /*application's signature*/
      unsigned short    aliasSize;        /*size of record when created*/
} AliasRecord;

typedef AliasRecord *AliasPtr;
typedef AliasRecord **AliasHandle;
typedef short AliasInfoType;              /*alias record information type*/

typedef pascal Boolean (*AliasFilterProcPtr)(CInfoPBPtr cpbPtr,
                        Boolean *quitFlag, Ptr yourDataPtr);

Alias Manager Routines

Creating and Updating Alias Records

pascal OSErr NewAlias		(const FSSpec *fromFile, const FSSpec *target, 
				AliasHandle *alias);
pascal OSErr NewAliasMinimal	(const FSSpec *target, AliasHandle *alias);
pascal OSErr NewAliasMinimalFromFullPath
   				(short fullPathLength, 
				const unsigned char *fullpath, 
				const Str32 zoneName, const Str31 serverName,
				AliasHandle *alias);
pascal OSErr UpdateAlias		(const FSSpec *fromFile, const FSSpec *target, 
				AliasHandle alias, Boolean *wasChanged);

Resolving and Reading Alias Records

pascal OSErr ResolveAlias	(const FSSpec *fromFile, AliasHandle alias, 
				FSSpec *target, Boolean *wasChanged);
pascal OSErr MatchAlias		(const FSSpec *fromFile, 
				unsigned long rulesMask, 
				const AliasHandle alias, short *aliasCount,
				FSSpecPtr aliasList, Boolean *needsUpdate, 
				AliasFilterProcPtr aliasFilter, 
				Ptr yourDataPtr);
				pascal OSErr GetAliasInfo(const AliasHandle alias, AliasInfoType index, 
				Str63 theString);

Application-Defined Routine

pascal Boolean MyMatchAliasFilter
   	(CInfoPBPtr cpbPtr, Boolean *quitFlag, 
	Ptr myDataPtr);

Assembly-Language Summary

Data Structure

Alias Record Data Structure

0	userType	long	file type of target file
4	aliasSize	word	size, in bytes, of record

Trap Macros

Trap Macro Requiring Routine Selectors

_AliasDispatch 
Selector
Routine

$0002
NewAlias

$0003
ResolveAlias

$0005
MatchAlias

$0006
UpdateAlias

$0007
GetAliasInfo

$0008
NewAliasMinimal

$0009
NewAliasMinimalFromFullPath

$000C
ResolveAliasFile

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	Parameter error
dirNFErr	-120	Parent directory not found
usrCanceledErr	-128	The user canceled the operation