NetBIOS Programming Basics

Now that we have gone over some of the basic concepts of NetBIOS, we will discuss the NetBIOS API set, which is easy because only one function exists:

 UCHAR Netbios(PNCB pNCB); 

All the function declarations, constants, and so on for NetBIOS are defined in the header file Nb30.h. The only library necessary for linking NetBIOS applications is Netapi32.lib. The most important feature of this function is the parameter pNCB, which is a pointer to a network control block (NCB). This is a pointer to an NCB structure that contains all the information that the required Netbios function needs to execute a NetBIOS command. The definition of this structure is as follows:

 typedef struct _NCB { UCHAR ncb_command; UCHAR ncb_retcode; UCHAR ncb_lsn; UCHAR ncb_num; PUCHAR ncb_buffer; WORD ncb_length; UCHAR ncb_callname[NCBNAMSZ]; UCHAR ncb_name[NCBNAMSZ]; UCHAR ncb_rto; UCHAR ncb_sto; void (*ncb_post) (struct _NCB *); UCHAR ncb_lana_num; UCHAR ncb_cmd_cplt; UCHAR ncb_reserve[10]; HANDLE ncb_event; } * PNCB, NCB; 

Not all members of the structure will be used in every call to NetBIOS; some of the data fields are output parameters (in other words, set on the return from the Netbios call). One important tip: it is always a good idea to zero out the NCB structure before filling in members prior to a Netbios call. Take a look at Table 1-4, which describes the usage of each field. Additionally, the command reference in Appendix A contains a detailed summary of each NetBIOS command and its required (and optional) fields in an NCB structure.

Table 1-4. NCB structure members

Field	Definition
ncb_command	Specifies the NetBIOS command to execute. Many commands can be executed synchronously or asynchronously by bitwise ORing the ASYNCH (0x80) flag and the command.
ncb_retcode	Specifies the return code for the operation. The function sets this value to NRC_PENDING while an asynchronous operation is in progress.
ncb_lsn	Identifies the local session number that uniquely identifies a session within the current environment. The function returns a new session number after a successful NCBCALL or NCBLISTEN command.
ncb_num	Specifies the number of the local network name. A new number is returned for each call with an NCBADDNAME or NCBADDGRNAME command. You must use a valid number on all datagram commands.
ncb_buffer	Points to the data buffer. For commands that send data, this buffer is the data to send. For commands that receive data, this buffer will hold the data on the return from the Netbios function. For other commands, such as NCBENUM, the buffer will be the predefined structure LANA_ENUM.
ncb_length	Specifies the length of the buffer in bytes. For receive commands, Netbios sets this value to the number of bytes received. If the specified buffer is not large enough, Netbios returns the error NRC_BUFLEN.
ncb_callname	Specifies the name of the remote application.
ncb_name	Specifies the name by which the application is known.
ncb_rto	Specifies the timeout period for receive operations. This value is specified as a multiple of 500-millisecond units. The value 0 implies no timeout. This value is set for NCBCALL and NCBLISTEN commands that affect subsequent NCBRECV commands.
ncb_sto	Specifies the timeout period for send operations. You specify the value in 500-millisecond units. The value 0 implies no timeout. This value is set for NCBCALL and NCBLISTEN commands that affect subsequent NCBSEND and NCBCHAINSEND commands.
ncb_post	Specifies the address of the post routine to call upon completion of the asynchronous command. The function is defined as void CALLBACK PostRoutine(PNCB pncb); where pncb points to the network control block of the completed command.
ncb_lana_num	Specifies the LANA number to execute the command on.
ncb_cmd_cplt	Specifies the return code for the operation. Netbios sets this value to NRC_PENDING while an asynchronous operation is in progress.
ncb_reserve	Reserved. Must be 0.
ncb_event	Specifies a handle to a Windows event object set to the nonsignaled state. When an asynchronous command is completed, the event is set to its signaled state. Only manual reset events should be used. This field must be 0 if ncb_command does not have the ASYNCH flag set or if ncb_post is nonzero; otherwise, Netbios returns the error NRC_ILLCMD.

Synchronous vs. Asynchronous

When calling the Netbios function, you have the option of making the call synchronous or asynchronous. All NetBIOS commands by themselves are synchronous, which means the call to Netbios blocks until the command completes. For an NCBLISTEN command, the call to Netbios does not return until a client establishes a connection or until an error of some kind occurs. To make a command asynchronous, perform a logical OR of the NetBIOS command with the flag ASYNCH. If you specify the ASYNCH flag, you must specify either a post routine in the ncb_post field or an event handle in the ncb_event field. When an asynchronous command is executed, the value returned from Netbios is NRC_GOODRET (0x00) but the ncb_cmd_cplt field is set to NRC_PENDING (0xFF). Additionally, the Netbios function sets the ncb_cmd_cplt field of the NCB structure to NRC_PENDING until the command completes. After the command completes, the ncb_cmd_cplt field is set to the return value of the command. Netbios also sets the ncb_retcode field to the return value of the command upon completion.