Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

Previous Book Contents Book Index Next

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

PLookupName Parameter Variant
26csCodewordcommand code; always lookupName
28intervalbyteretry interval
29countbyteretry count
30entityPtrlongpointer to entity name
34retBuffPtrlongpointer to return data buffer
38retBuffSizewordsize in bytes of return buffer
40maxToGetwordmaximum number of matches to get
42numGottenwordnumber of matches returned

PConfirmName Parameter Variant
26csCodewordcommand code; always confirmName
28intervalbyteretry interval
29countbyteretry count
30entityPtrlongpointer to entity name
34confirmAddrlongaddress of names table entry to confirm
38newSocketbytesocket number, if different from specified one
39fillerbytereserved

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

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


Previous Book Contents Book Index Next

© Apple Computer, Inc.
7 JUL 1996