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'll 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. With the advent of the IP Helper functions for Windows 2000 and Windows 98 (discussed in Appendix A), there is a more generic interface for finding the MAC address; however, for the other Win32 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.

The fields required to call NCBASTAT are ncb_command, ncb_buffer, ncb_length, ncb_lana_num, and ncb_callname. If the first character of ncb_callname is an asterisk (*), a status command is executed, but only those NetBIOS names added by the calling process are returned. However, if you call Netbios with an adapter status command, add a unique name to the current process's name table, and then use that name in the ncb_callname field, all NetBIOS names are registered in the local process's name table, as well as any names registered by the system. You can also perform an adapter status query on a machine other than the one the command is executed on. To do this, set the ncb_callname field to the machine name of the remote workstation.

NOTE
Remember that all Microsoft machine names have their 16th byte set to 0 and should be padded with spaces.

The sample program Astat.c is a simple adapter status program that runs the given query on all LANA adapters. Also, by using the /l:LOCALNAME flag, the command is executed on the local machine but provides the entire name table. The /r:REMOTENAME flag executes a remote query for the given machine name.

A few things should be considered when using the adapter status command. First, a multihomed machine will have more than one MAC address. Since NetBIOS provides no way to find which adapters and protocols a LANA is bound to, it is up to you to sort out the values returned. Also, if Remote Access Service (RAS) is installed, the system will allocate LANA numbers for those connections as well. While the RAS connections are unconnected, an adapter status on those LANAs will return all zeros for the MAC address. If a RAS connection is established, the MAC address is the same MAC address RAS assigns to all its virtual network devices. Finally, when you perform a remote adapter status query, you must perform it over a transport protocol that both machines have in common. For example, the system command Nbtstat (which is a command line version of NCBASTAT) issues its query over the TCP/IP transport only. If the remote machine doesn't have TCP/IP as one of its protocols, the command will fail.

Find Name (NCBFINDNAME)

The find name command, available only on Windows NT and Windows 2000, tells you who, if anyone, has a given NetBIOS name registered. In order to perform a successful find name query, the process must add its own unique name to the name table. The required fields for this command are command, LANA number, buffer, and buffer length. The query will return a FIND_NAME_HEADER structure and any number of FIND_NAME_BUFFER structures, which are defined as follows:

 typedef struct _FIND_NAME_HEADER { WORD node_count; UCHAR reserved; 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 will return 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_BUFFERS 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, while 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.) Under Windows NT 4, 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 under Windows NT 4, 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 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 is 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 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. Additionally, 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. This is 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.



Network Programming for Microsoft Windows
Linux Server Hacks, Volume Two: Tips & Tools for Connecting, Monitoring, and Troubleshooting
ISBN: 735615799
EAN: 2147483647
Year: 1998
Pages: 159

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net