SnmpStrToContext function (winsnmp.h)

Article
10/13/2021

[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 SnmpStrToContext function returns a handle to SNMP context information that is specific to the Microsoft WinSNMP implementation. The handle is a valid value that a WinSNMP application can use as the context parameter in a call to the SnmpSendMsg and SnmpRegister functions.

Syntax

HSNMP_CONTEXT SNMPAPI_CALL SnmpStrToContext(
  [in] HSNMP_SESSION session,
  [in] smiLPCOCTETS  string
);

Parameters

[in] session

Handle to the WinSNMP session.

[in] string

Pointer to an smiOCTETS structure that contains a string to interpret. The string can identify a collection of managed objects, or it can be a community string.

The current setting of the entity and context translation mode determines the way SnmpStrToContext interprets the input string structure as shown in the following table.

Entity/Context Translation Mode	Meaning
SNMPAPI_TRANSLATED	The implementation interprets the string parameter as a user-friendly name for a collection of managed objects. 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 community string.
SNMPAPI_UNTRANSLATED_V2	The implementation interprets the string parameter as a literal SNMP community string.

Return value

If the function succeeds, the return value is a handle to the context 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_CONTEXT_INVALID	The string parameter format is invalid. For example, the len member or the ptr member of the smiOCTETS structure pointed to by the string parameter is NULL.
SNMPAPI_CONTEXT_UNKNOWN	The value referenced in the string parameter does not exist.
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 SnmpStrToContext interprets the input string structure. For additional information, see Setting the Entity and Context Translation Mode.

The WinSNMP application must call the SnmpFreeContext function to release the context handle allocated by the SnmpStrToContext function. For additional information about releasing resources, see WinSNMP Data Management Concepts.

The WinSNMP application should free the memory associated with the ptr member of the smiOCTETS structure pointed to by the string parameter. This is because the application defines and allocates the resources. For example, if the application allocated resources with a call to the GlobalAlloc function, it should use the GlobalFree function to deallocate the resources. For additional information, see Freeing WinSNMP Descriptors.

Requirements

Requirement	Value
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