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
ACTION_HEADER, ADAPTER_STATUS, FIND_NAME_BUFFER, FIND_NAME_HEADER, LANA_ENUM, NAME_BUFFER, Netbios, SESSION_BUFFER, SESSION_HEADER