SnmpStrToEntity function (winsnmp.h)

[SNMP is available for use in the operating systems specified in the Requirements section. It may be altered or unavailable in subsequent versions. Instead, use Windows Remote Management, which is the Microsoft implementation of WS-Man.]

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

Syntax

HSNMP_ENTITY SNMPAPI_CALL SnmpStrToEntity(
  [in] HSNMP_SESSION session,
  [in] LPCSTR        string
);

Parameters

[in] session

Handle to the WinSNMP session.

[in] 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 value

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.

Return 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 Support for IPX Address Strings in WinSNMP and Setting the Entity and Context Translation Mode.

The WinSNMP 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 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 application can change the setting of the entity and context translation mode with a call to the SnmpSetTranslateMode function.

Requirements

   
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header winsnmp.h
Library Wsnmp32.lib
DLL Wsnmp32.dll

See also

SnmpDecodeMsg

SnmpEncodeMsg

SnmpFreeEntity

SnmpRecvMsg

SnmpRegister

SnmpSendMsg

SnmpSetTranslateMode

SnmpStartup

WinSNMP Functions

WinSNMP API Overview