---

Apple Filing Protocol Reference

Overview

This document describes the Apple Filing Protocol (AFP) commands, data types and constants that can be used to communicate with an AFP file server. AFP allows users of multiple computers to share files easily and efficiently over a network.

Functions

FPAccess

Requests access to a file or directory on a volume for which ACLs are enabled.

   
byte CommandCode
byte Pad
short VolumeID
long DirectoryID
unsigned short Bitmap
16 bytes UUID
long ReqAccess
byte Pathtype
string Pathname

Parameters

CommandCode

kFPAccess (75).

Pad

Pad byte.

VolumeID

Volume identifier.

DirectoryID

Directory identifier.

Bitmap

Reserved.

UUID

Universally Unique Identifier (UUID) of the process sending this command.

ReqAccess

Requested access. For definitions, see “ACL Access Rights.”

PathType

Type of names in Pathname. See Path Type Constants for possible values.

Pathname

Pathname to the file or directory for which access is being requested. Pathname is a string if it contains Short or Long Names or an AFPName if it contains a UTF-8–encoded path.

Result

kFPNoErr if access is allowed. See Table 2 for other possible result codes.

Discussion

The request is sent to the server, which determines whether to grant access.

Support for this command, as well as FPGetACL and FPSetACL is required in order to support access control lists (ACLs). Support for UTF-8 and UUIDs is also required in order to support ACLs.

Table 2 lists the result codes for the FPAccess command.

Figure 1 shows the request block for the FPAccess command.

Version Notes

Introduced in AFP 3.2.

FPAddAPPL

Adds an APPL mapping to the Desktop database.

   
byte CommandCode
byte Pad
short DTRefNum
long DirectoryID
long FileCreator
long ApplTag
byte PathType
string Pathname

Parameters

CommandCode

kFPAddAPPL (53).

Pad

Pad byte.

DTRefNum

Desktop database reference number.

DirectoryID

Ancestor Directory ID.

FileCreator

File creator of the application corresponding to the APPL mapping being added.

ApplTag

User-defined tag stored with the APPL mapping.

PathType

Type of names in Pathname. See Path Type Constants for possible values.

Pathname

Pathname to the application corresponding to the APPL mapping being added. Pathname is a string if it contains Short or Long Names or an AFPName if it contains a UTF-8–encoded path.

Result

kFPNoErr if no error occurred. See Table 2 for other possible result codes.

Reply block

None.

Discussion

This command adds the specified mapping to the volume’s Desktop database, including the application’s location, and file creator. If an APPL mapping for the same application (same filename, same directory, and same file creator) already exists, the mapping is replaced.

The user must have search or write privileges to all ancestors except the application’s parent directory, as well as write access to the parent directory.

There may be more than one application in the Desktop database’s list of APPL mappings for a given file creator. To distinguish among them, the ApplTag parameter is stored with each APPL mapping. The tag information may be used to decide among these multiple applications and is not interpreted by the Desktop database.

The user must have previously called FPOpenDT for the corresponding volume. In addition, the application must be present in the specified directory before this command is sent.

Table 2 lists the result codes for the FPAddAPPL command.

Figure 2 shows the request block for the FPAddAPPL command.

FPAddComment

Adds a comment for a file or directory to a volume’s Desktop database.

   
byte CommandCode
byte Pad
short DTRefNum
long DirectoryID
byte PathType
string Pathname
string Comment

Parameters

CommandCode

kFPAddComment (56).

Pad

Pad byte.

DTRefNum

Desktop database reference number.

DirectoryID

Ancestor Directory ID.

PathType

Type of name in Pathname. See Path Type Constants for possible values.

Pathname

Pathname to the file or directory with which the comment is to be associated. Pathname is a string if it contains Short or Long Names or an AFPName if it contains a UTF-8–encoded path.

Comment

Comment data to be associated with the specified file or directory.

Result

kFPNoErr if no error occurred. See Table 3 for other possible result codes.

ReplyBlock

None.

Discussion

This command stores the comment data in the Desktop database and associates the comment with the specified file or directory. If the comment is longer than 199 bytes, the comment is truncated to 199 bytes without returning an error.

To add a comment to a directory that is not empty, the user needs search access to all ancestors including the directory’s parent directory, as well as write access to the parent directory. To add a comment to an empty directory, the user needs search or write access to all ancestors except the directory’s parent directory, as well as write access to the parent directory.

To add a comment to a file that is not empty, the user needs search access to all ancestors except the file’s parent directory, as well as read and write access to the parent directory. To add a comment to an empty file, the user needs search or write access to all ancestors except the files’s parent directory, as well as write access to the parent directory.

The user must have previously called FPOpenDT for the corresponding volume. In addition, the specified file or directory must be present in the specified directory before this command is sent.

Table 3 lists the result codes for the FPAddComment command.

Figure 3 shows the request block for the FPAddComment command.

FPAddIcon

Adds an icon bitmap to a volume’s Desktop database.

   
byte CommandCode
byte Pad
short DTRefNum
long FileCreator
long FileType
byte IconType
byte Pad
long IconTag
short BitmapSize

Parameters

CommandCode

kFPAddIcon (192).

Pad

Pad byte.

DTRefNum

Desktop database reference number.

FileCreator

File creator associated with the icon that is to be added.

FileType

File type associated with the icon that is to be added.

IconType

Type of icon that is to be added.

Pad

Pad byte.

IconTag

Tag information to be stored with the icon.

BitmapSize

Size of the bitmap for this icon.

Result

kFPNoErr if no error occurred, kFPParamErr if the session reference number or the Desktop database reference number is unknown or if the pathname is invalid, kFPIconTypeError if the new icon’s size is different from the size of the existing icon, or kFPMiscErr if an error occurred that is not specific to AFP.

ReplyBlock

None.

Discussion

This command adds the icon for the specified file creator and icon type to the Desktop database and associates the tag information with the icon. If an icon of the same file creator and icon type already exists in the database, the icon is replaced. However, if the new icon’s size is different from the old icon, the server returns a kFPIconTypeError result code.

The user must have previously called FPOpenDT for the corresponding volume.

Figure 4 shows the request block for the FPAddIcon command.

FPByteRangeLock

Locks or unlocks a specified range of bytes within an open fork.

   
byte CommandCode
byte Flags
short OForkRefNum
long Offset
long Length

Parameters

CommandCode

kFPByteRangeLock (1).

Pad

Pad byte.

DTRefNum

Bit 0 is the LockUnlock bit, where 0 indicates lock and 1 indicates unlock. Bit 7 is the StartEndFlag bit, where 0 indicates that Offset is relative to the beginning of the fork and 1 indicates that Offset is relative to the end of the fork. The StartEndFlag bit is only used when locking a range.

OForkRefNum

Open fork reference number.

Offset

Offset to the first byte of the range to be locked or unlocked (can be negative if the StartEndFlag bit is set to 1).

Length

Number of bytes to be locked or unlocked (a signed, positive long integer; cannot be negative except for the special value $FFFFFFFF).

Result

kFPNoErr if no error occurred. See Table 4 for possible result codes.

ReplyBlock

If the result code is kFPNoErr and the reply is for an attempt to lock a range, the server returns a reply block. The reply block consists of a long, called RangeStart, containing the number of the first byte of the range that was locked.

Discussion

This command locks and unlocks the specified range of bytes within an open fork for use by a user application. When locking a range, the server returns the number of the first locked byte.

Bytes are numbered from 0 to $7FFFFFFF. The latter value is the maximum size of the fork. The end of fork is one more than the number of the last byte in the fork.

If no user holds a lock on any part of the requested range, the server locks the range specified by this command. A user can hold multiple locks within the same open fork, up to a server-specific limit. Locks cannot overlap. A locked range can start or extend past the end of fork; this does not move the end of fork or prevent another user from writing to the fork past the locked range. Setting Offset to zero, the StartEndFlag bit to zero (start), and Length to $FFFFFFFF locks the entire fork to the maximum size of the fork. Setting Offset to a value other than zero, the StartEndFlag bit to zero, and Length to $FFFFFFFF locks a range beginning at Offset and extending to the maximum size of the fork.

Setting the StartEndFlag bit to 1 (end) allows a lock to be offset relative to the end of the fork. This enables a user to set a lock when the user does not know the exact end of the fork, as can happen when multiple writers are concurrently modifying the fork. The server returns the number of the first locked byte.

Lock conflicts are determined by the value of OForkRefNum. That is, if a fork is opened twice, the two open fork reference numbers are considered two different “users” regardless of whether they were opened for the same or different sessions.

All locks held by a user are unlocked when the user closes the fork. Unlocking a range makes it available to other users for reading and writing. The server returns a result code of kFPRangeNotLocked if a user tries to unlock a range that was locked by another user or that was not locked at all.

To unlock a range, the StartEndFlag bit must be set to zero (start), Length must match the size of the range that was locked, and Offset must match the number of the first byte in the locked range. If the range was locked with the StartEndFlag bit set to zero (start), use the same value of Offset to unlock the range that was used to lock the range. If the range was locked with the StartEndFlag bit set to 1 (end), set Offset to the value of RangeStart that was returned by the server. You cannot unlock part of range.

Mac OS X supports memory-mapped files, but byte range locks should not be used in conjunction with them.

Table 4 lists the result codes for the FPByteRangeLock command.

Figure 5 shows the request and reply blocks for the FPByteRangeLock command.

FPByteRangeLockExt

Locks or unlocks a specified range of bytes within an open fork.

   
byte CommandCode
byte Flags
short OForkRefNum
long long Offset
long long Length

Parameters

CommandCode

kFPByteRangeLockExt (59).

Pad

Pad byte.

Flags

Bit 0 is the LockUnlock bit, where 0 indicates lock and 1 indicates unlock. Bit 7 is the StartEndFlag bit, where 0 indicates that Offset is relative to the beginning of the fork and 1 indicates that Offset is relative to the end of the fork. The StartEndFlag bit is only used when locking a range.

OForkRefNum

Open fork reference number.

Offset

Offset to the first byte of the range to be locked or unlocked (can be negative if the StartEndFlag bit is set to 1).

Length

Number of bytes to be locked or unlocked (a signed, positive long integer; cannot be negative except for the special value $FFFFFFFFFFFFFFFF).

Result

kFPNoErr if no error occurred. See Table 5 for possible result codes.

ReplyBlock

If the result code is kFPNoErr and the reply is for an attempt to lock a range, the server returns a reply block. The reply block consists of a long, called RangeStart, containing the number of the first byte of the range that was locked.

Discussion

This command locks and unlocks the specified range of bytes within an open fork for use by a user application. When locking a range, the server returns the number of the locked byte.

The FPByteRangeLockExt command differs from the FPByteRangeLock command in that the FPByteRangeLockExt command is prepared to handle large values that may be required for locking ranges for volumes larger than 4 GB in size.

Bytes are numbered starting from 0. The end of fork is one more than the number of the last byte in the fork.

If no user holds a lock on any part of the requested range, the server locks the range specified by this command. A user can hold multiple locks within the same open fork, up to a server-specific limit. Locks cannot overlap. A locked range can start or extend past the end of the fork; this does not move the end of the fork or prevent another user from writing to the fork past the locked range. Setting Offset to zero, the StartEndFlag bit to zero (start), and Length to $FFFFFFFFFFFFFFFF locks the entire for to the maximum size of the fork. Specifying an offset other than zero, the StartEndFlag bit to zero (start), and Length to $FFFFFFFFFFFFFFFF locks a range beginning at Offset and extending to the maximum size of the fork.

Setting the StartEndFlag bit to 1 (end) allows a lock to be offset relative to the end of the fork. This enables a user to set a lock when the user does not know the exact end of the fork, as can happen when multiple writers are concurrently modifying the fork. The server returns the number of the first locked byte.

Lock conflicts are determined by the value of OForkRefNum. That is, if a fork is opened twice, the two open fork reference numbers are considered two different “users” regardless of whether they were opened for the same or different sessions.

All locks held by a user are unlocked when the user closes the fork. Unlocking a range makes it available to other users for reading and writing. The server returns a result code of kFPRangeNotLocked if a user tries to unlock a range that was locked by another user or that was not locked at all.

To unlock a range, the StartEndFlag bit must be set to zero (start), Length must match the size of the range that was locked, and Offset must match the number of the first byte in the locked range. If the range was locked with StartEndFlag set to zero (start), use the same value of Offset to unlock the range that was used to lock the range. If the range was locked with the StartEndFlag bit set to 1 (end), set Offset to the value of RangeStart that was returned by the server. You cannot unlock part of range.

Mac OS X supports memory-mapped files, but byte range locks should not be used in conjunction with them.

Table 5 lists the result codes for the FPByteRangeLockExt command.

Figure 6 shows the request and reply blocks for the FPByteRangeLockExt command.

FPCatSearch

Searches a volume for files and directories that match specified criteria.

   
byte CommandCode
byte Pad
short VolumeID
long ReqMatches
long Reserved
16 bytes CatalogPosition
short FileRsltBitmap
short DirectoryRsltBitmap
long ReqBitmap
Specification1
Specification2
unsigned char Length

Parameters

CommandCode

kFPCatSearch (43).

Pad

Pad byte.

VolumeID

The ID of the volume to search.

Reserved

Reserved; must be zero.

ReqMatches

The maximum number of matches to return.

CatalogPosition

Current position in the catalog.

FileRsltBitmap

File bitmap describing the file parameters to get or null to get directory parameters only. Set the bit that corresponds to each desired parameter. This bitmap is the same as the FileBitmap parameter of the FPGetFileDirParms command with some restrictions described in the Discussion section. For bit definitions for this bitmap, see File Bitmap.

DirectoryRsltBitmap

Directory bitmap describing the directory parameters to get or null to get file parameters only. Set the bit that corresponds to each desired parameter. This bitmap is the same as the DirectoryBitmap parameter of the FPGetFileDirParms command with some restrictions described in the Discussion section. For bit definitions for this bitmap, see Directory Bitmap.

ReqBitmap

Directory and file parameters that are to be searched. For directory parameters only, see Figure 7. For file parameters only, see Figure 8. For directory and file parameters, see Figure 9.

Specification1

Search criteria lower bounds and values.

Specification2

Optional search criteria upper bounds and masks.

Length

Length of this request block.

Result

kFPNoErr if no error occurred. See Table 6 for possible result codes.

ReplyBlock

If the result code is kFPNoErr, the server returns a reply block. See Table 7 for the format of the reply block.

Discussion

This command searches a volume for files and directories that match the specified criteria and returns an array of records that describe the matches that were found. The criteria can include most parameters in the File bitmap, the Directory bitmap, or both bitmaps, that are defined for the FPGetFileDirParms command. Parameters for the matching files and directories are returned. These parameters can also be any of those specified by the FPGEtFileDirParms command.

The first word of the CatalogPosition parameter specifies whether the parameter denotes an actual catalog position or a hint. If the first word is zero, the search starts at the beginning of the volume. If the first word is non-zero, CatalogPosition is a actual catalog position and the search starts with this entry.

The Specification1 and Specification2 parameters are used together to specify the search parameters. These parameters are packed in the same order as the bits in ReqBitmap. All variable-length parameters (such as those containing names) are put at the end of each specification record. An offset is stored in the specification parameters to indicate where the actual variable-length parameter is located. This offset is measured from the start of the specification parameters (not including the length and filler bytes). Results are packed in the same way.

The fields in Specification1 and Specification2 have different uses:

• In the name field, Specification1 holds the target string; Specification2 must always have a null name field.

• In all date and length fields, Specification1 holds the lowest value in the target range and Specification2 holds the highest value in the target range.

• In file attributes and Finder Info fields, Specification1 holds the target value and Specification2 holds the bitwise mask that specifies which bits in that field in Specification1 are relevant to the current search.

This command returns a result code of kFPEOFErr only when it has reached the end of the volume directory tree. For example, if the client requests ten matches, the server may return only four matches, without returning an error. The client should then send a request for six (ten minus four) more matches, using the same CatalogPosition value that was received in the previous reply. This process continues until the originally requested matches are received or a kFPEOFErr is returned. If this command returns a result code of kFPCatalogChanged, the client cannot continue the search. The client must restart the search by setting the first word of CatalogPosition to zero.

This command returns parameters for files, directories or both, depending on the value of the FileRsltBitmap and DirectoryRsltBitmap parameters. If FileRsltBitmap is null, this command assumes that you are not searching for files. Likewise, if DirectoryRsltBitmap is null, this command assumes that you are not searching for directories. If both parameters are non-zero, this command searches for files and directories. Note that if you are searching for both files and directories, certain restrictions apply with regard to the parameters that are searched. The rest of this section describes these restrictions.

The ReqBitmap parameter specifies the directory and file parameters to be searched. The low-order word of ReqBitmap is the same as low-order word of the File bitmap and the Directory bitmap used by the FPGetFileDirParms command, with the exception of the Short Name parameter, which cannot be searched. The high bit of the high-order word of ReqBitmap indicates whether the search should match on full names or partial names (0 = full name, 1 = partial name). There is no equivalent to the fsSBNegate bit used by the Macintosh File Manager’s PBCatSearch function.

Figure 7 shows parameters this command can search when it is searching directories only.

Figure 8 shows parameters this command can search when it is searching files only.

Figure 9 shows parameters this command can search when it is searching both directories and files.

Before sending this command, the user must call FPOpenVol for the volume that is to be searched.

To return all files and directories that match the specified criteria, the user must have Read Only or Read & Write privileges for all directories. This command skips directories for which the user does not have Read Only or Read & Write privileges.

Table 6 lists the result codes for the FPCatSearch command.

Table 7 describes the reply block for the FPCatSearch command.

Figure 10 shows the request and reply blocks for the FPCatSearch command.

FPCatSearchExt

Searches a volume for files and directories that match specified criteria.

   
byte CommandCode
byte Pad
short VolumeID
long ReqMatches
long Reserved
16 bytes CatalogPosition
short FileRsltBitmap
short DirectoryRsltBitmap
long ReqBitmap
Specification1
Specification2
unsigned char Length

Parameters

CommandCode

kFPCatSearchExt (67).

Pad

Pad byte.

VolumeID

Volume ID.

ReqMatches

Maximum number of matches to return.

Reserved

Reserved; must be zero.

CatalogPosition

Current position in the catalog.

FileRsltBitmap

Bitmap describing the file parameters to get or null to get directory parameters only. Set the bit that corresponds to each desired parameter. This bitmap is the same as the FileBitmap parameter of the FPGetFileDirParms command with some restrictions described later in this section. For bit definitions for this bitmap, see File Bitmap.

DirectoryRsltBitmap

Bitmap describing the directory parameters to get or null to get file parameters only. Set the bit that corresponds to each desired parameter. This bitmap is the same as the DirectoryBitmap parameter of the FPGetFileDirParms command with some restrictions described later in this section. For bit definitions for this bitmap, see Directory Bitmap.

ReqBitmap

Directory and file parameters that are to be searched. For directory parameters, see Figure 11. For file parameters, see Figure 12. For directory and file parameters, see Figure 13.

Specification1

Search criteria lower bounds and values.

Specification2

Optional search criteria upper bounds and masks.

Length

Length of this request block.

Result

kFPNoErr if no error occurred. See Table 8 for possible result codes.

ReplyBlock

If the result code is kFPNoErr, the server returns a reply block. See Table 9 for the format of the reply block.

Discussion

This command searches a volume for files and directories that match the specified criteria and returns an array of records that describe the matches that were found.

This command differs from the FPCatSearch command in that FPCatSearchExt is prepared to handle longer search results that can occur when searching volumes that are more than 4 GB in size.

The criteria can include most parameters in the File bitmap, the Directory bitmap, or both bitmaps, that are defined for the FPGetFileDirParms command. Parameters for the matching files and directories are returned. These parameters can also be any of those specified by the FPGetFileDirParms command.

The first word of the CatalogPosition parameter specifies whether the parameter denotes an actual catalog position or a hint. If the first word is zero, the search starts at the beginning of the volume. If the first word is non-zero, CatalogPosition is an actual catalog position and the search starts with this entry.

The Specification1 and Specification2 parameters are used together to specify the search parameters. These parameters are packed in the same order as the bits in the ReqBitmap. All variable-length parameters (such as those containing names) are put at the end of each specification record. An offset is stored in the specification parameters to indicate where the actual variable-length parameter is located. This offset is measured from the start of the specification parameters (not including the length and filler bytes). Results are packed in the same way.

The fields in Specification1 and Specification2 have different uses:

• In the name field, Specification1 holds the target string; Specification2 must always have a null name field.

• In all date and length fields, Specification1 holds the lowest value in the target range and Specification2 holds the highest value in the target range.

• In Attributes and Finder Info fields, Specification1 holds the target value and Specification2 holds the bitwise mask that specifies which bits in that field in Specification1 are relevant to the current search.

This command returns a result code of kFPEOFErr only when it has reached the end of the volume directory tree. For example, if the client requests ten matches, the server may return only four matches, without returning an error. The client should then send a request for six (ten minus four) more matches, using the same CatalogPosition value that was received in the previous reply. This process continues until the originally requested matches are received or a result code of kFPEOFErr is returned. If this command returns a result code of kFPCatalogChanged, the client cannot continue the search. The client must restart the search by setting the first word of CatalogPosition to zero.

This command returns parameters for files, directories or both, depending on the value of the FileRsltBitmap and DirectoryRsltBitmap parameters. If FileRsltBitmap is null, this command assumes that you are not searching for files. Likewise, if DirectoryRsltBitmap is null, this command assumes that you are not searching for directories. If both parameters are non-zero, this command searches for files and directories. Note that if you are searching for both files and directories, certain restrictions apply with regard to the parameters that are searched. The rest of this section describes these restrictions.

The ReqBitmap parameter specifies the directory and file parameters to be searched. The low-order word of ReqBitmap is the same as low-order word of the File bitmap and the Directory bitmap in FPGetFileDirParms, with the exception of the Short Name parameter, which cannot be searched. The high bit of the high-order word of ReqBitmap indicates whether the search should match on full names or partial names (0 = full name, 1 = partial name). There is no equivalent to the fsSBNegate bit used by the Macintosh File Manager’s PBCatSearch function.

Figure 11 shows parameters this command can search when it is searching directories only.

Figure 8 shows parameters this command can search when it is searching files only.

Figure 9 shows parameters this command can search when it is searching both directories and files.

Before sending this command, the user must call FPOpenVol for the volume that is to be searched.

To return all files and directories that match the specified criteria, the user must have Read Only or Read & Write privileges for all directories. This command skips directories for which the user does not have Read Only or Read & Write privileges.

Table 8 lists the result codes for the FPCatSearchExt command.

Table 9 describes the reply block for the FPCatSearchExt command.

Figure 14 shows the request and reply blocks for the FPCatSearchExt command.

FPChangePassword

Allows users to change their passwords.

   
byte CommandCode
byte Pad
string UAM
string UserName
UserAuthInfo

Parameters

CommandCode

kFPChangePassword (36).

Pad

Pad byte.

UAM

String specifying the UAM to uses.

UserName

Name of the user whose password is to be changed. Starting with AFP 3.0, UserName is two bytes with each byte set to zero. The first byte indicates a zero length string, and the second byte is a pad byte.

UserAuthInfo

UAM-specific information.

Result

kFPNoErr if no error occurred. See Table 10 for other possible result codes.

ReplyBlock

None.

Discussion

If the UAM is Cleartxt Passwrd, the AFP client sends the server the user’s name plus the user’s old and new eight-byte passwords in cleartext. The server looks up the password for that user. If it matches the old password sent in the packet, the new password is saved for that user. For more information on the Cleartext Password UAM, see the section “Cleartext Password” in the “Introduction” section.

If the UAM is Randnum Exchange, DES is used to encrypt and decrypt passwords. The AFP client sends the server the user name, the user’s old eight-byte password encrypted with the user’s new eight-byte password, and the user’s new eight-byte password encrypted with the user’s old eight-byte password. The server looks up the password for that user, uses that password as a key to decrypt the new password, and uses the result to decrypt the old password. If the final result matches what the server knows to be the old password, the new password is saved for that user. For more information on the Random Number Exchange UAM, see the section “Random Number Exchange” in the “Introduction” section.

When using the Random Number Exchange UAM, be sure to append null bytes to any password that is less than eight bytes so that the resulting password has a length of eight bytes.

If the user logged in using the Two-Way Random Number Exchange UAM, the client uses the Randnum UAM for changing the user’s password.

If the UAM is DHCAST128, the AFP client must call FPChangePassword twice. The first time, the AFP client calls FPChangePassword to send the user name and a random number that has been encrypted. The server replies with an ID, a random number, and a nonce/server signature value encrypted by a session key. The AFP client calls FPChangePassword again, this time sending the user name and the ID returned by the server. The client also sends the nonce incremented by one, the new password, and the old password, all encrypted by the session key. For information on using the DHX UAM to change passwords, see the section “DHX and Changing a Password” in the “Introduction” section.

Servers are not required to support this command. Call FPGetSrvrInfo to determine whether a server supports this command.

The user may not have been granted the ability to change his or her password. Granting the ability to change a password is an administrative function and is beyond the scope of this protocol specification.

Table 10 lists the result codes for the FPChangePassword command.

Figure 15 shows the request block for the FPChangePassword command.

FPCloseDir

Closes a directory and invalidates its Directory ID.

   
byte CommandCode
byte Pad
short VolumeID
long DirectoryID

Parameters

CommandCode

kFPCloseDir (3).

Pad

Pad byte.

VolumeID

Volume ID.

DirectoryID

Directory ID.

Result

kFPNoErr if no error occurred, kFPParamErr if the session reference number, Volume ID, or Directory ID is unknown, or kFPMiscErr if an error occurred that is not specific to AFP.

ReplyBlock

None.

Discussion

This command invalidates the Directory ID specified by DirectoryID.

This command should be used only for variable Directory ID volumes. The user must have previously called FPOpenVol for this volume and FPOpenDir for this directory.

Figure 16 shows the request block for the FPCloseDir command.

FPCloseDT

Closes a volume’s Desktop database.

   
byte CommandCode
byte Pad
short DTRefNum

Parameters

CommandCode

kFPCloseDT (49).

Pad

Pad byte.

DTRefNum

Desktop database reference number.

Result

kFPNoErr if no error occurred, kFPParamErr if the session reference number or the Desktop database reference number is unknown, or kFPMiscErr if an error occurred that is not specific to AFP.

ReplyBlock

None.

Discussion

This command invalidates the Desktop database reference number specified by DTRefNum.

The user must first have sent a successful FPOpenDT command.

Figure 17 shows the request block for the FPCloseDT command.

FPCloseFork

Closes a fork.

   
byte CommandCode
byte Pad
short OForkRefNum

Parameters

CommandCode

kFPCloseFork (4).

Pad

Pad byte.

OForkRefNum

Open fork reference number.

Result

kFPNoErr if no error occurred, kFPParamErr if the session reference number or the open fork reference number is unknown, or kFPMiscErr if an error occurred that is not specific to AFP.

ReplyBlock

None.

Discussion

This command causes the server to flush and close the specified fork, invalidating the open fork reference number. If the fork was written to, the file’s modification date is set to the server’s clock.

The user must first have sent a successful FPOpenFork command.

Figure 18 shows the request block for the FPCloseFork command.

FPCloseVol

Closes a volume.

   
byte CommandCode
byte Pad
short VolumeID

Parameters

CommandCode

kFPCloseVol (2).

Pad

Pad byte.

VolumeID

Volume ID.

Result

kFPNoErr if no error occurred, kFPParamErr if the session reference number or the Volume ID is unknown, or kFPMiscErr if an error occurred that is not specific to AFP.

ReplyBlock

None.

Discussion

This command invalidates the specified Volume ID but does not necessarily close all open files on a volume before closing the volume, so you should close all open files before calling FPCloseVol.

The user must first have sent a successful FPOpenVol command for this volume.

After sending this command, the user can send no other commands for this volume without opening the volume again.

Figure 19 shows the request block for the FPCloseVol command.

FPCopyFile

Copies a file from one location to another on the same file server.

   
byte CommandCode
byte Pad
short SourceVolumeID
long SourceDirectoryID
short DestVolumeID
long DestDirectoryID
byte SourcePathType
string SourcePathname
byte DestPathType
string DestPathname
byte NewType
string NewName

Parameters

CommandCode

kFPCopyFile (5).

Pad

Pad byte.

SourceVolumeID

Source Volume ID.

SourceDirectoryID

Source ancestor Directory ID.

DestVolumeID

Destination Volume ID.

DestDirectoryID

Destination ancestor Directory ID.

SourcePathType

Type of names in SourcePathname. See Path Type Constants for possible values.

SourcePathname

Pathname of the file to be copied (cannot be null). SourcePathname is a string if it contains Short or Long Names or an AFPName if it contains a UTF-8–encoded path.

DestPathType

Type of names in DestPathname. See Path Type Constants for possible values.

DestPathname

Pathname to the destination parent directory (may be null). DestPathname is a string if it contains Short or Long Names or an AFPName if it contains a UTF-8–encoded path.

NewType

Type of name in NewName. See Path Type Constants for possible values.

NewName

Name to be given to the copy (may be null).

Result

kFPNoErr if no error occurred. See Table 11 for other possible result codes.

ReplyBlock

None.

Discussion

This command copies a file to a new location on the server. The source and destination can be on the same or on different volumes.

The server tries to open the source file for Read, DenyWrite access. If this fails, the server returns kFPDenyConflict as the result code. If the server successfully opens the file, it copies the file to the directory specified by the destination parameters.

The copy is given the name specified by the NewName parameter. If NewName is null, the server gives the copy the same name as the original. The file’s other name (Long, Short) is generated as described in the section “Catalog Node Names” in Chapter 1. A unique file number is assigned to the file. The server also sets the file’s Parent ID to the Directory ID of the destination parent directory. All other file parameters remain the same as the source file’s parameters. The modification date of the destination parent directory is set to the server’s lock.

The user must have search access to all ancestors of the source file, except the source parent directory, and read access to the source parent directory. Further, the user must have search or write access to all ancestors of the destination file, except the destination parent directory, and write access to the destination parent directory.

This command is optional and may not be supported by all servers.

Table 11 lists the result codes for the FPCopyFile command.

Figure 20 shows the request block for the FPCopyFile command.

FPCreateDir

Creates a new directory.

   
byte CommandCode
byte Pad
short VolumeID
long DirectoryID
byte PathType
string Pathname

Parameters

CommandCode

kFPCreateDir (6).

Pad

Pad byte.

VolumeID

Volume ID.

DirectoryID

Ancestor Directory ID.

PathType

Type of names in Pathname. See Path Type Constants for possible values.

Pathname

Pathname, including the name of the new directory (cannot be null). Pathname is a string if it contains Short or Long Names or an AFPName if it contains a UTF-8– encoded path.

Result

kFPNoErr if no error occurred. See Table 12 for other possible result codes.

ReplyBlock

If the result code is kFPNoErr, the server returns a long, called NewDirectoryID, containing the Directory ID of the new directory in the reply block.

Discussion

This command creates an empty directory having the name specified by the Pathname parameter. The file server assigns the directory a unique Directory ID and returns it in the reply block. The new directory’s Owner ID is set to the User ID of the user sending the command, and its Group ID is set to the ID of the user’s Primary Group ID, if a primary group has been specified for the user.

The new directory’s privileges are initially set to read, write, and search for the owner, with no privileges for a group or Everyone. Finder information is set to zero and all directory attributes are initially cleared. The directory’s creation and modification dates, as well as the modification date of the parent directory, are set to the server’s clock. The directory’s backup date is set to $80000000, signifying that the directory has never been backed up. The directory’s other names are generated as described in the section “Catalog Node Names” in Chapter 1.

The user must have search or write access to all ancestors, except this directory’s parent directory, as well as write access to the parent directory.

Table 12 lists the result codes for the FPCreateDir command.

Figure 21 shows the request and reply blocks for the FPCreateDir command.

FPCreateFile

Creates a new file.

   
byte CommandCode
byte Flag
short VolumeID
long DirectoryID
byte PathType
string Pathname

Parameters

CommandCode

kFPCreateFile (7).

Flag

Bit 7 of the Flag parameter is the CreateFlag bit, where 0 indicates a soft create and 1 indicates a hard create.

VolumeID

Volume ID.

DirectoryID

Ancestor Directory ID.

PathType

Type of names in Pathname. See Path Type Constants for possible values.

Pathname

Pathname, including the name of the new file (cannot be null). Pathname is a string if it contains Short or Long Names or an AFPName if it contains a UTF-8–encoded path.

Result

kFPNoErr if no error occurred. See Table 13 for other possible result codes.

ReplyBlock

None.

Discussion

This command creates an empty file having the name specified by Pathname. For a soft create, if a file by that name already exists, the server returns a result code of kFPObjectExists. Otherwise, it creates a new file and assigns it the name specified by Pathname. A unique file number is assigned to the file. Finder information is set to zero, and all file attributes are initially cleared. The file’s creation and modification dates, and the modification date of the file’s parent of the file’s parent directory, are set to the server’s clock. The file’s backup date is set to $80000000, signifying that this file has never been backed up. The file’s other names are generated as described in the section “Catalog Node Names” in Chapter 1. The lengths of both of the file’s forks are set to zero.

For a soft create, the user must have search or write access to all ancestors, except this file’s parent directory, as well as write access to the parent directory. For a hard create, the user must have search access to all ancestors, except the parent directory, as well as read and write access to the parent directory.

For a hard create, if the file already exists and is not open, the file is deleted and then recreated. All file parameters (including the creation date) are reinitialized as described above.

Table 13 lists the result codes for the FPCreateFile command.

Figure 22 shows the request block for the FPCreateFile command.

FPCreateID

Creates a unique File ID for a file.

   
byte CommandCode
byte Pad
short VolumeID
long DirectoryID
byte PathType
string Pathname

Parameters

CommandCode

kFPCreateID (39).

Pad

Pad byte.

VolumeID

Volume ID.

DirectoryID

Directory ID of the directory in which the file is to be created.

PathType

Type of names in Pathname. See Path Type Constants for possible values.

Pathname

Name of the file that is the target of the File ID (that is, the filename of the file for which a File ID is being created). Pathname is a string if it contains Short or Long Names or an AFPName if it contains a UTF-8–encoded path.

Result

kFPNoErr if no error occurred. See Table 14 for other possible result codes.

ReplyBlock

None.

Discussion

File IDs provide a way to keep track of a file even if its name or location changes. The scope of a File ID is limited to the files on a volume. File IDs cannot be used across volumes.

The AFP server should take steps to ensure that every File ID is unique and that no File ID is reused once it has been deleted.

The user must have the Read Only or the Read & Write privilege to use this command.

Table 14 lists the result codes for the FPCreateID command.

Figure 23 shows the request block for the FPCreateID command.

FPDelete

Deletes a file or directory.

   
byte CommandCode
byte Pad
short VolumeID
long DirectoryID
byte PathType
string Pathname

Parameters

CommandCode

kFPDelete (8).

Pad

Pad byte.

VolumeID

Volume ID.

DirectoryID

Ancestor Directory ID.

PathType

Type of names in Pathname. See Path Type Constants for possible values.

Pathname

Pathname of the file or directory to be deleted (may be null if a directory is to be deleted). Pathnameis a string if it contains Short or Long Names or an AFPName if it contains a UTF-8–encoded path.

Result

kFPNoErr if no error occurred. See Table 15 for other possible result codes.

ReplyBlock

None.

Discussion

When deleting a directory, the server checks to see if it contains any offspring. If a directory contains offspring, the server returns a result code of kFPDirNotEmpty. If a file that is to be deleted is open by any user, the server returns a result code of kFPFileBusy. The modification date of the parent directory of the deleted file or directory is set to the servers clock.

The user must have search access to all ancestors except the file or directory’s parent directory, as well as write access to the parent directory. If a directory is being deleted, the user must also have search access to the parent directory; for a file, the user must also have read access to the parent directory.

The AFP server identifies the Network Trash Folder by name, and that name is not localized in international versions of the Mac OS because it is invisible.

Table 15 lists the result codes for the FPDelete command.

Figure 24 shows the request block for the FPDelete command.

FPDeleteID

Invalidates all instances of the specified File ID.

   
byte CommandCode
byte Pad
short VolumeID
long FileID

Parameters

CommandCode

kFPDeleteID (40).

Pad

Pad byte.

VolumeID

Volume ID.

FileID

File ID that is to be deleted.

Result

kFPNoErr if no error occurred. See Table 16 for other possible result codes.

ReplyBlock

None.

Discussion

This command deletes the specified File ID, which was created by an earlier call to FPCreateID.

The user must have the Read Only or the Read & Write access privilege to use this command.

Table 16 lists the result codes for the FPDeleteID command.

Figure 25 shows the request block for the FPDeleteID command.

FPDisconnectOldSession

Disconnects an old session and transfers its resources to a new session.

   
byte CommandCode
byte Pad
short Type
long TokenLength
string Token

Parameters

CommandCode

kFPDisconnectOldSession (65).

Pad

Pad byte.

Type

Volume ID.

TokenLength

Length of Token.

Token

Token previous obtained by calling FPGetSessionToken.

Result

kFPNoErr if no error occurred, kFPCallNotSupported if the server does not support this command, or kFPMiscErr if an error occurred that is not specific to AFP.

ReplyBlock

None.

Discussion

This command disconnects the session identified by the Token parameter, which was obtained by previously calling FPGetSessionToken and transfers the resources of the old session to the new session.

The AFP client calls this command when the session it previously established was inadvertently disconnected, it successfully establishes a new session, and it is able to restore the state of the previous session. If the AFP client cannot successfully reestablish the state of the previous session, it should call this command, log out, and report the failure to the local operating system.

If the AFP client successfully reestablishes the state of the previous session, it should call this command again to get a new session token.

Figure 26 shows the request block for the FPDisconnectOldSession command.

FPEnumerate

Lists the contents of a directory.

   
byte CommandCode
byte Pad
short VolumeID
long DirectoryID
short FileBitmap
short DirectoryBitmap
short ReqCount
short StartIndex
short MaxReplySize
byte PathType
string Pathname

Parameters

CommandCode

kFPEnumerate (9).

Pad

Pad byte.

VolumeID

Volume ID.

DirectoryID

Identifier for the directory to list.

FileBitmap

Bitmap describing the parameters to return if the enumerated offspring is a file. Set the bit that corresponds to each desired parameter. This bitmap is the same as the FileBitmap parameter of the FPGetFileDirParms command and can be null. For bit definitions for this bitmap, see File Bitmap.

DirectoryBitmap

Bitmap describing the parameters to return if the enumerated offspring is a directory. Set the bit that corresponds to each desired parameter. This bitmap is the same as the DirectoryBitmap parameter of the FPGetFileDirParms command and can be null. For bit definitions for this bitmap, see Directory Bitmap.

ReqCount

Maximum number of ResultsRecord structures for which information is to be returned.

StartIndex

Directory offspring index.

MaxReplySize

Maximum size of the reply block.

PathType

Type of names in Pathname. See Path Type Constants for possible values.

Pathname

Pathname to the desired directory. Pathname is a string if it contains Short or Long Names or an AFPName if it contains a UTF-8–encoded path.

Result

kFPNoErr if no error occurred. See Table 17 for other possible result codes.

ReplyBlock

If the result code is kFPNoErr, the server returns a reply block. See Table 18 for the format of the reply block.

Discussion

This command enumerates a directory as specified by the input parameters. This command differs from the FPEnumerateExt and FPEnumerateExt2 commands in that it is not able to handle values that may be returned when volumes are larger than 4 GB in size.

If FileBitmap is null, only directory offspring are enumerated, and StartIndex can range from one to the total number of directory offspring. Similarly, if DirectoryBitmap is null, only file offspring are enumerated, and StartIndex can range from one to the total number of file offspring. If both bitmaps have bits set, StartIndex can range from one to the total number of offspring. In this case, offspring structures for both files and directories are returned. These structures are not returned in any particular order.

This command is completed when the number of structures specified by ReqCount has been inserted into the reply block, when the reply block is full, or when no more offspring exist to be enumerated. No partial offspring structures are returned.

The server retrieves the specified parameters for each enumerated offspring and packs them, in bitmap order, in structures in the reply block. The server inserts one copy of the input bitmaps before all of the structures.

The server needs to keep variable-length parameters, such as Long Name and Short Name, at the end of each structure. In order to do this, the server represents variable-length parameters in the bitmap order as fixed-length offsets (integers). Each offset is measured from the start of the parameters in each structure (not from the start of the bitmap or the start of the header bytes) to the start of the variable-length parameter. Each structure is padded (suffixed) with a null byte if necessary to make its length even.

If this command returns a result code of kFPNoErr, all structures in the reply block are valid. If any error result code is returned, no valid offspring structures are in the reply block.

If the OffSpring Count bit in the Directory bitmap is set, the server adjusts the Offspring Count of each directory to reflect the access rights the user has to that directory. For example, if a particular directory contains three file and two directory offspring, the server returns the Offspring Count as 2 if the user has only search access to the directory, 3 if the user has only read access to the directory, or 5 if the user has both search and read access to the directory.

The user must have search access to all ancestors except this directory. In addition, the user needs search access to this directory in order to enumerate directory offspring and read access in order to enumerate file offspring.

Enumerating a large directory may require the sending of several FPEnumerate commands. During that time, other users may add to or delete from the directory, so enumeration can miss offspring or return duplicate offspring. To enumerate a directory accurately, enumerate until a kFPObjectNotFound result code is returned and then filter out duplicate entries.

A given offspring is not guaranteed to occupy the same index number in the parent directory from one enumeration to the next.

Table 17 lists the result codes for the FPEnumerate command.

Table 18 describes the reply block for the FPEnumeratecommand.

Figure 27 shows the request and reply blocks for the FPEnumerate command.

FPEnumerateExt

Lists the contents of a directory.

   
byte CommandCode
byte Pad
short VolumeID
long DirectoryID
short FileBitmap
short DirectoryBitmap
short ReqCount
short StartIndex
short MaxReplySize
byte PathType
string Pathname

Parameters

CommandCode

kFPEnumerateExt (66).

Pad

Pad byte.

VolumeID

Volume ID.

DirectoryID

Identifier for the directory to list.

FileBitmap

Bitmap describing the parameters to return if the enumerated offspring is a file. Set the bit that corresponds to each desired parameter. This bitmap is the same as the FileBitmap parameter of the FPGetFileDirParms command and can be null. For bit definitions for this bitmap, see File Bitmap.

DirectoryBitmap

Bitmap describing the parameters to return if the enumerated offspring is a directory. Set the bit that corresponds to each desired parameter. This bitmap is the same as the DirectoryBitmap parameter of the FPGetFileDirParms command and can be null. For bit definitions for this bitmap, see Directory Bitmap.

ReqCount

Maximum number of ResultsRecord structures for which information is to be returned.

StartIndex

Directory offspring index.

MaxReplySize

Maximum size of the reply block.

PathType

Type of names in Pathname. See Path Type Constants for possible values.

Pathname

Pathname to the desired directory. Pathname is a string if it