Funzione SnmpCreateSession (winsnmp.h)

Articolo
08/27/2023

[SNMP è disponibile per l'uso nei sistemi operativi specificati nella sezione Requisiti. È possibile che in versioni successive sia stata modificata o non sia più disponibile. Usare invece Gestione remota Windows, ovvero l'implementazione Microsoft di WS-Man.

La funzione SnmpCreateSession richiede l'implementazione di Microsoft WinSNMP per aprire una sessione per l'applicazione WinSNMP. L'applicazione può specificare in che modo l'implementazione deve informare la sessione WinSNMP dei messaggi SNMP disponibili e degli eventi asincroni. L'applicazione può specificare un messaggio di notifica della finestra o una funzione SNMPAPI_CALLBACK per notificare la sessione.

La funzione SnmpCreateSession è un elemento dell'API WinSNMP, versione 2.0. Quando si sviluppano nuove applicazioni WinSNMP, è consigliabile chiamare SnmpCreateSession per aprire una sessione WinSNMP anziché chiamare la funzione SnmpOpen .

Sintassi

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

Parametri

[in] hWnd

Gestire una finestra dell'applicazione WinSNMP per notificare quando viene completata una richiesta asincrona o quando si verifica una notifica trap. Questo parametro è necessario per i messaggi di notifica della finestra per la sessione.

[in] wMsg

Specifica un intero senza segno che identifica il messaggio di notifica da inviare alla finestra dell'applicazione WinSNMP. Questo parametro è necessario per i messaggi di notifica della finestra per la sessione.

[in] fCallBack

Specifica l'indirizzo di una funzione di SNMPAPI_CALLBACK specifica della sessione definita dall'applicazione. L'implementazione chiamerà questa funzione per informare la sessione WinSNMP quando sono disponibili le notifiche.

Questo parametro è necessario per specificare le notifiche di callback per la sessione. Questo parametro deve essere NULL per specificare i messaggi di notifica della finestra per la sessione. Per altre informazioni, vedere la sezione Osservazioni seguenti.

[in] lpClientData

Puntatore ai dati definiti dall'applicazione da passare alla funzione di callback specificata dal parametro fCallback . Questo parametro è facoltativo e può essere NULL. Se il parametro fCallback è NULL, l'implementazione ignora questo parametro.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è un handle che identifica la sessione WinSNMP aperta dall'implementazione per l'applicazione chiamante.

Se la funzione ha esito negativo, il valore restituito è SNMPAPI_FAILURE. Per ottenere informazioni sull'errore estese, chiamare SnmpGetLastError. La funzione SnmpGetLastError può restituire uno degli errori seguenti.

Codice restituito	Descrizione
SNMPAPI_NOT_INITIALIZED	La funzione SnmpStartup non è stata completata correttamente.
SNMPAPI_ALLOC_ERROR	Errore durante l'allocazione della memoria.
SNMPAPI_HWND_INVALID	Il parametro fCallback è NULL, ma il parametro hWnd non è un handle di finestra valido.
SNMPAPI_MESSAGE_INVALID	Il parametro fCallback è NULL, ma il parametro wMsg non è un valore di messaggio valido.
SNMPAPI_MODE_INVALID	Il parametro fCallback è NULL e i parametri hWnd e wMsg sono validi singolarmente. Tuttavia, i valori sono reciprocamente incompatibili nella piattaforma Windows.
SNMPAPI_OPERATION_INVALID	La combinazione di valori dei parametri non specifica le notifiche di callback o i messaggi di notifica delle finestre.
SNMPAPI_OTHER_ERROR	Si è verificato un errore sconosciuto o non definito.

Commenti

La funzione SnmpCreateSession restituisce un handle univoco per ogni sessione WinSNMP aperta all'interno dell'applicazione WinSNMP chiamante. L'applicazione deve usare l'handle di sessione restituito da SnmpCreateSession in altre chiamate di funzione WinSNMP per facilitare l'allocazione e la deallocazione delle risorse dall'implementazione.

È consigliabile che un'applicazione WinSNMP chiami la funzione SnmpClose una volta per ogni sessione aperta dall'implementazione come risultato di una chiamata alla funzione SnmpCreateSession . Se un'applicazione WinSNMP termina in modo imprevisto, deve chiamare SnmpCleanup prima che venga terminata per abilitare l'implementazione per deallocare tutte le risorse.

Notifiche di callback

Se il parametro fCallback non è NULL in una chiamata corretta alla funzione SnmpCreateSession , l'implementazione avvisa la sessione alle notifiche usando la funzione di callback specificata dal parametro fCallback .

Di seguito è riportato un esempio di una chiamata alla funzione SnmpCreateSession , richiedendo che l'implementazione segnali la sessione sui messaggi ed eventi usando le notifiche di callback.

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

Messaggi di notifica finestra

La funzione SnmpCreateSession passa all'implementazione dell'handle in una finestra dell'applicazione e a un identificatore di messaggio di notifica. Quando la finestra dell'applicazione riceve il messaggio di notifica specificato dal parametro wMsg , l'applicazione WinSNMP deve recuperare l'unità dati del protocollo in ingresso (PDU). L'applicazione esegue questa operazione chiamando la funzione SnmpRecvMsg con l'handle di sessione restituito da SnmpCreateSession.

Un'applicazione WinSNMP può aprire più sessioni WinSNMP. Se un'applicazione apre più sessioni usando lo stesso handle di finestra, è consigliabile che l'applicazione WinSNMP specifichi un parametro wMsg univoco per ogni sessione.

Di seguito è riportato un esempio di chiamata alla funzione SnmpCreateSession , richiedendo che l'implementazione segnali la sessione sui messaggi ed eventi usando i messaggi di notifica della finestra.

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

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winsnmp.h
Libreria	Wsnmp32.lib
DLL	Wsnmp32.dll