Inside Macintosh: Networking /: Chapter 3 - Name-Binding Protocol (NBP)

Summary of NBP

Pascal Summary

Constants

CONST
   {.MPP driver unit and reference number}
   mppUnitNum     =     9;          {MPP driver unit number}
   mppRefNum      =   -10;          {MPP reference number}

   {csCodes for NBP}
   confirmName    =   250;          {confirm name}
   lookupName     =   251;          {lookup name}
   removeName     =   252;          {remove name from names table}
   registerName   =   253;          {register name in names table}
   killNBP        =   254;          {kill outstanding NBP request}

Data Types

Address Block Record

   AddrBlock = 
   PACKED RECORD
      aNet:       Integer;          {network number}
      aNode:      Byte;             {node ID}
      aSocket:    Byte;             {socket number}
   END;

Names Table Entry Record

TYPE  NamesTableEntry =
   RECORD
      qLink:      QElemPtr;         {pointer to next NTE in names table}
      nteAddress: AddrBlock;        {pointer to this names table entry}
      nteData: PACKED ARRAY[1..100] OF Char; 
                                    {names table entry}
   END;

Entity Name Record

   EntityName = 
   RECORD
      objStr:        Str32;      {object name}
      typeStr:       Str32;      {type name}
      zoneStr:       Str32;      {zone name}
   END;
   EntityPtr = ^EntityName;

MPP Parameter Block for NBP

MPPParmType    =     (...RegisterNameParm, LookupNameParm,
                        ConfirmNameParm,RemoveNameParm...);
TYPE MPPParamBlock = 
   PACKED RECORD
      qLink:               QElemPtr;      {reserved}
      qType:               Integer;       {reserved}
      ioTrap:              Integer;       {reserved}
      ioCmdAddr:           Ptr;           {reserved}
      ioCompletion:        ProcPtr;       {completion routine}
      ioResult:            OSErr;         {result code}
      ioNamePtr:           StringPtr;     {reserved}
      ioVRefNum:           Integer;       {reserved}
      ioRefNum:            Integer;       {driver reference number}
      csCode:              Integer;       {primary command code}
   CASE MPPParmType OF
      RegisterNameParm,
      LookupNameParm,
      ConfirmNameParm,
      RemoveNameParm:
         (interval:        Byte;          {retry interval}
         count:            Byte;          {retry count}
         entityPtr:        Ptr;           {pointer to entity name or }
                                          { names table entry}
         CASE MPPParmType OF
            RegisterNameParm:
               (verifyFlag:   Byte;       {verify uniqueness of name or not}
               filler3:       Byte;)
            LookupNameParm:
               (retBuffPtr:   Ptr;        {pointer to return buffer}
               retBuffSize:   Integer;    {return buffer size}
               maxToGet:      Integer;    {matches to get}
               numGotten:     Integer;)   {matches gotten}
            ConfirmNameParm:
               (confirmAddr:  AddrBlock;  {pointer to entity name}
               newSocket:     Byte;       {socket number}
               filler4:       Byte);
            )
      KillNBPParm:
         (nKillQEl:        Ptr;)       {pointer to queue element to cancel}
   END;
MPPPBPtr    =     ^MPPParamBlock;

Routines

Registering an Entity

PROCEDURE NBPSetNTE (ntePtr: Ptr; nbpObject,nbpType,nbpZone: Str32; 
socket: Integer);
FUNCTION PRegisterName(thePBptr: MPPPBPtr; async: Boolean): OSErr;

Handling Name and Address Requests

PROCEDURE NBPSetEntity(buffer: Ptr; nbpObject,nbpType,nbpZone: Str32);
FUNCTION PLookupName(thePBptr: MPPPBPtr; async: Boolean): OSErr;
FUNCTION NBPExtract(theBuffer: Ptr; numInBuf: Integer; whichOne: 
Integer; VAR abEntity: EntityName; VAR address: 
AddrBlock): OSErr;
FUNCTION PConfirmName(thePBptr: MPPPBPtr; async: Boolean): OSErr;
FUNCTION PRemoveName(thePBptr: MPPPBPtr; async: Boolean): OSErr;
FUNCTION PKillNBP(thePBptr: MPPPBPtr; async: Boolean): OSErr;

C Summary

Constants

/*NBP parameter constants*/
#define MPPioCompletion MPP.ioCompletion
#define MPPioResult MPP.ioResult
#define MPPioRefNum MPP.ioRefNum
#define MPPcsCode MPP.csCode
#define NBPinterval NBP.interval
#define NBPcount NBP.count
#define NBPntQElPtr NBP.NBPPtrs.ntQElPtr
#define NBPentityPtr NBP.NBPPtrs.entityPtr
#define NBPverifyFlag NBP.parm.verifyFlag
#define NBPretBuffPtr NBP.parm.Lookup.retBuffPtr
#define NBPretBuffSize NBP.parm.Lookup.retBuffSize
#define NBPmaxToGet NBP.parm.Lookup.maxToGet
#define NBPnumGotten NBP.parm.Lookup.numGotten
#define NBPconfirmAddr NBP.parm.Confirm.confirmAddr
#define NBPnKillQEl NBPKILL.nKillQEl
#define NBPnewSocket NBP.parm.Confirm.newSocket 
enum {                                 /*.MPP driver unit and reference */
                                       /* number*/
   mppUnitNum     =     9,             /*.MPP driver unit number*/
   mppRefNum      =     -10};          /*MPP reference number*/

enum {                                 /*.MPP csCodes*/
   confirmName    =     250,           /*confirm name*/
   lookupName     =     251,           /*lookup name*/
   removeName     =     252,           /*remove name from names table*/
   registerName   =     253,           /*register name in names table*/    
   killNBP        =     254};          /*kill outstanding NBP request*/

Data Types

Address Block Record

struct AddrBlock {
   short             aNet;       /*network name*/
   unsigned char     aNode;      /*node name*/
   unsigned char     aSocket;    /*socket number*/
};

typedef struct AddrBlock AddrBlock;

Names Table Entry Data Structure

struct {
   Ptr            qNext;            /*pointer to next names table element*/
   NTElement      nt;
}NamesTableEntry;

Entity Name Record

struct EntityName {
   Str32          objStr;        /*object name*/
   char           pad1;          /*Str32's aligned on even word boundaries*/
   Str32          typeStr;       /*type name*/
   char           pad2;
   Str32          zoneStr;       /*zone name*/
   char           pad3;
};

typedef struct EntityName EntityName;
typedef EntityName *EntityPtr;

MPP Parameter Block for NBP

#define MPPATPHeader \
   QElem          *qLink;        /*reserved*/\
   short          qType;         /*reserved*/\
   short          ioTrap;        /*reserved*/\
   Ptr            ioCmdAddr;     /*reserved*/\
   ProcPtr        ioCompletion;  /*completion routine*/\
   OSErr          ioResult;      /*result code*/\
   long           userData;      /*command result (ATP user bytes)*/\
   short          reqTID;        /*request transaction ID*/\
   short          ioRefNum;      /*driver reference number*/\
   short          csCode;        /*primary command code*/

typedef struct {
   MPPATPHeader 
}MPPparms;

typedef struct {
   MPPATPHeader
   char           interval;         /*retry interval*/
   char           count;            /*retry count*/
   union {
      Ptr            ntQElPtr;      /*pointer to queue element to cancel*/
      Ptr            entityPtr;   
                                    /*pointer to entity name or names */
                                    /* table entry*/
                                 
      } NBPPtrs;

   union {
      char           verifyFlag;    /*verify uniqueness of name or not*/
   struct {
      Ptr            retBuffPtr;    /*pointer to return buffer*/
      short          retBuffSize;   /*return buffer size*/
      short          maxToGet;      /*matches to get*/
      short          numGotten;     /*matches gotten*/
   } Lookup;
   struct {
         AddrBlock      confirmAddr; /*pointer to entity name*/
         char           newSocket;   /*socket number*/
      } Confirm;
   } parm;
}NBPparms;

struct {
   MPPATPHeader
   Ptr            nKillQEl;         
                                    /*pointer to queue element to cancel*/
}NBPKillparms;

union ParamBlockRec {
   MPPparms       MPP;              /*general MPP parms*/
   NBPparms       NBP;              /*NBP calls*/
   NBPKillparms   NBPKILL;          /*cancel call to NBP*/
};
typedef MPPParamBlock *MPPPBPtr;

Routines

Registering an Entity

pascal void NBPSetNTE(Ptr ntePtr, Ptr nbpObject, Ptr nbpType,
Ptr nbpZone, short socket);
pascal OSErr PRegisterName(MPPPBPtr thePBpt, Boolean async);

Handling Name and Address Requests

pascal void NBPSetEntity (Ptr buffer, Ptr nbpObject, Ptr nbpType, 
Ptr nbpZone);
pascal OSErr PLookupName(MPPPBPtr thePBptr, Boolean async);
pascal OSErr NBPExtract (Ptr theBuffer, short numInBuf, short whichOne,
EntityName *abEntity, AddrBlock *address);
pascal OSErr PConfirmName (MPPPBPtr thePBptr, Boolean async);
pascal OSErr PRemoveName (MPPPBPtr thePBptr, Boolean async);
pascal OSErr PKillNBP(MPPPBPtr thePBptr, Boolean async);

Assembly-Language Summary

Constants

Unit Number for the .MPP Driver

mppUnitNum        EQU   9           ;MPP unit number

NBP Symbolic Characters

equals            EQU   '='         ;wildcard symbol
NBPWildCard       EQU   '[double tilde]'         ;wildcard symbol
star              EQU   '*'         ;"This zone" symbol

NBP Command Codes

registerName      EQU   253         ;register name in names table
lookupReply       EQU   242         ;used internally
lookupName        EQU   251         ;look up an NBP name
confirmName       EQU   250         ;confirm name
removeName        EQU   252         ;remove name from names table
killNBP           EQU   254         ;kill outstanding NBP request

NBP Packet

nbp               EQU   $02         ;DDP protocol type code for NBP
nbpControl        EQU   0           ;control code
nbpTCount         EQU   0           ;tuple count
nbpID             EQU   1           ;NBP ID
nbpTuple          EQU   2           ;start of the first tuple

NBP Tuple Header Offsets

tupleNet          EQU   0           ;offset to network number (word)
tupleNode         EQU   2           ;offset to node ID (byte)
tupleSkt          EQU   3           ;offset to socket number (byte)
tupleEnum         EQU   4           ;offset to enumerator (byte)
tupleName         EQU   5           ;offset to name part of tuple (byte)
tupleAddrSz       EQU   5           ;tuple address field size

NBP Packet Types

brRq              EQU   1           ;broadcast request
lkUp              EQU   2           ;lookup request
lkUpReply         EQU   3           ;lookup reply

NBP Names Information Socket (NIS) Number

nis               EQU   2           ;NIS number

Maximum Number of Tuples in NBP Packet, Maximum Size of a Tuple Name

tupleMax          EQU   15          ;maximum number of tuples returned from 
                                    ; a lookup request
NBPMaxTupleSize   EQU   32          ;maximum size of a tuple name

Data Structures

MPP Parameter Block Common Fields for NBP
0 qLink long reserved
4 qType word reserved
6 ioTrap word reserved
8 ioCmdAddr long reserved
12 ioCompletion long address of completion routine
16 ioResult word result code
18 ioNamePtr long reserved
22 ioVRefNum word reserved
24 ioRefNum word driver reference number

`PRegisterName` Parameter Variant
26 csCode word command code; always `registerName`
28 interval byte retry interval
29 count byte retry count
30 entityPtr (ntQElPtr) long names table queue element pointer
34 verifyFlag byte verify name flag
40 filler byte reserved

PLookupName Parameter Variant
26 csCode word command code; always `lookupName`
28 interval byte retry interval
29 count byte retry count
30 entityPtr long pointer to entity name
34 retBuffPtr long pointer to return data buffer
38 retBuffSize word size in bytes of return buffer
40 maxToGet word maximum number of matches to get
42 numGotten word number of matches returned

PConfirmName Parameter Variant
26 csCode word command code; always `confirmName`
28 interval byte retry interval
29 count byte retry `count`
30 entityPtr long pointer to entity name
34 confirmAddr long address of names table entry to confirm
38 newSocket byte socket number, if different from specified one
39 filler byte reserved

PRemoveName Parameter Variant
26 csCode word command code; always `removeName`
28 filler word reserved
30 entityPtr long pointer to entity name

PKillNBP Parameter Variant
26 csCode word command code; always `killNBP`
28 nKillQEl long pointer to queue element to remove

Result Codes
noErr 0 No error
nbpNoConfirm -1025 Name not confirmed
nbpConfDiff -1026 Name confirmed for different socket
nbpDuplicate -1027 Name already exists
nbpNotFound -1028 Name not found
tooManyReqs -1097 Too many concurrent requests; wait a few minutes, then try the request again
cbNotFound -1102 NBP queue element not found
reqAborted -1105 Request canceled
extractErr -3104 Can't find tuple in buffer

0	qLink	long	reserved
4	qType	word	reserved
6	ioTrap	word	reserved
8	ioCmdAddr	long	reserved
12	ioCompletion	long	address of completion routine
16	ioResult	word	result code
18	ioNamePtr	long	reserved
22	ioVRefNum	word	reserved
24	ioRefNum	word	driver reference number

26	csCode	word	command code; always `registerName`
28	interval	byte	retry interval
29	count	byte	retry count
30	entityPtr (ntQElPtr)	long	names table queue element pointer
34	verifyFlag	byte	verify name flag
40	filler	byte	reserved

26	csCode	word	command code; always `lookupName`
28	interval	byte	retry interval
29	count	byte	retry count
30	entityPtr	long	pointer to entity name
34	retBuffPtr	long	pointer to return data buffer
38	retBuffSize	word	size in bytes of return buffer
40	maxToGet	word	maximum number of matches to get
42	numGotten	word	number of matches returned

26	csCode	word	command code; always `confirmName`
28	interval	byte	retry interval
29	count	byte	retry `count`
30	entityPtr	long	pointer to entity name
34	confirmAddr	long	address of names table entry to confirm
38	newSocket	byte	socket number, if different from specified one
39	filler	byte	reserved

26	csCode	word	command code; always `removeName`
28	filler	word	reserved
30	entityPtr	long	pointer to entity name

26	csCode	word	command code; always `killNBP`
28	nKillQEl	long	pointer to queue element to remove

noErr	0	No error
nbpNoConfirm	-1025	Name not confirmed
nbpConfDiff	-1026	Name confirmed for different socket
nbpDuplicate	-1027	Name already exists
nbpNotFound	-1028	Name not found
tooManyReqs	-1097	Too many concurrent requests; wait a few minutes, then try the request again
cbNotFound	-1102	NBP queue element not found
reqAborted	-1105	Request canceled
extractErr	-3104	Can't find tuple in buffer

Summary of NBP

Pascal Summary

Constants

Data Types

Address Block Record

Names Table Entry Record

Entity Name Record

MPP Parameter Block for NBP

Routines

Registering an Entity

Handling Name and Address Requests

C Summary

Constants

Data Types

Address Block Record

Names Table Entry Data Structure

Entity Name Record

MPP Parameter Block for NBP

Routines

Registering an Entity

Handling Name and Address Requests

Assembly-Language Summary

Constants

Unit Number for the .MPP Driver

NBP Symbolic Characters

NBP Command Codes

NBP Packet

NBP Tuple Header Offsets

NBP Packet Types

NBP Names Information Socket (NIS) Number

Maximum Number of Tuples in NBP Packet, Maximum Size of a Tuple Name

Data Structures

MPP Parameter Block Common Fields for NBP 0qLinklongreserved 4qTypewordreserved 6ioTrapwordreserved 8ioCmdAddrlongreserved 12ioCompletionlongaddress of completion routine 16ioResultwordresult code 18ioNamePtrlongreserved 22ioVRefNumwordreserved 24ioRefNumworddriver reference number

PRegisterName Parameter Variant 26csCodewordcommand code; always registerName 28intervalbyteretry interval 29countbyteretry count 30entityPtr (ntQElPtr)longnames table queue element pointer 34verifyFlagbyteverify name flag 40fillerbytereserved

PRemoveName Parameter Variant 26csCodewordcommand code; always removeName 28fillerwordreserved 30entityPtrlongpointer to entity name

PKillNBP Parameter Variant 26csCodewordcommand code; always killNBP 28nKillQEllongpointer to queue element to remove

`PRegisterName` Parameter Variant
26 csCode word command code; always `registerName`
28 interval byte retry interval
29 count byte retry count
30 entityPtr (ntQElPtr) long names table queue element pointer
34 verifyFlag byte verify name flag
40 filler byte reserved

PRemoveName Parameter Variant
26 csCode word command code; always `removeName`
28 filler word reserved
30 entityPtr long pointer to entity name

PKillNBP Parameter Variant
26 csCode word command code; always `killNBP`
28 nKillQEl long pointer to queue element to remove