[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
);
| 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. |
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. |
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.
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.
WinSNMP Manager API Overview, WinSNMP Functions, SnmpFreeEntity, SnmpSetTranslateMode, SnmpStartup, SnmpSendMsg, SnmpRecvMsg, SnmpRegister, SnmpEncodeMsg, SnmpDecodeMsg