| Platform SDK: Network Management |
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.
HSNMP_CONTEXT SnmpStrToContext( HSNMP_SESSION session, // handle to the WinSNMP session smiLPCOCTETS string // pointer to a string structure );
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. |
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. |
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.
Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.
WinSNMP API Overview, WinSNMP Functions, SnmpSendMsg, SnmpRegister, SnmpFreeDescriptor, SnmpFreeContext, smiOCTETS