Legacy Document

Inside Macintosh: Networking /

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

Routines /

AFP General Command Format

You use the general command format for the AFPCommand function to pass any of the AFP commands to the .XPP driver to be sent to the server except afpLogin, afpRead,
and afpWrite.

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

thePBptr

A pointer to the XPP parameter block format for the AFP commands that use the AFP general command format.

async

A Boolean that specifies whether the function is to be executed synchro-
nously or asynchronously. Set the async parameter to TRUE to execute the function asynchronously.

-->	ioCompletion	ProcPtr	A pointer to a completion routine.
<--	ioResult	OSErr	The function result.
<--	cmdResult	LongInt	The AFP command result.
-->	ioRefNum	Integer	The .XPP driver reference number.
-->	csCode	Integer	Always afpCall for this function.
-->	sessRefnum	Integer	The session reference number.
-->	aspTimeout	Byte	The retry interval in seconds.
-->	cbSize	Integer	The command buffer size.
-->	cbPtr	Ptr	The command buffer.
<->	rbSize	Integer	The reply buffer size and reply size.
-->	rbPtr	Ptr	A pointer to the reply buffer.
<->	wdSize	Integer	The write data size.
-->	wdPtr	Ptr	A pointer to the write data.

Field Description

cmdResult

Four bytes of data returned from the server indicating the result of the AFP command.

sessRefnum

The session reference number, which is a unique number that the .XPP driver assigns to the session and returns in response to an afpLogin command.

aspTimeout

The interval in seconds that the .XPP driver waits between retries of the AFP command.

cbSize

The size in bytes of the block of data that contains the command and its parameters to be sent to the server across the session.
The size of the command block must not exceed the value of aspMaxCmdSize that the ASPGetParms function returns. For information on the ASPGetParms function, see the chapter "AppleTalk Session Protocol (ASP)" in this book.

cbPtr

A pointer to the beginning of the command block that contains the AFP command to be sent across the session to the server. (The cbSize field value specifies the command block size.) The first byte of the command block must contain the AFP command. The following bytes contain the parameters for the command. See
Inside AppleTalk, second edition, and the AppleShare 3.0 Developer's Kit version 3.0 for the definitions of the AFP commands and their command codes and parameters.

rbSize

On input, the size in bytes of the reply buffer that is to hold the expected response to the AFP command. On return, the actual size of the reply to the AFP command that the .XPP driver returned in the buffer.

rbPtr

A pointer to the reply buffer.

wdSize

The size of the write data buffer that contains the data to be written to the server. This field's value is used only if the AFP command is one that the .XPP driver maps to the ASPUserWrite function.

wdPtr

A pointer to the write-data buffer. This field's value is used only
if the AFP command is one that the .XPP driver maps to the ASPUserWrite function.

DESCRIPTION

The general format of the AFPCommand function provides a way to pass an AFP command to the server end of an open session and receive a reply. After you open a session with
an AFP file server using the login format of the AFPCommand function, you can send a sequence of AFP commands across the session to the server. You use the general format for the AFPCommand function to send all of the AFP commands to the server, except for afpLogin, afpRead, and afpWrite, which have their own AFPCommand formats. AFP delivers the commands in the same order in which you send them and returns replies to the commands in the reply buffer that you provide. The cmdResult field indicates the result of the command that was delivered to the server, not the function result.

SPECIAL CONSIDERATIONS

Note that you must provide the .XPP driver reference number as an input parameter
to this function. You can obtain the driver reference number by calling the Device Manager's OpenDriver function. For information on the OpenDriver function, see Inside Macintosh: Devices.

Any memory that you allocate for the parameter block, buffers, and command block belongs to the .XPP driver until the function completes execution, after which you can reuse or release the memory.

ASSEMBLY-LANGUAGE INFORMATION

To execute the AFPCommand function from assembly language, call the _Control trap macro with a value of afpCall in the csCode field of the parameter block.

RESULT CODES

aspBufTooSmall	-1067	The command reply from the server is larger than the response buffer; ASP will fill the buffer and truncate the reply data
aspParamErr	-1070	You specified an invalid session reference number, or the session has been closed
aspSessClosed	-1072	The .XPP driver is in the process of closing the session
aspSizeErr	-1073	The size of the command block exceeds the maximum size of aspMaxCmdSize
afpParmError	-5019	The AFP command block size is equal to 0 (this error is also returned when the command block is equal to 0 or $FF [255] or GetSrvrStatus [15])

SEE ALSO

For a list of the AFP commands and their command code numeric values and constants, see Table 9-1 on page 9-9. To determine which AFP commands take the general AFPCommand format, see Table 9-2 on page 9-13. For a description of the AFP commands that you can send to a server and their required command block formats, see Inside AppleTalk, second edition, and the AppleShare 3.0 Developer's Kit version 3.0.