SnmpExtensionQueryEx-Funktion (snmp.h)

Artikel
08/26/2023

[SNMP ist für die Verwendung in den im Abschnitt Anforderungen angegebenen Betriebssystemen verfügbar. Es kann in nachfolgenden Versionen geändert oder entfernt werden. Verwenden Sie stattdessen die Windows-Remoteverwaltung, die Microsoft-Implementierung von WS-Man.]

Der Microsoft SNMP-Dienst ruft die SnmpExtensionQueryEx-Funktion auf, um SNMP-Anforderungen zu verarbeiten, die Variablen in einer oder mehreren MIB-Unterstrukturen angeben, die von SNMP-Erweiterungs-Agents registriert sind. Diese Funktion ist ein Element der SNMP-Erweiterungs-Agent-API.

Hinweis Es wird empfohlen, die SnmpExtensionQueryExEx-Funktion zu verwenden, die SNMP-Datentypen der Version 2C (SNMPv2C) und mehrstufige SNMP-SET-Vorgänge unterstützt. Der SNMP-Dienst ruft die SnmpExtensionQuery-Funktion nicht auf, wenn der Erweiterungs-Agent die SnmpExtensionQueryEx-Funktion exportiert.

Syntax

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
);

Parameter

[in] nRequestType

Gibt den Typ des Vorgangs an, zu dem der SNMP-Dienst den Erweiterungs-Agent anfordert. Dieser Parameter kann einen der folgenden Werte annehmen.

Wert	Bedeutung
SNMP_EXTENSION_GET	Rufen Sie den Wert oder die Werte der angegebenen Variablen ab.
SNMP_EXTENSION_GET_NEXT	Rufen Sie den Wert oder die Werte des lexikografischen Nachfolgers der angegebenen Variablen ab.
SNMP_EXTENSION_SET_TEST	Überprüfen Sie die Werte der angegebenen Variablen. Dieser Vorgang maximiert die Wahrscheinlichkeit eines erfolgreichen Schreibvorgangs während der COMMIT-Anforderung.
SNMP_EXTENSION_SET_COMMIT	Schreiben Sie die neuen Werte in die angegebenen Variablen.
SNMP_EXTENSION_SET_UNDO	Setzen Sie die Werte der angegebenen Variablen vor der COMMIT-Anforderung auf ihre Werte zurück.
SNMP_EXTENSION_SET_CLEANUP	Geben Sie die Ressourcen frei, die in früheren Anforderungen und Vorgängen zugeordnet wurden.

Weitere Informationen zu den SET-Anforderungstypen, d. h. zu denen, die mit SNMP_EXTENSION_SET_ beginnen, finden Sie im folgenden Abschnitt Hinweise.

[in] nTransactionId

Gibt eine DWORD-Variable an, die den eindeutigen Bezeichner der eingehenden SNMP-Anforderungs-PDU darstellt. Der Erweiterungs-Agent kann diesen Wert verwenden, um mehrere Aufrufe des SNMP-Diensts zu korrelieren, die dieselbe PDU umfassen.

[in, out] pVarBindList

Zeiger auf die Variablenbindungsliste, die die relevanten Variablen enthält.

[in, out] pContextInfo

Zeiger auf eine Oktettzeichenfolge, die benutzerdefinierte Kontextinformationen enthält.

Der Erweiterungs-Agent kann diesen Parameter verwenden, um Kontextinformationen zu speichern, die bei mehrstufigen SNMP-SET-Vorgängen verwendet werden. Der Erweiterungs-Agent muss ressourcen freigeben, die diesem Parameter während der CLEANUP-Anforderung zugeordnet sind. Der SNMP-Dienst gibt keine Ressourcen frei, die diesem Parameter zugeordnet sind. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[out] pErrorStatus

Zeiger auf eine Variable, um den Fehler status Ergebnis zu erhalten. Dieser Parameter kann einer der folgenden Werte sein, die von SNMPv2C definiert werden.

Fehlercode	Bedeutung
SNMP_ERRORSTATUS_NOERROR	Der Agent meldet, dass während der Übertragung keine Fehler aufgetreten sind.
SNMP_ERRORSTATUS_TOOBIG	Der Agent konnte die Ergebnisse des angeforderten SNMP-Vorgangs nicht in einer einzelnen SNMP-Nachricht platzieren.
SNMP_ERRORSTATUS_NOSUCHNAME	Der angeforderte SNMP-Vorgang identifizierte eine unbekannte Variable.
SNMP_ERRORSTATUS_BADVALUE	Der angeforderte SNMP-Vorgang hat versucht, eine Variable zu ändern, aber er hat entweder einen Syntax- oder Wertfehler angegeben.
SNMP_ERRORSTATUS_READONLY	Der angeforderte SNMP-Vorgang hat versucht, eine Variable zu ändern, die gemäß dem Communityprofil der Variablen nicht geändert werden durfte.
SNMP_ERRORSTATUS_GENERR	Während des angeforderten SNMP-Vorgangs ist ein anderer Fehler als einer der hier aufgeführten aufgetreten.
SNMP_ERRORSTATUS_NOACCESS	Auf die angegebene SNMP-Variable kann nicht zugegriffen werden.
SNMP_ERRORSTATUS_WRONGTYPE	Der -Wert gibt einen Typ an, der mit dem für die Variable erforderlichen Typ inkonsistent ist.
SNMP_ERRORSTATUS_WRONGLENGTH	Der -Wert gibt eine Länge an, die mit der für die Variable erforderlichen Länge inkonsistent ist.
SNMP_ERRORSTATUS_WRONGENCODING	Der Wert enthält eine ASN.1-Codierung (Abstract Syntax Notation One), die mit dem ASN.1-Tag des Felds inkonsistent ist.
SNMP_ERRORSTATUS_WRONGVALUE	Der Wert kann der Variablen nicht zugewiesen werden.
SNMP_ERRORSTATUS_NOCREATION	Die Variable ist nicht vorhanden, und der Agent kann sie nicht erstellen.
SNMP_ERRORSTATUS_INCONSISTENTVALUE	Der Wert ist mit Werten anderer verwalteter Objekte inkonsistent.
SNMP_ERRORSTATUS_RESOURCEUNAVAILABLE	Das Zuweisen des Werts zur Variablen erfordert die Zuordnung von Ressourcen, die derzeit nicht verfügbar sind.
SNMP_ERRORSTATUS_COMMITFAILED	Es sind keine Validierungsfehler aufgetreten, aber es wurden keine Variablen aktualisiert.
SNMP_ERRORSTATUS_UNDOFAILED	Es sind keine Validierungsfehler aufgetreten. Einige Variablen wurden aktualisiert, da es nicht möglich war, ihre Zuweisung rückgängig zu machen.
SNMP_ERRORSTATUS_AUTHORIZATIONERROR	Ein Autorisierungsfehler ist aufgetreten.
SNMP_ERRORSTATUS_NOTWRITABLE	Die Variable ist vorhanden, aber der Agent kann sie nicht ändern.
SNMP_ERRORSTATUS_INCONSISTENTNAME	Die Variable ist nicht vorhanden. Der Agent kann es nicht erstellen, weil das benannte Objekt instance mit den Werten anderer verwalteter Objekte nicht übereinstimmt.

[out] pErrorIndex

Zeiger auf eine Variable zum Empfangen des Fehlerindexergebnisses.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert TRUE.

Wenn die Funktion fehlschlägt, ist der Rückgabewert FALSE.

Hinweise

Der SNMP-Dienst ruft die SnmpExtensionQueryEx-Funktion mehrmals auf, um eine eingehende SNMP SET-Anforderung zu verarbeiten. Der Dienst kann SnmpExtensionQueryExex während der TEST-Anforderungsphase, der COMMIT-Anforderungsphase, der UNDO-Anforderungsphase und der CLEANUP-Anforderungsphase aufrufen.

TEST-Anforderung

Der SNMP-Dienst verarbeitet einen SNMP SET-Anforderungstyp, indem er zuerst die SnmpExtensionQueryEx-Funktion mit einem dwRequestType-Wert von SNMP_EXTENSION_SET_TEST aufruft. Der Dienst ruft jeden Erweiterungs-Agent auf, der für die Variablenbindungen in der Anforderung verantwortlich ist. Jeder Erweiterungs-Agent muss die Variablen in der Variablenbindungsliste überprüfen. Sie können optional alle Kontextinformationen speichern, die für die folgenden Anforderungen in der Variablen erforderlich sind, auf die der Parameter pContextInfo verweist.

Wenn die TEST-Anforderung fehlschlägt, initiiert der Dienst eine CLEANUP-Anforderung. Der Dienst ruft jeden Erweiterungs-Agent, der zuvor TRUE an die TEST-Anforderung zurückgegeben hat, erneut mit der SnmpExtensionQueryEx-Funktion auf. Der Dienst ruft jeden Erweiterungs-Agent mithilfe des SNMP_EXTENSION_SET_CLEANUP dwRequestType auf.

COMMIT-Anforderung

Wenn alle Erweiterungs-Agents TRUE an die TEST-Anforderung zurückgeben, ruft der SNMP-Dienst jeden Erweiterungs-Agent mit der SnmpExtensionQueryEx-Funktion unter Verwendung des SNMP_EXTENSION_SET_COMMIT dwRequestType auf. Der Dienst kehrt an die Kontextinformationen des Erweiterungs-Agents zurück, die der Erweiterungs-Agent an den Dienst übergeben hat. Dies sind die Kontextinformationen, die der Erweiterungs-Agent im pContextInfo-Parameter während der TEST-Anforderung übergeben hat. Der Erweiterungs-Agent kann die Kontextinformationen verwenden, um die Werte der angegebenen Variablen auf instrumentsspezifische Weise zu aktualisieren.

Wenn der Erweiterungs-Agent die Rollbackverarbeitung unterstützt, kann er die Kontextinformationen im pContextInfo-Parameter zu diesem Zeitpunkt aktualisieren. Der SNMP-Dienst übergibt die Informationen während der UNDO-Anforderung an den Erweiterungs-Agent.

Wenn alle Erweiterungs-Agents TRUE an die COMMIT-Anforderung zurückgeben, ruft der Dienst jeden Erweiterungs-Agent mit der SnmpExtensionQueryEx-Funktion unter Verwendung des SNMP_EXTENSION_SET_CLEANUP dwRequestType auf.

Wenn ein Erweiterungs-Agent die COMMIT-Anforderung fehlschlägt, initiiert der Dienst auch eine CLEANUP-Anforderung. Der Dienst ruft jeden Erweiterungs-Agent, der zuvor TRUE an die COMMIT-Anforderung zurückgegeben hat, erneut mit der SnmpExtensionQueryEx-Funktion auf. Der Dienst ruft jeden Erweiterungs-Agent mithilfe des SNMP_EXTENSION_SET_CLEANUP dwRequestType auf.

CLEANUP-Anforderung

Der Dienst gibt die Kontextinformationen, die während der TEST- oder COMMIT-Anforderung im pContextInfo-Parameter übergeben wurden, an den Erweiterungs-Agent zurück. Der Erweiterungs-Agent muss die dem Parameter zugeordneten Ressourcen zu diesem Zeitpunkt freigeben.

UNDO-Anforderung

Wenn ein Erweiterungs-Agent FALSE an die COMMIT-Anforderung zurückgibt, beendet der SNMP-Dienst die COMMIT-Anforderung. Der Dienst ruft jeden Erweiterungs-Agent, der TRUE an die COMMIT-Anforderung zurückgegeben hat, mit einem dwRequestType-Wert von SNMP_EXTENSION_SET_UNDO auf. Dies signalisiert den Erweiterungs-Agents, dass bei der COMMIT-Anforderung ein Fehler aufgetreten ist, und sie müssen die Rollbackverarbeitung initiieren.

Die Erweiterungs-Agents müssen versuchen, die Werte der relevanten Variablen auf die Werte zurückzusetzen, die sie vor dem Fehler bei der COMMIT-Anforderung waren. Dazu verwenden die Erweiterungs-Agents die Kontextinformationen, die im pContextInfo-Parameter während der COMMIT-Anforderung zurückgegeben wurden.

Wenn ein Erweiterungs-Agent FALSE an die UNDO-Anforderung zurückgibt, schlägt der gesamte SET-Vorgang mit dem Fehlercode SNMP_ERRORSTATUS_UNDOFAILED fehl. Wenn alle Erweiterungs-Agents TRUE an die UNDO-Anforderung zurückgeben, schlägt der SNMP SET-Vorgang mit dem Fehlercode fehl, der vom Erweiterungs-Agent festgelegt wurde, der die COMMIT-Anforderung fehlgeschlagen hat.

Nach der UNDO-Anforderung ruft der Dienst immer jeden Erweiterungs-Agent mit der SnmpExtensionQueryEx-Funktion auf, wobei der SNMP_EXTENSION_SET_CLEANUP dwRequestType verwendet wird.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	snmp.h