snmpRecvMsg 函式 (winsnmp.h)

發行項
03/13/2024

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

WinSNMP SnmpRecvMsg 函 式會擷取 SnmpSendMsg 函式呼叫所提交之已完成異步要求的結果，格式為 SNMP 訊息。 SnmpRecvMsg 函式也會傳回針對 WinSNMP 工作階段註冊的未處理陷阱數據和通知。

語法

SNMPAPI_STATUS SNMPAPI_CALL SnmpRecvMsg(
  [in]  HSNMP_SESSION   session,
  [out] LPHSNMP_ENTITY  srcEntity,
  [out] LPHSNMP_ENTITY  dstEntity,
  [out] LPHSNMP_CONTEXT context,
  [out] LPHSNMP_PDU     PDU
);

參數

[in] session

WinSNMP 會話的句柄。

[out] srcEntity

接收傳送訊息之實體句柄的變數指標。請注意，SnmpRegister 函式的 srcEntity 參數會指定註冊陷阱通知的管理實體句柄。

[out] dstEntity

接收接收訊息之實體句柄之變數的指標。請注意，SnmpRegister 函式的 dstEntity 參數會指定傳送陷阱的管理實體句柄。

[out] context

接收內容句柄的變數指標，這是一組 Managed 物件資源。 srcEntity 參數指定的實體會發出來自此內容的訊息。

[out] PDU

接收訊息之通訊協議數據單位句柄的變數指標， (PDU) 元件。

傳回值

如果函式成功，傳回值會SNMPAPI_SUCCESS，而輸出參數會包含上述參數描述中所指出的值。

如果函式失敗，傳回值會SNMPAPI_FAILURE。如果函式失敗，並出現指出網路傳輸層錯誤的擴充錯誤碼，也就是開頭為 SNMPAPI_TL_ 的錯誤碼，輸出參數也會包含先前指示的值，讓 WinSNMP 應用程式能夠正常復原。

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

傳回碼	Description
SNMPAPI_NOT_INITIALIZED	SnmpStartup 函式未順利完成。
SNMPAPI_ALLOC_ERROR	記憶體配置期間發生錯誤。
SNMPAPI_SESSION_INVALID	會話參數無效。
SNMPAPI_NOOP	指定的工作階段目前在其佇列中沒有訊息。
SNMPAPI_TL_NOT_INITIALIZED	網路傳輸層未初始化。
SNMPAPI_TL_NOT_SUPPORTED	網路傳輸層不支援SNMP通訊協定。
SNMPAPI_TL_NOT_AVAILABLE	網路子系統失敗。
SNMPAPI_TL_RESOURCE_ERROR	網路傳輸層發生資源錯誤。
SNMPAPI_TL_UNDELIVERABLE	dstEntity 參數指定的實體無法使用。
SNMPAPI_TL_SRC_INVALID	srcEntity 參數指定的實體未初始化。
SNMPAPI_TL_INVALID_PARAM	網路傳輸層函式呼叫收到無效的輸入參數。
SNMPAPI_TL_PDU_TOO_BIG	PDU 太大，網路傳輸層無法傳送或接收。
SNMPAPI_TL_OTHER	發生未定義的網路傳輸層錯誤。
SNMPAPI_OTHER_ERROR	發生未知或未定義的錯誤。

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

備註

SnmpCreateSession 函式會將應用程式視窗句柄和通知訊息標識碼傳遞給 Microsoft WinSNMP 實作。當應用程式視窗收到 wMsg 參數指定的通知訊息時，WinSNMP 應用程式必須使用 SnmpCreateSession 所傳回的會話句柄呼叫 SnmpRecvMsg 函式，以擷取傳入通訊協定數據單位 (PDU) 。如需詳細資訊，請參閱關於SNMP 訊息。

SnmpRecvMsg 函式會具現化四個物件，並配置其資源：兩個實體句柄、一個內容句柄和一個 PDU 句柄。在 WinSNMP 應用程式呼叫 SnmpGetPduData 函式之前，不會具現化傳回 PDU 之變數系結清單元件的句柄。當不再需要 SnmpRecvMsg 傳回的資源時，WinSNMP 應用程式必須使用對應至資源的 WinSNMP 函式釋放個別資源。如需詳細資訊，請參閱 SnmpFreePdu、 SnmpFreeEntity 和 SnmpFreeContext。

當實作從SNMP 第1版架構下運作的實體收到陷阱 (SNMPv1) 時，它會將陷阱轉譯為SNMP 第 2C 版 (SNMPv2C) 格式。因此， 當 SnmpRecvMsg 提供陷阱時，它一律為 SNMPv2C 格式。如需詳細資訊，請參閱將陷阱從 SNMPv1 轉譯為 SNMPv2C 和 WinSNMP 程式設計工作。

規格需求

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