Legacy Document

Inside Macintosh: Files /

Chapter 4 - Alias Manager / Using the Alias Manager

Creating Alias Records

You create a new alias record by calling one of three functions: NewAlias, NewAliasMinimal, or NewAliasMinimalFromFullPath. The NewAlias function creates a complete alias record that can make full use of the alias-resolution a gorithms. The other two functions are streamlined variations designed for circumstances when speed is more important than robust resolution services. All three functions allocate the memory for the record, fill it in, and return a handle to it.

The NewAlias function always records the name and the file or directory ID of the target, its creation date, the parent directory name and ID, and the volume name and creation date. It also records the full pathname of the target and a collection of other information. You can have NewAlias store relative path information as well by supplying a starting point for a relative path (see "Relative Searches" on page 4-5 for a description of relative paths).

Call NewAlias when you want to create an alias record to store for later use. For example, suppose you are writing a word-processing application that allows the user to customize a dictionary for use with a single text file. Your application stores the custom data in a separate dictionary file in the same directory as the document. As soon as you create the dictionary file, you can call NewAlias to create an alias record for that file, including path information relative to the user's text file. Listing 4-1 shows how to use NewAlias to create a new alias.

Listing 4-1 Creating an alias record

FUNCTION DoCreateAlias (myDoc, myDict: FSSpec): OSErr;
VAR
   myAliasHdl: AliasHandle;                        {handle to created alias}
   myErr:      OSErr;
BEGIN
   myErr := NewAlias(@myDoc, myDict, myAliasHdl);  {create alias record}
   IF myAliasHdl <> NIL THEN
      myErr := DoSaveAlias(myDoc, myAliasHdl);     {save it as a resource}
   DoCreateAlias := myErr;                         {return result code}
END;

The function DoCreateAlias defined in Listing 4-1 takes two FSSpec records as parameters. The first specifies the document that is to serve as the starting point for a relative search, in this case the user's text file. The second FSSpec record specifies the target of the alias to be created, in this example the dictionary file. The DoCreateAlias function calls NewAlias to create the alias record; if successful, it calls the application- defined function DoSaveAlias to save the alias record as a resource in the document file's resource fork. See Listing 4-2 on page 4-12 for a definition of DoSaveAlias.

The two variations on the NewAlias function, NewAliasMinimal and NewAliasMinimalFromFullPath, record only a minimum of information about
the target. The NewAliasMinimal function records only the target's name, parent directory ID, volume name and creation date, and volume mounting information. The NewAliasMinimalFromFullPath function records only the full pathname of the target, including the volume name.

Use NewAliasMinimal or NewAliasMinimalFromFullPath when you are willing to give up robust alias-resolution service in return for speed. The Finder, for example, stores minimal aliases in the Apple events that tell your application to open or print a document. Because the alias record is resolved almost immediately, the description is likely to remain valid, and the shorter record is probably safe.

You can use NewAliasMinimalFromFullPath to create an alias record for a target that doesn't exist or that resides on an unmounted volume.