Funções
de Comunicação
Funções
de Comunicação
Nesta parte são apresentadas as funções de comunicação entre a aplicação WinSNMP e um objeto gerenciado. Comunicações com outros gerentes SNMP são manipuladas pela implementação WinSNMP.
Descrição:
A função SnmpStartup notifica a implementação WinSNMP que a aplicação usará seus serviçoes, abilitando a implementação a realizar quaisquer procedimentos de inicialização e alocação de recursos e retornar alguma informação útil à aplicação.
Sintaxe:
SNMPAPI_STATUS SnmpStartup ( OUT smiLPUINT32 nMajorVersion, OUT smiLPUINT32 nMinorVersion, OUT smiLPUINT32 nLevel, OUT smiLPUINT32 nTranslateMode, OUT smiLPUINT32 nRetransmitMode);
Parâmetros:
Retorno:
O valor de retorno será SNMPAPI_SUCCESS se tudo ocorreu de forma correta. Neste caso, os parâmetros de saída conterão valores apropriados. No caso de falha o valor de retorno será SNMPAPI_FAILURE.
Comentários:
Toda aplicação WinSNMP deve fazer uma chamada SnmpStartup pelo menos uma vez e esta chamada deve preceder qualquer chamada às outras funções da interface WinSNMP.
Quando esta chamada falha, a aplicação não deve fazer nenhuma outra chamada às funções na API WinSNMP, exceto SnmpGetLastError e, se apropriado tentar novamente iniciar o processo.
Descrição:
A função SnmpCleanup informa que a aplicação não requisitará mais nenhum recurso que possa ser alocado pela implementação e que nenhum outro serviço ou funções serão usados. A implementação WinSNMP libera então todos os recursos alocados pela implementação, a não ser que eles tenham sido também alocados por outro aplicação ainda ativa.
Sintaxe:
SNMPAPI_STATUS SnmpCleanup (void);
Retorno:
A função retorna SNMPAPI_SUCCES se a operação foi concluída com sucesso. Toda chamada subsequente à funções da interface WinSNMP retornará SNMPAPI_FAILURE com SnmpGetLastError retornando SNMPAPI_NOT_INITIALIZED.
Se a função não puder ser completada de forma correta a mesma retornará SNMPAPI_FAILURE.
Comentários:
É responsabilidade da aplicação o uso das respectivas funções SnmpFree<xxx> para liberar recursos específicos criados e chamar SnmpClose para fechar fechar a sessão criada com SnmpOpen. Entretanto, no caso de uma aplicação necessitar proceder com uma saída emergencial e chamar SnmpCleanup sem executar as funções anteriores a implementação WinSNMP deverá executar todos os procedimentos e liberação de qualquer recurso sobre seu controle que foi criado pela aplicação. Mesmo nesta situação emergencial, entretanto, a aplicação deve chamar SnmpCleanup para abilitar a funcionalidade descrita.
Descrição:
A função aloca e inicializa a memória, recursos, mecanismos de comunicação e estruturas de dados necessários para que a aplicação possa usar os serviços da interface. A aplicação continuará a usar o identificador de sessão retornado pela função nas subsequentes chamadas às funções da interface para facilitar a identificação dos recursos alocados para cada sessão. Este mecanismo abilitará a implementação WinSNMP a executar uma liberação de recursos em resposta a uma chamada SnmpClose.
Sintaxe:
HSNMP_SESSION SnmpOpen ( IN HWND hWnd, IN UINT wMsg);
Parâmetros:
Retorno:
A função retorna SNMPAPI_SUCCESS se tudo ocorreu sem problemas ou então SNMPAPI_FAILURE se falhou. Maiores detalhas das causas da falha podem ser obtidos com a função SnmpGetLastError. Um erro comum que pode ser observado é SNMPAPI_HWND_INVALID significando que o parâmetro hWnd informado não é um descritor válido de janela.
Comentários:
Uma aplicação pode abrir várias sessões. Cada sessão de um mesmo hWnd deve fornecer diferentes valores para wMsg, mas isto não é obrigatório. Uma chamada com suscesso retorna um handle único (em relação a todos os handles de sessões abertas).
O parâmetro hWnd especifica o handle da janela que será notificada quando uma resposta de requisição estiver disponível ou uma trap ocorreu, e o parâmetro wMsg especifica o valor de mensagem que será enviado à janela nesta situação. Recebendo a mensagem, a aplicação deve chama SnmpRecvMsg para recuperar a PDU para processamento da mensagem.
Descrição:
A função libera memória, recursos, mecanismos de comunicação e estruturas de dados associados com a sessão especificada.
Sintaxe:
SNMPAPI_STATUS SnmpClose ( IN HSNMP_SESSION session);
Parâmetros:
Retorno:
A função retorna SNMPAPI_SUCCESS se tudo ocorreu sem problemas ou então SNMPAPI_FAILURE se falhou. Maiores detalhas das causas da falha podem ser obtidos com a função SnmpGetLastError.
Comentários:
Se uma sessão for fechada antes que a resposta de uma requisição chegue fará com que a resposta seja descartada pela implementação WinSNMP.
Descrição:
A função transmite a PDU especificada para a entidade de destino, usando o contexto especificado - para comunicações SNMPv2.
Quando a função é chamada, a implementação WinSNMP determina que versão do SNMP e que tipo de transporte será usado baseado na propriedades requisitadas para aquela sessão.
Sintaxe:
SNMPAPI_STATUS SnmpSendMsg ( IN HSNMP_SESSION session, IN HSNMP_ENTITY srcEntity, IN HSNMP_ENTITY dstEntity, IN HSNMP_CONTEXT context, IN HSNMP_PDU pdu);
Parâmetros:
Retorno:
A função retorna SNMPAPI_SUCCESS se tudo ocorreu sem problemas ou então SNMPAPI_FAILURE se falhou. Os valores mais significantes de retorno para SnmpGetLastError neste caso são:
Comentários:
A função retorna imediatamente. Se o retorno indica erro, SnmpGetLastError deve ser chamado imediatamente para descobrir-se o tipo de erro. Quando a requisição for completa uma mensagem informada pelo parâmetro wMsg de SnmpOpen é enviada à janela especificada no parâmetro hWnd. A aplicação, no processamento dessa mensagem, deve então chamar SnmpRecvMsg para receber o retorno da requisição.
Descrição:
A função recupera o resultado de uma requisição. Ela também recebe traps registradas para a sessão.
Sintaxe:
SNMPAPI_STATUS SnmpRecvMsg ( IN HSNMP_SESSION session, OUT LPHSNMP_ENTITY srcEntity, OUT LPHSNMP_ENTITY dstEntity, OUT LPHSNMP_CONTEXT context OUT LPHSNMP_PDU pdu);
Parâmetros:
Retorno:
A função retorna SNMPAPI_SUCCESS se tudo ocorreu sem problemas ou então SNMPAPI_FAILURE se falhou. Os valores mais significantes de retorno para SnmpGetLastError neste caso são:
Comentários:
Quando um trap for recebido e encontra-se no formato SNMPv2, mesmo que tenha sido gerado por uma entidade SNMPv1.
Descrição:
A função registra que a aplicação deseja receber (ou deixar de receber) notificações de uma entidade específica de interesse (dstEntity).
Sintaxe:
SNMPAPI_STATUS SnmpRegister ( IN HSNMP_SESSION session, IN HSNMP_ENTITY srcEntity, IN HSNMP_ENTITY dstEntity, IN HSNMP_CONTEXT context, IN smiLPCOID notification, IN smiUINT32 status);
Parâmetros:
Retorno:
A função retorna SNMPAPI_SUCCESS se tudo ocorreu sem problemas ou então SNMPAPI_FAILURE se falhou. Os valores mais significantes de retorno para SnmpGetLastError neste caso são:
Comentários:
No WinSNMP todas as traps são entregues para a aplicação como traps SNMPv2. Se a implementação recebe uma trap SNMPv1 de um agente SNMPv1, ela deve converte para uma trap SNMPv2 de acordo com a RFC 1452.
Notificações e traps são definidas usando-se OBJECT IDENTIFIERs, como definido no SNMPv2. Assim, uma aplicação interessada em receber traps coldStart deve contruir um OBJECT IDENTIFIER correspondente a esta trap baseada na MID SNMPv2 (RFC 1450) e usar esta estrutura como parâmetro de notificação.
Uma aplicação pode passar NULL para qualquer dos parâmetros srcEntity, dstEntity, context e notification. O significa de NULL em qualquer um destes casos é, efetivamente, de dizer à implementação para não filtrar qualquer trap recebida com base nesses parâmetros.
Se o parâmetro notification for NULL, então a aplicação estará indicando que está interessada em registrar todas as traps da entidade destino.