Tips for Writing Windows Sockets Apps That Use AF_NETBIOS

• Microsoft Win32 Software Development Kit (SDK) for Windows NT version 3.5

SUMMARY

The six issues listed in this article must be addressed when writing Windows Sockets applications that use the AF_NETBIOS protocol family.

NOTE: Windows 95 does not support AF_NETBIOS.

MORE INFORMATION

Issues to Address When Writing Windows Sockets Applications

1. When 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 multihomed host (a machine 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 machine 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. This
      symbol cannot be used as a protocol option and should be ignored.
   
   

2. Use the snb_type values provided by the WSNETBS.H header for NetBIOS name registration and deregistration.

   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.

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.

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
   

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
   
      The above 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.
   
      The EnumProtocols() function can be used to enumerate valid lana
      numbers. Listed below is a code fragment that demonstrates this type
      of functionality:
   
      #include <nspapi.h>
   
            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.
            // The following code must appear on one line.
            assert( iRes == -1 && GetLastError() ==
                         ERROR_INSUFFICIENT_BUFFER );
   
            if (!cb)
            {
               fprintf( stderr, "No available NetBIOS transports.\n");
               break;
            }
   
            // 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[ pPI[iRes].iProtocol ] = TRUE;
   
            fprintf( stderr, "Available NetBIOS lana numbers: " );
            while( nLanas-- )
               if ( pfLanas[nLanas] )
                  fprintf( stderr, "%d ", nLanas );
   
            free( pPI );
         }
   
   

6. Performance: Use of AF_NETBIOS is recommended 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.