Legacy Document

Inside Macintosh: Networking /

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

Routines /

AFP Read Command Format

To read a block of data on an AFP file server, you use the read command format for the AFPCommand function, which passes the afpRead command to the .XPP driver.

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.

-->	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	A pointer to the command buffer.
<->	rbPtr	Ptr	A pointer to the reply buffer.

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 call.

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. The "Description" section that follows explains the command block structure that you use for the afpRead command. See the chapter "AppleTalk Session Protocol (ASP)" for information on the ASPGetParms function.

cbPtr

A pointer to the beginning of the command block that contains
the afpRead command. The cbSize field value specifies the command block size. The first byte of the command block must contain the AFP command. The following command block
bytes contain the parameters for the command.

rbPtr

A pointer to the reply buffer. The .XPP driver updates this field as it proceeds; the value of this field points to the section of the buffer into which the . XPP driver is currently reading data.

DESCRIPTION

After you open a session, you can use the afpRead command to read a block of data from the server. The AFPCommand function format for the read command allows you to read more data than you can through a single call to an ASPUserCommand function.

You use the command block buffer to pass the read command and its parameters to the .XPP driver. (You pass the size of the read data buffer in the command block, not in the parameter block.) The command block for the afpRead command consists of the following fields. The byte offsets for these fields are relative to the location indicated by the command block pointer (cbPtr).

Command block

-->	cmdByte	Byte	The AFP command code.
<->	rwOffset	LongInt	The offset within fork to begin reading
<->	reqCount	LongInt	On input, size of the read data buffer; on return, size of data actually read into the buffer.
-->	newLineFlag	Byte	A flag indicating whether the read is to be terminated at a specified character.
-->	newLineChar	Byte	The character used to determine where the read should be terminated.

Field Description

cmdByte

The AFP command code, which is always afpRead for
this command.

rwOffset

The byte offset within the fork at which the read is to begin. The .XPP driver modifies the value of this field as it proceeds; the field always reflects the current value.

reqCount

On input, the requested size of the read data buffer. On return, the actual size of the data that was read. The .XPP driver modifies
the value of this field as it proceeds; the field always reflects the current value.

newLineFlag

A 1-bit flag (the high bit of the byte) indicating whether the read is to be terminated at a specified character: set the high bit to 0 to indicate that you are not specifying a new-line character in the newLineChar field; set the high bit to 1 to indicate that you are specifying a new-line character in the newLineChar field. Set all other bits to 0.

newLineChar

A character from $00 to $FF inclusive that, when encountered in reading the fork, causes the read operation to terminate.

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 more information on the OpenDriver function, see Inside Macintosh: Devices.

The memory that you allocate for the XPP parameter block, command block, and reply buffer belongs to AFP until the function completes execution, after which you can reuse the memory or release it.

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

SEE ALSO

See "AFP Command Block Record" on page 9-5 for the Pascal structure of the command block for an afpRead command.