snmpRegister 函式 (winsnmp.h)

發行項
03/13/2024

[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_OFF	停用陷阱和通知。
SNMPAPI_ON	註冊以接收陷阱和通知。

傳回值

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

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

傳回碼	Description
SNMPAPI_NOT_INITIALIZED	SnmpStartup 函式未順利完成。
SNMPAPI_ALLOC_ERROR	記憶體配置期間發生錯誤。
SNMPAPI_SESSION_INVALID	會話參數無效。
SNMPAPI_ENTITY_INVALID	一或兩個實體參數無效。
SNMPAPI_CONTEXT_INVALID	內容參數無效。
SNMPAPI_OID_INVALID	通知參數無效。
SNMPAPI_TL_NOT_INITIALIZED	網路傳輸層未初始化，或無法啟動 SNMPTRAP.EXE 服務。
SNMPAPI_TL_IN_USE	無法使用陷阱埠。
SNMPAPI_TL_NOT_AVAILABLE	網路子系統失敗。
SNMPAPI_OTHER_ERROR	發生未知或未定義的錯誤。

如需詳細資訊，請參閱網路傳輸錯誤。

備註

一般而言，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