SnmpCreateSession-Funktion (winsnmp.h)

Artikel
08/27/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.]

Die SnmpCreateSession-Funktion fordert die Microsoft WinSNMP-Implementierung an, eine Sitzung für die WinSNMP-Anwendung zu öffnen. Die Anwendung kann angeben, wie die Implementierung die WinSNMP-Sitzung über verfügbare SNMP-Nachrichten und asynchrone Ereignisse informieren soll. Die Anwendung kann eine Fensterbenachrichtigung oder eine SNMPAPI_CALLBACK-Funktion angeben, um die Sitzung zu benachrichtigen.

Die SnmpCreateSession-Funktion ist ein Element der WinSNMP-API, Version 2.0. Beim Entwickeln neuer WinSNMP-Anwendungen wird empfohlen, SnmpCreateSession aufzurufen, um eine WinSNMP-Sitzung zu öffnen, anstatt die SnmpOpen-Funktion aufzurufen.

Syntax

HSNMP_SESSION SNMPAPI_CALL SnmpCreateSession(
  [in] HWND             hWnd,
  [in] UINT             wMsg,
  [in] SNMPAPI_CALLBACK fCallBack,
  [in] LPVOID           lpClientData
);

Parameter

[in] hWnd

Behandeln Sie ein Fenster der WinSNMP-Anwendung, um zu benachrichtigen, wenn eine asynchrone Anforderung abgeschlossen ist oder wenn eine Trapbenachrichtigung auftritt. Dieser Parameter ist für Fensterbenachrichtigungen für die Sitzung erforderlich.

[in] wMsg

Gibt eine ganze Zahl ohne Vorzeichen an, die die Benachrichtigung identifiziert, die an das WinSNMP-Anwendungsfenster gesendet werden soll. Dieser Parameter ist für Fensterbenachrichtigungen für die Sitzung erforderlich.

[in] fCallBack

Gibt die Adresse einer anwendungsdefinierten sitzungsspezifischen SNMPAPI_CALLBACK-Funktion an. Die Implementierung ruft diese Funktion auf, um die WinSNMP-Sitzung zu informieren, wenn Benachrichtigungen verfügbar sind.

Dieser Parameter ist erforderlich, um Rückrufbenachrichtigungen für die Sitzung anzugeben. Dieser Parameter muss NULL sein, um Fensterbenachrichtigungen für die Sitzung anzugeben. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in] lpClientData

Zeiger auf anwendungsdefinierte Daten, die an die vom fCallback-Parameter angegebene Rückruffunktion übergeben werden sollen. Dieser Parameter ist optional und kann NULL sein. Wenn der fCallback-ParameterNULL ist, ignoriert die Implementierung diesen Parameter.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Handle, das die WinSNMP-Sitzung identifiziert, die die Implementierung für die aufrufende Anwendung öffnet.

Wenn die Funktion fehlschlägt, wird der Rückgabewert SNMPAPI_FAILURE. Rufen Sie SnmpGetLastError auf, um erweiterte Fehlerinformationen zu erhalten. Die SnmpGetLastError-Funktion kann einen der folgenden Fehler zurückgeben.

Rückgabecode	Beschreibung
SNMPAPI_NOT_INITIALIZED	Die SnmpStartup-Funktion wurde nicht erfolgreich abgeschlossen.
SNMPAPI_ALLOC_ERROR	Während der Speicherbelegung ist ein Fehler aufgetreten.
SNMPAPI_HWND_INVALID	Der fCallback-Parameter ist NULL, aber der hWnd-Parameter ist kein gültiges Fensterhandle.
SNMPAPI_MESSAGE_INVALID	Der fCallback-Parameter ist NULL, aber der wMsg-Parameter ist kein gültiger Nachrichtenwert.
SNMPAPI_MODE_INVALID	Der fCallback-Parameter ist NULL , und die Parameter hWnd und wMsg sind einzeln gültig. Die Werte sind jedoch auf der Windows-Plattform gegenseitig inkompatibel.
SNMPAPI_OPERATION_INVALID	Die Kombination von Parameterwerten gibt keine Rückrufbenachrichtigungen oder Fensterbenachrichtigungen an.
SNMPAPI_OTHER_ERROR	Es ist ein unbekannter oder nicht definierter Fehler aufgetreten.

Hinweise

Die SnmpCreateSession-Funktion gibt ein eindeutiges Handle für jede geöffnete WinSNMP-Sitzung in der aufrufenden WinSNMP-Anwendung zurück. Die Anwendung muss das Sitzungshandle verwenden, das SnmpCreateSession in anderen WinSNMP-Funktionsaufrufen zurückgibt, um die Zuordnung und Aufhebung der Zuordnung von Ressourcen durch die Implementierung zu erleichtern.

Es wird empfohlen, dass eine WinSNMP-Anwendung die SnmpClose-Funktion einmal für jede Sitzung aufruft, die die Implementierung als Ergebnis eines Aufrufs der SnmpCreateSession-Funktion öffnet. Wenn eine WinSNMP-Anwendung unerwartet beendet wird, muss sie SnmpCleanup aufrufen, bevor sie beendet wird, damit die Implementierung die Zuordnung aller Ressourcen aufheben kann.

Rückrufbenachrichtigungen

Wenn der fCallback-Parameter bei einem erfolgreichen Aufruf der SnmpCreateSession-Funktion nicht NULL ist, benachrichtigt die Implementierung die Sitzung mit der rückruffunktion, die vom fCallback-Parameter angegeben wird.

Im Folgenden finden Sie ein Beispiel für einen Aufruf der SnmpCreateSession-Funktion , bei dem angefordert wird, dass die Implementierung die Sitzung über Nachrichten und Ereignisse mithilfe von Rückrufbenachrichtigungen signalisiert.

hSession = SnmpCreateSession (0, 0, myFunc, <NULL|myData>);

Fensterbenachrichtigungen

Die SnmpCreateSession-Funktion übergibt an die Implementierung das Handle an ein Anwendungsfenster und einen Benachrichtigungsbezeichner. Wenn das Anwendungsfenster die durch den wMsg-Parameter angegebene Benachrichtigung empfängt, muss die WinSNMP-Anwendung die eingehende Protokolldateneinheit (PDU) abrufen. Die Anwendung ruft dazu die SnmpRecvMsg-Funktion mit dem von SnmpCreateSession zurückgegebenen Sitzungshandle auf.

Eine WinSNMP-Anwendung kann mehrere WinSNMP-Sitzungen öffnen. Wenn eine Anwendung mehrere Sitzungen mit demselben Fensterhandle öffnet, wird empfohlen, dass die WinSNMP-Anwendung einen eindeutigen wMsg-Parameter für jede Sitzung angibt.

Im Folgenden finden Sie ein Beispiel für einen Aufruf der SnmpCreateSession-Funktion , in der angefordert wird, dass die Implementierung die Sitzung über Nachrichten und Ereignisse mithilfe von Fensterbenachrichtigungen signalisiert.

hSession = SnmpCreateSession (myWnd, myMsg, NULL, NULL);

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