NCB
The NCB
structure describes a network control block. A pointer to this structure is
passed to the Netbios
function.
typedef struct _NCB { // 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;
} NCB;
Members
ncb_command
Specifies the
command code and a flag that indicates whether the NCB structure is
processed asynchronously. The most significant bit contains the flag. If the
ASYNCH constant is combined with a command code (by using the OR operator), the
NCB structure is processed asynchronously. The following command codes
are supported:
|
Code |
Meaning |
|
NCBACTION |
Enables
extensions to the transport interface. NCBACTION commands are mapped to
TdiAction. When this code is specified, the ncb_buffer member points
to a buffer to be filled with an ACTION_HEADER structure, which is
optionally followed by data. NCBACTION commands cannot be canceled by using
NCBCANCEL. |
|
NCBADDGRNAME |
Adds a
group name to the local name table. |
|
NCBADDNAME |
Adds a
unique name to the local name table. |
|
NCBASTAT |
Retrieves
the status of the adapter. When this code is specified, the ncb_buffer
member points to a buffer to be filled with an ADAPTER_STATUS structure, followed by an
array of NAME_BUFFER
structures. |
|
NCBCALL |
Opens a
session with another name. |
|
NCBCANCEL |
Cancels a
previous command. |
|
NCBCHAINSEND |
Sends the
contents of two data buffers to the specified session partner. |
|
NCBCHAINSENDNA |
Sends the
contents of two data buffers to the specified session partner and does not
wait for acknowledgment. |
|
NCBDELNAME |
Deletes a
name from the local name table. |
|
NCBDGRECV |
Receives a
datagram from any name. |
|
NCBDGRECVBC |
Receives
broadcast datagram from any host. |
|
NCBDGSEND |
Sends
datagram to a specified name. |
|
NCBDGSENDBC |
Sends a
broadcast datagram to every host on the local area network (LAN). |
|
NCBENUM |
Enumerates
LAN adapter (LANA) numbers. When this code is specified, the ncb_buffer
member points to a buffer to be filled with a LANA_ENUM structure. |
|
NCBFINDNAME |
Determines
the location of a name on the network. When this code is specified, the ncb_buffer
member points to a buffer to be filled with a FIND_NAME_HEADER structure followed by one
or more FIND_NAME_BUFFER
structures. |
|
NCBHANGUP |
Closes a
specified session. |
|
NCBLANSTALERT |
Notifies
the user of LAN failures that last for more than one minute. |
|
NCBLISTEN |
Enables a
session to be opened with another name. |
|
NCBRECV |
Receives
data from the specified session partner. |
|
NCBRECVANY |
Receives
data from any session corresponding to a specified name. |
|
NCBRESET |
Resets a
LAN adapter. An adapter must be reset before any other NCB command that
specifies the same number in the ncb_lana_num member will be accepted. |
|
|
The IBM
NetBIOS 3.0 specification documents several NCB_RESET NCB s. Win32 implements the NCB.RESET using the dynamic
link routine interface. Particular values can be passed in specific bytes of
the NCB, more specifically: |
|
|
If ncb_lsn
is not 0x00, all resources associated with ncb_lana_num are to be
freed. |
|
|
If ncb_lsn
is 0x00, all resources associated with ncb_lana_num are to be freed,
and new resources are to be allocated. The ncb_callname[0] byte
specifies the maximum number of sessions, and the ncb_callname[2] byte
specifies the maximum number of names. A nonzero value for the ncb_callname[3]
byte requests that the application use NAME_NUMBER_1. |
|
NCBSEND |
Sends data
to the specified session partner. |
|
NCBSENDNA |
Sends data
to specified session partner and does not wait for an acknowledgment. |
|
NCBSSTAT |
Retrieves
the status of the session. When this value is specified, the ncb_buffer
member points to a buffer to be filled with a SESSION_HEADER structure, followed by
one or more SESSION_BUFFER
structures. |
|
NCBTRACE |
Activates
or deactivates NCB tracing. Support for this command in the system is
optional and system-specific. |
|
NCBUNLINK |
Unlinks the
adapter. |
ncb_retcode
Specifies the
return code. This value is set to NRC_PENDING while an asynchronous operation
is in progress. One of the following return code values can be specified:
|
Value |
Meaning |
|
NRC_GOODRET |
The
operation succeeded. |
|
NRC_BUFLEN |
An illegal
buffer length was supplied. |
|
NRC_ILLCMD |
An illegal
command was supplied. |
|
NRC_CMDTMO |
The command
was timed out. |
|
NRC_INCOMP |
The message
was incomplete. The application is to issue another command. |
|
NRC_BADDR |
The buffer
address was illegal. |
|
NRC_SNUMOUT |
The session
number was out of range. |
|
NRC_NORES |
No resource
was available. |
|
NRC_SCLOSED |
The session
was closed. |
|
NRC_CMDCAN |
The command
was canceled. |
|
NRC_DUPNAME |
A duplicate
name existed in the local name table. |
|
NRC_NAMTFUL |
The name
table was full. |
|
NRC_ACTSES |
The command
finished; the name has active sessions and is no longer registered. |
|
NRC_LOCTFUL |
The local
session table was full. |
|
NRC_REMTFUL |
The remote
session table was full. The request to open a session was rejected. |
|
NRC_ILLNN |
An illegal
name number was specified. |
|
NRC_NOCALL |
The system
did not find the name that was called. |
|
NRC_NOWILD |
Wildcards
are not permitted in the ncb_name member. |
|
NRC_INUSE |
The name
was already in use on the remote adapter. |
|
NRC_NAMERR |
The name
was deleted. |
|
NRC_SABORT |
The session
ended abnormally. |
|
NRC_NAMCONF |
A name
conflict was detected. |
|
NRC_IFBUSY |
The
interface was busy. |
|
NRC_TOOMANY |
Too many
commands were outstanding; the application can retry the command later. |
|
NRC_BRIDGE |
The ncb_lana_num
member did not specify a valid network number. |
|
NRC_CANOCCR |
The command
finished while a cancel operation was occurring. |
|
NRC_CANCEL |
The
NCBCANCEL command was not valid; the command was not canceled. |
|
NRC_DUPENV |
The name
was defined by another local process. |
|
NRC_ENVNOTDEF |
The
environment was not defined. A reset command must be issued. |
|
NRC_OSRESNOTAV |
Operating
system resources were exhausted. The application can retry the command later. |
|
NRC_MAXAPPS |
The maximum
number of applications was exceeded. |
|
NRC_NOSAPS |
No service
access points (SAPs) were available for NetBIOS. |
|
NRC_NORESOURCES |
The
requested resources were not available. |
|
NRC_INVADDRESS |
The NCB
address was not valid. |
|
|
This return
code is not part of the IBM NetBIOS 3.0 specification and is not returned in
the NCB structure. Instead, it is returned by the Netbios
function. |
|
NRC_INVDDID |
The NCB
DDID was invalid. |
|
NRC_LOCKFAIL |
The attempt
to lock the user area failed. |
|
NRC_OPENERR |
An error
occurred during an open operation being performed by the device driver. This
return code is not part of the IBM NetBIOS 3.0 specification. |
|
NRC_SYSTEM |
A system
error occurred. |
|
NRC_PENDING |
An
asynchronous operation is not yet finished. |
ncb_lsn
Specifies the
local session number. This number uniquely identifies a session within an
environment.
ncb_num
Specifies the
number for the local network name. This number is returned by Netbios
after a successful NCBADDNAME or NCBADDGRNAME command. This number, not the
name, must be used with all datagram commands and for NCBRECVANY commands.
The number for NAME_NUMBER_1 (see NCBRESET) is always 0x01. Netbios
assigns values in the range 0x02 to 0xFE for the remaining names.
ncb_buffer
Points to the
message buffer.
ncb_length
Specifies the
size, in bytes, of the message buffer.
ncb_callname
Specifies the
string that contains the remote name. Trailing space characters should be
supplied to make the length of the string equal to NCBNAMSZ.
ncb_name
Specifies the
string that contains the local name. Trailing space characters should be
supplied to make the length of the string equal to NCBNAMSZ.
ncb_rto
Specifies the
receive time-out period, in 500-millisecond units, for the session. A value of
zero implies no time-out. Specified with the NCBCALL or NCBLISTEN command.
Affects subsequent NCBRECV commands.
ncb_sto
Specifies the
send time-out period, in 500-millisecond units, for the session. A value of
zero implies no time-out. Specified with the NCBCALL or NCBLISTEN command.
Affects subsequent NCBSEND and NCBCHAINSEND commands.
ncb_post
Specifies the
address of the routine to call when the asynchronous NCB finishes. The
completion routine is passed a pointer to the completed network control block.
ncb_lana_num
Specifies the
LAN adapter number. This zero-based number corresponds to a particular
transport provider using a particular LAN adapter board.
ncb_cmd_cplt
Specifies the
command complete flag. This value is the same as the ncb_retcode member.
ncb_reserve
Reserved;
must be zero.
ncb_event
Specifies a
handle to a Windows event that is set to the signaled state when the
asynchronous network control block finishes. The event is signaled if the Netbios
function returns a nonzero value.
The ncb_event member must be zero if the ncb_command
member does not have the ASYNCH value set or if ncb_post is nonzero.
Otherwise, NRC_ILLCMD is returned.
The event specified by ncb_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 given
event should not be associated with more than one active asynchronous NetBIOS
command.
See Also