SnmpContextToStr 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 SnmpContextToStr function returns a string that identifies an SNMP context, which is a set of managed object resources. The function returns the string in an smiOCTETS structure.

Syntax

SNMPAPI_STATUS SNMPAPI_CALL SnmpContextToStr(
  [in]  HSNMP_CONTEXT context,
  [out] smiLPOCTETS   string
);

Parameters

[in] context

Handle to the SNMP context of interest.

[out] string

Pointer to an smiOCTETS structure to receive the string that identifies the context of interest. The string can have a null-terminating byte.

Return value

If the function succeeds, the return value is SNMPAPI_SUCCESS.

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_CONTEXT_INVALID	The context parameter is invalid.
SNMPAPI_OTHER_ERROR	An unknown or undefined error occurred.

Remarks

The current setting of the entity and context translation mode determines the type of output string SnmpContextToStr returns. For additional information, see Setting the Entity and Context Translation Mode.

The WinSNMP application must provide the address of a valid smiOCTETS structure for the string parameter. If the SnmpContextToStr function completes successfully, the Microsoft WinSNMP implementation initializes the len and ptr members of the structure. The WinSNMP application must call the SnmpFreeDescriptor function to enable the implementation to free the resources for these members.

When the entity and context translation mode is SNMPAPI_TRANSLATED, and the entry exists in the implementation's database, the implementation returns the associated user-friendly name of the context. If an entry does not exist for the context name, SnmpContextToStr returns the SNMP community string.

When the entity and context translation mode is SNMPAPI_UNTRANSLATED_V1 or SNMPAPI_UNTRANSLATED_V2, the implementation also returns the SNMP community string.

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