SnmpCreateSession 函式 (winsnmp.h)

發行項
03/04/2024

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

SnmpCreateSession 函式會要求 Microsoft WinSNMP 實作來開啟 WinSNMP 應用程式的會話。應用程式可以指定實作如何通知 WinSNMP 會話可用的SNMP訊息和異步事件。應用程式可以指定視窗通知訊息或 SNMPAPI_CALLBACK 函式來通知工作階段。

SnmpCreateSession 函式是 WinSNMP API 2.0 版的元素。開發新的 WinSNMP 應用程式時，建議您呼叫 SnmpCreateSession 來開啟 WinSNMP 會話，而不是呼叫 SnmpOpen 函式。

語法

HSNMP_SESSION SNMPAPI_CALL SnmpCreateSession(
  [in] HWND             hWnd,
  [in] UINT             wMsg,
  [in] SNMPAPI_CALLBACK fCallBack,
  [in] LPVOID           lpClientData
);

參數

[in] hWnd

處理 WinSNMP 應用程式的視窗，以在異步要求完成時或發生陷阱通知時通知。工作階段的視窗通知訊息需要此參數。

[in] wMsg

指定不帶正負號的整數，識別要傳送至 WinSNMP 應用程式視窗的通知訊息。工作階段的視窗通知訊息需要此參數。

[in] fCallBack

指定應用程式定義的會話特定 SNMPAPI_CALLBACK 函式的位址。實作會在有通知可用時呼叫此函式，以通知 WinSNMP 會話。

需要這個參數，才能指定會話的回呼通知。此參數必須是 NULL ，才能指定工作階段的視窗通知訊息。如需詳細資訊，請參閱下列一節。

[in] lpClientData

要傳遞至 fCallback 參數所指定回呼函式的應用程式定義數據指標。此參數是選擇性的，可以是 NULL。如果 fCallback 參數為 NULL，則實作會忽略此參數。

傳回值

如果函式成功，傳回值就是識別呼叫應用程式實作開啟之 WinSNMP 會話的句柄。

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

傳回碼	Description
SNMPAPI_NOT_INITIALIZED	SnmpStartup 函式未順利完成。
SNMPAPI_ALLOC_ERROR	記憶體配置期間發生錯誤。
SNMPAPI_HWND_INVALID	fCallback 參數為 NULL，但 hWnd 參數不是有效的視窗句柄。
SNMPAPI_MESSAGE_INVALID	fCallback 參數為 NULL，但 wMsg 參數不是有效的訊息值。
SNMPAPI_MODE_INVALID	fCallback 參數為 NULL，且 hWnd 和 wMsg 參數個別有效。不過，這些值在 Windows 平臺上相互不相容。
SNMPAPI_OPERATION_INVALID	參數值的組合不會指定回呼通知或視窗通知訊息。
SNMPAPI_OTHER_ERROR	發生未知或未定義的錯誤。

備註

SnmpCreateSession 函式會傳回呼叫 WinSNMP 應用程式內每個開啟 WinSNMP 會話的唯一句柄。應用程式必須使用 SnmpCreateSession 在其他 WinSNMP 函式呼叫中傳回的會話句柄，以協助實作配置和解除分配資源。

建議 WinSNMP 應用程式針對實作開啟的每個會話呼叫 SnmpClose 函式一次，因為呼叫 SnmpCreateSession 函式 。如果 WinSNMP 應用程式意外終止，它必須先呼叫 SnmpCleanup ，才能終止，才能讓實作解除分配所有資源。

回呼通知

如果 fCallback 參數在成功呼叫 SnmpCreateSession 函式時不是 NULL，則實作會使用 fCallback 參數所指定的回呼函式，將會話警示給通知。

以下是 對 SnmpCreateSession 函式的呼叫範例，要求實作使用回呼通知向會話發出訊息和事件的訊號。

hSession = SnmpCreateSession (0, 0, myFunc, <NULL|myData>);

視窗通知訊息

SnmpCreateSession 函式會將句柄傳遞給應用程式視窗和通知訊息識別碼的實作。當應用程式視窗收到 wMsg 參數指定的通知訊息時，WinSNMP 應用程式必須擷取傳入通訊協定數據單位 (PDU) 。應用程式會呼叫 SnmpRecvMsg 函式，並使用 SnmpCreateSession 所傳回的會話句柄來執行此動作。

一個 WinSNMP 應用程式可以開啟多個 WinSNMP 會話。如果應用程式使用相同的視窗句柄開啟多個會話，建議 WinSNMP 應用程式為每個會話指定唯一 的 wMsg 參數。

以下是 對 SnmpCreateSession 函式的呼叫範例，要求實作會使用視窗通知訊息來通知會話有關訊息和事件的訊號。

hSession = SnmpCreateSession (myWnd, myMsg, NULL, NULL);

規格需求

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