snmpGetVb 函式 (winsnmp.h)

發行項
03/15/2023

[SNMP 可用於需求一節中指定的作業系統。它在後續版本中可能會變更或無法使用。請改用 Windows 遠端系統管理，這是 WS-Man 的 Microsoft 實作。

WinSNMP 應用程式會呼叫 SnmpGetVb 函式，以從變數系結清單中擷取資訊。這個 WinSNMP 函式會從 index 參數所指定的變數系結專案擷取變數名稱及其相關聯的值。

語法

SNMPAPI_STATUS SNMPAPI_CALL SnmpGetVb(
  [in]  HSNMP_VBL  vbl,
  [in]  smiUINT32  index,
  [out] smiLPOID   name,
  [out] smiLPVALUE value
);

參數

[in] vbl

要擷取之變數系結清單的控制碼。

[in] index

指定要擷取之變數系結專案的不帶正負號長整數變數。此變數包含變數系結專案在變數系結清單中的位置。

此參數的有效值介於 1 到 n 的範圍內，其中 1 表示變數系結清單中的第一個變數系結專案，而 n 是清單中的專案總數。如需詳細資訊，請參閱下列一節。

[out] name

smiOID結構的指標，以接收變數系結專案的變數名稱。

[out] value

smiVALUE結構的指標，以接收與 name參數所識別之變數相關聯的值。

如果函式成功，value參數所指向之結構的語法成員可以是下列其中一種語法資料類型。如需詳細資訊，請參閱 RFC 1902，「簡單網路管理通訊協定第 2 版的管理資訊結構 (SNMPv2) 」。

語法資料類型	意義
SNMP_SYNTAX_INT	表示 32 位帶正負號的整數變數。
SNMP_SYNTAX_OCTETS	表示二進位或文字資料的八位字串變數。
SNMP_SYNTAX_Null	表示 Null 值。
SNMP_SYNTAX_OID	表示物件識別碼變數，此變數是最多 128 個子名稱的指派名稱。
SNMP_SYNTAX_INT32	表示 32 位帶正負號的整數變數。
SNMP_SYNTAX_IPADDR	表示 32 位網際網路位址變數。如果使用 SNMPv1 PDU 陷阱格式來表示 IPv6 位址，則此值為 0.0.0.0。
SNMP_SYNTAX_CNTR32	指出計數器變數，直到達到最大值 (2^32) - 1 為止。
SNMP_SYNTAX_GAUGE32	表示量測計變數，此變數是可以增加或減少的非負整數，但永遠不會超過最大值。
SNMP_SYNTAX_TIMETICKS	指出計數器變數，測量秒數百分之一的時間，直到達到最大值 (2^32) – 1 為止。它是相對於特定計時器事件的非負整數。
SNMP_SYNTAX_OPAQUE	此類型提供回溯相容性，不應用於新的物件類型。它支援傳遞任意抽象語法標記法 One (ASN.1) 語法的功能。
SNMP_SYNTAX_CNTR64	指出計數器變數，直到達到最大值 2^64 () - 1 為止。
SNMP_SYNTAX_UINT32	表示 32 位不帶正負號的整數變數。
SNMP_SYNTAX_NOSUCHOBJECT	表示代理程式不支援對應至變數的物件類型。
SNMP_SYNTAX_NOSUCHINSTANCE	表示作業的物件實例不存在。
SNMP_SYNTAX_ENDOFMIBVIEW	指出 WinSNMP 應用程式嘗試參考物件識別碼，該識別碼超出代理程式所支援的 MIB 樹狀結構結尾。

傳回值

如果函式成功，傳回值會SNMPAPI_SUCCESS。

如果函式失敗，傳回值會SNMPAPI_FAILURE。若要取得擴充的錯誤資訊，請呼叫 SnmpGetLastError。 SnmpGetLastError函式可以傳回下列其中一個錯誤。

傳回碼	描述
SNMPAPI_NOT_INITIALIZED	SnmpStartup函式未順利完成。
SNMPAPI_ALLOC_ERROR	記憶體配置期間發生錯誤。
SNMPAPI_INDEX_INVALID	索引參數無效。
SNMPAPI_VBL_INVALID	vbl參數無效。
SNMPAPI_OTHER_ERROR	發生未知或未定義的錯誤。

備註

最後三種語法類型描述 SNMP 第 2C 版 (SNMPv2C) 架構下的例外狀況。

SnmpGetVb函式會傳回name參數所指向結構中變數系結專案的變數名稱。它會傳回 value 參數所指向之結構中的變數相關聯值。

在輸入時，SnmpGetVb函式會分別忽略名稱與值參數所指向之 smiOID和smiVALUE結構的成員。如果函式成功完成，Microsoft WinSNMP 實作就會覆寫成員。

要用於索引參數的 WinSNMP 應用程式的有效值如下所示：

從對 SnmpCountVbl函式的呼叫傳回值
SNMP_PDU_RESPONSE 通訊協定 資料單位的錯誤索引欄位， (PDU) 呼叫 SnmpRecvMsg 函式所傳回

WinSNMP 應用程式必須呼叫SnmpFreeDescriptor函式，以釋放為名稱參數所指向之 smiOID結構ptr成員所配置的資源。應用程式也必須呼叫SnmpFreeDescriptor函式，以在下列情況下釋放值參數所指向之 smiVALUE結構所配置的資源。如果值成員是 smiOCTETS 或 smiOID 結構，應用程式必須呼叫 SnmpFreeDescriptor 以釋放配置給這些結構的資源。如需詳細資訊，請參閱WinSNMP 資料管理概念。

規格需求


最低支援的用戶端	Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	winsnmp.h
程式庫	Wsnmp32.lib
Dll	Wsnmp32.dll