SnmpContextToStr

[This is preliminary documentation and subject to change.]

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. 

SNMPAPI_STATUS SnmpContextToStr(
  HSNMP_CONTEXT context,  // handle to the context 
  smiLPOCTETS string      // pointer to a structure to receive the
                          // context string 
);

Parameters

context
Handle to the SNMP context of interest.
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 Values

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.

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

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, SnmpFreeDescriptor, smiOCTETS