SnmpGetVb, fonction (winsnmp.h)

Article
08/27/2023

[SNMP est disponible pour une utilisation dans les systèmes d’exploitation spécifiés dans la section Configuration requise. Il sera peut-être modifié ou indisponible dans les versions ultérieures. Utilisez plutôt Windows Remote Management, qui est l’implémentation Microsoft de WS-Man.]

Une application WinSNMP appelle la fonction SnmpGetVb pour récupérer des informations à partir d’une liste de liaisons de variables. Cette fonction WinSNMP récupère un nom de variable et sa valeur associée à partir de l’entrée de liaison de variable spécifiée par le paramètre d’index .

Syntaxe

SNMPAPI_STATUS SNMPAPI_CALL SnmpGetVb(
  [in]  HSNMP_VBL  vbl,
  [in]  smiUINT32  index,
  [out] smiLPOID   name,
  [out] smiLPVALUE value
);

Paramètres

[in] vbl

Gérez la liste des liaisons de variables à récupérer.

[in] index

Spécifie une variable entière longue non signée qui identifie l’entrée de liaison de variable à récupérer. Cette variable contient la position de l’entrée de liaison de variable, dans la liste des liaisons de variables.

Les valeurs valides pour ce paramètre sont comprises entre 1 et n, où 1 indique la première entrée de liaison de variable dans la liste des liaisons de variables, et n est le nombre total d’entrées dans la liste. Pour plus d’informations, consultez la section Remarques suivante.

[out] name

Pointeur vers une structure smiOID pour recevoir le nom de la variable de l’entrée de liaison de variable.

[out] value

Pointeur vers une structure smiVALUE pour recevoir la valeur associée à la variable identifiée par le paramètre name .

Si la fonction réussit, le membre de syntaxe de la structure pointée par le paramètre value peut être l’un des types de données syntaxiques suivants. Pour plus d’informations, consultez RFC 1902, « Structure des informations de gestion pour la version 2 du protocole SNMPv2 (Simple Network Management Protocol) ».

Type de données syntaxique	Signification
SNMP_SYNTAX_INT	Indique une variable entière signée 32 bits.
SNMP_SYNTAX_OCTETS	Indique une variable de chaîne d’octets qui est des données binaires ou textuelles.
SNMP_SYNTAX_NULL	Indique une valeur NULL .
SNMP_SYNTAX_OID	Indique une variable d’identificateur d’objet qui est un nom attribué avec un maximum de 128 sous-identificateurs.
SNMP_SYNTAX_INT32	Indique une variable entière signée 32 bits.
SNMP_SYNTAX_IPADDR	Indique une variable d’adresse Internet 32 bits. Si le format d’interruption PDU SNMPv1 est utilisé pour représenter une adresse IPv6, cette valeur est 0.0.0.0.
SNMP_SYNTAX_CNTR32	Indique une variable de compteur qui augmente jusqu’à ce qu’elle atteigne une valeur maximale de (2^32) – 1.
SNMP_SYNTAX_GAUGE32	Indique une variable de jauge qui est un entier non négatif qui peut augmenter ou diminuer, mais ne jamais dépasser une valeur maximale.
SNMP_SYNTAX_TIMETICKS	Indique une variable de compteur qui mesure le temps en centièmes de seconde, jusqu’à ce qu’elle atteigne une valeur maximale de (2^32) – 1. Il s’agit d’un entier non négatif relatif à un événement de minuteur spécifique.
SNMP_SYNTAX_OPAQUE	Ce type fournit une compatibilité descendante et ne doit pas être utilisé pour les nouveaux types d’objets. Il prend en charge la possibilité de passer la syntaxe ASN.1 (Abstract Syntax Notation One) arbitraire.
SNMP_SYNTAX_CNTR64	Indique une variable de compteur qui augmente jusqu’à ce qu’elle atteigne une valeur maximale de (2^64) – 1.
SNMP_SYNTAX_UINT32	Indique une variable entière non signée 32 bits.
SNMP_SYNTAX_NOSUCHOBJECT	Indique que l’agent ne prend pas en charge le type d’objet qui correspond à la variable.
SNMP_SYNTAX_NOSUCHINSTANCE	Indique que l’objet instance n’existe pas pour l’opération.
SNMP_SYNTAX_ENDOFMIBVIEW	Indique que l’application WinSNMP tente de référencer un identificateur d’objet qui se trouve au-delà de la fin de l’arborescence MIB prise en charge par l’agent.

Valeur retournée

Si la fonction réussit, la valeur de retour est SNMPAPI_SUCCESS.

Si la fonction échoue, la valeur de retour est SNMPAPI_FAILURE. Pour obtenir des informations d’erreur étendues, appelez SnmpGetLastError. La fonction SnmpGetLastError peut retourner l’une des erreurs suivantes.

Code de retour	Description
SNMPAPI_NOT_INITIALIZED	La fonction SnmpStartup ne s’est pas terminée correctement.
SNMPAPI_ALLOC_ERROR	Une erreur s’est produite lors de l’allocation de mémoire.
SNMPAPI_INDEX_INVALID	Le paramètre d’index n’est pas valide.
SNMPAPI_VBL_INVALID	Le paramètre vbl n’est pas valide.
SNMPAPI_OTHER_ERROR	Une erreur inconnue ou non définie s’est produite.

Remarques

Les trois derniers types de syntaxe décrivent des conditions d’exception dans l’infrastructure SNMP version 2C (SNMPv2C).

La fonction SnmpGetVb retourne le nom de la variable de l’entrée de liaison de variable dans la structure vers laquelle pointe le paramètre name . Elle retourne la valeur associée à la variable dans la structure pointée par le paramètre value .

Lors de l’entrée, la fonction SnmpGetVb ignore les membres des structures smiOID et smiVALUE pointées respectivement par les paramètres name et value . L’implémentation de Microsoft WinSNMP remplace les membres si la fonction se termine correctement.

Les valeurs valides pour une application WinSNMP à utiliser pour le paramètre d’index sont les suivantes :

Valeur de retour d’un appel à la fonction SnmpCountVbl
Champ d’index d’erreur d’une unité de données de protocole SNMP_PDU_RESPONSE (PDU) retournée par un appel à la fonction SnmpRecvMsg

L’application WinSNMP doit appeler la fonction SnmpFreeDescriptor pour libérer les ressources allouées au membre ptr de la structure smiOID vers laquelle pointe le paramètre name . L’application doit également appeler la fonction SnmpFreeDescriptor pour libérer les ressources allouées à la structure smiVALUE pointée par le paramètre value dans les conditions suivantes. Si le membre de valeur est une structure smiOCTETS ou smiOID , l’application doit appeler SnmpFreeDescriptor pour libérer les ressources allouées à ces structures. Pour plus d’informations, consultez Concepts de Gestion des données WinSNMP.

Configuration requise


Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winsnmp.h
Bibliothèque	Wsnmp32.lib
DLL	Wsnmp32.dll