SnmpStrToEntity

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpStrToEntity function returns a handle to information about an SNMP management entity that is specific to the Microsoft WinSNMP implementation.

HSNMP_ENTITY SnmpStrToEntity(
  HSNMP_SESSION session,  // handle to the WinSNMP session 
  LPCSTR string           // pointer to a string that identifies
                          // the entity 
);
 

Parameters

session
Handle to the WinSNMP session.
string
Pointer to a null-terminated string that identifies the SNMP management entity of interest. The current setting of the entity and context translation mode determines the manner in which SnmpStrToEntity interprets the input string as follows.
Entity/Context Translation Mode Meaning
SNMPAPI_TRANSLATED The implementation interprets the string parameter as a user-friendly name. The implementation translates the name into its SNMPv1 or SNMPv2C components using the implementation's database.
SNMPAPI_UNTRANSLATED_V1 The implementation interprets the string parameter as a literal SNMP transport address.
SNMPAPI_UNTRANSLATED_V2 The implementation interprets the string parameter as a literal SNMP transport address.

Return Values

If the function succeeds, the return value is a handle to the SNMP management entity of interest.

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_SESSION_INVALID The session parameter is invalid.
SNMPAPI_ENTITY_UNKNOWN The entity string is invalid.
SNMPAPI_OTHER_ERROR An unknown or undefined error occurred.

Remarks

The current setting of the entity and context translation mode determines the manner in which SnmpStrToEntity interprets the input string that identifies the management entity of interest. For additional information, see Setting the Entity and Context Translation Mode.

The WinSNMP manager application should call the SnmpFreeEntity function to release the entity handle allocated by the SnmpStrToEntity function. For additional information, see WinSNMP Data Management Concepts.

The SnmpStrToEntity function returns a valid entity handle that a WinSNMP manager application can use as the srcEntity or the dstEntity parameter in multiple WinSNMP functions. These functions include the SnmpSendMsg, SnmpRecvMsg, SnmpRegister, SnmpEncodeMsg, and SnmpDecodeMsg functions.

The implementation returns the current entity and context translation mode in the nTranslateMode parameter of the SnmpStartup function. A WinSNMP manager application can change the setting of the entity and context translation mode with a call to the SnmpSetTranslateMode function.

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, SnmpFreeEntity, SnmpSetTranslateMode, SnmpStartup, SnmpSendMsg, SnmpRecvMsg, SnmpRegister, SnmpEncodeMsg, SnmpDecodeMsg