SnmpCreateVbl function (winsnmp.h)

Article
02/22/2024

[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 SnmpCreateVbl function creates a new variable bindings list for the calling WinSNMP application. If the name and value parameters are not NULL, SnmpCreateVbl uses their values to create the first variable binding entry for the new variable bindings list. The SnmpCreateVbl function returns a handle to the new variable bindings list and allocates any necessary memory for it.

Syntax

HSNMP_VBL SNMPAPI_CALL SnmpCreateVbl(
  [in] HSNMP_SESSION session,
  [in] smiLPCOID     name,
  [in] smiLPCVALUE   value
);

Parameters

[in] session

Handle to the WinSNMP session.

[in] name

Pointer to an smiOID structure that contains the variable name for the first variable binding entry. This parameter can be NULL. For additional information, see the following Remarks section.

[in] value

Pointer to an smiVALUE structure that contains a value to associate with the variable in the first variable binding entry. This parameter can be NULL. For additional information, see the following Remarks section.

Return value

If the function succeeds, the return value is a handle to a new variable bindings list.

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_SESSION_INVALID	The session handle is invalid.
SNMPAPI_OID_INVALID	The name parameter references an invalid smiOID structure.
SNMPAPI_SYNTAX_INVALID	The syntax member of the structure pointed to by the value parameter is invalid.
SNMPAPI_OTHER_ERROR	An unknown or undefined error occurred.

Remarks

The SnmpCreateVbl function uses the values of the name and value parameters to create and initialize the first variable binding entry of a new variable bindings list. If the name parameter is NULL, the Microsoft WinSNMP implementation ignores the value parameter and creates an empty variable bindings list.

If the name parameter is not NULL, but the value parameter is NULL, the implementation creates and initializes the first variable binding entry in the variable bindings list. It initializes the syntax member of the structure pointed to by the value parameter with the value SNMP_SYNTAX_NULL.

The WinSNMP application must release the resources associated with each variable bindings list. It should do this by matching each call to the SnmpCreateVbl and SnmpDuplicateVbl functions with a corresponding call to the SnmpFreeVbl function. To avoid memory leaks, a WinSNMP application must call SnmpFreeVbl before it reuses the handle to a variable bindings list in a subsequent call to SnmpCreateVbl or SnmpDuplicateVbl. For additional information, see 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