Platform SDK: Network Management

SnmpEntityToStr

The WinSNMP SnmpEntityToStr function returns a string that identifies an SNMP management entity.

SNMPAPI_STATUS SnmpEntityToStr(
  HSNMP_ENTITY entity, // handle to the entity 
  smiUINT32 size,      // buffer size, in bytes, for output string 
  LPSTR string         // pointer to the buffer to receive the 
                       //   output string 
);

Parameters

entity: [in] Handle to the SNMP management entity of interest.
size: [in] Specifies the size, in bytes, of the buffer pointed to by the string parameter. The WinSNMP application must allocate a buffer that is large enough to contain the output string.
string: [out] Pointer to a buffer to receive the null-terminated string that identifies the SNMP management entity of interest.

Return Values

If the function succeeds, the return value is the number of bytes, including a terminating null byte, that SnmpEntityToStr returns in the string buffer. This value can be less than or equal to the value of the size parameter, but it cannot be greater.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error Code	Description
SNMPAPI_NOT_INITIALIZED	The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR	An error occurred during memory allocation.
SNMPAPI_ENTITY_INVALID	The entity parameter is invalid.
SNMPAPI_OUTPUT_TRUNCATED	The output buffer length is insufficient.
SNMPAPI_OTHER_ERROR	An unknown or undefined error occurred.

Remarks

The current setting of the entity and context translation mode determines the type of output string SnmpEntityToStr returns. For additional information, see Support for IPX Address Strings in WinSNMP and Setting the Entity and Context Translation Mode.

When the entity and context translation mode is SNMPAPI_TRANSLATED, and an entry exists in the implementation's database, the implementation returns the associated user-friendly name of the management entity. If an entry does not exist for the management entity, SnmpEntityToStr returns the literal SNMP transport address of the management entity.

When the entity and context translation mode is SNMPAPI_UNTRANSLATED_V1 or SNMPAPI_UNTRANSLATED_V2, the Microsoft WinSNMP implementation also returns the literal SNMP transport address of the management entity.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Unsupported.
  Header: Declared in Winsnmp.h.
  Library: Use Wsnmp32.lib.

SnmpEntityToStr

Parameters

Return Values

Remarks

Requirements

See Also