This section introduces the file access model used by AFP to enable file sharing and discusses the components of AFP software.
Note: All values exchanged between an AFP client and an AFP server are sent over the network in network byte order.
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:
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.
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
The following sections describe the file system structure’s AFP-file-system-visible entities.
A file server is a computer with at least one large-capacity disk that allows other computers on the network to share information stored in it. AFP imposes no limit on the number of shared disks. Each disk attached to a file server usually contains one volume, although the disk may be subdivided into multiple volumes. Each volume appears as a separate entity to the AFP client.
A file server has a unique name and other identifying parameters. These parameters identify the server’s machine type and number of attached volumes, as well as the AFP versions user authentication methods (UAMs) that the server supports. Some of the more common AFP file server parameters are listed Table 1-1 . For a complete list, see FPGetSrvrInfo .
A UTF-8 string containing the server name.
A string in Pascal format of up to 16 characters that describes the file server’s hardware and software but has no significance to AFP.
Supported AFP versions—one or more strings of up to 16 characters each. For more information, see Apple Filing Protocol Reference .
One or more strings of up to 16 characters each. For more information, see Table 1-5 .
Deprecated. An optional value of 256 bytes that is used to customize the appearance of server volumes on the Mac OS Desktop. It consists of a 32-by-32 bit (128 bytes) icon bitmap followed by a 32-by-32 bit (128 bytes) icon mask. The mask usually consists of the icon’s outline filled with black (bits that are set). For more information about icons, refer to Inside OS X.
A 16-byte value that uniquely identifies a server used to prevent an AFP client from logging on to the same server twice.
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.
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.
Flat (no directories supported). Deprecated.
Fixed Directory ID.
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.
Note: OS X AFP clients do not support variable directory ID or flat volumes.
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:
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.
CNode names identify every directory and file in a volume catalog. Each directory and file has a Long Name, a Short Name, and may also have an AFPName.
Long Names and Short Names correspond in two of the native file systems that AFP supports: the Mac OS refers to files and directories by Long Names; MS-DOS computers use Short Names.
AFPNames are encoded in conformance to the Unicode standard (UTF-8), which uses 16-bits to encode more than 65,000 characters. To keep character coding simple and efficient, the Unicode Standard assigns each character a unique numeric value and name. To help when converting from UTF-8 to other script systems, AFPNames begin with a four-byte text encoding hint that specifies the script that was originally used to compose the name. The text encoding hint is followed by a two-byte length field specifying the length of the UTF-8 encoded name that follows.
The header file, TextCommon.h , for the Text Encoding Conversion Manager defines the constants for the text encoding hint. See AFP Text Encodings for a list.
To allow dissimilar computers to share resources, the file server provides CNode names in all three formats. When creating or renaming files and directories, the user provides a name consistent with the native file system. The server then uses an algorithm to generate the other name (Long or Short). This section describes the rules for forming CNode names and the algorithm used for creating and maintaining dual names.
The syntax for forming AFP Long Names is the same as the naming syntax used by the Macintosh HFS, with one exception: Null (0x00) is not a permissible character in AFP Long Names. Otherwise, the mapping of character code to character is the same for AFP as it is for OS X. [See AFP Character Encoding .] AFP Long Names are made up of at most 31 characters; valid characters are any printable ASCII code except colon (0x3A) and null (0x00). The volume name, and by inference the root’s Long Name, cannot be longer than 27 bytes.
The syntax for forming AFP Short Names is the same as the naming syntax used by MS-DOS, which is more restrictive than the naming syntax used in the Mac OS: Names may be up to eight alphanumeric characters, optionally followed by a period (0x2E) and a one-to-three character alphanumeric character extension.
To ensure that a CNode can be uniquely specified by either name, AFP defines the following rules:
Therefore, either name, Long or Short, uniquely identifies CNodes within the same directory.
AFP naming rules are such that any MS-DOS name can be used directly as a CNode Short Name, and any OS X name can be used as a Long Name. The file server generates the other name for each CNode, deriving it from the first name specified and matching the second name as closely as possible. The Long Name format is a superset of the Short Name format. The name management algorithm mandates that whenever a CNode is created or renamed with a Short Name, the Long Name will always match. Deriving a Short Name from a Long Name is not so simple, and AFP does not stipulate an exact algorithm for this derivation. Therefore, different servers may create Short Names differently.
When a CNode is created, the caller supplies the node’s name and a name type that indicates whether the name is a Long or Short Name. The server then checks the name to verify that the name conforms to the accepted format. The algorithm that follows describes how servers assign Short and Long Names to a CNode (referred to as an object in this algorithm).
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
