Legacy Document

Inside Macintosh: Networking /

Chapter 9 - AppleTalk Filing Protocol (AFP) / AFP Reference

Routines

The programming interface to AFP is different in form from the programming interfaces to the other AppleTalk protocols described in this book. For AFP, the programming interface consists of a single function, the AFPCommand function, which allows you to call AFP and pass it the command code for a particular AFP command. There are four categories or types of commands that you can send to a server: general, login, write, and read. To use the commands that form these categories, in addition to this chapter, you must also refer to the books Inside AppleTalk, second edition, and AppleShare 3.0 Developer's Kit version 3.0.

The AFPCommand function requires as a parameter a pointer to an XPP parameter block. This function uses a different parameter block format for each category. You do not specify the command code as a parameter block field value, as you might expect. Instead, as the value of a parameter block field you specify a pointer to a command buffer. You use the command buffer to specify the command code of the AFP command to be sent to
the server.

Although the AFPCommand function syntax is the same for all four formats, the fields of the XPP parameter block that are used for each format differ. The AFPCommand function is defined as follows:

FUNCTION AFPCommand (thePBptr: XPPParmBlkPtr; 
                     async: Boolean): OSErr;

thePBptr

A pointer to the XPP parameter block format for a particular group of AFP commands.

async

A Boolean that specifies whether the function is to execute synchronously or asynchronously. Set the async parameter to TRUE to execute the function asynchronously.

This section describes the XPP parameter block format for each category of commands. An arrow preceding a parameter block field indicates whether the field's value is an input parameter, an output parameter, or both:

Arrow	Meaning
-->	Input
<--	Output
<->	Both

Within the parameter block, you specify a pointer to a command block, the first byte of which contains the command code of the command to be sent to the server. The range
of command codes is 0 through 255, inclusive, although AppleTalk does not currently implement all command codes and some command codes are invalid. Table 9-1 shows the AFP command codes that are implemented in AppleTalk. This table shows the AFP command code constant, the numeric value, and a description of the command.

Note

The following six constants may not be defined in the header files: afpGetSrvrMsg, afpCreateID, afpDeleteID, afpResolveID, afpExchangeFiles, and afpCatSearch. If you use the commands that these constants identify, you must either specify the numeric values for the commands or declare the constants in your application.

AFP command codes

AFP command constant	Command code	Action
afpByteRangeLock	1	Locks or unlocks a specified range of bytes within an open fork.
afpVolClose	2	Informs the server that the workstation no longer needs the volume.
afpDirClose	3	Closes a directory and invalidates its directory identifier.
afpForkClose	4	Closes a fork that was opened by afpOpenFork.
afpCopyFile	5	Copies a file from one location to another on the same file server.
afpDirCreate	6	Creates a new directory.
afpFileCreate	7	Creates a new file.
afpDelete	8	Deletes a file or directory.
afpEnumerate	9	Lists the contents of a directory.
afpFlush	10	Writes to a disk any volume data that has been modified.
afpForkFlush	11	Writes to a disk any data buffered from previous afpWrite calls.
afpGetForkParms	14	Retrieves parameters for a file associated with a particular open fork.
afpGetSInfo	15	Obtains a block of descriptive information from the server, without requiring an open session. Use the ASPGetStatus function instead of this command code. See the chapter "AppleTalk Session Protocol (ASP)" in this book for information on ASPGetStatus. Making an afpGetSInfo call using the AFPCommand results in an error.
afpGetSParms	16	Retrieves server parameters.
afpGetVolParms	17	Retrieves parameters for a particular volume.
afpLogin	18	Establishes an AFP session with a server.
afpContLogin	19	Continues the login and user authentication process started by the afpLogin command.
afpLogout	20	Terminates a session with a server.
afpMapID	21	Maps a user ID to a user name, or a group ID to a group name.
afpMapName	22	Maps a user name to a user ID, or a group name to a group ID.
afpMove	23	Moves a directory or file to another location on the same volume.
afpOpenVol	24	Makes a volume available to the workstation.
afpOpenDir	25	Opens a directory on a variable directory ID volume and returns its directory ID.
afpOpenFork	26	Opens the data or resource fork of an existing file to read from it or write to it.
afpRead	27	Reads a block of data from an open fork.
afpRename	28	Renames a directory or file.
afpSetDirParms	29	Sets parameters for a specified directory.
afpSetFileParms	30	Sets parameters for a specified file.
afpSetForkParms	31	Sets the fork length for a specified open fork.
afpSetVolParms	32	Sets the backup date for a specified volume.
afpWrite	33	Writes a block of data to an open fork.
afpGetFlDrParms	34	Retrieves parameters for either a file or a directory.
afpSetFlDrParms	35	Sets parameters for a file or directory.
afpGetSrvrMsg[1]	38	Gets a string message from the server, such as shutdown, user, and login messages.
afpCreateID*	39	Creates a unique file ID for a specified file.
afpDeleteID*	40	Invalidates all instances of a specified file ID.
afpResolveID*	41	Returns parameters for the file referred to by the specified file ID.
afpExchangeFiles*	42	Preserves an existing file ID when an application performs a "Save" or "Save As" operation.
afpCatSearch*	43	Allows an application to efficiently search an entire volume for files that match specified criteria.
afpDTOpen	48	Opens the Desktop database on a particular volume.
afpDTClose	49	Informs the server that the workstation no longer needs the volume's Desktop database.
afpGetIcon	51	Retrieves an icon from the volume's Desktop database.
afpGtIcnInfo	52	Retrieves icon information from the volume's Desktop database.
afpAddAPPL	53	Adds an APPL mapping to the Desktop database.
afpRmvAPPL	54	Removes an APPL mapping from the volume's Desktop database.
afpGetAPPL	55	Retrieves an APPL mapping from the volume's Desktop database.
afpAddCmt	56	Adds a comment for a file or directory to the volume's Desktop database.
afpRmvCmt	57	Removes a comment from the volume's Desktop database.
afpGetCmt	58	Retrieves a comment associated with a specified file or directory from the volume's Desktop database.
afpAddIcon	192	Adds an icon bitmap to the volume's Desktop database.

The command block buffer that you provide for each AFPCommand function contains the command code and the command parameters. The format for the command block differs for each command.

For a description of the commands and their required command block formats and parameters, see Inside AppleTalk, second edition, and the AppleShare 3.0 Developer's Kit version 3.0 as follows:

• For command codes 38 through 43, inclusive, see the AppleShare 3.0 Developer's Kit version 3.0.
• For all other AFP command codes, see Inside AppleTalk, second edition.

The .XPP driver implements most AFP commands by mapping the AFP command to an ASP function, without interpreting or verifying the data. The .XPP driver maps AFP commands to ASP functions according to the following conventions:

AFP commands are mapped to ASP functions, which use the services of ATP to transport data. The following two AFP command codes can send or receive more data than a single eight-packet ATP transaction will support.

• The afpRead command (27) can cause the server to return more data than fits in
  eight ATP response packets. (The aspQuantumSize parameter of the ASPGetParms function returns the maximum amount of data that you can receive from the server.) The afpRead command can return up to the number of bytes indicated in the command block's requested count (reqCount) field. The .XPP driver may issue multiple calls to ASP for this command mapping.
• The afpWrite command (33) can pass more data than fits in eight ATP response packets. The afpWrite command can pass up to the number of bytes indicated in
  the command block's requested count (reqCount) field. The .XPP driver may issue multiple calls to ASP for this command mapping.

Table 9-2 summarizes the mapping of AFP commands to ASP functions.

Table 9-2 Mapping of AFP commands to ASP functions

AFP command code	ASP function mapping
0	Invalid AFP command.
1-14, 16, 17, 21-32, 34-190	Mapped to ASPUserCommand.
15	Mapped to ASPGetStatus. Use ASPGetStatus instead of this command code. Making an afpGetSInfo call using the AFPCommand function results in an error.
18	Mapped to appropriate login dialog including ASPOpenSession.
19	Mapped to appropriate login dialog.
20	Mapped to ASPCloseSession.
33	Mapped to ASPUserWrite.
191	Mapped to ASPUserCommand. Reserved for developers; Apple Computer, Inc., will not use this command code.
192-253	Mapped to ASPUserWrite.
254	Mapped to ASPUserWrite. Reserved for developers; Apple Computer, Inc., will not use this command code.
255	Invalid AFP command.

Before you can call the AFPCommand function, you must open the .XPP driver. You can use the Device Manager's OpenDriver function to open the .XPP driver. You should not close the .XPP driver because other applications and processes may be using it. For more information on opening the .XPP driver, see the chapter "AppleTalk Utilities" in this book. The .MPP and .ATP drivers must be open before you open the .XPP driver.

The chapter "AppleTalk Utilities" also describes how to close the .XPP driver. However, in most circumstances, you should not close the .XPP driver because other applications and processes could be using the protocols implemented by the .XPP driver.

You must pass the .XPP driver reference number as a parameter to the AFPCommand function; the MPW interface does not fill in this value. The OpenXPP function that you use to open the .XPP driver returns the driver reference number in the refnum field. You can call this function to obtain the .XPP driver's reference number even if the .XPP driver is already open.

For all AFPCommand formats, the XPP parameter block includes a CCBStart field.
The .XPP driver uses the memory at the end of the XPP parameter block defined as
a CCBStart array as an internal command control block (CCB). To ensure that the function executes successfully, you can specify the maximum size for this array as indicated for the particular function that uses it.

---

[1] An asterisk (*) marks the constants that may not be defined in the header files. If you use them, you must first declare the constants in your application.