SnmpStrToContext

[This is preliminary documentation and subject to change.]

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 manager application can use as the context parameter in a call to the SnmpSendMsg and SnmpRegister functions. 

HSNMP_CONTEXT SnmpStrToContext(
  HSNMP_SESSION session,  // handle to the WinSNMP session 
  smiLPCOCTETS string     // pointer to a string structure 
);

Parameters

session
Handle to the WinSNMP session.
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 Values

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.

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_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 manager 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 manager 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.

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, SnmpSendMsg, SnmpRegister, SnmpFreeDescriptor, SnmpFreeContext, smiOCTETS