Funzione SnmpRegister (winsnmp.h)

Articolo
03/04/2024

[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 SnmpRegister WinSNMP registra o annulla la registrazione di un'applicazione WinSNMP per la ricezione di trap e notifiche. L'applicazione può registrare e ricevere trap e notifiche oppure annullare la registrazione e disabilitare trap e notifiche.

Un'applicazione WinSNMP può registrare o annullare la registrazione per un tipo di trap o notifica oppure per tutte le trap e le notifiche, a seconda del valore del parametro di notifica .

Sintassi

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

Parametri

[in] session

Gestire la sessione WinSNMP che sta registrando o annullando la registrazione per trap e notifiche.

[in] srcEntity

Gestire l'entità di gestione che rappresenta l'origine della richiesta di registrazione. Questa entità, che agisce in un ruolo di gestione SNMP, riceverà la notifica o la trap.

Poiché l'implementazione non usa questo parametro per filtrare le trap e le notifiche dal raggiungimento dell'applicazione WinSNMP, un'applicazione di gestione WinSNMP passa in genere NULL in questo parametro.

Se questo parametro è NULL, l'implementazione di Microsoft WinSNMP registra o annulla la registrazione di tutte le origini di richieste trap e di notifica.

Si noti che il parametro srcEntity per la funzione SnmpRecvMsg ha un ruolo diverso. In tale funzione , srcEntity riceve un handle per l'entità che ha inviato la trap.

[in] dstEntity

Gestire l'entità di gestione che è il destinatario della richiesta di registrazione. Questa entità, che agisce in un ruolo agente SNMP, invierà la notifica o la trap.

Se questo parametro è NULL, l'implementazione registra o annulla la registrazione dell'applicazione WinSNMP per trap e notifiche da tutte le entità di gestione.

Si noti che il parametro dstEntity per la funzione SnmpRecvMsg riceve un handle per l'entità di gestione che esegue la registrazione per la notifica trap.

[in] context

Gestire nel contesto, ovvero un set di risorse dell'oggetto gestito.

Se questo parametro è NULL, l'implementazione registra o annulla la registrazione dell'applicazione WinSNMP per trap e notifiche per ogni contesto.

[in] notification

Puntatore a una struttura smiOID che contiene la sequenza di corrispondenza dei criteri per un tipo di trap o notifica. L'implementazione usa questa sequenza per identificare il tipo di trap o notifica per cui l'applicazione WinSNMP sta registrando o annullando la registrazione. Per altre informazioni, vedere la sezione Osservazioni seguente.

Se questo parametro è NULL, l'implementazione registra o annulla la registrazione dell'applicazione WinSNMP per tutte le trap e le notifiche dall'entità di gestione o dalle entità specificate dal parametro dstEntity .

[in] state

Specifica una variabile long integer senza segno che indica se l'applicazione WinSNMP sta registrando per ricevere trap e notifiche o se è stata annullata la registrazione. Questo parametro deve essere uguale a uno dei valori seguenti, ma se contiene un valore diverso, l'implementazione registra l'applicazione.

Valore	Significato
SNMPAPI_OFF	Disabilitare le trap e le notifiche.
SNMPAPI_ON	Registrarsi per ricevere trap e notifiche.

Valore restituito

Se la funzione ha esito positivo, il valore restituito viene SNMPAPI_SUCCESS.

Se la funzione ha esito negativo, il valore restituito viene SNMPAPI_FAILURE. Per ottenere informazioni estese sull'errore, chiamare SnmpGetLastError. La funzione SnmpGetLastError può restituire uno dei seguenti errori del livello di trasporto di rete o WinSNMP.

Codice restituito	Descrizione
SNMPAPI_NOT_INITIALIZED	La funzione SnmpStartup non è stata completata correttamente.
SNMPAPI_ALLOC_ERROR	Errore durante l'allocazione della memoria.
SNMPAPI_SESSION_INVALID	Il parametro di sessione non è valido.
SNMPAPI_ENTITY_INVALID	Uno o entrambi i parametri dell'entità non sono validi.
SNMPAPI_CONTEXT_INVALID	Il parametro di contesto non è valido.
SNMPAPI_OID_INVALID	Il parametro di notifica non è valido.
SNMPAPI_TL_NOT_INITIALIZED	Il livello trasporto di rete non è stato inizializzato oppure non è stato possibile avviare il servizio SNMPTRAP.EXE.
SNMPAPI_TL_IN_USE	La porta trap non è disponibile.
SNMPAPI_TL_NOT_AVAILABLE	Il sottosistema di rete non è riuscito.
SNMPAPI_OTHER_ERROR	Si è verificato un errore sconosciuto o non definito.

Per altre informazioni, vedere Errori di trasporto di rete.

Commenti

In genere un'applicazione di gestione WinSNMP, anziché un'applicazione agente, chiama la funzione SnmpRegister .

È importante notare che per gli utenti che non sono amministratori, la funzione SnmpRegister ha esito positivo in Windows 2000 e Windows XP solo se è stato avviato il servizio trap SNMP.

Se un'applicazione WinSNMP passa NULL in una chiamata alla funzione SnmpRegister nei parametri srcEntity, dstEntity, context o notification, l'implementazione non usa tale parametro per filtrare trap e notifiche dal raggiungimento dell'applicazione WinSNMP. Se un'applicazione passa NULL in tutti i parametri indicati in precedenza, l'implementazione recapita tutte le notifiche ricevute alla sessione.

Se un'applicazione WinSNMP si registra per ricevere un tipo specifico di trap o notifica, deve definire un identificatore di oggetto, ovvero una struttura smiOID , che corrisponde a quel tipo di trap. Il parametro di notifica deve puntare a questa struttura. RFC 1907, "Management Information Base for Version 2 of the Simple Network Management Protocol (SNMPv2)," definisce gli identificatori di oggetto trap e notification. Per altre informazioni, vedere Gestione di trap e notifiche e conversione di trap da SNMPv1 a SNMPv2C.

L'implementazione usa il valore del parametro di notifica come modello per la corrispondenza con le trap e le notifiche ricevute. Ad esempio, se l'applicazione WinSNMP passa n numero di subidentifier nel parametro di notifica e i primi n subidentifier in una trap ricevuta corrispondono a tutti i subidentifier passati, l'identificatore dell'oggetto trap è una corrispondenza. Se un trap ricevuto ha meno identificatori secondari di n, l'identificatore dell'oggetto non corrisponde. Se esiste una corrispondenza, l'implementazione invia la notifica o la trap all'applicazione WinSNMP.

Se uno o tutti i parametri dstEntity, srcEntity o context sono NULL, l'implementazione potrebbe dover allocare risorse in una chiamata successiva alla funzione SnmpRecvMsg , per i parametri corrispondenti di tale funzione. Quando l'applicazione WinSNMP non richiede più le risorse restituite da SnmpRecvMsg , l'applicazione deve liberare le singole risorse con la funzione corrispondente alla risorsa. Per altre informazioni, vedere SnmpFreeEntity e SnmpFreeContext.

Per altre informazioni, vedere Più registrazioni trap.

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