Função SnmpRecvMsg (winsnmp.h)

Artigo
03/09/2024

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

A função WinSNMP SnmpRecvMsg recupera os resultados de uma solicitação assíncrona concluída enviada por uma chamada para a função SnmpSendMsg , na forma de uma mensagem SNMP. A função SnmpRecvMsg também retorna dados de interceptação e notificações pendentes registrados para uma sessão WinSNMP.

Sintaxe

SNMPAPI_STATUS SNMPAPI_CALL SnmpRecvMsg(
  [in]  HSNMP_SESSION   session,
  [out] LPHSNMP_ENTITY  srcEntity,
  [out] LPHSNMP_ENTITY  dstEntity,
  [out] LPHSNMP_CONTEXT context,
  [out] LPHSNMP_PDU     PDU
);

Parâmetros

[in] session

Manipule para a sessão WinSNMP.

[out] srcEntity

Ponteiro para uma variável que recebe um identificador para a entidade que envia a mensagem. Observe que o parâmetro srcEntity para a função SnmpRegister especifica um identificador para a entidade de gerenciamento que se registra para notificação de interceptação.

[out] dstEntity

Ponteiro para uma variável que recebe um identificador para a entidade que recebe a mensagem. Observe que o parâmetro dstEntity para a função SnmpRegister especifica um identificador para a entidade de gerenciamento que envia armadilhas.

[out] context

Ponteiro para uma variável que recebe um identificador para o contexto, que é um conjunto de recursos de objeto gerenciado. A entidade especificada pelo parâmetro srcEntity emite a mensagem desse contexto.

[out] PDU

Ponteiro para uma variável que recebe um identificador para o componente PDU (unidade de dados de protocolo) da mensagem.

Retornar valor

Se a função for bem-sucedida, o valor retornado será SNMPAPI_SUCCESS e os parâmetros de saída conterão os valores indicados nas descrições de parâmetro anteriores.

Se a função falhar, o valor retornado será SNMPAPI_FAILURE. Se a função falhar com um código de erro estendido que indica um erro de camada de transporte de rede, ou seja, um que começa com SNMPAPI_TL_, os parâmetros de saída também contêm os valores indicados anteriormente para permitir que o aplicativo WinSNMP se recupere normalmente.

Para obter informações de erro estendidas, chame SnmpGetLastError. A função SnmpGetLastError pode retornar um dos seguintes erros de camada de transporte de rede ou WinSNMP.

Código de retorno	Descrição
SNMPAPI_NOT_INITIALIZED	A função SnmpStartup não foi concluída com êxito.
SNMPAPI_ALLOC_ERROR	Ocorreu um erro durante a alocação de memória.
SNMPAPI_SESSION_INVALID	O parâmetro de sessão é inválido.
SNMPAPI_NOOP	A sessão especificada não tem mensagens em sua fila no momento.
SNMPAPI_TL_NOT_INITIALIZED	A camada de transporte de rede não foi inicializada.
SNMPAPI_TL_NOT_SUPPORTED	A camada de transporte de rede não dá suporte ao protocolo SNMP.
SNMPAPI_TL_NOT_AVAILABLE	Falha no subsistema de rede.
SNMPAPI_TL_RESOURCE_ERROR	Ocorreu um erro de recurso na camada de transporte de rede.
SNMPAPI_TL_UNDELIVERABLE	A entidade especificada pelo parâmetro dstEntity não está disponível.
SNMPAPI_TL_SRC_INVALID	A entidade especificada pelo parâmetro srcEntity não foi inicializada.
SNMPAPI_TL_INVALID_PARAM	Uma chamada de função de camada de transporte de rede recebeu um parâmetro de entrada inválido.
SNMPAPI_TL_PDU_TOO_BIG	A PDU é muito grande para a camada de transporte de rede enviar ou receber.
SNMPAPI_TL_OTHER	Ocorreu um erro de camada de transporte de rede indefinida.
SNMPAPI_OTHER_ERROR	Ocorreu um erro desconhecido ou indefinido.

Para obter informações adicionais, consulte Erros de transporte de rede.

Comentários

A função SnmpCreateSession passa um identificador de janela do aplicativo e o identificador de mensagem de notificação para a implementação do Microsoft WinSNMP. Quando a janela do aplicativo recebe a mensagem de notificação especificada pelo parâmetro wMsg , o aplicativo WinSNMP deve chamar a função SnmpRecvMsg com o identificador de sessão retornado por SnmpCreateSession para recuperar uma PDU (unidade de dados de protocolo de entrada). Para obter informações adicionais, consulte Sobre mensagens SNMP.

A função SnmpRecvMsg cria uma instância de quatro objetos e aloca seus recursos: dois identificadores de entidade, um identificador de contexto e um identificador de PDU. O identificador para o componente de lista de associações de variáveis da PDU retornada não é instanciado até que o aplicativo WinSNMP chame a função SnmpGetPduData . Quando ele não precisa mais dos recursos retornados por SnmpRecvMsg , o aplicativo WinSNMP deve liberar os recursos individuais usando a função WinSNMP que corresponde ao recurso. Para obter informações adicionais, consulte SnmpFreePdu, SnmpFreeEntity e SnmpFreeContext.

Quando a implementação recebe armadilhas de uma entidade que opera sob a estrutura SNMPv1 (SNMPv1), ela converte as armadilhas para o formato SNMPv2C (versão 2C do SNMP). Portanto, quando SnmpRecvMsg entrega uma armadilha, ele está sempre no formato SNMPv2C. Para obter informações adicionais, consulte Traduzindo armadilhas de SNMPv1 para tarefas de programação SNMPv2C e WinSNMP.

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	winsnmp.h
Biblioteca	Wsnmp32.lib
DLL	Wsnmp32.dll