Inside Macintosh: Networking /

Chapter 9 - AppleTalk Filing Protocol (AFP)

Summary of AFP

Pascal Summary

Constants

CONST
   {.XPP Driver unit and reference numbers}
   xppUnitNum      =    40;         {XPP unit number}
   xppRefNum       =    -41;        {XPP reference number}
   afpCall         =    250;        {AFP call command. Command buffer }
                                    { contains code for the command to be }
                                    { executed}
   {AFP command codes}
   afpByteRangeLock  =  1;                   
   afpVolClose       =  2;
   afpDirClose       =  3;
   afpForkClose      =  4;
   afpCopyFile       =  5; 
   afpDirCreate      =  6;
   afpFileCreate     =  7;
   afpDelete         =  8;
   afpEnumerate      =  9;
   afpFlush          =  10;
   afpForkFlush      =  11;
   afpGetDirParms    =  12;
   afpGetFileParms   =  13;
   afpGetForkParms   =  14;
   afpGetSInfo       =  15;
   afpGetSParms      =  16;
   afpGetVolParms    =  17;
   afpLogin          =  18;
   afpContLogin      =  19;
   afpLogout         =  20;
   afpMapID          =  21;
   afpMapName        =  22;
   afpMove           =  23;
   afpOpenVol        =  24;
   afpOpenDir        =  25;
   afpOpenFork       =  26;
   afpRead           =  27;
   afpRename         =  28;
   afpSetDirParms    =  29;
   afpSetFileParms   =  30;
   afpSetForkParms   =  31;
   afpSetVolParms    =  32;
   afpWrite          =  33;
   afpGetFlDrParms   =  34;
   afpSetFlDrParms   =  35;
   afpDTOpen         =  48;
   afpDTClose        =  49;
   afpGetIcon        =  51;
   afpGtIcnInfo      =  52;
   afpAddAPPL        =  53;
   afpRmvAPPL        =  54;
   afpGetAPPL        =  55;
   afpAddCmt         =  56;
   afpRmvCmt         =  57;
   afpGetCmt         =  58;
   afpAddIcon        =  192;     {special code for ASP write commands}

   {miscellaneous}
   xppLoadedBit      =  5;       {XPP bit in PortBUse}
   scbMemSize        =  192;     {size of memory for SCB}
   
   {constants for AFP command block startEndFlag & newLineFlag fields}
   xppFlagClr        =  0;       
   xppFlagSet        =  128;        

Data Types

Command Block for AFP Read and AFP Write Commands

TYPE AFPCommandBlock = 
   PACKED RECORD
      cmdByte:          Byte;       {AFP command}
      startEndFlag:     Byte;       {flag identifying offset relative }
                                    { to fork}
      forkRefNum:       Integer;    {reserved}
      rwOffset:         LongInt;    {offset within fork to begin }
                                    { reading or writing}
      reqCount:         LongInt;    {on input, size of the data buffer; }
                                    { on return, size of the data actually }
                                    { written or read}
      newLineFlag:      Byte;       {for read, a flag indicating whether }
                                    { the read is to be terminated at }
                                    { a specific character; not used by }
                                    { write}
      newLineChar:      Char;       {character used to determine where }
                                    { the read is to be terminated; not }
                                    { used by write}
   END;

XPP Parameter Block for AFP

XPPPrmBlkType = (XPPPrmBlk...);
XPPSubPrmType = (ASPOpenPrm,ASPSubPrm);
XPPEndPrmType = (AFPLoginPrm,ASPEndPrm);
TYPE XPPParamBlock = 
   PACKED RECORD
      qLink:               QElemPtr;      {reserved}
      qType:               Integer;       {reserved}
      ioTrap:              Integer;       {reserved}
      ioCmdAddr:           Ptr;           {reserved}
      ioCompletion:        ProcPtr;       {completion routine}
      ioResult:            OSErr;         {result code}
      cmdResult:           LongInt;       {command result (ATP user bytes)}
      ioVRefNum:           Integer;       {reserved}
      ioRefNum:            Integer;       {driver reference number}
      csCode:              Integer;       {command code}
   CASE XPPPrmBlkType OF
      XPPPrmBlk:
         (sessRefnum:      Integer;       {offset to session refnum}
         aspTimeout:       Byte;          {timeout for ATP}
         aspRetry:         Byte;          {retry count for ATP}
   CASE XPPSubPrmType OF
      ASPOpenPrm:
         (serverAddr:      AddrBlock;     {server address block}
         scbPointer:       Ptr;           {SCB pointer}
         attnRoutine:      Ptr);          {attention routine pointer}
      ASPSubPrm:
         (cbSize:          Integer;       {command block size}
         cbPtr:            Ptr;           {command block pointer}
         rbSize:           Integer;       {reply buffer size}
         rbPtr:            Ptr;           {reply buffer pointer}
   CASE XPPEndPrmType OF
      AFPLoginPrm:
         (afpAddrBlock:    AddrBlock;     {address block in AFP login}
         afPSCBPtr:        Ptr;           {SCB pointer in AFP login}
         afpAttnRoutine:   Ptr);          {attn routine pointer in AFP login}
      ASPEndPrm:
         (wdSize:          Integer;       {write data size}
         wdPtr:            Ptr;           {write data pointer}
         ccbStart:         ARRAY[0..295] OF Byte)));              
                                          {command control block}
   END;
XPPParmBlkPtr = ^XPPParamBlock;

XPPPrmBlkType = (XPPPrmBlk...);
XPPSubPrmType = (ASPOpenPrm,ASPSubPrm);
XPPEndPrmType = (AFPLoginPrm,ASPEndPrm);

Routines

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

C Summary

Constants

enum {
   afpCall     = 250             /*AFP command (buffer has command code)*/
};

enum {                           /*AFPCall command codes*/
   afpFlush          = 10,
   afpForkFlush      = 11,       
   afpGetDirParms    = 12,       
   afpGetFileParms   = 13,       
   afpGetForkParms   = 14,       
   afpGetSInfo       = 15,       
   afpGetSParms      = 16,       
   afpGetVolParms    = 17,       
   afpLogin          = 18,       
   afpContLogin      = 19,       
   afpLogout         = 20,       
   afpMapID          = 21,          
   afpMapName        = 22,       
   afpMove           = 23,       
   afpOpenVol        = 24,       
   afpOpenDir        = 25,       
   afpOpenFork       = 26,       
   afpRead           = 27,       
   afpRename         = 28,       
   afpSetDirParms    = 29        
};
enum {                           /*AFPCall command codes*/
   afpSetFileParms   = 30,       
   afpSetForkParms   = 31,       
   afpSetVolParms    = 32,       
   afpWrite          = 33,       
   afpGetFlDrParms   = 34,       
   afpSetFlDrParms   = 35,       
   afpDTOpen         = 48,       
   afpDTClose        = 49,       
   afpGetIcon        = 51,       
   afpGtIcnInfo      = 52,       
   afpAddAPPL        = 53,       
   afpRmvAPPL        = 54,       
   afpGetAPPL        = 55,       
   afpAddCmt         = 56,
   afpRmvCmt         = 57,       
   afpGetCmt         = 58,       
   afpAddIcon        = 192       /*special code for ASP write commands*/
};
enum {
   xppLoadedBit      = 5,        /*XPP bit in PortBUse*/
   scbMemSize        = 192,      /*size of memory for SCB*/
   xppFlagClr        = 0         /*cs for AFPCommandBlock*/
};

enum {
xppFlagSet           = 128}      /*startEndFlag & NewLineFlag fields*/
};    

Data Types

Command Block for AFP Read and AFP Write Commands

typedef struct {
   char  cmdByte;             /*AFP command*/
   char  startEndFlag;        /*flag identifying offset relative to fork*/
   short forkRefNum;          /*reserved*/
   long  rwOffset;            /*offset within fork to begin reading */
                              /* or writing*/
   long  reqCount;            /*on input, size of the data buffer; */
                              /* on return, size of the data actually */
                              /* written or read*/
   char  newLineFlag;         /*for read, a flag indicating whether the */
                              /* read is to be terminated at a specific */
                              /* character; not used by write*/
   char  newLineChar;         /*character used to determine where the read */
                              /* is to be terminated; not used by write*/
} AFPCommandBlock;

XPP Parameter Block for AFP

#define  XPPPBHeader\
   QElem    *qLink;           /*reserved*/\
   short    qType;            /*reserved*/\
   short    ioTrap;           /*reserved*/\
   Ptr      ioCmdAddr;        /*reserved*/\
   ProcPtr  ioCompletion;     /*completion routine*/\
   OSErr    ioResult;         /*result code*/\
   long     cmdResult;        /*command result*/\
   short    ioVRefNum;        /*reserved*/\
   short    ioRefNum;         /*.XPP driver reference number*/\
   short    csCode;           /*function code*/

typedef struct {
   XPPPBHeader 
   short    sessRefnum;       /*offset to session refnum*/
   char     aspTimeout;       /*timeout for ATP*/
   char     aspRetry;         /*retry count for ATP*/
   short    cbSize;           /*command block size*/
   Ptr      cbPtr;            /*command block pointer*/
   short    rbSize;           /*reply buffer size*/
   Ptr      rbPtr;            /*reply buffer pointer*/
   short    wdSize;           /*write data size*/
   Ptr      wdPtr;            /*write data pointer*/
   char     ccbStart[296];    /*beginning of command control block */
                              /* (CCB)*/
}XPPPrmBlk;
typedef struct {
   XPPPBHeader
   short       sessRefnum;       /*offset to session refnum*/
   char        aspTimeout;       /*timeout for ATP*/
   char        aspRetry;         /*retry count for ATP*/
   short       cbSize;           /*command block size*/
   Ptr         cbPtr;            /*command block pointer*/
   short       rbSize;           /*reply buffer size*/
   Ptr         rbPtr;            /*reply buffer pointer*/
   AddrBlock   afpAddrBlock;     /*block in AFP login*/
   Ptr         afpSCBPtr;        /*SCB pointer in AFP login*/
   Ptr         afpAttnRoutine;   /*attn routine pointer in AFP login*/
   char        ccbFill[144];     /*beginning of command control block*/
}AFPLoginPrm;                                         
typedef struct {
   XPPPBHeader
   short       sessRefnum;       /*offset to session refnum*/
   char        aspTimeout;       /*timeout for ATP*/
   char        aspRetry;         /*retry count for ATP*/
   AddrBlock   serverAddr;       /*server address block*/
   Ptr         scbPointer;       /*SCB pointer*/
   Ptr         attnRoutine;      /*attention routine pointer*/
} ASPOpenPrm;

typedef ASPOpenPrm *ASPOpenPrmPtr;

Routines

pascal OSErr AFPCommand(XPPParmBlkPtr thePBptr, Boolean async); 

Assembly-Language Summary

Constants

XPP Driver Unit Number

xppUnitNum           EQU         40                ;XPP unit number
xppLoadedBit         EQU         atpLoadedBit+1    ;XPP loaded bit number in
                                                   ; PortBUse

AFP Control Code

afpCall              EQU         250               ;AFP csCode

AFP Command Codes

afpByteRangeLock     EQU      1
afpVolClose          EQU      2
afpDirClose          EQU      3
afpForkClose         EQU      4
afpCopyFile          EQU      5
afpDirCreate         EQU      6
afpFileCreate        EQU      7
afpDelete            EQU      8
afpEnumerate         EQU      9
afpFlush             EQU      10
afpForkFlush         EQU      11
afpGetDirParms       EQU      12
afpGetFileParms      EQU      13
afpGetForkParms      EQU      14
afpGetSInfo          EQU      15
afpGetSParms         EQU      16
afpGetVolParms       EQU      17
afpLogin             EQU      18
afpContLogin         EQU      19
afpLogout            EQU      20
afpMapID             EQU      21
afpMapName           EQU      22
afpMove              EQU      23
afpOpenVol           EQU      24
afpOpenDir           EQU      25
afpOpenFork          EQU      26
afpRead              EQU      27
afpRename            EQU      28
afpSetDirParms       EQU      29
afpSetFileParms      EQU      30
afpSetForkParms      EQU      31
afpSetVolParms       EQU      32
afpWrite             EQU      33
afpGetFlDrParms      EQU      34
afpSetFlDrParms      EQU      35

afpDTOpen            EQU      48
afpDTClose           EQU      49
afpGetIcon           EQU      51
afpGtIcnInfo         EQU      52
afpAddAPPL           EQU      53
afpRmvAPPL           EQU      54
afpGetAPPL           EQU      55
afpAddCmt            EQU      56
afpRmvCmt            EQU      57
afpGetCmt            EQU      58

afpAddIcon           EQU   192      ;special code for ASP write commands

Miscellaneous

afpUseWrite    EQU   $C0            ;first call in range that maps to an
                                    ; ASPWrite

Data Structures

Parameter Block for General Command Format

18	cmdResult	long	AFP command result
26	csCode	word	command code; always afpCall
28	sessRefnum	word	session reference number
30	aspTimeout	byte	retry interval in seconds
32	cbSize	word	command buffer size
34	cbPtr	pointer	command buffer
38	rbSize	word	reply buffer size and actual reply size
40	rbPtr	pointer	reply buffer pointer
44	wdSize	word	write data size
46	wdPtr	pointer	write data pointer
50	ccbStart	record	beginning of memory for CCB

Parameter Block for Login Command Format

18	cmdResult	long	AFP command result
26	csCode	word	command code; alwaysafpCall
28	sessRefnum	word	session reference number
30	aspTimeout	byte	retry interval in seconds
31	aspRetry	byte	number of retries
32	cbSize	word	command buffer size
34	cbPtr	pointer	command buffer
38	rbSize	word	reply buffer size and actual reply size
40	rbPtr	pointer	reply buffer pointer
44	afpAddrBlock	long	server address block
48	afpSCBPtr	pointer	SCB pointer
52	afpAttnRoutine	pointer	attention routine pointer
50	ccbStart	record	beginning of memory for CCB

Parameter Block for AFP Write Command Format

18	cmdResult	long	AFP command result
26	csCode	word	command code; always afpCall
28	sessRefnum	word	session reference number
30	aspTimeout	byte	retry interval in seconds
32	cbSize	word	command buffer size
34	cbPtr	pointer	command buffer
38	rbSize	word	reply buffer size and actual reply size
40	rbPtr	pointer	reply buffer pointer
44	wdSize	word	used internally
46	wdPtr	pointer	write data pointer, updated
50	ccbStart	record	beginning of memory for CCB

Command Block for the AFP Write Command

0	cmdByte	byte	AFP command code
1	startEndFlag	byte	start/end flag
4	rwOffset	long	offset within fork to begin writing
8	reqCount	long	on input, requested size of data; on return, size of data actually written
12	newLineFlag	byte	new line flag
13	newLineChar	byte	new line character

Parameter Block for AFP Read Command Format

18	cmdResult	long	AFP command result
26	csCode	word	command code; always afpCall
28	sessRefnum	word	session reference number
30	aspTimeout	byte	retry interval in seconds
32	cbSize	word	command buffer size
34	cbPtr	pointer	command buffer
38	rbSize	word	used internally
40	rbPtr	pointer	reply buffer pointer (updated)
50	ccbStart	record	beginning of memory for CCB

Command Block for the AFP Read Command

0	cmdByte	byte	AFP command code
1	startEndFlag	byte	flag identifying offset relative to fork
4	rwOffset	long	offset within fork to begin reading
8	reqCount	long	on input, requested size of data; on return, size of data actually read into the buffer

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 not a 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
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])