Legacy Document

Inside Macintosh: Networking /

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

Routines /

AFP Login Command Format

You use the login command format for the AFPCommand function to pass the afpLogin command to the .XPP driver to open a session with an AFP file server.

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

thePBptr

A pointer to the XPP parameter block format for the afpLogin command.

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.
-->	ioRefNum	Integer	The .XPP driver reference number.
<--	cmdResult	LongInt	The AFP command result.
-->	csCode	Integer	Always afpCall for this function.
<--	sessRefnum	Integer	The session reference number.
-->	aspTimeout	Byte	The retry interval in seconds.
-->	aspRetry	Byte	The number of retries.
-->	cbSize	Integer	The command buffer size.
-->	cbPtr	Integer	A pointer to the command buffer.
<->	rbSize	Integer	On input, the reply buffer size. On return, the actual reply size.
-->	rbPtr	Ptr	A pointer to the reply buffer.
-->	afpAddrBlock	AddrBlock	The internet socket address of the server.
<->	afpSCBPtr	Ptr	A pointer to the SCB.
<->	afpAttnRoutine	Ptr	A pointer to an attention routine.

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.

aspTimeout

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

aspRetry

The number of times that the .XPP driver is to retry to execute 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)."

cbPtr

A pointer to the beginning of the command block that contains the AFP login 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 login command. The following command block bytes contain the parameters for the command. For the definitions of the AFP commands and their command codes and parameters, see Inside AppleTalk, second edition, and the AppleShare 3.0 Developer's Kit version 3.0.

rbSize

On input, the size in bytes of the reply buffer that is to hold the expected response to the AFP login 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.

afpAddrBlock

The internet socket address of the server to which the command is to be sent.

afpSCBPtr

A pointer to a session control block (SCB) that the .XPP driver requires to maintain an open session. The scbMemSize constant defines the size of the session control block. The memory that you allocate for the SCB must be nonrelocatable or locked because it belongs to the .XPP driver for the life of the session. Each session requires its own SCB.

afpAttnRoutine

A pointer to a routine that the .XPP driver calls when it receives an attention request from the server. If you do not want the .XPP driver to call an attention routine, set this field to 0.

DESCRIPTION

To open a session with an AFP file server, you call the AFPCommand function and
pass it the afpLogin command in the command block that you provide. You point
to the command block from the XPP parameter block's cbPtr field. You specify the internet socket address of the server that you want to access as the value of the afpAddrBlock field.

In addition to allocating memory for the parameter block and the command block, you must provide a session control block (SCB) and pass the AFPCommand function a pointer to the SCB in the afpSCBPtr field. The .XPP driver uses the SCB internally to manage the session. Each session requires its own SCB. You must either allocate nonrelocatable memory for the session control block or lock the memory and not modify it for the duration of the session. The SCB size is defined by the constant scbMemSize. The memory belongs to the .XPP driver for the life of the session. You can reuse an SCB after either of the following events occurs:

• You have called an AFPCommand function using the general command format to specify an afpLogout command to close the session and the AFPCommand function has successfully completed execution.
• The server end of the session has closed the session or the .XPP driver has closed
  the session.

AFP includes an attention mechanism that allows the server to send an attention request to the workstation. For example, a file server can use this messaging system to notify all of the workstations that are using the file server that it is shutting down. The XPP parameter block for the login format includes a pointer to an attention routine.

When the .XPP driver receives an attention request, it sets the first 2 bytes of the SCB to the attention bytes from the packet. If you have provided an attention routine, the .XPP driver calls it. The .XPP driver also calls the attention routine when the session is closed by either the workstation or the server or AFP itself, for example, because the .XPP driver could not open a session before it exhausted the number of retries.

You code the attention routine in assembly language. Because the .XPP driver calls your attention routine at interrupt level, you must observe the following interrupt conven-
tions in writing the attention routine:

• An attention routine can change registers A0 through A3 and D0 through D3.
• The routine must not call any Memory Manager routines.

The .XPP driver calls your attention routine with

• D0 (word) equal to the session reference number (sessRefnum) for that session. This is the number that AFP returns on completion of the AFPCommand function for the afpLogin command.
• D1 (word) equal to the attention bytes passed by the server or 0 if the session
  is closing.

To resume normal execution, your attention routine must return with an RTS (return from subroutine) instruction.

If you code your program in a high-level language, such as Pascal, you might not want to provide an attention routine written in assembly language. If you do not want to provide an attention routine, you can poll the attention bytes to determine if your application has received an attention request from the server. The attention bytes are the first 2 bytes of the session control block. When the server sends an attention request to the workstation, the .XPP driver receives the request and it sets the first 2 bytes of the SCB to the attention bytes from the packet. (When the session was opened, the .XPP driver set these bytes
to 0.) If the first 2 bytes of the SCB are nonzero when your Pascal program polls them,
the program will know that it has received an attention request from the server. Your program can handle the request and reset the SCB's attention bytes to 0. However, using this method to determine if the workstation has received an attention request from
the server has limitations; two or more attention requests could be received between successive polls and only the last one would be preserved.

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.

In the XPP parameter block for the AFPCommand function login format, the afpSCBPointer and afpAttnRoutine fields overlap with the beginning of the
CCB and are modified by AFPCommand function.

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. However, the memory that you allocate for the SCB belongs to AFP for the life of the session. You must either allocate nonrelocatable memory for the SCB or lock the memory and not modify it for the duration of the session.

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

aspBadVersNum	-1066	The server cannot support the ASP version number
aspBufTooSmall	-1067	The command reply from the server is larger than the response buffer; ASP will fill the buffer and truncate the reply data
aspNoMoreSess	-1068	The .XPP driver cannot support another ASP session
aspNoServers	-1069	There is no server at the specified server address, or the server did not respond to the request
aspParamErr	-1070	You specified an invalid session reference number, or the session has been closed
aspServerBusy	-1071	The server cannot open another session
aspSizeErr	-1073	The size of the command block exceeds the maximum size of aspMaxCmdSize

SEE ALSO

For information on how to obtain the internet socket address of a server, see the chapter "Name-Binding Protocol (NBP)" in this book.