Funções utilitárias

As funções utilitárias são fornecidas para facilitar algumas tarefas. Tais funções são as seguintes:

SnmpGetLastError ();

SnmpStrToOid ();

SnmpOidToStr ();

SnmpOidCopy ();

SnmpOidCompare ();

SnmpEncodeMsg ();

SnmpDecodeMsg ();

SnmpFreeDescriptor ();

`SnmpGetLastError()`

Descrição:

A função retorna um valor indicando porque a última operação WinSNMP que foi executada não acabou com sucesso.

Sintaxe:

SNMPAPI_STATUS SnmpGetLastError ( IN HSNMP_SESSION session);

Parâmetros:

session - Indica a sessão ao qual se está recuperando o valor do erro.

Retorno:

Esta função retorna o último erro WinSNMP que ocorreu para a sessão indicada, ou para a aplicação caso o valor da sessão seja NULL.

Comentários:

Esta função deve ser chamada imediatamente após qualquer chamada à API que falhar, visto que o valor é perdido para as próximas chamadas às funções da API.

Note que a função deve ser capaz de retornar o valor de erro de uma operação mesmo quando SnmpStartup falhar, e/ou antes de qualquer sessão ser criada com SnmpOpen.

`SnmpStrToOid()`

Descrição:

A função converte uma representação textual de um objeto em um OBJECT IDENTIFIER.

Sintaxe:

SNMPAPI_STATUS SnmpStrToOid ( IN LPCSTR string, OUT smiLPOID dstOID);

Parâmetros:

string - Aponta para a string a ser convertida;
dstOID - Aponta para uma variável smiOID que receberá o valor convertido.

Retorno:

Se a função terminar um sucesso, o valor de retorno é o número de sub-identificadores da saída OBJECT IDENTIFIER. Este número será também o valor do membro "len" da estrutura dstOID.

Se a função falhar, o valor de retorno será SNMPAPI_FAILURE.

`SnmpOidToStr()`

Descrição:

A função converte uma representação interna de um OBJECT IDENTIFIER em uma string.

Sintaxe:

SNMPAPI_STATUS SnmpOidToStr ( IN smiLPCOID srcOID, IN smiUINT32 size, OUT LPSTR string);

Parâmetros:

srcOID - Aponta para uma variável com contém o identificador a ser convertido;
size - O tamanho da string de resposta;
string - Aponta para a string a receber o retorno.

Retorno:

Se a função acabar com sucesso, o retorno é o número de bytes colocados na string de retorno. Se a função falhar, o valor de retorno será SNMPAPI_FAILURE.

`SnmpOidCopy()`

Descrição:

A função copia o srcOID para dstOID.

Sintaxe:

SNMPAPI_STATUS SnmpOidCopy ( IN smiLPCOID srcOID, OUT smiLPOID dstOID);

Parâmetros:

srcOID - Aponta para uma variável que contém o identificador do objeto;
dstOID - Aponta para uma variável que receberá o valor copiado.

Retorno:

Se a função terminar com sucesso, o valor de retorno será o número de sub-identificadores do OBJECT IDENTIFIER. Este número será também o valor do membro "len" da estrutura dstOID. Se a função falhar, o retorno será SNMPAPI_FAILURE.

`SnmpOidCompare()`

Descrição:

A função compara lexicamente dois OIDs. Se "maxlen" for diferente de zero, então seu valor é usado como um limite superior no número de sub-identificadores a serem comparados. Esta proposta será muito frequentemente usada para identificar se dois OIDs possuem prefixos comuns ou não. Se "maxlen" for zero, então o membro "len" das duas estruturas determinará o número máximo de sub-identificadores a comparar.

Sintaxe:

SNMPAPI_STATUS SnmpOidCompare ( IN smiLPCOID xOID, IN smiLPCOID yOID, IN smiUINT32 maxlen, OUT smiLPINT result);

Parâmetros:

xOID - Aponta para a primeira variável da comparação;
yOID - Aponta para a segunda variável da comparação;
maxlen - Se diferente de zero, idica o número de sub-identificados a serem comparados. Deve ser menor que MAXOBJIDSIZE;
result - Aponta para uma variável que receberá o resultado da comparação: >0 se xOID for maior que yOID; =0 if xOID for iqual d yOID e <0 se xOID for menor que yOID.

Retorno:

Se a função terminar com sucesso, o valor de retorno será SNMPAPI_SUCCESS. Em caso de falha o retorno será SNMPAPI_SUCCESS.

`SnmpEncodeMsg()`

Descrição:

A função pega como seus cinco primeiro parâmetro de entrada os mesmos parâmetro passados a SnmpSendMsg. A implementação usará estes parâmetros para formar a mensagem SNMP, como se pensasse que a mesma chegou via SnmpSendMsg. A implementação não ser preocupará entretanto em transmitir a mensagem resultante para "dstEntity". Ela irá, ao invés disso, usar o parâmetro "msgBufDesc" para retornar à aplicação a mensagem SNMP que seria transmitida.

Sintaxe:

SNMPAPI_STATUS SnmpEncodeMsg ( IN HSNMP_SESSION session, IN HSNMP_ENTITY srcEntity, IN HSNMP_ENTITY dstEntity, IN HSNMP_CONTEXT context, IN HSNMP_PDU pdu, OUT smiLPOCTETS msgBufDesc);

Parâmetros:

session - Identifica a sessão;
srcEntity - Identifica a entidade de gerenciamento;
dstEntity - Identificar a entidade alvo;
context - Identifica o contexto alvo de interesse;
PDU - Identifica a unidade de dados do protocolo SNMP que requisitará a operação;
msgBufDesc - Identifica a variável que receberá a mensagem SNMP codificada.

Retorno:

Se executou com sucesso, a função retorna o tamanho, em bytes, da mensagem SNMP codificada. Se a função falhar, o retorno será SNMPAPI_FAILURE.

`SnmpDecodeMsg()`

Descrição:

A função é o complemento da função SnmoEncodeMsg.

Sintaxe:

SNMPAPI_STATUS SnmpDecodeMsg ( IN HSNMP_SESSION session, OUT LPHSNMP_ENTITY srcEntity, OUT LPHSNMP_ENTITY dstEntity, OUT LPHSNMP_CONTEXT context, OUT LPHSNMP_PDU pdu, IN smiLPCOCTETS msgBufDesc);

Parâmetros:

session - Identifica a sessão;
srcEntity - Identifica a entidade origem;
dstEntity - Identifica a entidade destino;
context - Identifica o contexto alvo de interesse;
PDU - Identifica a unidade de dados do protocolo SNMP;
msgBufDesc - Identifica o buffer que contém a mensagem SNMP codificada.

Retorno:

Terminando com sucesso, a função retorna o valor real do número de bytes decodificados. Isto pode ser igual ou menor que o membro "len" de "msgBufDesc". Em caso de falha o retorno será SNMPAPI_FAILURE.

`SnmpFreeDescriptor()`

A função é usada pela aplicação para informar que a mesma não precisa ter acesso ao descritor de objeto preenchido anteriormente.

Sintaxe:

SNMPAPI_STATUS SnmpFreeDescriptor ( IN smiUINT32 syntax, IN smiLPOPAQUE descriptor);

Parâmetros:

syntax - Identifica a sintaxe (tipo de dados) do descritor alvo;
descriptor - Identifica o descritor de objeto alvo.

Retorno:

Se ocorrer com sucesso a função retorno SNMPAPI_SUCCES. Caso contrário o valor de retorno será SNMPAPI_FAILURE.