SnmpCreatePdu

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpCreatePdu function creates and initializes an SNMP protocol data unit (PDU). 

HSNMP_PDU SnmpCreatePdu(
  HSNMP_SESSION session, // handle to the WinSNMP session 
  smiINT PDU_type,       // PDU type 
  smiINT32 request_id,   // PDU request identifier 
  smiINT error_status,   // valid only for SNMP_PDU_GETBULK requests
  smiINT error_index,    // valid only for SNMP_PDU_GETBULK requests
  HSNMP_VBL varbindlist  // handle to the variable bindings list 
);

Parameters

session
Handle to the WinSNMP session.
PDU_type
Specifies a PDU type that identifies the SNMP operation. This parameter can be NULL, or it can be one of the following values. If this parameter is NULL, the Microsoft WinSNMP implementation supplies the default PDU type SNMP_PDU_GETNEXT.
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_V1TRAP Alerts the management system to an extraordinary event under the SNMP version 1 (SNMPv1) framework. This type is obsolete in SNMP version 2C (SNMPv2C).
SNMP_PDU_GETBULK Search and retrieve multiple values with a single request.
SNMP_PDU_TRAP Alerts the management system to an event under SNMPv2C.

request_id
Specifies a unique numeric value that the WinSNMP manager application supplies to identify the PDU. If this parameter is NULL, the implementation assigns a value.
error_status
If the PDU_type parameter is equal to SNMP_PDU_GETBULK, this parameter specifies a value for the non_repeaters field of the PDU. This parameter is ignored for other PDU types, and the implementation sets the value of this parameter to SNMP_ERROR_NOERROR. This parameter can be NULL.
error_index
If the PDU_type parameter is equal to SNMP_PDU_GETBULK, this parameter specifies a value for the max_repetitions field of the PDU. This parameter is ignored for other PDU types, and the implementation sets the value of this parameter to zero. This parameter can be NULL.
varbindlist
Handle to a structure that represents an SNMP variable bindings list. This parameter can be NULL.

Return Values

If the function succeeds, the return value is the handle to a new SNMP PDU.

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_SESSION_INVALID The session handle is invalid.
SNMPAPI_PDU_INVALID The PDU type is invalid.
SNMPAPI_VBL_INVALID The variable bindings list is invalid.
SNMPAPI_OTHER_ERROR An unknown or undefined error occurred.

Remarks

A WinSNMP manager application must create a PDU before it calls the SnmpSendMsg or the SnmpEncodeMsg functions.

All of the parameters of the SnmpCreatePdu function are required. However, all parameters, except the session parameter, can be NULL. In this instance, the new PDU has the following default values.

Field Contents
PDU_type SNMP_PDU_GETNEXT
request_id The implementation generates a numeric value.
error_status SNMP_ERROR_NOERROR
error_index 0
varbindlist NULL

The application must call the SnmpFreePdu function to release the resources that the SnmpCreatePdu function allocates for the new PDU.

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, SnmpFreePdu, SnmpSendMsg, SnmpEncodeMsg