SnmpEncodeMsg

[This is preliminary documentation and subject to change.]

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 manager application in the buffer specified by the msgBufDesc parameter. 

SNMPAPI_STATUS SnmpEncodeMsg(
  HSNMP_SESSION session,     // handle to the WinSNMP session 
  HSNMP_ENTITY srcEntity,    // handle to the source entity 
  HSNMP_ENTITY dstEntity,    // handle to the target entity 
  HSNMP_CONTEXT context,     // handle to the context 
  HSNMP_PDU pdu,             // handle to the PDU 
  smiLPOCTETS msgBufDesc     // pointer to the message buffer 
);

Parameters

session
Handle to the WinSNMP session.
srcEntity
Handle to the management entity that initiates the request to encode the SNMP message.
dstEntity
Handle to the target management entity.
context
Handle to the context (a set of managed object resources) that the target management entity controls.
PDU
Handle to the PDU that contains the SNMP operation request.
msgBufDesc
Pointer to an smiOCTETS structure that receives the encoded SNMP message.

Return Values

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.

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

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, SnmpDecodeMsg, SnmpSendMsg, smiOCTETS