Função SnmpCreateSession (winsnmp.h)
[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 |
|---|---|
|
A função SnmpStartup não foi concluída com êxito. |
|
Ocorreu um erro durante a alocação de memória. |
|
O parâmetro fCallback é NULL, mas o parâmetro hWnd não é um identificador de janela válido. |
|
O parâmetro fCallback é NULL, mas o parâmetro wMsg não é um valor de mensagem válido. |
|
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. |
|
A combinação de valores de parâmetro não especifica notificações de retorno de chamada ou mensagens de notificação de janela. |
|
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 |