SnmpExtensionQueryEx, fonction (snmp.h)

Article
08/26/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.]

Le service SNMP Microsoft appelle la fonction SnmpExtensionQueryEx pour traiter les demandes SNMP qui spécifient des variables dans une ou plusieurs sous-arborescences MIB inscrites par des agents d’extension SNMP. Cette fonction est un élément de l’API de l’agent d’extension SNMP.

Note Il est recommandé d’utiliser la fonction SnmpExtensionQueryEx , qui prend en charge les types de données SNMP version 2C (SNMPv2C) et les opérations SET SNMP multiphase. Le service SNMP n’appelle pas la fonction SnmpExtensionQuery si l’agent d’extension exporte la fonction SnmpExtensionQueryEx .

Syntaxe

BOOL SNMP_FUNC_TYPE SnmpExtensionQueryEx(
  [in]      UINT            nRequestType,
  [in]      UINT            nTransactionId,
  [in, out] SnmpVarBindList *pVarBindList,
  [in, out] AsnOctetString  *pContextInfo,
  [out]     AsnInteger32    *pErrorStatus,
  [out]     AsnInteger32    *pErrorIndex
);

Paramètres

[in] nRequestType

Spécifie le type d’opération que le service SNMP demande à l’agent d’extension d’effectuer. Ce paramètre peut prendre les valeurs suivantes.

Valeur	Signification
SNMP_EXTENSION_GET	Récupérez la ou les valeurs des variables spécifiées.
SNMP_EXTENSION_GET_NEXT	Récupérez la ou les valeurs du successeur lexicographique des variables spécifiées.
SNMP_EXTENSION_SET_TEST	Validez les valeurs des variables spécifiées. Cette opération optimise la probabilité d’une écriture réussie pendant la requête COMMIT.
SNMP_EXTENSION_SET_COMMIT	Écrivez les nouvelles valeurs dans les variables spécifiées.
SNMP_EXTENSION_SET_UNDO	Réinitialisez les valeurs des variables spécifiées à leurs valeurs avant la requête COMMIT.
SNMP_EXTENSION_SET_CLEANUP	Libérez les ressources allouées dans les requêtes et opérations précédentes.

Pour plus d’informations sur les types de requêtes SET, c’est-à-dire ceux qui commencent par SNMP_EXTENSION_SET_, consultez la section Remarques suivante.

[in] nTransactionId

Spécifie une variable DWORD qui est l’identificateur unique de la PDU de requête SNMP entrante. L’agent d’extension peut utiliser cette valeur pour mettre en corrélation plusieurs appels du service SNMP qui impliquent la même PDU.

[in, out] pVarBindList

Pointeur vers la liste de liaisons de variables contenant les variables d’intérêt.

[in, out] pContextInfo

Pointeur vers une chaîne d’octets qui contient des informations de contexte définies par l’utilisateur.

L’agent d’extension peut utiliser ce paramètre pour stocker les informations de contexte utilisées lors des opérations SNMP SET multiphase. L’agent d’extension doit libérer les ressources associées à ce paramètre pendant la demande CLEANUP. Le service SNMP ne libère aucune ressource associée à ce paramètre. Pour plus d’informations, consultez la section Remarques suivante.

[out] pErrorStatus

Pointeur vers une variable pour recevoir l’erreur status résultat. Ce paramètre peut être l’une des valeurs suivantes définies par SNMPv2C.

Code d'erreur	Signification
SNMP_ERRORSTATUS_NOERROR	L’agent signale qu’aucune erreur ne s’est produite pendant la transmission.
SNMP_ERRORSTATUS_TOOBIG	L’agent n’a pas pu placer les résultats de l’opération SNMP demandée dans un seul message SNMP.
SNMP_ERRORSTATUS_NOSUCHNAME	L’opération SNMP demandée a identifié une variable inconnue.
SNMP_ERRORSTATUS_BADVALUE	L’opération SNMP demandée a tenté de modifier une variable, mais elle a spécifié une erreur de syntaxe ou de valeur.
SNMP_ERRORSTATUS_READONLY	L’opération SNMP demandée a tenté de modifier une variable qui n’était pas autorisée à changer, en fonction du profil de la communauté de la variable.
SNMP_ERRORSTATUS_GENERR	Une erreur autre que l’une de celles répertoriées ici s’est produite pendant l’opération SNMP demandée.
SNMP_ERRORSTATUS_NOACCESS	La variable SNMP spécifiée n’est pas accessible.
SNMP_ERRORSTATUS_WRONGTYPE	La valeur spécifie un type qui n’est pas cohérent avec le type requis pour la variable.
SNMP_ERRORSTATUS_WRONGLENGTH	La valeur spécifie une longueur qui n’est pas cohérente avec la longueur requise pour la variable.
SNMP_ERRORSTATUS_WRONGENCODING	La valeur contient un encodage ASN.1 (Abstract Syntax Notation One) incompatible avec la balise ASN.1 du champ.
SNMP_ERRORSTATUS_WRONGVALUE	La valeur ne peut pas être affectée à la variable.
SNMP_ERRORSTATUS_NOCREATION	La variable n’existe pas et l’agent ne peut pas la créer.
SNMP_ERRORSTATUS_INCONSISTENTVALUE	La valeur est incompatible avec les valeurs d’autres objets managés.
SNMP_ERRORSTATUS_RESOURCEUNAVAILABLE	L’affectation de la valeur à la variable nécessite l’allocation de ressources actuellement indisponibles.
SNMP_ERRORSTATUS_COMMITFAILED	Aucune erreur de validation ne s’est produite, mais aucune variable n’a été mise à jour.
SNMP_ERRORSTATUS_UNDOFAILED	Aucune erreur de validation ne s’est produite. Certaines variables ont été mises à jour, car il n’était pas possible d’annuler leur affectation.
SNMP_ERRORSTATUS_AUTHORIZATIONERROR	Une erreur d’autorisation s’est produite.
SNMP_ERRORSTATUS_NOTWRITABLE	La variable existe, mais l’agent ne peut pas la modifier.
SNMP_ERRORSTATUS_INCONSISTENTNAME	La variable n’existe pas ; l’agent ne peut pas le créer, car l’objet nommé instance est incohérent avec les valeurs d’autres objets managés.

[out] pErrorIndex

Pointeur vers une variable pour recevoir le résultat de l’index d’erreur.

Valeur retournée

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

Si la fonction échoue, la valeur de retour est FALSE.

Remarques

Le service SNMP appelle la fonction SnmpExtensionQueryEx plusieurs fois pour traiter une requête SNMP SET entrante. Le service peut appeler SnmpExtensionQueryEx pendant la phase de demande TEST, la phase de requête COMMIT, la phase de requête UNDO et la phase de requête CLEANUP.

REQUÊTE DE TEST

Le service SNMP traite un type de requête SET SNMP en appelant d’abord la fonction SnmpExtensionQueryEx avec un dwRequestType de SNMP_EXTENSION_SET_TEST. Le service appelle chaque agent d’extension responsable des liaisons de variable dans la requête. Chaque agent d’extension doit valider les variables dans la liste de liaisons de variables. Ils peuvent éventuellement stocker toutes les informations de contexte requises pour les requêtes suivantes dans la variable pointée par le paramètre pContextInfo .

Si la requête TEST échoue, le service lance une requête CLEANUP. Le service appelle à nouveau chaque agent d’extension qui a précédemment retourné TRUE à la requête TEST avec la fonction SnmpExtensionQueryEx . Le service appelle chaque agent d’extension à l’aide du SNMP_EXTENSION_SET_CLEANUP dwRequestType.

Requête COMMIT

Si tous les agents d’extension retournent TRUE à la requête TEST, le service SNMP appelle chaque agent d’extension avec la fonction SnmpExtensionQueryEx , à l’aide de la SNMP_EXTENSION_SET_COMMIT dwRequestType. Le service retourne au contexte de l’agent d’extension les informations que l’agent d’extension a transmises au service. Il s’agit des informations de contexte que l’agent d’extension a transmises dans le paramètre pContextInfo pendant la requête TEST. L’agent d’extension peut utiliser les informations de contexte pour mettre à jour les valeurs des variables spécifiées d’une manière spécifique à l’instrumentation.

Si l’agent d’extension prend en charge le traitement de restauration, il peut mettre à jour les informations de contexte dans le paramètre pContextInfo pour le moment. Le service SNMP transmet les informations à l’agent d’extension pendant la demande UNDO.

Si tous les agents d’extension retournent TRUE à la requête COMMIT, le service appelle chaque agent d’extension avec la fonction SnmpExtensionQueryEx , à l’aide de la SNMP_EXTENSION_SET_CLEANUP dwRequestType.

Si un agent d’extension échoue à la requête COMMIT, le service lance également une demande CLEANUP. Le service appelle à nouveau chaque agent d’extension qui a précédemment retourné TRUE à la requête COMMIT avec la fonction SnmpExtensionQueryEx . Le service appelle chaque agent d’extension à l’aide du SNMP_EXTENSION_SET_CLEANUP dwRequestType.

Demande CLEANUP

Le service retourne à l’agent d’extension les informations de contexte passées dans le paramètre pContextInfo pendant la requête TEST ou COMMIT. L’agent d’extension doit libérer les ressources associées au paramètre à ce stade.

DEMANDE UNDO

Si un agent d’extension retourne FALSE à la requête COMMIT, le service SNMP termine la requête COMMIT. Le service appelle chaque agent d’extension qui a retourné TRUE à la requête COMMIT avec un dwRequestType de SNMP_EXTENSION_SET_UNDO. Cela signale aux agents d’extension que la requête COMMIT a échoué et qu’ils doivent lancer le traitement de restauration.

Les agents d’extension doivent tenter de réinitialiser les valeurs des variables d’intérêt, en rétablissant les valeurs qu’elles étaient avant l’échec de la requête COMMIT. Pour ce faire, les agents d’extension utilisent les informations de contexte retournées dans le paramètre pContextInfo pendant la requête COMMIT.

Si un agent d’extension retourne FALSE à la requête UNDO, l’opération SET entière échoue avec le code d’erreur SNMP_ERRORSTATUS_UNDOFAILED. Si tous les agents d’extension retournent TRUE à la requête UNDO, l’opération SNMP SET échoue avec le code d’erreur défini par l’agent d’extension qui a échoué la requête COMMIT.

Après la demande UNDO, le service appelle toujours chaque agent d’extension avec la fonction SnmpExtensionQueryEx , à l’aide de la SNMP_EXTENSION_SET_CLEANUP dwRequestType.

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]
Plateforme cible	Windows
En-tête	snmp.h