SnmpGetVb 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.]

A WinSNMP application calls the SnmpGetVb function to retrieve information from a variable bindings list. This WinSNMP function retrieves a variable name and its associated value from the variable binding entry specified by the index parameter.

Syntax

SNMPAPI_STATUS SNMPAPI_CALL SnmpGetVb(
  HSNMP_VBL  vbl,
  smiUINT32  index,
  smiLPOID   name,
  smiLPVALUE value
);

Parameters

vbl

Handle to the variable bindings list to retrieve.

index

Specifies an unsigned long integer variable that identifies the variable binding entry to retrieve. This variable contains the position of the variable binding entry, within the variable bindings list.

Valid values for this parameter are in the range from 1 to n, where 1 indicates the first variable binding entry in the variable bindings list, and n is the total number of entries in the list. For additional information, see the following Remarks section.

name

Pointer to an smiOID structure to receive the variable name of the variable binding entry.

value

Pointer to an smiVALUE structure to receive the value associated with the variable identified by the name parameter.

If the function succeeds, the syntax member of the structure pointed to by the value parameter can be one of the following syntax data types. For additional information, see RFC 1902, "Structure of Management Information for Version 2 of the Simple Network Management Protocol (SNMPv2)."

Syntax data type Meaning
SNMP_SYNTAX_INT
Indicates a 32-bit signed integer variable.
SNMP_SYNTAX_OCTETS
Indicates an octet string variable that is binary or textual data.
SNMP_SYNTAX_NULL
Indicates a NULL value.
SNMP_SYNTAX_OID
Indicates an object identifier variable that is an assigned name with a maximum of 128 subidentifiers.
SNMP_SYNTAX_INT32
Indicates a 32-bit signed integer variable.
SNMP_SYNTAX_IPADDR
Indicates a 32-bit Internet address variable. If SNMPv1 PDU trap format is used to represent an IPv6 address, this value is 0.0.0.0.
SNMP_SYNTAX_CNTR32
Indicates a counter variable that increases until it reaches a maximum value of (2^32) – 1.
SNMP_SYNTAX_GAUGE32
Indicates a gauge variable that is a non-negative integer that can increase or decrease, but never exceed a maximum value.
SNMP_SYNTAX_TIMETICKS
Indicates a counter variable that measures the time in hundredths of a second, until it reaches a maximum value of (2^32) – 1. It is a non-negative integer that is relative to a specific timer event.
SNMP_SYNTAX_OPAQUE
This type provides backward compatibility, and should not be used for new object types. It supports the capability to pass arbitrary Abstract Syntax Notation One (ASN.1) syntax.
SNMP_SYNTAX_CNTR64
Indicates a counter variable that increases until it reaches a maximum value of (2^64) – 1.
SNMP_SYNTAX_UINT32
Indicates a 32-bit unsigned integer variable.
SNMP_SYNTAX_NOSUCHOBJECT
Indicates that the agent does not support the object type that corresponds to the variable.
SNMP_SYNTAX_NOSUCHINSTANCE
Indicates that the object instance does not exist for the operation.
SNMP_SYNTAX_ENDOFMIBVIEW
Indicates the WinSNMP application is attempting to reference an object identifier that is beyond the end of the MIB tree that the agent supports.

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_INDEX_INVALID
The index parameter is invalid.
SNMPAPI_VBL_INVALID
The vbl parameter is invalid.
SNMPAPI_OTHER_ERROR
An unknown or undefined error occurred.

Remarks

The last three syntax types describe exception conditions under the SNMP version 2C(SNMPv2C) framework.

The SnmpGetVb function returns the variable name of the variable binding entry in the structure pointed to by the name parameter. It returns the variable's associated value in the structure pointed to by the value parameter.

On input, the SnmpGetVb function ignores the members of the smiOID and smiVALUE structures pointed to by the name and value parameters respectively. The Microsoft WinSNMP implementation overwrites the members if the function completes successfully.

Valid values for a WinSNMP application to use for the index parameter are as follows:

  • The return value from a call to the SnmpCountVbl function
  • The error index field of an SNMP_PDU_RESPONSE protocol data unit (PDU) returned by a call to the SnmpRecvMsg function
The WinSNMP application must call the SnmpFreeDescriptor function to free resources allocated for the ptr member of the smiOID structure pointed to by the name parameter. The application must also call the SnmpFreeDescriptor function to release resources allocated for the smiVALUE structure pointed to by the value parameter under the conditions following. If the value member is an smiOCTETS or an smiOID structure, the application must call SnmpFreeDescriptor to free the resources allocated for these structures. For additional information, see WinSNMP Data Management Concepts.

Requirements

   
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

SnmpCountVbl

SnmpFreeDescriptor

SnmpRecvMsg

WinSNMP Functions

WinSNMP API Overview

smiOCTETS

smiOID

smiVALUE