SnmpDecodeMsg 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 SnmpDecodeMsg function decodes an encoded SNMP message into its components. This function performs the opposite action of the WinSNMP SnmpEncodeMsg function.
Syntax
SNMPAPI_STATUS SNMPAPI_CALL SnmpDecodeMsg(
[in] HSNMP_SESSION session,
[out] LPHSNMP_ENTITY srcEntity,
[out] LPHSNMP_ENTITY dstEntity,
[out] LPHSNMP_CONTEXT context,
[out] LPHSNMP_PDU pdu,
[in] smiLPCOCTETS msgBufDesc
);
Parameters
[in] session
Handle to the WinSNMP session. This parameter is required. For additional information, see the following Remarks section.
[out] srcEntity
Pointer to a variable that receives a handle to the source management entity. For more information, see the following Remarks section.
[out] dstEntity
Pointer to a variable that receives a handle to the target management entity. For more information, see the following Remarks section.
[out] context
Pointer to a variable that receives a handle to the context (a set of managed object resources) that the target management entity controls.
[out] pdu
Pointer to a variable that receives a handle to the SNMP protocol data unit (PDU).
[in] msgBufDesc
Pointer to an smiOCTETS structure that contains the SNMP message to decode into its components. The len member of the structure specifies the maximum number of bytes to process; the ptr member points to the encoded SNMP message.
Return value
If the function succeeds, the return value is the number of decoded bytes. This value can be equal to, or less than, the len member of the smiOCTETS structure pointed to by the msgBufDesc parameter.
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. |
|
One or both of the entity parameters is invalid. |
|
The context parameter is invalid. |
|
The pdu parameter is invalid. |
|
The output buffer length is insufficient. No output parameters were created. |
|
The SNMP message format in the buffer indicated by the msgBufDesc parameter is invalid. No output parameters were created. |
|
An unknown or undefined error occurred. |
Remarks
The Microsoft WinSNMP implementation returns a value of zero in the srcEntity and the dstEntity parameters when an application submits an SNMPv1 or an SNMPv2C message to the SnmpDecodeMsg function. This is because the message format does not include the address information necessary to create WinSNMP entity resources.
The Microsoft WinSNMP implementation allocates resources to the WinSNMP application as a result of a successful call to the SnmpDecodeMsg function. It is recommended that the WinSNMP application free individual resources with the WinSNMP function that corresponds to the resource. For additional information, see Freeing WinSNMP Descriptors and WinSNMP Data Management Concepts.
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 |