Função SnmpStartupEx (winsnmp.h)

Artigo
08/27/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.]

A função SnmpStartupEx notifica a implementação do Microsoft WinSNMP de que o aplicativo WinSNMP requer os serviços da implementação. A função WinSNMP SnmpStartupEx permite que a implementação inicialize e retorne ao aplicativo a versão da API WinSNMP (Interface de Programação de Aplicativo SNMP do Windows), o nível de comunicações SNMP compatíveis com a implementação e os modos de conversão e retransmissão padrão da implementação.

Essa função deve ser usada em vez de SnmpStartup se o Windows Server 2003 com Service Pack 1 (SP1) ou posterior estiver instalado. SnmpStartupEx habilita o suporte para vários módulos de software independentes que usam WinSNMP no mesmo aplicativo.

Nota Um aplicativo WinSNMP deve chamar a função SnmpStartupEx com êxito antes de chamar qualquer outra função WinSNMP.

Sintaxe

SNMPAPI_STATUS SNMPAPI_CALL SnmpStartupEx(
  [out] smiLPUINT32 nMajorVersion,
  [out] smiLPUINT32 nMinorVersion,
  [out] smiLPUINT32 nLevel,
  [out] smiLPUINT32 nTranslateMode,
  [out] smiLPUINT32 nRetransmitMode
);

Parâmetros

[out] nMajorVersion

Ponteiro para uma variável de inteiro longo sem sinal para receber o número de versão principal da API WinSNMP compatível com a implementação. Por exemplo, para indicar que a implementação dá suporte ao WinSNMP versão 2.0, a função retorna um valor de 2.

[out] nMinorVersion

Ponteiro para uma variável de inteiro longo sem sinal para receber o número de versão secundária da API WinSNMP compatível com a implementação. Por exemplo, para indicar que a implementação dá suporte ao WinSNMP versão 2.0, a função retorna um valor de 0.

[out] nLevel

Ponteiro para uma variável de inteiro longo sem sinal para receber o nível mais alto de comunicações SNMP compatíveis com a implementação. Após o retorno bem-sucedido, esse parâmetro contém um valor de 2. Para obter uma descrição do suporte de nível 2, consulte Níveis de suporte SNMP.

[out] nTranslateMode

Ponteiro para uma variável de inteiro longo sem sinal para receber o modo de tradução padrão em vigor para a implementação. O modo de tradução se aplica a como a implementação interpreta o parâmetro de entidade , que o aplicativo WinSNMP passa para a função SnmpStrToEntity . O modo de tradução também se aplica ao parâmetro de cadeia de caracteres que o aplicativo WinSNMP passa para a função SnmpStrToContext . Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
SNMPAPI_TRANSLATED	A implementação usa seu banco de dados para traduzir nomes amigáveis para entidades SNMP e objetos gerenciados. A implementação os converte em seus componentes SNMPv1 ou SNMPv2C.
SNMPAPI_UNTRANSLATED_V1	A implementação interpreta parâmetros de entidade SNMP como endereços de transporte SNMP e parâmetros de contexto como cadeias de caracteres da comunidade SNMP. Para entidades de destino SNMPv2, a implementação cria mensagens SNMP de saída que contêm um valor igual a zero no campo de versão.
SNMPAPI_UNTRANSLATED_V2	A implementação interpreta parâmetros de entidade SNMP como endereços de transporte SNMP e parâmetros de contexto como cadeias de caracteres da comunidade SNMP. Para entidades de destino SNMPv2, a implementação cria mensagens SNMP de saída que contêm um valor de 1 no campo de versão.

Para obter informações adicionais, consulte Configurando o modo de conversão de entidade e contexto.

[out] nRetransmitMode

Ponteiro para uma variável de inteiro longo sem sinal para receber o modo de retransmissão padrão em vigor para a implementação. Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
SNMPAPI_OFF	A implementação não está executando a política de retransmissão do aplicativo WinSNMP.
SNMPAPI_ON	A implementação está executando a política de retransmissão do aplicativo WinSNMP.

Para obter informações adicionais, consulte Sobre a retransmissão.

Valor retornado

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

Se a função falhar, o valor retornado será SNMPAPI_FAILURE. Para obter informações de erro estendidas, chame SnmpGetLastError especificando um valor NULL em seu parâmetro de sessão . A função SnmpGetLastError pode retornar um dos erros a seguir. Para obter informações adicionais, consulte a seção "Comentários" mais adiante neste documento.

Código de retorno	Descrição
SNMPAPI_TL_RESOURCE_ERROR	Ocorreu um erro de alocação de recursos durante a inicialização.
SNMPAPI_TL_NOT_INITIALIZED	A função SnmpStartupEx não foi inicializada corretamente.
SNMPAPI_ALLOC_ERROR	Ocorreu um erro durante a alocação de memória.
SNMPAPI_OTHER_ERROR	Ocorreu um erro desconhecido ou indefinido.

Comentários

Um aplicativo WinSNMP deve chamar a função SnmpStartupEx com êxito pelo menos uma vez, antes de chamar qualquer outra função WinSNMP. Se um aplicativo WinSNMP chamar outra função WinSNMP antes de chamar SnmpStartupEx com êxito, a implementação retornará o erro SNMPAPI_NOT_INITIALIZED.

O aplicativo WinSNMP pode chamar SnmpGetLastError para obter informações de erro ou tentar novamente SnmpStartupEx se uma chamada para a função SnmpStartupEx falhar. Quando SnmpStartupEx retorna SNMPAPI_FAILURE e uma chamada subsequente para SnmpGetLastError retorna SNMP_ALLOC_ERROR, o aplicativo WinSNMP pode optar por aguardar. Ele pode repetir a chamada para SnmpStartupEx quando a implementação tiver recursos livres adequados.

Um aplicativo WinSNMP deve chamar SnmpCleanupEx para cada chamada bem-sucedida para SnmpStartupEx. A implementação do WinSNMP executa a limpeza final em que não há chamadas bem-sucedidas pendentes para SnmpStartup ou SnmpStartupEx.

Para obter informações adicionais, consulte Níveis de suporte de SNMP e Sobre versões SNMP.

Requisitos


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