SnmpCreateVbl

[This is preliminary documentation and subject to change.]

The WinSNMP SnmpCreateVbl function creates a new variable bindings list for the calling WinSNMP manager 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. 

HSNMP_VBL SnmpCreateVbl(
  HSNMP_SESSION session,  // handle to the WinSNMP session 
  smiLPCOID name,         // pointer to the variable name 
  smiLPCVALUE value       // pointer to the value to associate
                          // with the variable 
);

Parameters

session
Handle to the WinSNMP session.
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.
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 Values

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.

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

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, SnmpDuplicateVbl, SnmpFreeVbl, smiOID, smiVALUE