snmpExtensionQueryEx 函式 (snmp.h)

發行項
03/02/2024

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

Microsoft SNMP 服務會呼叫 SnmpExtensionQueryEx 函 式來處理 SNMP 要求，這些要求會在 SNMP 擴充代理程式所註冊的一或多個 MIB 子樹中指定變數。此函式是SNMP延伸模組代理程式 API 的元素。

注意建議您使用 SnmpExtensionQueryEx 函式，其支援 SNMP 第 2C 版 (SNMPv2C) 數據類型和多密碼 SNMP SET 作業。如果擴充代理程序導出 SnmpExtensionQueryEx函式，SNMP 服務就不會呼叫 SnmpExtensionQuery 函 式。

語法

BOOL SNMP_FUNC_TYPE SnmpExtensionQueryEx(
  [in]      UINT            nRequestType,
  [in]      UINT            nTransactionId,
  [in, out] SnmpVarBindList *pVarBindList,
  [in, out] AsnOctetString  *pContextInfo,
  [out]     AsnInteger32    *pErrorStatus,
  [out]     AsnInteger32    *pErrorIndex
);

參數

[in] nRequestType

指定SNMP服務要求擴充代理程式執行之作業的類型。此參數可以是下列其中一個值。

值	意義
SNMP_EXTENSION_GET	擷取指定變數的值或值。
SNMP_EXTENSION_GET_NEXT	擷取指定變數的語彙後續任務值。
SNMP_EXTENSION_SET_TEST	驗證指定變數的值。這項作業可最大化 COMMIT 要求期間成功寫入的機率。
SNMP_EXTENSION_SET_COMMIT	將新值寫入指定的變數。
SNMP_EXTENSION_SET_UNDO	在 COMMIT 要求之前，將指定變數的值重設為其值。
SNMP_EXTENSION_SET_CLEANUP	釋放先前要求和作業中配置的資源。

如需 SET 要求類型的詳細資訊，也就是開頭為 SNMP_EXTENSION_SET_ 的使用者，請參閱下列一節。

[in] nTransactionId

指定 DWORD 變數，這是傳入 SNMP 要求 PDU 的唯一識別碼。擴充代理程式可以使用此值，讓涉及相同 PDU 的 SNMP 服務相互關聯多個呼叫。

[in, out] pVarBindList

包含感興趣變數的變數系結清單指標。

[in, out] pContextInfo

包含使用者定義內容資訊的八位字串指標。

擴充代理程式可以使用此參數來儲存在多密碼 SNMP SET 作業期間所使用的內容資訊。擴充代理程式必須在 CLEANUP 要求期間釋放與此參數相關聯的資源。 SNMP 服務不會釋放與此參數相關聯的任何資源。如需詳細資訊，請參閱下列一節。

[out] pErrorStatus

要接收錯誤狀態結果之變數的指標。此參數可以是SNMPv2C所定義的下列其中一個值。

錯誤碼	意義
SNMP_ERRORSTATUS_NOERROR	代理程式會報告傳輸期間未發生任何錯誤。
SNMP_ERRORSTATUS_TOOBIG	代理程式無法將要求SNMP作業的結果放入單一 SNMP 訊息中。
SNMP_ERRORSTATUS_NOSUCHNAME	要求的SNMP作業識別出未知的變數。
SNMP_ERRORSTATUS_BADVALUE	要求的SNMP作業嘗試變更變數，但指定語法或值錯誤。
SNMP_ERRORSTATUS_READONLY	要求的SNMP作業嘗試根據變數的社群配置檔變更不允許變更的變數。
SNMP_ERRORSTATUS_GENERR	在要求的SNMP作業期間，發生此處所列錯誤以外的錯誤。
SNMP_ERRORSTATUS_NOACCESS	無法存取指定的SNMP變數。
SNMP_ERRORSTATUS_WRONGTYPE	值指定與變數所需的類型不一致的類型。
SNMP_ERRORSTATUS_WRONGLENGTH	值會指定長度，該長度與變數所需的長度不一致。
SNMP_ERRORSTATUS_WRONGENCODING	值包含抽象語法表示法一 (ASN.1) 編碼，與欄位的 ASN.1 標籤不一致。
SNMP_ERRORSTATUS_WRONGVALUE	值無法指派給變數。
SNMP_ERRORSTATUS_NOCREATION	變數不存在，且代理程式無法建立它。
SNMP_ERRORSTATUS_INCONSISTENTVALUE	值與其他 Managed 物件的值不一致。
SNMP_ERRORSTATUS_RESOURCEUNAVAILABLE	將值指派給變數需要配置目前無法使用的資源。
SNMP_ERRORSTATUS_COMMITFAILED	未發生驗證錯誤，但未更新任何變數。
SNMP_ERRORSTATUS_UNDOFAILED	未發生驗證錯誤。某些變數已更新，因為無法復原其指派。
SNMP_ERRORSTATUS_AUTHORIZATIONERROR	發生授權錯誤。
SNMP_ERRORSTATUS_NOTWRITABLE	變數存在，但代理程式無法修改它。
SNMP_ERRORSTATUS_INCONSISTENTNAME	變數不存在;代理程式無法建立它，因為具名對象實例與其他 Managed 物件的值不一致。

[out] pErrorIndex

要接收錯誤索引結果之變數的指標。

傳回值

如果函式成功，則傳回值為 TRUE。

如果函式失敗，則傳回值為 FALSE。

備註

SNMP 服務會多次呼叫 SnmpExtensionQueryEx 函式，以處理傳入的 SNMP SET 要求。服務可以在測試要求階段、COMMIT 要求階段、UNDO 要求階段和 CLEANUP 要求階段呼叫 SnmpExtensionQueryEx 。

TEST 要求

SNMP 服務會先呼叫具有 dwRequestType 的 snmpExtensionQueryEx 函式 SNMP_EXTENSION_SET_TEST，以處理 SNMP SET 要求類型。服務會呼叫負責要求中變數系結的每個擴充代理程式。每個擴充代理程式都必須驗證變數系結清單中的變數。他們可以選擇性地將下列要求所需的任何內容資訊儲存在 pContextInfo 參數所指向的變數中。

如果 TEST 要求失敗，服務會起始 CLEANUP 要求。服務會呼叫先前使用SnmpExtensionQueryEx函式再次傳回 TEST 要求的擴充代理程式。服務會使用 SNMP_EXTENSION_SET_CLEANUP dwRequestType 呼叫每個擴充代理程式。

COMMIT 要求

如果所有擴充代理程式都傳回 TEST 要求，SNMP 服務會使用 SNMP_EXTENSION_SET_COMMIT dwRequestType，使用 SnmpExtensionQueryEx 函式呼叫每個擴充代理程式。服務會傳回延伸模組代理程序傳遞給服務的擴充代理程式內容資訊。這是在 TEST 要求期間，延伸模組代理程式在 pContextInfo 參數中傳遞的內容資訊。擴充代理程式可以使用內容資訊，以檢測特定方式更新指定變數的值。

如果延伸模組代理程式支持復原處理，它現在可以更新 pContextInfo 參數中的內容資訊。 SNMP 服務會在 UNDO 要求期間將資訊傳回延伸模組代理程式。

如果所有擴充代理程式都傳回 TRUE 給 COMMIT 要求，服務會使用 SNMP_EXTENSION_SET_CLEANUP dwRequestType，以 SnmpExtensionQueryEx 函式呼叫每個擴充代理程式。

如果有任何擴充代理程序失敗 COMMIT 要求，服務也會起始 CLEANUP 要求。服務會呼叫先前使用SnmpExtensionQueryEx函式再次傳回 COMMIT 要求的每個擴充代理程式。服務會使用 SNMP_EXTENSION_SET_CLEANUP dwRequestType 呼叫每個擴充代理程式。

CLEANUP 要求

服務會在 TEST 或 COMMIT 要求期間傳回 pContextInfo 參數中傳遞的內容資訊給延伸模組代理程式。擴充代理程式目前必須釋放與參數相關聯的資源。

UNDO 要求

如果有任何擴充代理程式將 FALSE 傳回 COMMIT 要求，SNMP 服務就會終止 COMMIT 要求。服務會呼叫每個傳回 TRUE 給 COMMIT 要求的擴充代理程式，其 dwRequestType 為 SNMP_EXTENSION_SET_UNDO。這表示擴充代理程序認可要求失敗，而且必須起始復原處理。

擴充代理程式必須嘗試重設感興趣的變數值，再重設為在 COMMIT 要求失敗之前的值。若要這樣做，擴充代理程式會在 COMMIT 要求期間使用 pContextInfo 參數中傳回的內容資訊。

如果有任何擴充代理程式將 FALSE 傳回 UNDO 要求，整個 SET 作業就會失敗，並出現錯誤碼SNMP_ERRORSTATUS_UNDOFAILED。如果所有擴充代理程式都會將 TRUE 傳回 UNDO 要求，SNMP SET 作業會失敗，而擴充代理程式所設定的錯誤碼會失敗 COMMIT 要求。

在 UNDO 要求之後，服務一律使用 snmpExtensionQueryEx 函 式呼叫每個擴充代理程式，並使用 SNMP_EXTENSION_SET_CLEANUP dwRequestType。

規格需求

需求	值
最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
目標平台	Windows
標頭	snmp.h