Ref: 18960007
Title: Locator Packet Formats and Codes
date: 5/10/90

Copyright 3Com Corporation, 1991.  All rights reserved.

3Com's Locator Service is responsible for maintaining the list of NetBIOS
names on 3Com networks running the XNS protocols.  The Locator uses the
Packet Exchange Protocol (PEP), which provides fast, unreliable transport.
The Locator uses the following well-known socket numbers:

   Socket (hex)    Purpose
   ------------    -------
      046D    For all transmissions
      046B    To establish a reliable NetBIOS session (once a
        session is established, each node assigns a unique
         socket number to it.)
      046C      To make a NetBIOS datagram call

The Locator packet begins at offset hex 32 from the beginning of the
Ethernet frame.  All of the offsets in the following Locator packet formats
are from the beginning of the Locator header.


.H1;Locator Header
Each Locator packet has a header with the same format:

.LT
 Hex    Length
Offset  (bytes)  Description

 0      4        Locator identification string = '\0','LOC'
 4      2        Locator function code
 6      2        Return code
 8      2        Handle/sequence number
 A      2        Number of items returned
 C      4        Index for functions that require multiple messages
10      2        Total size of message
.EL


The Locator function code has the following values:

.LT
 Hex
Value   Function                Description

01      Find Locator            A workstation broadcasts a Find Locator
                                Packet to get the Ethernet address of the
                                Locator and to register the machine name
                                for the first time.

02      Add Name                The Add Name function adds a NetBIOS name
                                to the Locator for that workstation.

03      Delete Name             The Delete Name function deletes a NetBIOS
                                name from the Locator.

04      Lookup Name             A workstation sends the Lookup Name packet
                                to the Locator to resolve a NetBIOS name to
                                an Ethernet (or token ring) address.

05      Heartbeat               The workstation sends a heartbeat to the
                                Locator so the Locator knows that workstation
                                is still alive.  The heartbeat response from
                                the Locator will contain a list of
                                workstations whose state has changed since
                                the last heartbeat.

08      Dump Nodes              Dump a list of current nodes registered in
                                the Locator.

09      Dump NetBIOS Names      Dump the list of NetBIOS names for the
                                specified node.

0B      Validate Nodes          Get the state of the specified nodes.

0C      Internet Lookup Name    Look up a name in a Locator on a remote
                                XNS network and return the Ethernet address.

0D      Internet Add Name       Register a NetBIOS name in a Locator on a
                                remote XNS network.  This is done by the 3NB
                                REGISTER command.

0E      Internet Delete Name    Delete a NetBIOS name from a remote Locator.


Locator Return Codes:

 Hex
Result  Meaning

00      Successful return
01      Found a group name
02      Name not found
03      Duplicate name
04      Client handle incorrect
05      No find request detected
06      Only old names allowed (Locator is reloading)
07      Receive packet timeout
08      Illegal function number
09      No more nodes available.  (Configured in 3OPT)
0A      No more NetBIOS names available.  (Configured in 3OPT)
0B      Name conflict detected
0C      Multi-packet request could not go
0D      Node has already added this name
40      Internal error
41      Internal error
42      Try to acquire Locator again
43      Node not found for dump name
.EL


.H1;Find Locator Variable Portion
In addition to the standard Locator header, the Find Locator request has
another field:

.LT
 Hex    Length
Offset  (bytes) Description

12      4       Time to first heartbeat (1/18 seconds)


The Find Locator reply contains the following:

 Hex    Length
Offset  (bytes) Description

12      4       Current Locator time
.EL


.H1;Add Name Variable Portion
In addition to the standard Locator header, the Add Name request has these
fields:

.LT
 Hex    Length
Offset  (bytes) Description

12      2       Name type
14      0x10    NetBIOS name (16 decimal characters)
24      2       Name number

This structure repeats as many times as the item count in the header.


The Add Name reply contains the following:

 Hex    Length
Offset  (bytes) Description

12      2       Return code for this name
14      0x10    Reserved 16 bytes
24      2       Name number


The Name Type field has the following values:

 Hex
Value   Description

02      Unique NetBIOS name
04      NetBIOS group name
08      NetBIOS name is a member of a group
10      Hardware name
.EL


.H1;Delete Name Variable Portion
In addition to the standard Locator header, the Delete Name request has these
fields:

.LT
 Hex    Length
Offset  (bytes) Description

12      2       Name type
14      0x10    NetBIOS name to delete (16 characters)
24      2       Name number

 Hex
Value   Description

02      Unique NetBIOS name
04      NetBIOS group name
08      NetBIOS name is a member of a group
10      Hardware name
.EL


.H1;Lookup Name Variable Portion
In addition to the standard Locator header, the Lookup Name request has these
fields:

.LT
 Hex    Length
Offset  (bytes) Description

12      2       Name type (0 - don't care)
14      0x10    NetBIOS name to look up (16 characters)


The Lookup Name response contains:

 Hex    Length
Offset  (bytes) Description

12      2       Name type (see Add Name Variable Portion)
14      4       XNS network number
18      6       Ethernet (or token ring) address
1E      2       IDP socket number
20      2       Name number
22      2       Handle of name owner's node
.EL

This structure repeats as many times as the item count in the header.


.H1;Heartbeat Variable Portion
In addition to the standard Locator header, the Heartbeat request has these
fields:

.LT
 Hex    Length
Offset  (bytes) Description

12      4       Time to next heartbeat (1/18 seconds)
16      4       Time at which last heartbeat occurred
1A      4       Time last partial heartbeat occurred
.EL


The Heartbeat response contains a single fixed field and a repeating
structure:

.LT
 Hex    Length
Offset  (bytes) Description
12      4       Current time

Repeating Structure:

 Hex    Length
Offset  (bytes) Description

16      2       Node status
18      4       XNS network number
1C      6       Ethernet (or token ring) address
22      2       IDP socket number
24      2       Handle of restarted node
.EL


The Node Status field can indicate more than one status.  Add the numbers
together to get the status (these are actually one-bit flags):

.LT
 Hex
Status  Description

01      Node descriptor not in use
02      Node just came up
04      Node just died
08      Node recently did an add name
10      Node recently deleted a name
20      Node dead, but restarted
40      Node is on a remote network
.EL


.H1;Validate Nodes Variable Portion
In addition to the standard Locator header, the Validate Nodes request has
these additional fields:

.LT
 Hex    Length
Offset  (bytes) Description

12      2       Reserved
14      4       XNS network number
18      6       Ethernet (or token ring) address
1E      2       IDP socket number

This structure repeats as many times as the item count in the header.


The Validate Nodes response contains:

 Hex    Length
Offset  (bytes) Description

12      2       Node status (see heartbeat)
14      4       XNS network number
18      6       Ethernet (or token ring) address
1E      2       IDP socket number
.EL

This structure repeats as many times as the item count in the header.


.H1;Dump Nodes Variable Portion.
In addition to the standard Locator header, the Dump Nodes request has
these fields:

.LT
 Hex    Length
Offset  (bytes) Description

12      4       Secondary index.  If there are more nodes to be dumped than
                will fit in a Locator packet, the secondary index is used to
                specify where to start dumping names in the next Dump Names
                request.
.EL


The Dump Nodes reply contains a fixed field and a repeating structure:

.LT
 Hex    Length
Offset  (bytes) Description

12      4       Secondary index.  If more nodes are to be dumped than will
                fit in one Locator packet, the Locator will return the index
                of the next node to be dumped.

Repeating structure:

 Hex    Length
Offset  (bytes) Description

14      2       Node status (see Heartbeat Variable Portion)
16      4       XNS network number
1A      6       Ethernet (or token ring) address
20      2       IDP socket number
.EL


.H1;Dump Names Variable Portion
In addition to the standard Locator header, the Dump Names request has
these additional fields:

.LT
 Hex    Length
Offset  (bytes) Description

12      4       XNS network number
16      6       Ethernet (or token ring) address
1C      2       IDP socket number


The Dump Names reply contains:

 Hex    Length
Offset  (bytes) Description

12      2       Name type (see Add Name Variable Portion)
14      0x10    NetBIOS name (16 characters)
24      2       Name number
.EL

This structure repeats as many times as the item count in the header.
