Função SnmpCreateSession (winsnmp.h)

Artigo
03/15/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 SnmpCreateSession solicita que a implementação do Microsoft WinSNMP abra uma sessão para o aplicativo WinSNMP. O aplicativo pode especificar como a implementação deve informar a sessão WinSNMP de mensagens SNMP disponíveis e eventos assíncronos. O aplicativo pode especificar uma mensagem de notificação de janela ou uma função SNMPAPI_CALLBACK para notificar a sessão.

A função SnmpCreateSession é um elemento da API WinSNMP, versão 2.0. Ao desenvolver novos aplicativos WinSNMP, é recomendável chamar SnmpCreateSession para abrir uma sessão WinSNMP em vez de chamar a função SnmpOpen .

Sintaxe

HSNMP_SESSION SNMPAPI_CALL SnmpCreateSession(
  [in] HWND             hWnd,
  [in] UINT             wMsg,
  [in] SNMPAPI_CALLBACK fCallBack,
  [in] LPVOID           lpClientData
);

Parâmetros

[in] hWnd

Manipule para uma janela do aplicativo WinSNMP para notificar quando uma solicitação assíncrona for concluída ou quando ocorrer uma notificação de interceptação. Esse parâmetro é necessário para mensagens de notificação de janela para a sessão.

[in] wMsg

Especifica um inteiro sem sinal que identifica a mensagem de notificação a ser enviada para a janela do aplicativo WinSNMP. Esse parâmetro é necessário para mensagens de notificação de janela para a sessão.

[in] fCallBack

Especifica o endereço de uma função de SNMPAPI_CALLBACK definida pelo aplicativo e específica da sessão. A implementação chamará essa função para informar a sessão WinSNMP quando as notificações estiverem disponíveis.

Esse parâmetro é necessário para especificar notificações de retorno de chamada para a sessão. Esse parâmetro deve ser NULL para especificar mensagens de notificação de janela para a sessão. Para obter informações adicionais, consulte a seção Comentários a seguir.

[in] lpClientData

Ponteiro para dados definidos pelo aplicativo a serem passados para a função de retorno de chamada especificada pelo parâmetro fCallback . Esse parâmetro é opcional e pode ser NULL. Se o parâmetro fCallback for NULL, a implementação ignorará esse parâmetro.

Retornar valor

Se a função for bem-sucedida, o valor retornado será um identificador que identifica a sessão WinSNMP que a implementação abre para o aplicativo de chamada.

Se a função falhar, o valor retornado será SNMPAPI_FAILURE. Para obter informações de erro estendidas, chame SnmpGetLastError. A função SnmpGetLastError pode retornar um dos erros a seguir.

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_HWND_INVALID	O parâmetro fCallback é NULL, mas o parâmetro hWnd não é um identificador de janela válido.
SNMPAPI_MESSAGE_INVALID	O parâmetro fCallback é NULL, mas o parâmetro wMsg não é um valor de mensagem válido.
SNMPAPI_MODE_INVALID	O parâmetro fCallback é NULL e os parâmetros hWnd e wMsg são válidos individualmente. No entanto, os valores são mutuamente incompatíveis na plataforma Windows.
SNMPAPI_OPERATION_INVALID	A combinação de valores de parâmetro não especifica notificações de retorno de chamada ou mensagens de notificação de janela.
SNMPAPI_OTHER_ERROR	Ocorreu um erro desconhecido ou indefinido.

Comentários

A função SnmpCreateSession retorna um identificador exclusivo para cada sessão WinSNMP aberta dentro do aplicativo WinSNMP de chamada. O aplicativo deve usar o identificador de sessão que SnmpCreateSession retorna em outras chamadas de função WinSNMP para facilitar a alocação e a desalocação de recursos pela implementação.

É recomendável que um aplicativo WinSNMP chame a função SnmpClose uma vez para cada sessão que a implementação abre como resultado de uma chamada para a função SnmpCreateSession . Se um aplicativo WinSNMP for encerrado inesperadamente, ele deverá chamar SnmpCleanup antes de ser encerrado para permitir que a implementação desaloque todos os recursos.

Notificações de retorno de chamada

Se o parâmetro fCallback não for NULL em uma chamada bem-sucedida para a função SnmpCreateSession, a implementação alertará a sessão para notificações usando a função de retorno de chamada especificada pelo parâmetro fCallback .

Veja a seguir um exemplo de uma chamada para a função SnmpCreateSession , solicitando que a implementação sinalize a sessão sobre mensagens e eventos usando notificações de retorno de chamada.

hSession = SnmpCreateSession (0, 0, myFunc, <NULL|myData>);

Mensagens de notificação da janela

A função SnmpCreateSession passa para a implementação o identificador para uma janela do aplicativo e um identificador de mensagem de notificação. Quando a janela do aplicativo recebe a mensagem de notificação especificada pelo parâmetro wMsg , o aplicativo WinSNMP deve recuperar a PDU (unidade de dados de protocolo de entrada). O aplicativo faz isso chamando a função SnmpRecvMsg com o identificador de sessão retornado por SnmpCreateSession.

Um aplicativo WinSNMP pode abrir várias sessões WinSNMP. Se um aplicativo abrir várias sessões usando o mesmo identificador de janela, é recomendável que o aplicativo WinSNMP especifique um parâmetro wMsg exclusivo para cada sessão.

Veja a seguir um exemplo de uma chamada para a função SnmpCreateSession , solicitando que a implementação sinalize a sessão sobre mensagens e eventos usando mensagens de notificação de janela.

hSession = SnmpCreateSession (myWnd, myMsg, NULL, NULL);

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