netbios-winapi.pdf

Opis funcji Netbiosa w WinAPI zaczerpnięty z oryginalnej dokumentacji WinAPI

Generalna zasada przy wypełnianiu pól NCB dla poszczególnych komend – wypełniamy te same

pola i tym samym rodzajem informacji co dla DOSa (np. w Pascalu, dokładny opis pól i zasad ich

wypełniania dla poszczególnych komend w dokumencie Netbios-1.pdf). Przykład w instrukcji

laboratoryjnej nr 2.

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.

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

UWAGA! Podkreślono komendy, które mogą przydatne w trakcie kolejnych zajęć

laboratoryjnych!

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.

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.

Plik z chomika:

Inne pliki z tego folderu:

Inne foldery tego chomika: