SnmpStrToContext 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 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.
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 |
|---|---|
|
The SnmpStartup function did not complete successfully. |
|
An error occurred during memory allocation. |
|
The session parameter is 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. |
|
The value referenced in the string parameter does not exist. |
|
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 |