eapHostPeerBeginSession 函式 (eappapis.h)

啟動 EAP 驗證會話。 如果 EapHostPeerBeginSession 函 式成功，呼叫端也必須呼叫 EapHostPeerEndSession 結束驗證會話。 不論 EapHostPeerBeginSession 以外的函式是否成功或失敗，都必須呼叫後者函式。

如果需要重新驗證，不論原因為何，參數 pConnectionId 所代表的介面都會取消註冊。 如果未註冊 pConnectionId ，您也必須呼叫 EapHostPeerClearConnection 來移除連線。

請勿在介面上再次呼叫 EapHostPeerBeginSession ，而不需呼叫 EapHostPeerEndSession。 pConnectionId所指定的介面上只能有一個驗證會話作用中。

語法

DWORD EapHostPeerBeginSession(
  [in]  DWORD                       dwFlags,
  [in]  EAP_METHOD_TYPE             eapType,
  [in]  const EapAttributes * const pAttributeArray,
  [in]  HANDLE                      hTokenImpersonateUser,
  [in]  DWORD                       dwSizeofConnectionData,
  [in]  const BYTE * const          pConnectionData,
  [in]  DWORD                       dwSizeofUserData,
  [in]  const BYTE * const          pUserData,
  [in]  DWORD                       dwMaxSendPacketSize,
  [in]  const GUID * const          pConnectionId,
  [in]  NotificationHandler         func,
  [in]  void                        *pContextData,
  [out] EAP_SESSIONID               *pSessionId,
  [out] EAP_ERROR                   **ppEapError
);

參數

[in] dwFlags

描述新 EAP 驗證會話行為的 EAP 旗標 組合。

[in] eapType

EAP_METHOD_TYPE結構，指定要用於此會話的 EAP 驗證類型。

[in] pAttributeArray

EapAttributes結構的指標，指定要驗證之實體的 EAP 屬性。

[in] hTokenImpersonateUser

要在此會話中使用的使用者模擬權杖控制碼。

[in] dwSizeofConnectionData

pConnectionData中提供之連接資料緩衝區的大小，以位元組為單位。

[in] pConnectionData

描述用於驗證的組態。 Null 連線資料會被視為有效。 方法應該使用預設組態。

[in] dwSizeofUserData

pUserData中提供之使用者資料緩衝區的大小，以位元組為單位。

[in] pUserData

位元組緩衝區的指標，其中包含不透明的使用者資料 BLOB，其中包含從 EapPeerGetIdentity 函式傳回的使用者資料。 使用者資料可能包含用於驗證的認證或憑證。 pUserData 可以是 Null。 Null指標的解譯取決於方法的實作。 使用者資料是由用於驗證的使用者或電腦認證所組成。 使用者資料通常取決於設定資料。

如果在dwflags中指出EAP_FLAG_PREFER_ALT_CREDENTIALS，則傳遞至EapPeerBeginSession的認證會優先用於所有其他形式的認證擷取，即使傳入pConnectionData的設定資料會要求不同的認證擷取模式。 如果將認證傳遞至 EapPeerBeginSession 失敗，則 EAPHost 會依賴方法特定的認證擷取，例如，從檔案、Windows 登入或憑證存放區取得認證。

EAP 方法作者會定義預設認證和替代認證。 例如，在 EAP-MSCHAPv2 預設認證是從 winlogon 取得的 Windows 認證，而替代認證是傳遞至 pUserData的使用者名稱、密碼、網域) 認證 (認證。

[in] dwMaxSendPacketSize

可在會話期間傳送之 EAP 封包的大小上限，以位元組為單位。

[in] pConnectionId

GUID 值的指標，可唯一識別邏輯網路介面，而該網路介面會透過該介面進行驗證。 如果建議者在 NAP 健康情況變更之後尋求重新驗證，它應該會提供唯一的 GUID。 當通道方法呼叫此函式以啟動其內部方法時，參數應該是 Null 。 當 pConnectionId 參數為 Null時， 會忽略 func 和 pCoNtextData 參數。

[in] func

NotificationHandler函式指標，提供 EAPHost 用來在需要重新驗證時通知支持對象的回呼。

如果函式處理常式為 Null，則會忽略 pCoNtextData 參數。 如果函式處理常式為 Null，這也表示呼叫端對 EAP 隔離強制執行用戶端的 SoH 變更通知不感興趣， (QEC) 。

下列程式碼顯示 NotificationHandler 回呼呼叫。

func(*pConnectionId, pContextData);

[in] pContextData

重新驗證內容資料的指標，當呼叫 func 時，建議者會與連接產生關聯。 此參數可以是 Null。

[out] pSessionId

EAP_SESSIONID結構的指標，其中包含 EAPHost 伺服器上這個 EAP 驗證會話的唯一控制碼。

[out] ppEapError

EAP_ERROR結構的位址指標。 在呼叫此函式之前，位址應該設定為 Null 。 如果有錯誤資料可用，就會收到包含此函式呼叫執行期間所引發之 錯誤之EAP_ERROR 結構的位址指標。 使用錯誤資料之後，請呼叫 EapHostPeerFreeEapError釋放此記憶體。

傳回值

無

備註

如果 EAPHost 成功參與 NAP，則建議者會回應其網路健康情況狀態的變更。 如果該狀態變更，則要求者必須接著起始重新驗證會話，如下所示。

• 如果發生重新驗證時有目前的會話，支援者應該藉由呼叫 EapHostPeerEndSession來終止目前的會話，然後藉由呼叫 EapHostPeerBeginSession來啟動新的會話。
• 如果沒有目前的會話發生重新驗證，或先前的會話已藉由呼叫 EapHostPeerEndSession 結束，則支援者只需要呼叫 EapHostPeerBeginSession來啟動新的會話。

連線可以跨多個會話保留，因為 EapHostPeerBeginSession 可以提供有效的 GUID 來註冊連線。 呼叫 EapHostPeerEndSession 時，只會終止目前的會話。 因為 GUID 的註冊不會終止， 所以 EapHostPeerBeginSession 的原始註冊會保持不變。 因此，註冊在多個會話之間有效。

需求

另請參閱

EAPHost Supplicant 執行時間函式

EapHostPeerClearConnection

EapHostPeerEndSession

SSO 和 PLAP