File Access Model

This section introduces the file access model used by AFP to enable file sharing and discusses the components of AFP software.

A program running in a local computer requests and manipulates files by using that computer’s native file system commands. These commands manipulate files on disk or other memory resource that is physically connected to the local computer. Through AFP, a program can use the same native file system commands to manipulate files on a shared resource that resides on a remote computer (for example, a file server).

A program running on the local computer sends a command to the native file system. A data structure in local memory indicates whether the volume is managed by the native file system or by some external file system. The native file system discovers whether the requested file resides locally or remotely by looking at this data structure. If the data structure indicates an external file system, the native file system routes the command to the AFP translator.

The translator, as its name implies, translates the native commands into AFP commands and sends them through to the file server that manages the remote resource. The AFP translator is not defined in the AFP specification; it is up to the applications programmer to design it.

A program running on the local computer may also need to send AFP commands for which no equivalent command exists in the native file system. In this case, the AFP command is sent directly to the desired external file system, as shown in Figure 1-1. For example, user authentication might have to be handled through an interface written for that purpose.

AFP supports computers using Mac OS and personal computers using MS-DOS. AFP can be extended to support additional types of computers. Any implementation of AFP must take into account the capabilities of the networked computer’s native file system and simulate its functionality in the shared environment. In other words, the shared file system should duplicate the characteristics of a local computer’s file system. Simulating the functionality of each local computer’s native file system becomes increasingly complex as different computer types share the same file server. Because each computer type has different characteristics in the way it manipulates files, the shared file system needs to possess the combined capabilities of all computers on the same network.

Three system components make up AFP:

• a file system structure, which is made up of resources (such as file servers, volumes, directories, files, and forks) that are addressable through the network. These resources are called AFP-file-system-visible entities. AFP specifies the relationship between these entities. For example, one directory can be the parent of another. For descriptions of AFP-file-system-visible entities, see File System Structure later in this chapter.

• AFP commands, which are the commands the local computer uses to manipulate the AFP file system structure. As mentioned earlier, the translator sends file system commands to the file server in the form of AFP commands, or the application running on the local computer can make AFP commands directly. Each AFP command is described in detail in the “Tasks” section of this document.

• algorithms associated with the commands, which specify the actions performed by the AFP commands.

Although this chapter distinguishes between local computers and file servers, AFP can support these two functions within the same node. However, AFP does not solve the concurrency problems that can arise when a computer is both an AFP client and an AFP server. The software on such combined nodes must be carefully designed to avoid potential conflicts.

AFP does not provide commands that support administration of the file server. Administrative functions, such as registering users and changing passwords, must be handled by separate network-administration software. Additional software must also be provided to add, remove, and find servers within the network.

File System Structure

This section describes the AFP file system structure and the parameters associated with its AFP-file-system-visible entities. These entities include the file server, its volumes, directories (“folders” in Mac OS terminology), files. and file forks. This section also describes the tree structure, called the volume catalog, which is a description of the relationships between directories and files.

By sending AFP commands, the AFP client can

• obtain information about the file server and other parts of the file system structure

• modify information that is obtained from a file server

• create and delete files and directories

• retrieve and store information within individual files

The following sections describe the file system structure’s AFP-file-system-visible entities.

Volumes

A file server can make one or more volumes visible to AFP clients. Each volume has parameters associated with it, as listed in Volume Bitmap. To provide security at the volume level, the server can maintain an optional password parameter for any volume.

The FPGetVolParms command provides additional information about the volume. Volume Bitmap lists the information it can return.

Volume Types

An AFP volume is structured hierarchically. There are two types of hierarchical volumes: fixed and variable. A fixed Directory ID volume contains multiple directories, with each directory having its own permanent Directory ID that is assigned when the directory is created. The Directory ID is not used for any other directory during the lifetime of the volume, even if the directory to which it is assigned is later deleted.

A variable Directory ID volume also maintains the uniqueness of its Directory IDs but differs from a fixed Directory ID volume in that it does not associate a permanent Directory ID with each directory. For variable Directory ID volumes, the file server creates a unique Directory ID for a directory whenever the AFP client sends an FPOpenDir command. The file server then maintains this Directory ID until the client sends an FPCloseDir command or the AFP session terminates. A Directory ID obtained by sending an FPOpenDir command to a variable Directory ID volume must be used only for that session. If the Directory ID is stored and used to reference the directory in a later session, the results cannot be predicted: the command may fail, manipulate the wrong directory, or accidentally manipulate the correct directory.

Table 1-2  Volume types

Value	Description
1	Flat (no directories supported). Deprecated.
2	Fixed Directory ID.
3	Variable Directory ID. Deprecated.

The volume types have the following support capabilities and constraints: Personal computers using MS-DOS can gain access to any type of server volume because the concept of Directory IDs is foreign to their file systems. However, Macintosh computers using the hierarchical file system (HFS) cannot directly use variable Directory ID volumes. Macintosh HFS volumes are fixed Directory ID volumes and hierarchical volumes on the file server can be handled by HFS only if they are fixed Directory ID volumes. Mac OS applications, such as the Finder, save Directory IDs and do no expect them to vary.

Volume Catalog

The volume catalog is the structure that describes the branching tree arrangement of files and directories on fixed and variable Directory ID volumes. The catalog does not span multiple volumes; the AFP client sees a separate volume catalog for each server volume that is visible to AFP clients. Figure 1-2 shows an example of a volume catalog and illustrates its elements.

The volume catalog contains directories and files branching from a base directory known as the root. These directories and files are referred to as catalog nodes or CNodes (not to be confused with devices on a network, which are also known as nodes). Within the tree structure, CNodes can be positioned in two ways:

• at the end of a limb, in which case the CNode is called a leaf; a leaf CNode can be a file or an empty directory

• connected from above and below to other CNodes, which case the CNode is called an internal CNode. Internal CNodes are always directories

CNodes have a parent/offspring relationship. A given CNode is the offspring of the CNode above it in the catalog tree, and the higher CNode is considered its parent directory. Offspring are contained within the parent directory. The only CNode that does not have a parent directory is the root directory.

When an AFP command makes its way through the volume catalog, it can take only one shortest path from the root to a specific CNode. The CNodes along that path are said to be ancestors of the destination node, which in turn is called the descendent of each of its ancestors.

IF name type is Short or name is in Short format

THEN check for new name in list of Short Names

    IF name already exists

    THEN return ObjectExists result

    ELSE set object’s Short and Long Names to new name

ELSE { name type is Long OR name is in Long format }

    check for new name in list of Long Names

    IF name already exists

    THEN return ObjectExists result

    ELSE set object’s Long Name to new name

        derive Short Name from Long Name

Designating a Path to a CNode

In order to perform any action on a CNode, the AFP client must designate a path to the CNode. AFP provides rules for specifying a path to any CNode in the volume catalog. A CNode (file or directory) can be unambiguously specified to the server by the identifiers shown in Figure 1-3.

The Volume ID specifies the volume on which the destination CNode resides. The Directory ID can belong to the destination CNode (if the CNode is a directory) or to any one of its ancestor directories, up to and including the root directory and the root’s parent directory.

An AFP pathname is formatted as a Pascal string (one length byte followed by the number of characters specified by the length byte) or a UTF-8 string (a four-byte text encoding hint followed by two length bytes followed by the number of characters specified by the length bytes). An AFP pathname is made up of CNode names, concatenated with intervening null-byte separators. Each element of a pathname must be the name of a directory, except for the last one, which can be the name of a directory or a file.

The elements of a pathname can be Long or Short Names. However, a given pathname cannot contain a mixture of Long and Short Names. A path type byte, which indicates whether the elements of the pathname are all Short or all Long Names, is associated with each pathname. A pathname consisting of Short Names has a path type of 1. A pathname consisting of Long Names has a path type of 2.

An AFP pathname that consists of Long or Short Names can be up to 255 characters long. A single null byte as the length byte indicates that no pathname is supplied. Because the length byte is included at the beginning of the string, each pathname element (CNode name) does not include a length indicator. Similarly, an AFP pathname that consists of UTF-8–encoded names is limited to 255 Unicode characters.

The syntax of an AFP pathname follows this paragraph. The asterisk (*) represents a sequence of zero or more of the preceding elements of the pathname; the plus (+) represents a sequence of one or more of the preceding elements; <Sep> represents the separators in the pathname; the vertical bar (|) is an OR operator; and the term on the left side of the ::= symbol is defined as the term(s) on the right side.

<Sep> ::= <null-byte>+

<Pathname> ::= empty-string |

    <Sep>*<CNode name>(<Sep><Pathname>*

The syntax represents a concatenation of CNode names separated by one or more null bytes. Pathnames can also start or end with a string of null bytes.

A pathname can be used to traverse the volume catalog in any direction. The pathname syntax allows paths either to descend from a particular CNode through its offspring or to ascend from a CNode to its ancestors. In either case, the directory that is the starting point of this path is defined separately from the pathname by its Directory ID. The first element of the pathname is an offspring of the starting point of the directory. The pathname must be parsed from left to right to obtain each element that is used as the next node on the path.

To descend through a volume, a valid pathname must proceed in order from parent to offspring. A single null-byte separator preceding this first element is ignored.

To ascend through a volume, a valid pathname must proceed from a particular CNode to its ancestor. To ascend one level in the catalog tree, two consecutive null bytes should follow the offspring CNode name. To ascend two levels in the catalog tree, three consecutive null bytes are used as the separator, and so on.

A particular volume may descend and ascend through the volume catalog. Because of this, many valid pathnames may refer to the same CNode.

A complete path specification can take a number of forms. The table that follows summarizes the different kinds of path specifications that can be used to traverse the volume catalog illustrated in Figure 1-4. A zero in square brackets [0] represents a null-byte separator.

The descriptors and examples that follow refer to this table and the corresponding volume catalog illustrated in Figure 1-4. To simplify these examples, the CNodes in this catalog are named a through j, except the root, which is named x. The path type is ignored in this example. The letter v represents the volume’s two-byte Volume ID. Lines connect the CNodes; the unconnected lines indicate that other CNodes in this volume are not shown.

Table 1-4 provides the Volume ID, Directory ID, and pathname for some sample path specifications in Figure 1-4.

The first example of a path specification in Table 1-4 contains the Volume ID, the root directory’s Directory ID, which is always 2, and a pathname. In this case, the pathname must contain the names of all of the destination file’s ancestors except the root, and it must end with the name of the file itself. The single trailing null byte is ignored.

The second example contains the Volume ID, the Directory ID of an ancestor, and a pathname.

The third example is essentially the same as the second example. The single leading null byte is ignored.

In the fourth example, the Directory ID is the Parent ID of the destination file. In this case, the pathname need contain only the name of the destination file itself.

The fifth example illustrates another way to uniquely specify a descending path to a directory. It includes the CNode’s Volume ID, its Directory ID, and a null pathname. This path specification is used to specify the directory e.

The sixth example illustrates a descending path. The first CNode in the pathname is the offspring of the starting point Directory ID. Then the pathname ascends though e’s parent (c) down to directory g, backup to g’s parent (c), and down again to h.

The seventh shows an ascending pathname that starts at directory c (whose Directory ID is 104), moves down to e, and then ascends to e’s parent’s parent (a).

The eighth example is a special case in which the starting point of the path is Directory ID 1, the parent of the root. The first name of the pathname must be the volume name or root directory name corresponding to Volume ID v; beyond that, pathname traversal is performed as in the other examples.

AFP Login

To make use of any resource managed by a file server, the AFP client must first log in to the server. This section provides an overview of the AFP login process.

After a user selects an AFP server to log in to, the AFP client sends the FPGetSrvrInfo command to request information about that server. The server returns information that includes

• the AFP versions the server supports

• the user authentication methods (UAMs) the server supports

• the server’s machine type

• the server’s name

• the server’s network address

• the server’s signature

• whether the server supports optional functionality, such as reconnect, Open Directory, FPCopyFile, FPChangePassword, saving passwords, and server notifications

During the AFP login process, the AFP client tells the server which AFP version the client will use to establish the connection and which UAM it will use to authenticate the user.

Each AFP version is uniquely described by a string of up to 16 characters called the AFP version string. The AFP version strings for the AFP versions supported by AFP 3.x are listed in Apple Filing Protocol Reference.

When working with different versions of AFP, the following differences in behavior occur:

• AFP 2.x—UNIX permissions and UTF-8 name support are disabled.

• AFP 3.x—GMT adjustments are disabled, and all time stamps are based on GMT.

The UAMs supported by AFP 3.x and their corresponding strings are listed in Table 1-5.

The prospective AFP client initiates the login process by sending an FPLogin or an FPLoginExt command to the server. Both commands include the AFP version string and the UAM string that the client has selected. Depending on the selected UAM method, the FPLogin or FPLoginExt command may include user login information (such as a user name or password), or a subsequent FPLoginCont command may include such information. The sending of additional FPLoginCont commands may be required to complete user authentication, as described in AFP File Server Security.

If the UAM succeeds, an AFP session between the AFP client and the server begins.

After login, the AFP client should immediately call FPGetUserInfo to see if the user’s password has expired.

As mentioned earlier, in addition to the AFP and UAM versions that the server supports, the FPGetSrvrInfo command returns a Flags parameter whose bits provide additional information about the server that is useful to an AFP client. The bits of the Flags parameter are listed in Server Flags Bitmap.

Desktop Database

For file server volumes, AFP provides an interface that replaces the Finder’s direct use of the Desktop file. This interface is necessary because the Desktop file was designed for a standalone environment and could not be shared by multiple users. The AFP interface to the Desktop database replaces the Desktop file and can be used transparently for both local and remote volumes.

The Desktop database is used by the file server to hold information needed specifically by the Finder to build its unique user interface, in which icons are used to represent objects on a disk volume. To create certain parts of this interface, the Finder uses the Desktop database to perform three functions:

• to associate documents and applications with particular icons and store the icon bitmaps

• to locate the corresponding application when a user opens a document

• to hold text comments associated with files and directories

Macintosh applications usually contain an icon that is to be displayed for the application itself as well as other icons to be displayed for documents that the application creates. These icons are stored in the application’s resource fork and in the Desktop database. The Desktop database associates these icons with each file’s creator (the fdCreator field in the FInfo record) and the type (the fdType field in the FInfo record), which are stored as part of the file’s Finder information.

The Finder allows a Mac OS user to open a document, that is, to select a file and implicitly start the application that created the file. To do this, the Desktop database maintains a mapping between the file creator and a list of the locations of each application that has that file creator associated with it. This mapping is referred to as an APPL mapping because all Macintosh applications have a file creator of ‘APPL’. The Finder obtains the first item in the list and tries to start the application. If for some reason the application cannot be started (for example, if it is currently in use), the Finder will obtain the next application from the Desktop database’s list and try that one. This list is dynamically filtered to present to the Finder only those applications for which the AFP client has the proper access rights.

The Desktop database is also a repository for the text of comments associated with files and directories on the volume. The Finder will make calls to the Desktop database to read or write these comments, which can be viewed and modified by selecting the Get Info item in the Finder’s File menu. Comments are completely uninterpreted by the Desktop database.

For more information about the Finder and the use of the Desktop file, refer to Inside OS X.

Submounting AFP Volumes

Beginning in version 10.6, OS X supports submounting—mounting a folder within a given sharepoint.

For example, if you want to mount the folder myfolder within a sharepoint called mysharepoint on the server example.com, you would mount it with this AFP URL:

afp://example.com/mysharepoint/myfolder

Prior to OS X v.10.6, the sharepoint itself is mounted. Beginning in version 10.6, the requested folder is mounted.

This is mainly intended for supporting AFP home directories in which you have a "Users" sharepoint with multiple users inside that folder.