Netbios - Win32 Programmer's Reference (win32.hlp)

Win32 Programmer's Reference

Index Commented Search About

Overview

Group

Quick Info

Windows NT
Yes
Win95
Yes
Win32s
No
Import Library
netapi32.lib
Header File
nb30.h
Unicode
No
Platform Notes
None

Netbios

The Netbios function interprets and executes the specified network control block (NCB).

UCHAR Netbios(

PNCB pncb	// address of network control block
);

Parameters
pncb

Pointer to an NCB structure describing the network control block.

Return Values
For synchronous requests, the return value is the return code of the NCB structure. That value is also returned in the ncb_retcode member of the NCB structure.

There are two return value possibilities for accepted asynchronous requests. If the asynchronous command has already completed when Netbios returns to its caller, the return value is the return code of the NCB structure, just as if it were a synchronous NCB structure. If the asynchronous command is still pending when Netbios returns to its caller, the return value is zero.

If the address specified by the pncb parameter is invalid, the return value is NRC_BADNCB.

Remarks
The Netbios function is primarily for applications written for the IBM NetBIOS system that need to be ported to Windows. Applications that do not have this requirement typically use other interfaces, such as mailslots and named pipes, instead of Netbios.

Netbios contains extensions to the standard IBM NetBIOS 3.0 specification to allow POST routines to be called from C and to operate efficiently in the Windows environment.

When an asynchronous network control block finishes and the ncb_post member is nonzero, the routine specified in ncb_post is called with a single parameter of type PNCB. This parameter contains the address of the finishing network control block. (In the standard IBM NetBIOS 3.0, the address of the network control block is supplied in a nonportable interface.)

Another extension to the NCB structure is a handle of an event (the ncb_event member). The event is set to the nonsignaled state by the system when an asynchronous NetBIOS command is accepted, and it is set to the signaled state when the asynchronous NetBIOS command finishes.

Using ncb_event to submit asynchronous requests requires fewer system resources than using ncb_post. Also, when ncb_event is nonzero, the pending request is canceled if the thread terminates before the request is processed. This is not true for requests sent by using ncb_post.

Only manual reset events should be used with Netbios. A specified event should not be associated with more than one active asynchronous NetBIOS command.

In Win32s, this function does not support features that conflict with the non-preemptive, shared-memory design of Windows 3.1. Because the system does not implement events, this function ignores the ncb_event member of the NCB structure. Also, the system maintains one systemwide name table rather the a per-process name table.