SnmpEncodeMsg 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 Microsoft WinSNMP implementation uses the parameters passed in the WinSNMP SnmpEncodeMsg function to encode an SNMP message. The implementation returns the encoded SNMP message to the WinSNMP application in the buffer specified by the msgBufDesc parameter.

Syntax

SNMPAPI_STATUS SNMPAPI_CALL SnmpEncodeMsg(
  [in]  HSNMP_SESSION session,
  [in]  HSNMP_ENTITY  srcEntity,
  [in]  HSNMP_ENTITY  dstEntity,
  [in]  HSNMP_CONTEXT context,
  [in]  HSNMP_PDU     pdu,
  [out] smiLPOCTETS   msgBufDesc
);

Parameters

[in] session

Handle to the WinSNMP session.

[in] srcEntity

Handle to the management entity that initiates the request to encode the SNMP message.

[in] dstEntity

Handle to the target management entity.

[in] context

Handle to the context (a set of managed object resources) that the target management entity controls.

[in] pdu

Handle to the PDU that contains the SNMP operation request.

[out] msgBufDesc

Pointer to an smiOCTETS structure that receives the encoded SNMP message.

Return value

If the function succeeds, the return value is the length, in bytes, of the encoded SNMP message. This number is also the value of the len member of the smiOCTETS structure pointed to by the msgBufDesc parameter.

If the function fails, the return value is SNMPAPI_FAILURE. For additional information, see the following Remarks section. 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_SESSION_INVALID
The session parameter is invalid.
SNMPAPI_ENTITY_INVALID
One or both of the entity parameters is invalid.
SNMPAPI_CONTEXT_INVALID
The context parameter is invalid.
SNMPAPI_PDU_INVALID
The pdu parameter is invalid.
SNMPAPI_OTHER_ERROR
An unknown or undefined error occurred.

Remarks

The first five parameters passed to the SnmpEncodeMsg function are the same parameters that are passed to the SnmpSendMsg function.

The WinSNMP application must call the SnmpFreeDescriptor function to free resources allocated for the ptr member of the smiOCTETS structure. This is the structure pointed to by the msgBufDesc parameter. For additional information, see WinSNMP Data Management Concepts.

On input, the SnmpEncodeMsg function ignores the members of the structure pointed to by the msgBufDesc parameter. The implementation overwrites the members of the structure if the function completes successfully.

The implementation verifies the format of the first five input parameters. If one of the parameters is invalid, SnmpEncodeMsg returns SNMPAPI_FAILURE, and SnmpGetLastError returns an extended error code.

Requirements

   
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

See also

SnmpDecodeMsg

SnmpFreeDescriptor

SnmpSendMsg

WinSNMP Functions

WinSNMP API Overview

smiOCTETS