Miscellaneous NetBIOS Commands | Network Programming for Microsoft Windows (Microsoft Professional Series)

Miscellaneous NetBIOS Commands

All of the commands discussed so far deal in some way with setting up a session, sending or receiving data through a session or a datagram, and related subjects. A few commands deal exclusively in getting information. These commands are the adapter status command (NCBASTAT) and the find name command (NCBFINDNAME), which are discussed in the following sections. The final section deals with matching LANA numbers to their protocols in a programmatic fashion. (This is not actually a NetBIOS function; we discuss it because it can gather useful NetBIOS information for you.)

Adapter Status (NCBASTAT)

The adapter status command is useful for obtaining information about the local computer and its LANA numbers. Using this command is also the only way to programmatically find the machine's MAC address from Windows 95 and Windows NT 4.0. With the advent of the IP Helper functions for Windows 2000 and Windows 98 (discussed in Chapter 22), there is a more generic interface for finding the Media Access Control (MAC) address; however, for the other Windows platforms, using the adapter status command is your only valid option.

The command and its syntax are fairly easy to understand, but two ways of calling the function affect what data is returned. The adapter status command returns an ADAPTER_STATUS structure followed by a number of NAME_BUFFER structures. The structures are defined as follows:

typedef struct _ADAPTER_STATUS {     UCHAR   adapter_address[6];     UCHAR   rev_major;     UCHAR   reserved0;     UCHAR   adapter_type;     UCHAR   rev_minor;     WORD    duration;     WORD    frmr_recv;     WORD    frmr_xmit;     WORD    iframe_recv_err;     WORD    xmit_aborts;     DWORD   xmit_success;     DWORD   recv_success;     WORD    iframe_xmit_err;     WORD    recv_buff_unavail;     WORD    t1_timeouts;     WORD    ti_timeouts;     DWORD   reserved1;     WORD    free_ncbs;     WORD    max_cfg_ncbs;     WORD    max_ncbs;     WORD    xmit_buf_unavail;     WORD    max_dgram_size;     WORD    pending_sess;     WORD    max_cfg_sess;     WORD    max_sess;     WORD    max_sess_pkt_size;     WORD    name_count; } ADAPTER_STATUS, *PADAPTER_STATUS; typedef struct _NAME_BUFFER {     UCHAR   name[NCBNAMSZ];     UCHAR   name_num;     UCHAR   name_flags; } NAME_BUFFER, *PNAME_BUFFER;

The fields of most interest are MAC address (adapter_address), maximum datagram size (max_dgram_size), and maximum number of sessions (max_sess). Also, the name_count field tells you how many NAME_BUFFER structures were returned. The maximum number of NetBIOS names per LANA is 254, so you have a choice of providing a buffer large enough for all names or calling the adapter status command once with ncb_length equal to 0. When the Netbios function returns, it provides the necessary buffer size.

     UCHAR   unique_group; } FIND_NAME_HEADER, *PFIND_NAME_HEADER; typedef struct _FIND_NAME_BUFFER {     UCHAR   length;     UCHAR   access_control;     UCHAR   frame_control;     UCHAR   destination_addr[6];     UCHAR   source_addr[6];     UCHAR   routing_info[18]; } FIND_NAME_BUFFER, *PFIND_NAME_BUFFER;

As with the adapter status command, if the NCBFINDNAME command is executed with a buffer length of 0, the Netbios function returns the required length with the error NRC_BUFLEN.

The FIND_NAME_HEADER structure that a successful query returns indicates whether the name is registered as a unique name or a group name. If the field unique_group is 0, it is a unique name. The value 1 indicates a group name. The node_count field indicates how many FIND_NAME_BUFFER structures were returned. The FIND_NAME_BUFFER structure returns quite a bit of information, most of which is useful at the protocol level. However, we're interested in the fields destination_addr and source_addr. The source_addr field contains the MAC address of the network adapter that has registered the name, and the destination_addr field contains the MAC address of the adapter that performed the query.

A find name query can be issued on any LANA number on the local machine. The data returned should be identical on all valid LANA numbers for the local network. (For example, you can execute a find name command on a RAS connection to determine whether a name is registered on the remote network.) Using Windows NT 4.0, you will find the following bug: when a find name query is executed over TCP/IP, Netbios returns bogus information. Therefore, if you plan to use this query with Windows NT 4.0, be sure to pick a LANA corresponding to a transport other than TCP/IP.

Matching Transports to LANA Numbers

This last section discusses matching transport protocols such as TCP/IP and NetBEUI to their LANA numbers. Because there are different potential problems to deal with depending on which transport your application is using, it's nice to be able to find these transports programmatically. This isn't possible with a native NetBIOS call, but it is possible with Winsock 2 under Windows NT 4.0 and Windows 2000. The Winsock 2 function WSAEnumProtocols returns information about available transport protocols. (See Chapters 5 and 6 for more information about WSAEnumProtocols.) Although Winsock 2 is available on Windows 95 and by default on Windows 98, the protocol information stored on these platforms does not contain any NetBIOS information, which is what we're looking for.

We won't discuss Winsock 2 in great detail, as this was the subject of Part II of this book. The basic steps involved are loading Winsock 2 through the WSAStartup function, calling WSAEnumProtocols, and inspecting the WSAPROTOCOL_INFO structures returned from the call. The sample file NBPROTO.C on this book's companion CD contains code for performing this query.

The WSAEnumProtocols function takes a buffer to a block of data and a buffer-length parameter. First call the function with a null buffer address and 0 for the length. The call will fail, but the buffer-length parameter will contain the size of the buffer required. Once you have the proper size, call the function again. WSAEnumProtocols returns the number of protocols it found. The WSAPROTOCOL_INFO structure is large and contains a lot of fields, but the ones we're interested in are szProtocol, iAddressFamily, and iProtocol. If iAddressFamily is equal to AF_NETBIOS, the absolute value of iProtocol is the LANA number for the protocol given in the string szProtocol. In addition, the ProviderId GUID can be used to match the returned protocol to certain predefined GUIDs for protocols.

There is only one “gotcha” with this method. Under Windows NT and Windows 2000, the iProtocol field for any protocol installed on LANA 0 is the value 0x80000000 because protocol 0 is reserved for special use. Any protocol assigned LANA 0 will always have the value 0x80000000, so it is a matter of simply checking for this value.