INFO: Tips for Writing Windows Sockets Apps That Use AF_NETBIOS

MORE INFORMATION

Issues to Address When Writing Windows Sockets Applications

Issue 1:

When you are creating an AF_NETBIOS socket, specify -1 times lana for the protocol option.

The Windows NT WinSock library allows the programmer to create a socket that allows communication over a particular lana. The lana number is specified via the protocol option of the socket() function. To create an AF_NETBIOS socket, specify -1 times the lana for the protocol option of the socket() function. For example:

   SOCKET hSock0 = socket( AF_NETBIOS, SOCK_DGRAM, 0 );  // lana 0;
   SOCKET hSock1 = socket( AF_NETBIOS, SOCK_DGRAM, -1 ); // lana 1;
				

The lana numbers are basically indices to the list of transports supported by the NetBIOS implementation. A given host has one unique lana number for every installed transport that supports NetBIOS. For example, listed below are some possible lana numbers for a typical Windows NT configuration:

   Lana     Transport
   ----------------------------------------------------------
   0        TCP/IP // lana 0 is the default NetBIOS transport
   1        IPX/SPX w/NetBIOS
   3        NetBEUI
				

In the case of a multi-homed host (a computer with multiple network adapters), the number of unique lana numbers equals the number of network transports that support NetBIOS times the number of network adapters. For example, if the computer depicted above contained two network adapters, it would have a total of 3 * 2 = 6 lana numbers.

Also, please note the WSNetBS.h header included with the Windows NT version 3.5 SDK erroneously defines the NBPROTO_NETBEUI symbol. You cannot use this symbol as a protocol option and you should ignore it.

Issue 2:

Use the snb_type values provided by the WSNETBS.H header for NetBIOS name registration and de-registration.

When filling out a sockaddr_nb structure, you must specify the appropriate value for the snb_type field. This field is used during the bind() operation to handle NetBIOS name registration. The WSNetBS.h header defines several values for this field. However, only the following two values are currently implemented:

• NETBIOS_UNIQUE_NAME Registers a unique NetBIOS name. This action is usually performed by a client or a server to register an endpoint.
• NETBIOS_GROUP_NAME Registers a group name. This action is typically performed in preparation for sending or receiving NetBIOS multicasts.

Names are registered during the bind() operation.

Issue 3:

Use the supported socket types of SOCK_DGRAM and SOCK_SEQPACKET.

Due to the nature of NetBIOS connection services, SOCK_STREAM is not supported.

Issue 4:

Choose a NetBIOS port that does not conflict with your network client software.

The NetBIOS port is an eight-bit value stored in the last position of the snb_name that is used by various network services to differentiate various type of NetBIOS names. When you register NetBIOS names, choose port values that do not cause conflicts with existing network services. This is of particular importance if you are registering a NetBIOS name that duplicates a user name or a machine name on the network. The following lists the reserved port values:

   0x00, 0x03, 0x06, 0x1f, 0x20, 0x21, 0xbe, 0xbf, 0x1b,
   0x1c, 0x1d, 0x1e
				

Issue 5:

Applications should use all available lana numbers when initiating communication.

Because the NetBIOS interface can take advantage of multiple transport protocols, it is important to use all lanas when initiating communication. Server applications should accept connections on sockets for each lana number, and client applications should attempt to connect on every available lana. In a similar fashion, data gram broadcasts should be sent from sockets created from each lana.

The following diagram depicts the lana mappings for two machines. In order for a client application running on Machine A to communicate with a server application on Host B, the client application must create a socket on lana 3, and the server must create a socket on lana 1. Because the client and the server cannot know in advance which single lana to use, they must create sockets for all lanas.

   Host A (Client)            Host B (Server)
   ---------------            ---------------
   lana  Transport            lana  Transport
   ----  ---------            ----  ---------

   0     NetBEUI              0     TCP/IP
   3     IPX/SPX <==========> 1     IPX/SPX
                              3     NetBEUI
				

This diagram illustrates several other important points about lanas. First, a transport that has a certain lana number on one host does not necessarily have the same lana number on other machines. Second, lana numbers do not have to be sequential.

You can use the EnumProtocols() function to enumerate valid lana numbers. The following sample code demonstrates this type of functionality:

Sample Code

   #include <windows.h>
   #include <assert.h>
   #include <nspapi.h>

   #include <stdio.h>
   void main()
   {
      DWORD          cb = 0;
      PROTOCOL_INFO *pPI;
      BOOL           pfLanas[100];

      int            iRes,
                     nLanas = sizeof(pfLanas) / sizeof(BOOL);

      // Specify NULL for lpiProtocols to enumerate all protocols.

      // First, determine the output buffer size.
      iRes = EnumProtocols( NULL, NULL, &cb );

      // Verify the expected error was received.
      assert( iRes == -1 && GetLastError() == ERROR_INSUFFICIENT_BUFFER );
      if (!cb)
      {
         printf( "No available NetBIOS transports.\n");
         return;
      }

      // Allocate a buffer of the specified size.
      pPI = (PROTOCOL_INFO*) malloc( cb );

      // Enumerate all protocols.
      iRes = EnumProtocols( NULL, pPI, &cb );

      // EnumProtocols() lists each lana number twice, once for
      // SOCK_DGRAM and once for SOCK_SEQPACKET. Set a flag in pfLanas
      // so unique lanas can be identified.

      memset( pfLanas, 0, sizeof( pfLanas ));

      while (iRes > 0)
      {
         // Scan protocols looking for AF_NETBIOS.
         if ( pPI[--iRes].iAddressFamily == AF_NETBIOS )
            // found one
            pfLanas[ abs(pPI[iRes].iProtocol) ] = TRUE;
      }

      printf( "Available NetBIOS lana numbers: " );
      while( nLanas-- )
         if ( pfLanas[nLanas] )
            printf( "%d ", nLanas );

      printf( "\n" );
      free( pPI );
      return;
   }
				

Issue 6:

Performance: Use AF_NETBIOS for communication with down-level clients.

On Windows NT, NetBIOS is a high-level emulated interface. Consequently, applications that use the WinSock() function over NetBIOS obtain lower throughput than applications that use WinSock() over a native transport such as IPX/SPX or TCP/IP. However, due to the simplicity of the WinSock interface, it is a desirable interface for writing new 32-bit applications that communicate with NetBIOS applications running on down-level clients like Windows for Workgroups or Novell Netware.