SnmpEntityToStr

[This is preliminary documentation and subject to change.]

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
Handle to the SNMP management entity of interest.
size
Specifies the size, in bytes, of the buffer pointed to by the string parameter. The WinSNMP manager application must allocate a buffer that is large enough to contain the output string.
string
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 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.

QuickInfo

  Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in winsnmp.h.
  Import Library: Use wsnmp32.lib.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SnmpStrToEntity