NetBIOS Specification


3. Commands


Name Commands

All NetBIOS communications occur between names. These commands are therefore essential. There are three name commands: add unique name, add group name, and delete name. Once a name has been added, a number is returned in the name_number field, which is used for all subsequent commands. Each station always has at least one name, as a name consisting of the station name must be present. Names cannot begin with * or nulls, an if any attempt to do this is made, error 15h will be returned. Names are 16-bytes in length, and should be left justified, padding with spaces, and terminated with a null (character 00h).

Add Unique Name

This is used to add a unique name to the local name table. When the function is called, the entire network is checked to ensure that the name requested does not exist anywhere else. The check includes the local name table, and may take some time. The name should be of the format described above and placed in the local_name field. If the function is successful, a name_number is returned, which should be used for all commands on that name. It is easiest to have an NCB for each name, so once the name has been added, the name_number can be left without alteration for all commands on that name.

Fields Set on Entry:

command - 30h (synchronous), or B0h (asynchronous) - there is little point in using the asynchronous form, since you will have to wait until the name has been added to use it

local_name - the name you want to add

post_address - set this if you use the asynchronous form of the command, or leave at 0000:0000 for no POST (ignored for synchronous commands)

network_number - set this to the network card number - in normal circumstances leave this as 00h

Fields Returned on Exit:

return_code - this is set to return the status of the command - 00h indicates success, other codes indicate some failure

name_number - this is set to a unique number, required to refer to the name added in all subsequent commands

Add Group Name

This is used in the same way as the Add Unique Name function, except that the name added is a group, so can be used by as many stations on the network as required. The fields used are the same as above, except the command field on entry must be set to 36h (synchronous), or B6h (asynchronous).

Delete Name

This is used to delete the name specified in the local_name field from the local name table. Normally, you should ensure that all sessions are closed before issuing this command. However, if session are active, the name is flagged as deregistered, and the return_code code field returns 0Fh (name has active sessions, and has been de-registered). When all such sessions have been closed, or terminated, the name is actually deleted. If no sessions are active when this command is issued, the name is deleted immediately. Certain commands will be terminated with the completion code of 17h (name was deleted), including listen (11h), receive any (16h), receive datagram (21h) and receive broadcast (23h), if the name they are using is deleted.

Fields Set on Entry:

command - 31h (synchronous), or A1h (asynchronous)

name - the name to delete

post_address

network_number

Fields Returned on Exit:

return_code


Connectionless Commands

These allow datagrams to be sent across a network. Datagrams are a simple way of communicating, but their delivery is not guaranteed, and they can only be 512 bytes in length. They can be used for programs such as talk programs, since sessions are much more complicated, and would require one station to act as a server. There are two types of datagram:

Send Specific Datagram

This commands sends a datagram, from the name specified by the name_number field, to the name specified in the call_name field. The datagram should be received by all stations with an outstanding receive specific datagram command, on the name specified. This includes the local station, as well as all other stations on the network. This is useful in testing software, as you can send messages from a station to itself.

Fields Set on Entry:

command - 20h (synchronous), or A0h (asynchronous)

name_number - number of name from which to send datagram

buffer - points to buffer containing message

length - specifies length of buffer (maximum length of 512 bytes)

call_name - name to send datagram to (either a unique or group name)

post_address

network_number

Fields Returned on Exit:

return_code

Receive Specific Datagram

This receives a specific datagram on the name specified by the number in name_number. A wildcard of FFh may be used in this field, to receive on any local name. A buffer length must be supplied. Ensure this is large enough for the entire message, or error 06h (message incomplete) will occur, and the rest of the datagram will be lost. If in doubt, use a buffer length of 512 bytes.

This command is often used in talk programs. A group name is added on which to receive messages, and an asynchronous receive specific datagram command is executed. A POST routine is set up for this, which processes the received messages, displays it, and reinitiates the NCB to receive the next specific datagram. This can all happen within the POST routine, as asynchronous commands are being used.

Fields Set on Entry:

command - 21h (synchronous), or A1h (asynchronous)

name_number - number of name on which to receive (FFh = any name)

buffer - points to buffer to receive message in

length - specifies length of receive buffer

post_address

network_number

Fields Returned on Exit:

return_code

length - length of received datagram

call_name - name that datagram was sent from

Send Broadcast Datagram

This sends a broadcast datagram, which may be received by both remote and local stations. It is used in the same way as the Send Specific Datagram, except for the following changes:

command - 22h (synchronous), or A2h (asynchronous)

name_number - not required, as the datagram is a broadcast datagram

call_name - not required, as the datagram is a broadcast datagram

Receive Broadcast Datagram

This receives a broadcast datagram, and is used in a similar way to Receive Specific Datagram. Again, ensure the buffer is long enough, or you will get error 06h (message incomplete). One unusual point to note is that the name_number field must be specified, although the datagram received will be a broadcast datagram. Ensure that this name will not be deleted, or this command will complete with completion code 17h (name deleted). If several asynchronous receive broadcast datagram commands are outstanding on one station, a single broadcast datagram will terminate all these commands, and return the same message to each. This is not true of several outstanding receive specific datagram commands. The fields used are the same as those for Receive Specific Datagram, except for the command field, which contains 23h (synchronous), or A3h (asynchronous)


Connection-Orientated Commands

Sorry. This part of the specification is still being written. It will be completed sometime in the future. In the meantime, if you have any questions please feel free to e-mail me.

(NEW!) A temporary version of this information is available here.


Miscellaneous Commands

Reset

This resets the networking software, clear all active sessions and removing all names from the local name table. This should only be used by networking software, since it will remove any connections to servers on the network. The fields local_session and name_number can be used to specify the maximum number of sessions, and outstanding commands respectively.

Fields Set on Entry:

command - 32h (synchronous) - no asynchronous form

local_session - maximum number of sessions (default 48) - usually set by a /NSESS switch in the networking software (for example, Microsoft Lan Manager)

name_number - maximum number of outstanding commands (default 255) - usually set by a /NCMDS switch in the networking software

Fields Return on Exit:

return_code

Adapter Status

This command can be used to retrieve detailed information about any local or remote adapter, which is specified in the call_name field. This should be set to the first name in the remote name table, which will always be the station name. Setting the first byte of this field to '*' returns information for the local adapter. The information is retrieved into the buffer specified by the buffer field. The buffer consists of 60 bytes of fixed information, followed by 18 bytes for each name. As the maximum number of names is usually 16 bytes, this gives a maximum buffer length of 348 bytes. If the buffer is too short, completion code 06h (message incomplete) will be returned. Increase the size of the buffer, and request the information again. If the specified adapter cannot be contacted, completion code 05h (command timed out) is returned.

Fields Set on Entry:

command - 33h (synchronous), or B3h (asynchronous)

buffer - points to buffer to return information

length - length of the buffer

call_name - name of station from which to retrieve adapter information (or '*' for local station)

post_address

network_number

Fields Returned on Exit

return_code

length - length of data returned

Buffer Format:

Disclaimer: this format may be slightly incorrect, as all the sources I have list different formats.

HEADER FORMAT

Bytes 00h-05h (0-5) - user identification number

The network address of the adapter - all adapter addresses are unique

Byte 06h (6) - session layer software major version

The major version of the session layer software, for example 3 for IBM NetBIOS 3.x

(One source I have states this is the adapter type, which appears incorrect)

Byte 07h (7) - reserved

Always set to 00h

(One source I have states this is the value after the /BOOT command switch)

Byte 08h (8) - adapter type

0xFF = token ring, 0xFE = Ethernet adapter

(One source I have states this is the session layer software major version, which appears incorrect)

Byte 09h (9) - session layer software minor version

The minor version of the session layer software, for example 0 for IBM NetBIOS x.0

Bytes 0Ah-0Bh (10-11) - duration of reporting period

The length (minutes) of the reporting period for traffic/error statistics - this is a measure of the time since the session layer was loaded

Bytes 0Ch-0Dh (12-13)- receive CRC errors

Bytes 0Eh-0Fh (14-15) - other receive errors

Bytes 10h-11h (16-17) - transmit collisions

Bytes 12h-13h (18-19) - other transmit errors

These list the number of various errors, since the session layer was loaded

Bytes 14h-17h (20-23) - successful transmissions

Bytes 18h-1Bh (24-27) - succesful receives

This list the number of frames transmitted and received successfully, since the session layer was loaded

Bytes 1Ch-1Dh (28-29) - transmit retries after collisions

This lists the number of retries after a packet transmission has resulted in a collision

Bytes 1Eh-1Fh (30-31) - no receive buffer

This lists the number of packets missed since no buffer was available to receive them

Bytes 20h-27h (32-39) - reserved

Bytes 28h-39h (40-57) - UNKNOWN (*)

Sorry. This part of the specification is still being written. It will be completed during the next few weeks. In the meantime, if you have any questions please feel free to e-mail me.

Bytes 3Ah-3Bh (58-59) - number of names in local table

The number of names present in the local name table. An 18-byte record is available for each name, which takes the following format:

NAME RECORD FORMAT

Bytes 00h-0Fh (0-15) - name

The 16-byte name supplied when the name was added

Byte 10h (16) - name number

The unique number associated with that name

Byte 11h (17) - status

Bit 7 - 0 (unique name) or 1 (group name)

Bits 6-3 - undefined

Bits 2-0 - status of the name

Cancel

This cancels an asynchronous command which has been issued. The buffer field is used to specify the NCB to cancel. The following commands may be cancelled:

All other commands cannot be cancelled, and completion code 26h (unable to cancel command) will be returned. Another possible completion code is 24h (command completed before cancelled)

Fields Set on Entry:

command - 35h (synchronous) - no asynchronous form

buffer - points to NCB to cancel

post_address

network_number

Fields Returned on Exit:

return_code

Unlink

This de-activates the code used to boot a station remotely from a server, and enables data reception in the session layer, so should only be used by networking software. It is called only once, once the session layer is loaded, regardless of whether the station was booted remotely or not.

Fields Set on Entry:

command - 70h (synchronous) - no asynchronous form

post_address

network_number

Fields Returned on Exit:

return_code

Find Name

Command code 78h - this information has been provided by Martin Goebel
type
  pFIND_NAME_HEADER=^tFIND_NAME_HEADER;
  tFIND_NAME_HEADER = RECORD
    node_count  : WORD;
    reserved    : UCHAR;
    unique_group: UCHAR;
  END;

  PFIND_NAME_BUFFER = ^tFIND_NAME_BUFFER;
  tFIND_NAME_BUFFER = RECORD
    length          : UCHAR;
    access_control  : UCHAR;
    frame_control   : UCHAR;
    destination_addr: ARRAY [0 .. 6 - 1] OF UCHAR;
    source_addr     : ARRAY [0 .. 6 - 1] OF UCHAR;
    routing_info    : ARRAY [0 .. 18 - 1] OF UCHAR;
  END;

  type tNameList=record
     header:tFInd_Name_Header;
     Names:array[0..30] of tFIND_NAME_BUFFER;
  end;

  type tNameList=record
     header:tFInd_Name_Header;
     Names:array[0..10] of tFIND_NAME_BUFFER;
  end;

var

namelist:tNameList; (*with Find_Name you can get Network-TCP Info on Win95 *) ... NCB.Buf := @NameList; NCB.Length := Sizeof(tNameList); ...

All text © 1998-2012 Gavin Winston