SnmpRegister-Funktion (winsnmp.h)

Artikel
08/27/2023

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

Die WinSNMP SnmpRegister-Funktion registriert oder hebt die Registrierung einer WinSNMP-Anwendung für den Trap- und Benachrichtigungsempfang auf. Die Anwendung kann Traps und Benachrichtigungen registrieren und empfangen oder die Registrierung von Traps und Benachrichtigungen aufheben und deaktivieren.

Eine WinSNMP-Anwendung kann je nach Wert des Benachrichtigungsparameters für einen Trap- oder Benachrichtigungstyp oder für alle Traps und Benachrichtigungen registrieren oder die Registrierung aufheben.

Syntax

SNMPAPI_STATUS SNMPAPI_CALL SnmpRegister(
  [in] HSNMP_SESSION session,
  [in] HSNMP_ENTITY  srcEntity,
  [in] HSNMP_ENTITY  dstEntity,
  [in] HSNMP_CONTEXT context,
  [in] smiLPCOID     notification,
  [in] smiUINT32     state
);

Parameter

[in] session

Behandeln Sie die WinSNMP-Sitzung, bei der die Registrierung für Traps und Benachrichtigungen registriert oder aufgehoben wird.

[in] srcEntity

Behandeln Sie die Verwaltungsentität, die die Quelle der Registrierungsanforderung ist. Diese Entität, die in einer SNMP-Managerrolle agiert, empfängt die Trap oder Benachrichtigung.

Da die Implementierung diesen Parameter nicht verwendet, um Traps und Benachrichtigungen beim Erreichen der WinSNMP-Anwendung zu filtern, übergibt eine WinSNMP-Manager-Anwendung normalerweise NULL in diesem Parameter.

Wenn dieser Parameter NULL ist, registriert oder hebt die Microsoft WinSNMP-Implementierung alle Quellen von Trap- und Benachrichtigungsanforderungen auf.

Beachten Sie, dass der srcEntity-Parameter der SnmpRecvMsg-Funktion eine andere Rolle hat. In dieser Funktion empfängt srcEntity ein Handle an die Entität, die die Trap gesendet hat.

[in] dstEntity

Behandeln Sie die Verwaltungsentität, die der Empfänger der Registrierungsanforderung ist. Diese Entität, die in einer SNMP-Agentrolle agiert, sendet die Trap oder Benachrichtigung.

Wenn dieser Parameter NULL ist, registriert oder hebt die Implementierung die Registrierung der WinSNMP-Anwendung für Traps und Benachrichtigungen von allen Verwaltungsentitäten auf.

Beachten Sie, dass der dstEntity-Parameter für die SnmpRecvMsg-Funktion ein Handle für die Verwaltungsentität empfängt, die sich für trap-Benachrichtigungen registriert.

[in] context

Handle mit dem Kontext, bei dem es sich um eine Gruppe von Ressourcen für verwaltete Objekte handelt.

Wenn dieser Parameter NULL ist, registriert oder hebt die Implementierung die Registrierung der WinSNMP-Anwendung für Traps und Benachrichtigungen für jeden Kontext auf.

[in] notification

Zeiger auf eine smiOID-Struktur , die die Musterabgleichssequenz für einen Trap- oder Benachrichtigungstyp enthält. Die Implementierung verwendet diese Sequenz, um den Typ der Trap oder Benachrichtigung zu identifizieren, für die die WinSNMP-Anwendung die Registrierung registriert oder auf hebt. Weitere Informationen finden Sie im abschnitt "Hinweise".

Wenn dieser Parameter NULL ist, registriert oder hebt die Implementierung die Registrierung der WinSNMP-Anwendung für alle Traps und Benachrichtigungen der Verwaltungsentität oder Entitäten auf, die durch den dstEntity-Parameter angegeben werden.

[in] state

Gibt eine variable lange Ganzzahl ohne Vorzeichen an, die angibt, ob die WinSNMP-Anwendung registriert wird, um Traps und Benachrichtigungen zu empfangen oder die Registrierung aufzuheben. Dieser Parameter sollte einem der folgenden Werte entsprechen, aber wenn er einen anderen Wert enthält, registriert die Implementierung die Anwendung.

Wert	Bedeutung
SNMPAPI_OFF	Deaktivieren Sie Traps und Benachrichtigungen.
SNMPAPI_ON	Registrieren Sie sich, um Traps und Benachrichtigungen zu empfangen.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert SNMPAPI_SUCCESS.

Wenn die Funktion fehlschlägt, wird der Rückgabewert SNMPAPI_FAILURE. Rufen Sie SnmpGetLastError auf, um erweiterte Fehlerinformationen zu erhalten. Die SnmpGetLastError-Funktion gibt möglicherweise einen der folgenden WinSNMP- oder Netzwerktransportebenenfehler zurück.

Rückgabecode	Beschreibung
SNMPAPI_NOT_INITIALIZED	Die SnmpStartup-Funktion wurde nicht erfolgreich abgeschlossen.
SNMPAPI_ALLOC_ERROR	Während der Speicherzuordnung ist ein Fehler aufgetreten.
SNMPAPI_SESSION_INVALID	Der Sitzungsparameter ist ungültig.
SNMPAPI_ENTITY_INVALID	Ein oder beide Entitätsparameter sind ungültig.
SNMPAPI_CONTEXT_INVALID	Der Kontextparameter ist ungültig.
SNMPAPI_OID_INVALID	Der Benachrichtigungsparameter ist ungültig.
SNMPAPI_TL_NOT_INITIALIZED	Die Netzwerktransportschicht wurde nicht initialisiert, oder der SNMPTRAP.EXE-Dienst konnte nicht gestartet werden.
SNMPAPI_TL_IN_USE	Der Trapport ist nicht verfügbar.
SNMPAPI_TL_NOT_AVAILABLE	Fehler beim Netzwerksubsystem.
SNMPAPI_OTHER_ERROR	Ein unbekannter oder nicht definierter Fehler ist aufgetreten.

Weitere Informationen finden Sie unter Fehler beim Netzwerktransport.

Hinweise

In der Regel ruft eine WinSNMP-Manager-Anwendung anstelle einer Agentanwendung die SnmpRegister-Funktion auf.

Es ist wichtig zu beachten, dass für Benutzer, die keine Administratoren sind, die SnmpRegister-Funktion unter Windows 2000 und Windows XP nur erfolgreich ist, wenn der SNMP-Trap-Dienst gestartet wurde.

Wenn eine WinSNMP-Anwendung NULL in einem Aufruf der SnmpRegister-Funktion in den srcEntity-, dstEntity-, Kontext- oder Benachrichtigungsparametern übergibt, verwendet die Implementierung diesen Parameter nicht zum Filtern von Traps und Benachrichtigungen, die die WinSNMP-Anwendung erreichen. Wenn eine Anwendung NULL in allen zuvor erwähnten Parametern übergibt, sendet die Implementierung alle empfangenen Benachrichtigungen an die Sitzung.

Wenn eine WinSNMP-Anwendung registriert wird, um einen bestimmten Typ von Trap oder Benachrichtigung zu empfangen, muss sie einen Objektbezeichner definieren, d. h. eine smiOID-Struktur , die diesem Traptyp entspricht. Der Benachrichtigungsparameter muss auf diese Struktur verweisen. RFC 1907, "Management Information Base for Version 2 of the Simple Network Management Protocol (SNMPv2)," definiert Trap- und Benachrichtigungsobjektbezeichner. Weitere Informationen finden Sie unter Verwalten von Traps und Benachrichtigungen und Übersetzen von Traps von SNMPv1 in SNMPv2C.

Die Implementierung verwendet den Wert des Benachrichtigungsparameters als Muster, um mit empfangenen Traps und Benachrichtigungen abzugleichen. Wenn die WinSNMP-Anwendung beispielsweise n Anzahl von Unteridentifizierern im Benachrichtigungsparameter übergibt und die ersten n Unteridentifizierer in einer empfangenen Trap mit allen übergebenen Unteridentifizierern übereinstimmen, ist der Trap-Objektbezeichner eine Übereinstimmung. Wenn eine empfangene Trap weniger Unteridentifizierer als n aufweist, stimmt der Objektbezeichner nicht überein. Wenn eine Übereinstimmung vorliegt, sendet die Implementierung die Trap oder Benachrichtigung an die WinSNMP-Anwendung.

Wenn ein oder alle dstEntity-, srcEntity- oder KontextparameterNULL sind, muss die Implementierung möglicherweise Ressourcen bei einem nachfolgenden Aufruf der SnmpRecvMsg-Funktion für die entsprechenden Parameter dieser Funktion zuweisen. Wenn die WinSNMP-Anwendung die von SnmpRecvMsg zurückgegebenen Ressourcen nicht mehr benötigt, muss die Anwendung die einzelnen Ressourcen mit der Funktion freigeben, die der Ressource entspricht. Weitere Informationen finden Sie unter SnmpFreeEntity und SnmpFreeContext.

Weitere Informationen finden Sie unter Mehrere Trap-Registrierungen.

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	winsnmp.h
Bibliothek	Wsnmp32.lib
DLL	Wsnmp32.dll