Função SnmpExtensionQueryEx (snmp.h)

Artigo
08/26/2023

[O SNMP está disponível para uso nos sistemas operacionais especificados na seção Requisitos. Ele poderá ser alterado ou ficar indisponível em versões subsequentes. Em vez disso, use o Gerenciamento Remoto do Windows, que é a implementação da Microsoft do WS-Man.]

O serviço Microsoft SNMP chama a função SnmpExtensionQueryEx para processar solicitações SNMP que especificam variáveis em uma ou mais subárvores MIB registradas por agentes de extensão SNMP. Essa função é um elemento da API do Agente de Extensão SNMP.

Nota É recomendável que você use a função SnmpExtensionQueryEx , que dá suporte a tipos de dados SNMPv2C (versão SNMPv2C) do SNMP e operações de SET SNMP multifase. O serviço SNMP não chamará a função SnmpExtensionQuery se o agente de extensão exportar a função SnmpExtensionQueryEx .

Sintaxe

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

Parâmetros

[in] nRequestType

Especifica o tipo de operação que o serviço SNMP está solicitando que o agente de extensão execute. Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
SNMP_EXTENSION_GET	Recupere o valor ou os valores das variáveis especificadas.
SNMP_EXTENSION_GET_NEXT	Recupere o valor ou os valores do sucessor lexicográfico das variáveis especificadas.
SNMP_EXTENSION_SET_TEST	Valide os valores das variáveis especificadas. Essa operação maximiza a probabilidade de uma gravação bem-sucedida durante a solicitação COMMIT.
SNMP_EXTENSION_SET_COMMIT	Escreva os novos valores nas variáveis especificadas.
SNMP_EXTENSION_SET_UNDO	Redefina os valores das variáveis especificadas para seus valores antes da solicitação COMMIT.
SNMP_EXTENSION_SET_CLEANUP	Libere os recursos alocados em solicitações e operações anteriores.

Para obter informações adicionais sobre os tipos de solicitação SET, ou seja, aqueles que começam com SNMP_EXTENSION_SET_, consulte a seção Comentários a seguir.

[in] nTransactionId

Especifica uma variável DWORD que é o identificador exclusivo da PDU de solicitação SNMP de entrada. O agente de extensão pode usar esse valor para correlacionar várias chamadas pelo serviço SNMP que envolvem a mesma PDU.

[in, out] pVarBindList

Ponteiro para a lista de associação de variáveis que contém as variáveis de interesse.

[in, out] pContextInfo

Ponteiro para uma cadeia de caracteres de octeto que contém informações de contexto definidas pelo usuário.

O agente de extensão pode usar esse parâmetro para armazenar informações de contexto usadas durante operações set de SNMP multifase. O agente de extensão deve liberar recursos associados a esse parâmetro durante a solicitação CLEANUP. O serviço SNMP não libera nenhum recurso associado a esse parâmetro. Para obter informações adicionais, consulte a seção Comentários a seguir.

[out] pErrorStatus

Ponteiro para uma variável para receber o erro status resultado. Esse parâmetro pode ser um dos seguintes valores definidos pelo SNMPv2C.

Código do erro	Significado
SNMP_ERRORSTATUS_NOERROR	O agente relata que nenhum erro ocorreu durante a transmissão.
SNMP_ERRORSTATUS_TOOBIG	O agente não pôde colocar os resultados da operação SNMP solicitada em uma única mensagem SNMP.
SNMP_ERRORSTATUS_NOSUCHNAME	A operação SNMP solicitada identificou uma variável desconhecida.
SNMP_ERRORSTATUS_BADVALUE	A operação SNMP solicitada tentou alterar uma variável, mas especificou uma sintaxe ou um erro de valor.
SNMP_ERRORSTATUS_READONLY	A operação SNMP solicitada tentou alterar uma variável que não tinha permissão para ser alterada, de acordo com o perfil da comunidade da variável.
SNMP_ERRORSTATUS_GENERR	Ocorreu um erro diferente de um dos listados aqui durante a operação SNMP solicitada.
SNMP_ERRORSTATUS_NOACCESS	A variável SNMP especificada não está acessível.
SNMP_ERRORSTATUS_WRONGTYPE	O valor especifica um tipo inconsistente com o tipo necessário para a variável.
SNMP_ERRORSTATUS_WRONGLENGTH	O valor especifica um comprimento inconsistente com o comprimento necessário para a variável.
SNMP_ERRORSTATUS_WRONGENCODING	O valor contém uma codificação ASN.1 (Abstract Syntax Notation One) inconsistente com a marca ASN.1 do campo.
SNMP_ERRORSTATUS_WRONGVALUE	O valor não pode ser atribuído à variável.
SNMP_ERRORSTATUS_NOCREATION	A variável não existe e o agente não pode criá-la.
SNMP_ERRORSTATUS_INCONSISTENTVALUE	O valor é inconsistente com valores de outros objetos gerenciados.
SNMP_ERRORSTATUS_RESOURCEUNAVAILABLE	Atribuir o valor à variável requer a alocação de recursos que estão indisponíveis no momento.
SNMP_ERRORSTATUS_COMMITFAILED	Nenhum erro de validação ocorreu, mas nenhuma variável foi atualizada.
SNMP_ERRORSTATUS_UNDOFAILED	Nenhum erro de validação ocorreu. Algumas variáveis foram atualizadas porque não era possível desfazer sua atribuição.
SNMP_ERRORSTATUS_AUTHORIZATIONERROR	Ocorreu um erro de autorização.
SNMP_ERRORSTATUS_NOTWRITABLE	A variável existe, mas o agente não pode modificá-la.
SNMP_ERRORSTATUS_INCONSISTENTNAME	A variável não existe; o agente não pode criá-lo porque a instância de objeto nomeada é inconsistente com os valores de outros objetos gerenciados.

[out] pErrorIndex

Ponteiro para uma variável para receber o resultado do índice de erro.

Retornar valor

Se a função for bem-sucedida, o valor retornado será TRUE.

Se a função falhar, o valor retornado será FALSE.

Comentários

O serviço SNMP chama a função SnmpExtensionQueryEx várias vezes para processar uma solicitação SET SNMP de entrada. O serviço pode chamar SnmpExtensionQueryEx durante a fase de solicitação TEST, a fase de solicitação COMMIT, a fase de solicitação UNDO e a fase de solicitação CLEANUP.

Solicitação TEST

O serviço SNMP processa um tipo de solicitação SET SNMP chamando primeiro a função SnmpExtensionQueryEx com um dwRequestType de SNMP_EXTENSION_SET_TEST. O serviço chama cada agente de extensão responsável pelas associações de variáveis na solicitação. Cada agente de extensão deve validar as variáveis na lista de associação de variáveis. Opcionalmente, eles podem armazenar todas as informações de contexto necessárias para as solicitações a seguir na variável apontada pelo parâmetro pContextInfo .

Se a solicitação TEST falhar, o serviço iniciará uma solicitação CLEANUP. O serviço chama cada agente de extensão que anteriormente retornou TRUE para a solicitação TEST novamente com a função SnmpExtensionQueryEx . O serviço chama cada agente de extensão usando o SNMP_EXTENSION_SET_CLEANUP dwRequestType.

Solicitação COMMIT

Se todos os agentes de extensão retornarem TRUE à solicitação TEST, o serviço SNMP chamará cada agente de extensão com a função SnmpExtensionQueryEx , usando o SNMP_EXTENSION_SET_COMMIT dwRequestType. O serviço retorna para as informações de contexto do agente de extensão que o agente de extensão passou para o serviço. Essas são as informações de contexto que o agente de extensão passou no parâmetro pContextInfo durante a solicitação TEST. O agente de extensão pode usar as informações de contexto para atualizar os valores das variáveis especificadas de maneira específica à instrumentação.

Se o agente de extensão der suporte ao processamento de reversão, ele poderá atualizar as informações de contexto no parâmetro pContextInfo no momento. O serviço SNMP passa as informações de volta para o agente de extensão durante a solicitação UNDO.

Se todos os agentes de extensão retornarem TRUE à solicitação COMMIT, o serviço chamará cada agente de extensão com a função SnmpExtensionQueryEx , usando o SNMP_EXTENSION_SET_CLEANUP dwRequestType.

Se algum agente de extensão falhar na solicitação COMMIT, o serviço também iniciará uma solicitação CLEANUP. O serviço chama cada agente de extensão que anteriormente retornava TRUE para a solicitação COMMIT novamente com a função SnmpExtensionQueryEx . O serviço chama cada agente de extensão usando o SNMP_EXTENSION_SET_CLEANUP dwRequestType.

Solicitação CLEANUP

O serviço retorna ao agente de extensão as informações de contexto passadas no parâmetro pContextInfo durante a solicitação TEST ou COMMIT. O agente de extensão deve liberar os recursos associados ao parâmetro no momento.

Solicitação UNDO

Se qualquer agente de extensão retornar FALSE para a solicitação COMMIT, o serviço SNMP encerrará a solicitação COMMIT. O serviço chama cada agente de extensão que retornou TRUE para a solicitação COMMIT com um dwRequestType de SNMP_EXTENSION_SET_UNDO. Isso sinaliza aos agentes de extensão que a solicitação COMMIT falhou e eles devem iniciar o processamento de reversão.

Os agentes de extensão devem tentar redefinir os valores das variáveis de interesse, de volta aos valores que eram antes da solicitação COMMIT falhar. Para fazer isso, os agentes de extensão usam as informações de contexto retornadas no parâmetro pContextInfo durante a solicitação COMMIT.

Se qualquer agente de extensão retornar FALSE para a solicitação UNDO, toda a operação SET falhará com o código de erro SNMP_ERRORSTATUS_UNDOFAILED. Se todos os agentes de extensão retornarem TRUE à solicitação UNDO, a operação SET do SNMP falhará com o código de erro definido pelo agente de extensão que falhou na solicitação COMMIT.

Após a solicitação UNDO, o serviço sempre chama cada agente de extensão com a função SnmpExtensionQueryEx , usando o SNMP_EXTENSION_SET_CLEANUP dwRequestType.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	snmp.h