Edit

Share via

SnmpGetPduData function (winsnmp.h)

  • Article

[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 SnmpGetPduData function returns selected data fields from a specified SNMP protocol data unit (PDU).

Syntax

SNMPAPI_STATUS SNMPAPI_CALL SnmpGetPduData(
  [in]  HSNMP_PDU   PDU,
  [out] smiLPINT    PDU_type,
  [out] smiLPINT32  request_id,
  [out] smiLPINT    error_status,
  [out] smiLPINT    error_index,
  [out] LPHSNMP_VBL varbindlist
);

Parameters

[in] PDU

Handle to the SNMP PDU.

[out] PDU_type

Pointer to a variable that receives the PDU_type field of the specified PDU. This parameter can be NULL, or one of the following values.

Value Meaning
SNMP_PDU_GET
Search and retrieve a value from a specified SNMP variable.
SNMP_PDU_GETNEXT
Search and retrieve the value of an SNMP variable without knowing the exact name of the variable.
SNMP_PDU_RESPONSE
Reply to an SNMP_PDU_GET or an SNMP_PDU_GETNEXT request.
SNMP_PDU_SET
Store a value in a specified SNMP variable.
SNMP_PDU_GETBULK
Search and retrieve multiple values with a single request.
SNMP_PDU_TRAP
Alerts the management system to an extraordinary event under SNMPv2C.

[out] request_id

Pointer to a variable that receives the request_id field of the specified PDU. This parameter can be NULL.

[out] error_status

Pointer to a variable that receives the error_status field of the specified PDU. If the PDU_type parameter is equal to SNMP_PDU_GETBULK, this parameter receives the value of the non_repeaters field of the PDU.

This parameter can be NULL, or one of the following values. The first six errors are common to the SNMP version 1 (SNMPv1) and SNMP version 2C frameworks (SNMPv2C). The remaining errors are available under SNMPv2C only.

Error code Meaning
SNMP_ERROR_NOERROR
 The agent reports that no errors occurred during transmission.
SNMP_ERROR_TOOBIG
 The agent could not place the results of the requested SNMP operation into a single SNMP message.
SNMP_ERROR_NOSUCHNAME
 The requested SNMP operation identified an unknown variable.
SNMP_ERROR_BADVALUE
 The requested SNMP operation tried to change a variable but it specified either a syntax or value error.
SNMP_ERROR_READONLY
 The requested SNMP operation tried to change a variable that was not allowed to change, according to the community profile of the variable.
SNMP_ERROR_GENERR
 An error other than one of those listed here occurred during the requested SNMP operation.
SNMP_ERROR_NOACCESS
 The specified SNMP variable is not accessible.
SNMP_ERROR_WRONGTYPE
 The value specifies a type that is inconsistent with the type required for the variable.
SNMP_ERROR_WRONGLENGTH
 The value specifies a length that is inconsistent with the length required for the variable.
SNMP_ERROR_WRONGENCODING
 The value contains an Abstract Syntax Notation One (ASN.1) encoding that is inconsistent with the ASN.1 tag of the field.
SNMP_ERROR_WRONGVALUE
 The value cannot be assigned to the variable.
SNMP_ERROR_NOCREATION
 The variable does not exist, and the agent cannot create it.
SNMP_ERROR_INCONSISTENTVALUE
 The value is inconsistent with values of other managed objects.
SNMP_ERROR_RESOURCEUNAVAILABLE
 Assigning the value to the variable requires allocation of resources that are currently unavailable.
SNMP_ERROR_COMMITFAILED
 No validation errors occurred, but no variables were updated.
SNMP_ERROR_UNDOFAILED
 No validation errors occurred. Some variables were updated because it was not possible to undo their assignment.
SNMP_ERROR_AUTHORIZATIONERROR
 An authorization error occurred.
SNMP_ERROR_NOTWRITABLE
 The variable exists but the agent cannot modify it.
SNMP_ERROR_INCONSISTENTNAME
 The variable does not exist; the agent cannot create it because the named object instance is inconsistent with the values of other managed objects.

[out] error_index

Pointer to a variable that receives the error_index field of the specified PDU.

If the PDU_type parameter is equal to SNMP_PDU_GETBULK, this parameter receives the value of the max_repetitions field of the specified PDU. This parameter can be NULL.

[out] varbindlist

Pointer to a variable that receives a handle to the variable bindings list field of the specified PDU. This parameter can be NULL. For additional information, see the following Remarks section.

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_NOOP
 All output parameters are NULL. The SNMP operation was not performed.
SNMPAPI_PDU_INVALID
 The PDU type is invalid.
SNMPAPI_OTHER_ERROR
 An unknown or undefined error occurred.

Remarks

All parameters of the SnmpGetPduData function are required. However, all parameters, except the PDU parameter, can be NULL. In parameters that the application passes as NULL, the SnmpGetPduData function does not return a value.

The SnmpGetPduData function always returns a handle to a new variable bindings list object if the varbindlist parameter is not NULL. Additionally, if the PDU parameter specifies a new PDU, the function also attaches a handle to the new PDU.

When an application calls SnmpGetPduData with a varbindlist parameter that is not NULL, but the PDU parameter specifies an existing PDU, the function returns a handle to a new duplicate variable bindings list. The function call does not disturb the handle attached to the existing PDU. An existing PDU is one that an application creates with a call to the SnmpCreatePdu function, or one that the application receives and then reads using a call to SnmpGetPduData.

When an application creates a PDU with SnmpCreatePdu, or after the application reads a PDU using SnmpGetPduData, the Microsoft WinSNMP implementation expects that the application "knows" the values of the PDU fields. If an application reads a PDU a second time with SnmpGetPduData, the call results in a copy of the variable bindings list of the specified PDU. This type of call to SnmpGetPduData also duplicates the handle to the PDU.

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

See also

SnmpCreatePdu

SnmpDuplicateVbl

WinSNMP Functions

WinSNMP API Overview