Structure NCB (nb30.h)

Article
08/25/2023

[Netbios n’est pas pris en charge sur Windows Vista, Windows Server 2008 et les versions ultérieures du système d’exploitation]

La structure NCB représente un bloc de contrôle réseau. Il contient des informations sur la commande à exécuter, une routine de publication facultative, un handle d’événement facultatif et un pointeur vers une mémoire tampon utilisée pour les messages ou d’autres données. Un pointeur vers cette structure est passé à la fonction Netbios .

Syntaxe

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 *)  * ncb_post;
  UCHAR  ncb_lana_num;
  UCHAR  ncb_cmd_cplt;
#if ...
  UCHAR  ncb_reserve[18];
#else
  UCHAR  ncb_reserve[10];
#endif
  HANDLE ncb_event;
} NCB, *PNCB;

Membres

ncb_command

Spécifie le code de commande et un indicateur qui indique si la structure NCB est traitée de manière asynchrone. Le bit le plus significatif contient l’indicateur. Si la constante ASYNCH est combinée à un code de commande (à l’aide de l’opérateur OR), la structure NCB est traitée de manière asynchrone. Les codes de commande suivants sont pris en charge.

Code	Signification
NCBACTION	Windows Server 2003, Windows XP, Windows 2000 et Windows NT : Active les extensions de l’interface de transport. NCBACTION est mappé à TdiAction. Lorsque ce code est spécifié, le membre ncb_buffer pointe vers une mémoire tampon à remplir avec une structure ACTION_HEADER , qui est éventuellement suivie de données. Les commandes NCBACTION ne peuvent pas être annulées à l’aide de NCBCANCEL. NCBACTION n’est pas une commande NetBIOS 3.0 standard.
NCBADDGRNAME	Ajoute un nom de groupe à la table de noms local. Ce nom ne peut pas être utilisé par un autre processus sur le réseau en tant que nom unique, mais il peut être ajouté par n’importe qui en tant que nom de groupe.
NCBADDNAME	Ajoute un nom unique à la table de noms locaux. Le pilote TDI garantit que le nom est unique sur le réseau.
NCBASTAT	Récupère la status d’un adaptateur local ou distant. Lorsque ce code est spécifié, le membre ncb_buffer pointe vers une mémoire tampon à remplir avec une structure ADAPTER_STATUS , suivie d’un tableau de structures NAME_BUFFER .
NCBCALL	Ouvre une session avec un autre nom.
NCBCANCEL	Annule une commande précédente en attente.
NCBCHAINSEND	Envoie le contenu de deux mémoires tampons de données au partenaire de session spécifié.
NCBCHAINSENDNA	Envoie le contenu de deux mémoires tampons de données au partenaire de session spécifié et n’attend pas d’accusé de réception.
NCBDELNAME	Supprime un nom de la table de noms local.
NCBDGRECV	Reçoit un datagramme de n’importe quel nom.
NCBDGRECVBC	Reçoit un datagramme de diffusion de n’importe quel nom.
NCBDGSEND	Envoie le datagramme à un nom spécifié.
NCBDGSENDBC	Envoie un datagramme de diffusion à chaque hôte sur le réseau local (LAN).
NCBENUM	Windows Server 2003, Windows XP, Windows 2000 et Windows NT : Énumère les numéros de l’adaptateur LAN (LANA). Lorsque ce code est spécifié, le membre ncb_buffer pointe vers une mémoire tampon à remplir avec une structure LANA_ENUM. NCBENUM n’est pas une commande NetBIOS 3.0 standard.
NCBFINDNAME	Détermine l’emplacement d’un nom sur le réseau. Lorsque ce code est spécifié, le membre ncb_buffer pointe vers une mémoire tampon à remplir avec une structure FIND_NAME_HEADER suivie d’une ou plusieurs structures FIND_NAME_BUFFER .
NCBHANGUP	Ferme une session spécifiée.
NCBLANSTALERT	Windows Server 2003, Windows XP, Windows 2000 et Windows NT : Avertit l’utilisateur des défaillances lan qui durent plus d’une minute.
NCBLISTEN	Permet d’ouvrir une session avec un autre nom (local ou distant).
NCBRECV	Reçoit des données du partenaire de session spécifié.
NCBRECVANY	Reçoit les données de toute session correspondant à un nom spécifié.
NCBRESET	Réinitialise un adaptateur LAN. Un adaptateur doit être réinitialisé avant de pouvoir accepter toute autre commande NCB qui spécifie le même numéro dans le membre ncb_lana_num . Utilisez les valeurs suivantes pour spécifier la façon dont les ressources doivent être libérées : Si ncb_lsn n’est pas 0x00, toutes les ressources associées à ncb_lana_num doivent être libérées. Si ncb_lsn est 0x00, toutes les ressources associées à ncb_lana_num doivent être libérées et de nouvelles ressources doivent être allouées. L’octet ncb_callname[0] spécifie le nombre maximal de sessions, et l’octet ncb_callname[2] spécifie le nombre maximal de noms. Une valeur différente de zéro pour l’octet ncb_callname[3] demande à l’application d’utiliser NAME_NUMBER_1.
NCBSEND	Envoie des données au partenaire de session spécifié.
NCBSENDNA	Envoie des données au partenaire de session spécifié et n’attend pas d’accusé de réception.
NCBSSTAT	Récupère le status de la session. Lorsque cette valeur est spécifiée, le membre ncb_buffer pointe vers une mémoire tampon à remplir avec une structure SESSION_HEADER , suivie d’une ou plusieurs structures SESSION_BUFFER .
NCBTRACE	Active ou désactive le suivi NCB. Cette commande n’est pas prise en charge.
NCBUNLINK	Dissocie l’adaptateur. Cette commande est fournie pour la compatibilité avec les versions antérieures de NetBIOS. Elle n’a aucun effet dans Windows.

ncb_retcode

Spécifie le code de retour. Cette valeur est définie sur NRC_PENDING pendant qu’une opération asynchrone est en cours. Le système retourne l’une des valeurs suivantes :

Valeur	Signification
NRC_GOODRET	L’opération a réussi.
NRC_BUFLEN	Une longueur de mémoire tampon non conforme a été fournie.
NRC_ILLCMD	Une commande illégale a été fournie.
NRC_CMDTMO	La commande a été expirée.
NRC_INCOMP	Le message était incomplet. L’application doit émettre une autre commande.
NRC_BADDR	L’adresse de la mémoire tampon n’était pas valide.
NRC_SNUMOUT	Le numéro de session était hors de portée.
NRC_NORES	Aucune ressource n’était disponible.
NRC_SCLOSED	La session a été fermée.
NRC_CMDCAN	La commande a été annulée.
NRC_DUPNAME	Un nom en double existait dans la table de noms local.
NRC_NAMTFUL	La table de noms était pleine.
NRC_ACTSES	La commande s’est terminée ; le nom a des sessions actives et n’est plus inscrit.
NRC_LOCTFUL	La table de session locale était pleine.
NRC_REMTFUL	La table de session distante était pleine. La demande d’ouverture d’une session a été rejetée.
NRC_ILLNN	Un numéro de nom non valide a été spécifié.
NRC_NOCALL	Le système n’a pas trouvé le nom appelé.
NRC_NOWILD	Les caractères génériques ne sont pas autorisés dans le membre ncb_name .
NRC_INUSE	Le nom était déjà utilisé sur l’adaptateur distant.
NRC_NAMERR	Le nom a été supprimé.
NRC_SABORT	La session s’est terminée anormalement.
NRC_NAMCONF	Un conflit de noms a été détecté.
NRC_IFBUSY	L’interface était occupée.
NRC_TOOMANY	Trop de commandes étaient en attente ; l’application peut réessayer la commande ultérieurement.
NRC_BRIDGE	Le membre ncb_lana_num n’a pas spécifié de numéro réseau valide.
NRC_CANOCCR	La commande s’est terminée alors qu’une opération d’annulation se produisait.
NRC_CANCEL	La commande NCBCANCEL n’était pas valide ; la commande n’a pas été annulée.
NRC_DUPENV	Le nom a été défini par un autre processus local.
NRC_ENVNOTDEF	L’environnement n’a pas été défini. Une commande de réinitialisation doit être émise.
NRC_OSRESNOTAV	Les ressources du système d’exploitation ont été épuisées. L’application peut réessayer la commande ultérieurement.
NRC_MAXAPPS	Le nombre maximal d’applications a été dépassé.
NRC_NOSAPS	Aucun point d’accès au service n’était disponible pour NetBIOS.
NRC_NORESOURCES	Les ressources demandées n’étaient pas disponibles.
NRC_INVADDRESS	L’adresse du NCB n’était pas valide.
NRC_INVDDID	Le DDID NCB n’était pas valide. Ce code de retour ne fait pas partie de la spécification IBM NetBIOS 3.0 et n’est pas retourné dans la structure NCB . Au lieu de cela, il est retourné par la fonction Netbios .
NRC_LOCKFAIL	La tentative de verrouillage de la zone utilisateur a échoué.
NRC_OPENERR	Une erreur s’est produite lors d’une opération ouverte effectuée par le pilote de périphérique. Ce code d’erreur ne fait pas partie de la spécification NetBIOS 3.0.
NRC_SYSTEM	Une erreur système s’est produite.
NRC_PENDING	Une opération asynchrone n’est pas encore terminée.

ncb_lsn

Identifie le numéro de session local. Ce nombre identifie de manière unique une session au sein d’un environnement. Ce nombre est retourné par la fonction Netbios après une commande NCBCALL réussie.

ncb_num

Spécifie le numéro du nom du réseau local. Ce nombre est retourné par Netbios après une commande NCBADDNAME ou NCBADDGRNAME réussie. Ce nombre, et non le nom, doit être utilisé avec toutes les commandes de datagramme et pour les commandes NCBRECVANY .

Le nombre de NAME_NUMBER_1 est toujours 0x01. La fonction Netbios affecte des valeurs dans la plage 0x02 à 0xFE pour les noms restants.

ncb_buffer

Pointeur vers la mémoire tampon de messages. La mémoire tampon doit avoir un accès en écriture. Ses utilisations sont les suivantes :

Commande	Objectif
NCBSEND	Contient le message à envoyer.
NCBRECV	Reçoit le message.
NCBSSTAT	Reçoit les informations status demandées.

ncb_length

Spécifie la taille, en octets, de la mémoire tampon de message. Pour les commandes de réception, ce membre est défini par la fonction Netbios pour indiquer le nombre d’octets reçus.

Si la longueur de la mémoire tampon est incorrecte, la fonction Netbios retourne le code d’erreur NRC_BUFLEN .

ncb_callname[NCBNAMSZ]

Spécifie le nom de l’application distante. Des caractères d’espace de fin doivent être fournis pour que la longueur de la chaîne soit égale à NCBNAMSZ.

ncb_name[NCBNAMSZ]

Spécifie le nom sous lequel l’application est connue. Des caractères d’espace de fin doivent être fournis pour que la longueur de la chaîne soit égale à NCBNAMSZ.

ncb_rto

Spécifie le délai d’attente pour les opérations de réception, en unités de 500 millisecondes, pour la session. Une valeur de zéro n’implique aucun délai d’attente. Spécifiez avec la commande NCBCALL ou NCBLISTEN . Affecte les commandes NCBRECV suivantes.

ncb_sto

Spécifie le délai d’attente pour les opérations d’envoi, en unités de 500 millisecondes, pour la session. Une valeur de zéro n’implique aucun délai d’attente. Spécifiez avec la commande NCBCALL ou NCBLISTEN . Affecte les commandes NCBSEND et NCBCHAINSEND suivantes.

ncb_post

Spécifie l’adresse de la post-routine à appeler lorsque la commande asynchrone est terminée. La post-routine est définie comme suit :

NCB_POST PostRoutine( PNCB pncb ) ;

où le paramètre pncb est un pointeur vers la structure NCB terminée.

ncb_lana_num

Spécifie le numéro d’adaptateur LAN. Ce nombre de base zéro correspond à un fournisseur de transport particulier à l’aide d’une carte d’adaptateur LAN particulière.

ncb_cmd_cplt

Spécifie l’indicateur d’exécution de la commande. Cette valeur est identique au membre ncb_retcode .

ncb_reserve[18]

Réservés au; doit être égal à zéro.

La longueur X du tableau ncb_reserve dépend de l’architecture système. Pour les systèmes 64 bits, le tableau contient 18 éléments. Sinon, le tableau contient 10 éléments.

ncb_reserve[10]

Réservés au; doit être égal à zéro.

La longueur X du tableau ncb_reserve dépend de l’architecture système. Pour les systèmes 64 bits, le tableau contient 18 éléments. Sinon, le tableau contient 10 éléments.

ncb_event

Spécifie un handle pour un objet d’événement qui est défini sur l’état non signé lorsqu’une commande asynchrone est acceptée, et qui est défini sur l’état signalé lorsque la commande asynchrone est terminée. L’événement est signalé si la fonction Netbios retourne une valeur différente de zéro. Seuls les événements de réinitialisation manuelle doivent être utilisés pour la synchronisation. Un événement spécifié ne doit pas être associé à plusieurs commandes asynchrones actives.

Le membre ncb_event doit être égal à zéro si le membre ncb_command n’a pas l’indicateur ASYNCH défini ou si ncb_post est différent de zéro. Dans le cas contraire, Netbios retourne le code d’erreur NRC_ILLCMD .

Remarques

L’utilisation de ncb_event pour émettre des requêtes asynchrones nécessite moins de ressources système que l’utilisation de ncb_post. En outre, lorsque ncb_event est différent de zéro, la requête en attente est annulée si le thread se termine avant le traitement de la demande. Cela n’est pas vrai pour les requêtes asynchrones envoyées à l’aide de ncb_post.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
En-tête	nb30.h