Condividi tramite


Funzione SnmpExtensionQueryEx (snmp.h)

[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.

Il servizio Microsoft SNMP chiama la funzione SnmpExtensionQueryEx per elaborare le richieste SNMP che specificano le variabili in uno o più sottoalberi MIB registrati dagli agenti di estensione SNMP. Questa funzione è un elemento dell'API dell'agente di estensione SNMP.

Nota È consigliabile usare la funzione SnmpExtensionQueryEx , che supporta i tipi di dati SNMP versione 2C (SNMPv2C) e le operazioni SNMP SET multifase. Il servizio SNMP non chiama la funzione SnmpExtensionQuery se l'agente di estensione esporta la funzione SnmpExtensionQueryEx .
 

Sintassi

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

Parametri

[in] nRequestType

Specifica il tipo di operazione che il servizio SNMP richiede l'esecuzione dell'agente di estensione. Questo parametro può avere uno dei valori seguenti.

Valore Significato
SNMP_EXTENSION_GET
Recuperare il valore o i valori delle variabili specificate.
SNMP_EXTENSION_GET_NEXT
Recuperare il valore o i valori del successore lessicografico delle variabili specificate.
SNMP_EXTENSION_SET_TEST
Convalidare i valori delle variabili specificate. Questa operazione ottimizza la probabilità di una scrittura riuscita durante la richiesta COMMIT.
SNMP_EXTENSION_SET_COMMIT
Scrivere i nuovi valori nelle variabili specificate.
SNMP_EXTENSION_SET_UNDO
Reimpostare i valori delle variabili specificate nei relativi valori prima della richiesta COMMIT.
SNMP_EXTENSION_SET_CLEANUP
Rilasciare le risorse allocate nelle richieste e nelle operazioni precedenti.
 

Per altre informazioni sui tipi di richiesta SET, ovvero quelli che iniziano con SNMP_EXTENSION_SET_, vedere la sezione Osservazioni seguenti.

[in] nTransactionId

Specifica una variabile DWORD che è l'identificatore univoco della richiesta SNMP in ingresso PDU. L'agente di estensione può usare questo valore per correlare più chiamate dal servizio SNMP che coinvolgono lo stesso PDU.

[in, out] pVarBindList

Puntatore all'elenco di associazione di variabili contenente le variabili di interesse.

[in, out] pContextInfo

Puntatore a una stringa ottetto contenente informazioni sul contesto definite dall'utente.

L'agente di estensione può usare questo parametro per archiviare le informazioni di contesto usate durante operazioni SNMP SET multifase. L'agente di estensione deve rilasciare le risorse associate a questo parametro durante la richiesta CLEANUP. Il servizio SNMP non rilascia risorse associate a questo parametro. Per altre informazioni, vedere la sezione Osservazioni seguenti.

[out] pErrorStatus

Puntatore a una variabile per ricevere il risultato dello stato di errore. Questo parametro può essere uno dei valori seguenti definiti da SNMPv2C.

Codice di errore Significato
SNMP_ERRORSTATUS_NOERROR
L'agente segnala che non si sono verificati errori durante la trasmissione.
SNMP_ERRORSTATUS_TOOBIG
L'agente non è riuscito a inserire i risultati dell'operazione SNMP richiesta in un singolo messaggio SNMP.
SNMP_ERRORSTATUS_NOSUCHNAME
L'operazione SNMP richiesta ha identificato una variabile sconosciuta.
SNMP_ERRORSTATUS_BADVALUE
L'operazione SNMP richiesta tentava di modificare una variabile, ma specificava un errore di sintassi o valore.
SNMP_ERRORSTATUS_READONLY
L'operazione SNMP richiesta ha tentato di modificare una variabile non consentita, in base al profilo della community della variabile.
SNMP_ERRORSTATUS_GENERR
Si è verificato un errore diverso da uno di quelli elencati qui durante l'operazione SNMP richiesta.
SNMP_ERRORSTATUS_NOACCESS
La variabile SNMP specificata non è accessibile.
SNMP_ERRORSTATUS_WRONGTYPE
Il valore specifica un tipo incoerente con il tipo necessario per la variabile.
SNMP_ERRORSTATUS_WRONGLENGTH
Il valore specifica una lunghezza incoerente con la lunghezza necessaria per la variabile.
SNMP_ERRORSTATUS_WRONGENCODING
Il valore contiene una codifica astratta Notation One (ASN.1) incoerente con il tag ASN.1 del campo.
SNMP_ERRORSTATUS_WRONGVALUE
Impossibile assegnare il valore alla variabile.
SNMP_ERRORSTATUS_NOCREATION
La variabile non esiste e l'agente non può crearlo.
SNMP_ERRORSTATUS_INCONSISTENTVALUE
Il valore è incoerente con i valori di altri oggetti gestiti.
SNMP_ERRORSTATUS_RESOURCEUNAVAILABLE
L'assegnazione del valore alla variabile richiede l'allocazione delle risorse attualmente non disponibili.
SNMP_ERRORSTATUS_COMMITFAILED
Non si sono verificati errori di convalida, ma non sono state aggiornate variabili.
SNMP_ERRORSTATUS_UNDOFAILED
Non si sono verificati errori di convalida. Alcune variabili sono state aggiornate perché non è stato possibile annullare l'assegnazione.
SNMP_ERRORSTATUS_AUTHORIZATIONERROR
Si è verificato un errore di autorizzazione.
SNMP_ERRORSTATUS_NOTWRITABLE
La variabile esiste ma l'agente non può modificarlo.
SNMP_ERRORSTATUS_INCONSISTENTNAME
La variabile non esiste; l'agente non può crearlo perché l'istanza dell'oggetto denominata non è coerente con i valori di altri oggetti gestiti.

[out] pErrorIndex

Puntatore a una variabile per ricevere il risultato dell'indice di errore.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è TRUE.

Se la funzione ha esito negativo, il valore restituito è FALSE.

Commenti

Il servizio SNMP chiama la funzione SnmpExtensionQueryEx più volte per elaborare una richiesta SNMP SET in ingresso. Il servizio può chiamare SnmpExtensionQueryEx durante la fase di richiesta TEST, la fase di richiesta COMMIT, la fase di richiesta UNDO e la fase di richiesta CLEANUP.

Richiesta TEST

Il servizio SNMP elabora un tipo di richiesta SNMP SET chiamando prima la funzione SnmpExtensionQueryEx con un dwRequestType di SNMP_EXTENSION_SET_TEST. Il servizio chiama ogni agente di estensione responsabile delle associazioni di variabili nella richiesta. Ogni agente di estensione deve convalidare le variabili nell'elenco di associazione delle variabili. Facoltativamente, possono archiviare tutte le informazioni di contesto necessarie per le richieste seguenti nella variabile a cui fa riferimento il parametro pContextInfo .

Se la richiesta TEST ha esito negativo, il servizio avvia una richiesta CLEANUP. Il servizio chiama di nuovo ogni agente di estensione che in precedenza ha restituito TRUE alla richiesta TEST con la funzione SnmpExtensionQueryEx . Il servizio chiama ogni agente di estensione usando il SNMP_EXTENSION_SET_CLEANUP dwRequestType.

Richiesta COMMIT

Se tutti gli agenti di estensione restituiscono TRUE alla richiesta TEST, il servizio SNMP chiama ogni agente di estensione con la funzione SnmpExEx, usando il SNMP_EXTENSION_SET_COMMIT dwRequestType. Il servizio restituisce le informazioni sul contesto dell'agente di estensione passate al servizio. Si tratta delle informazioni sul contesto che l'agente di estensione passato nel parametro pContextInfo durante la richiesta TEST. L'agente di estensione può usare le informazioni di contesto per aggiornare i valori delle variabili specificate in modo specifico della strumentazione.

Se l'agente di estensione supporta l'elaborazione del rollback, può aggiornare le informazioni sul contesto nel parametro pContextInfo in questo momento. Il servizio SNMP passa le informazioni all'agente di estensione durante la richiesta UNDO.

Se tutti gli agenti di estensione restituiscono TRUE alla richiesta COMMIT, il servizio chiama ogni agente di estensione con la funzione SnmpExExtensionQueryEx , usando il SNMP_EXTENSION_SET_CLEANUP dwRequestType.

Se un agente di estensione ha esito negativo, il servizio avvia anche una richiesta CLEANUP. Il servizio chiama di nuovo ogni agente di estensione che in precedenza ha restituito TRUE alla richiesta COMMIT con la funzione SnmpExtensionQueryEx . Il servizio chiama ogni agente di estensione usando il SNMP_EXTENSION_SET_CLEANUP dwRequestType.

Richiesta DI PULIZIA

Il servizio restituisce all'agente di estensione le informazioni di contesto passate nel parametro pContextInfo durante la richiesta TEST o COMMIT. L'agente di estensione deve rilasciare le risorse associate al parametro in questo momento.

Richiesta UNDO

Se un agente di estensione restituisce FALSE alla richiesta COMMIT, il servizio SNMP termina la richiesta COMMIT. Il servizio chiama ogni agente di estensione che ha restituito TRUE alla richiesta COMMIT con un dwRequestType di SNMP_EXTENSION_SET_UNDO. Questo segnala agli agenti di estensione che la richiesta COMMIT non è riuscita e deve avviare l'elaborazione del rollback.

Gli agenti di estensione devono tentare di reimpostare i valori delle variabili di interesse, tornare ai valori precedenti alla richiesta COMMIT non riuscita. A tale scopo, gli agenti di estensione usano le informazioni di contesto restituite nel parametro pContextInfo durante la richiesta COMMIT.

Se un agente di estensione restituisce FALSE alla richiesta UNDO, l'intera operazione SET ha esito negativo con il codice di errore SNMP_ERRORSTATUS_UNDOFAILED. Se tutti gli agenti di estensione restituiscono TRUE alla richiesta UNDO, l'operazione SNMP SET ha esito negativo con il codice di errore impostato dall'agente di estensione che ha superato la richiesta COMMIT.

Dopo la richiesta UNDO il servizio chiama sempre ogni agente di estensione con la funzione SnmpExtensionQueryEx usando il SNMP_EXTENSION_SET_CLEANUP dwRequestType.

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 snmp.h

Vedi anche

AsnOctetString

Funzioni SNMP

Panoramica del protocollo Simple Network Management Protocol (SNMP)

SnmpExtensionQuery

SnmpVarBindList