snmpRegister 函式 (winsnmp.h)
[SNMP 可用於需求一節中指定的作業系統。 它在後續版本中可能會變更或無法使用。 請改用 Windows 遠端管理,這是 WS-Man 的 Microsoft 實作。
WinSNMP SnmpRegister 函式會註冊或取消註冊 WinSNMP 應用程式以進行陷阱和通知接收。 應用程式可以註冊和接收陷阱和通知,或取消註冊和停用陷阱和通知。
WinSNMP 應用程式可以根據 通知 參數的值,註冊或取消註冊一種類型的陷阱或通知,或針對所有陷阱和通知註冊。
語法
SNMPAPI_STATUS SNMPAPI_CALL SnmpRegister(
[in] HSNMP_SESSION session,
[in] HSNMP_ENTITY srcEntity,
[in] HSNMP_ENTITY dstEntity,
[in] HSNMP_CONTEXT context,
[in] smiLPCOID notification,
[in] smiUINT32 state
);
參數
[in] session
處理正在註冊或取消註冊陷阱和通知的 WinSNMP 工作階段。
[in] srcEntity
處理屬於註冊要求來源的管理實體。 此實體在SNMP 管理員角色中會接收陷阱或通知。
由於實作不會使用此參數來篩選到達 WinSNMP 應用程式的陷阱和通知,因此 WinSNMP 管理員應用程式通常會在此參數中傳遞 NULL 。
如果此參數為 NULL,Microsoft WinSNMP 實作會註冊或取消註冊所有陷阱和通知要求的來源。
請注意,SnmpRecvMsg 函式的 srcEntity 參數具有不同的角色。 在該函式中, srcEntity 會接收傳送陷阱之實體的句柄。
[in] dstEntity
處理屬於註冊要求收件者的管理實體。 此實體在SNMP代理程式角色中運作,將會傳送陷阱或通知。
如果此參數為 NULL,實作會註冊或取消註冊 WinSNMP 應用程式,以取得來自所有管理實體的陷阱和通知。
請注意,SnmpRecvMsg 函式的 dstEntity 參數會收到註冊陷阱通知的管理實體句柄。
[in] context
處理內容,這是一組Managed對象資源。
如果此參數為 NULL,則實作會註冊或取消註冊 WinSNMP 應用程式,以取得每個內容的陷阱和通知。
[in] notification
smiOID 結構的指標,其中包含一種陷阱或通知類型的模式比對順序。 實作會使用此順序來識別 WinSNMP 應用程式正在註冊或取消註冊的陷阱或通知類型。 如需詳細資訊,請參閱下列一節。
如果此參數為 NULL,實作會註冊或取消註冊 WinSNMP 應用程式,以取得 dstEntity 參數所指定之管理實體或實體的所有陷阱和通知。
[in] state
指定不帶正負號的長整數變數,指出 WinSNMP 應用程式是否正在註冊以接收陷阱和通知,或者是否要取消註冊。 此參數應該等於下列其中一個值,但如果它包含不同的值,則實作會註冊應用程式。
值 | 意義 |
---|---|
|
停用陷阱和通知。 |
|
註冊以接收陷阱和通知。 |
傳回值
如果函式成功,傳回值會SNMPAPI_SUCCESS。
如果函式失敗,傳回值會SNMPAPI_FAILURE。 若要取得擴充的錯誤資訊,請呼叫 SnmpGetLastError。 SnmpGetLastError 函式可能會傳回下列其中一個 WinSNMP 或網路傳輸層錯誤。
傳回碼 | Description |
---|---|
|
SnmpStartup 函式未順利完成。 |
|
記憶體配置期間發生錯誤。 |
|
會話參數無效。 |
|
一或兩個實體參數無效。 |
|
內容參數無效。 |
|
通知參數無效。 |
|
網路傳輸層未初始化,或無法啟動 SNMPTRAP.EXE 服務。 |
|
無法使用陷阱埠。 |
|
網路子系統失敗。 |
|
發生未知或未定義的錯誤。 |
如需詳細資訊,請參閱 網路傳輸錯誤。
備註
一般而言,WinSNMP 管理員應用程式而不是代理程式應用程式,會呼叫 SnmpRegister 函式。
請務必注意,對於不是系統管理員的使用者,只有在SNMP 陷阱服務啟動時, SnmpRegister 函式才會在 Windows 2000 和 Windows XP 上成功。
如果 WinSNMP 應用程式在 srcEntity、dstEntity、內容或通知參數中呼叫 SnmpRegister 函式時傳遞 NULL,則實作不會使用該參數來篩選到達 WinSNMP 應用程式的陷阱和通知。 如果應用程式在先前提及的所有參數中傳遞 NULL ,則實作會將所有已接收的通知傳遞給會話。
如果 WinSNMP 應用程式註冊以接收特定類型的陷阱或通知,則必須定義物件識別碼,也就是對應至該類型陷阱的 smiOID 結構。 通知參數必須指向這個結構。 RFC 1907:「簡單網路管理通訊協定第 2 版的管理資訊基底 (SNMPv2) 」,定義陷阱和通知對象標識碼。 如需詳細資訊,請參閱 管理陷阱和通知, 以及 將陷阱從SNMPv1轉譯至 SNMPv2C。
實作會使用 通知 參數的值做為模式,以符合收到的陷阱和通知。 例如,如果 WinSNMP 應用程式在 通知 參數中傳遞 n 個子識別碼,而接收的陷阱中的前 n 個子識別元符合所有傳遞的子標識符,則陷阱對象標識碼是相符專案。 如果收到的陷阱的減號少於 n,則對象標識碼不相符。 如果有相符項目,實作會將陷阱或通知傳送至 WinSNMP 應用程式。
如果任何或所有 dstEntity、 srcEntity 或 內容 參數都是 NULL,則實作可能需要針對該函式的對應參數,在後續呼叫 SnmpRecvMsg 函式時配置資源。 當 WinSNMP 應用程式不再需要 SnmpRecvMsg 傳回的資源時,應用程式必須使用對應至資源的函式釋放個別資源。 如需詳細資訊,請參閱 SnmpFreeEntity 和 SnmpFreeContext。
如需詳細資訊,請參閱 多個陷阱註冊。
規格需求
需求 | 值 |
---|---|
最低支援的用戶端 | Windows 2000 專業版 [僅限傳統型應用程式] |
最低支援的伺服器 | Windows 2000 Server [僅限傳統型應用程式] |
目標平台 | Windows |
標頭 | winsnmp.h |
程式庫 | Wsnmp32.lib |
Dll | Wsnmp32.dll |