EapHostPeerBeginSession 関数 (eappapis.h)
EAP 認証セッションを開始します。 EapHostPeerBeginSession 関数が成功した場合、呼び出し元は認証セッションを終了するために EapHostPeerEndSession も呼び出す必要があります。 EapHostPeerBeginSession 以外の関数が成功するか失敗するかに関係なく、後者の関数を呼び出す必要があります。
理由に関係なく、再認証が必要な場合、パラメーター pConnectionId で表されるインターフェイスは登録解除されます。 pConnectionId が登録解除されている場合は、EapHostPeerClearConnection を呼び出して接続を削除する必要もあります。
EapHostPeerEndSession を呼び出さずに、インターフェイスで EapHostPeerBeginSession を再度呼び出すことはありません。 pConnectionId で指定されたインターフェイスでアクティブにできる認証セッションは 1 つだけです。
構文
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 認証の種類を指定する EAP_METHOD_TYPE 構造。
[in] pAttributeArray
認証するエンティティの EAP 属性を指定する EapAttributes 構造体へのポインター。
[in] hTokenImpersonateUser
このセッションで使用するユーザー偽装トークンを処理します。
[in] dwSizeofConnectionData
pConnectionData で提供される接続データ バッファーのサイズ (バイト単位)。
[in] pConnectionData
認証に使用される構成について説明します。 NULL 接続データは有効と見なされます。 メソッドは、既定の構成で動作する必要があります。
[in] dwSizeofUserData
pUserData で提供されるユーザー データ バッファーのサイズ (バイト単位)。
[in] pUserData
EapPeerGetIdentity 関数から返されるユーザー データを含む不透明なユーザー データ BLOB を含むバイト バッファーへのポインター。 ユーザー データには、認証に使用される資格情報または証明書が含まれる場合があります。 pUserData には NULL を指定できます。 NULL ポインターの解釈は、メソッドの実装によって異なります。 ユーザー データは、認証に使用されるユーザーまたはマシンの資格情報で構成されます。 通常、ユーザー データは構成データに依存します。
EAP_FLAG_PREFER_ALT_CREDENTIALSが dwlags で示されている場合、pConnectionData に渡された構成データが別の資格情報取得モードを要求する場合でも、EapPeerBeginSession に渡される資格情報は、他のすべての形式の資格情報取得に優先されます。 EapPeerBeginSession に資格情報を渡すことが失敗した場合、EAPHost はメソッド固有の資格情報の取得に頼ります。その場合、資格情報はファイル、Windows ログイン、または証明書ストアから取得できます。
EAP メソッドの作成者は、既定の資格情報と代替資格情報の両方を定義します。 たとえば、EAP-MSCHAPv2 の場合、既定の資格情報は winlogon から取得された Windows 資格情報であり、代替資格情報は pUserData に渡される資格情報 (ユーザー名、パスワード、ドメイン) です。
[in] dwMaxSendPacketSize
セッション中に送信できる EAP パケットの最大サイズ (バイト単位)。
[in] pConnectionId
サプリカントの認証が行われる論理ネットワーク インターフェイスを一意に識別する GUID 値へのポインター。 NAP 正常性の変更後にサプリカントが再認証を求める場合は、一意の GUID を指定する必要があります。 この関数がトンネリング メソッドによって呼び出されて内部メソッドを開始する場合、パラメーターは NULL である必要があります。 pConnectionId パラメーターが NULL の場合、func パラメーターと pContextData パラメーターは無視されます。
[in] func
再認証が必要な場合にサプリカントに通知するために EAPHost によって使用されるコールバックを提供する NotificationHandler 関数ポインター。
関数ハンドラーが NULL の場合、 pContextData パラメーターは無視されます。 関数ハンドラーが NULL の場合は、呼び出し元が EAP 検疫適用クライアント (QEC) からの SoH 変更通知に関心を持たないことを意味します。
次のコードは、 NotificationHandler コールバック呼び出しを示しています。
func(*pConnectionId, pContextData);
[in] pContextData
func が呼び出されたときにサプリカントが接続に関連付ける再認証コンテキスト データへのポインター。 このパラメーターは、NULL でもかまいません。
[out] pSessionId
EAPHost サーバー 上のこの EAP 認証セッションの一意のハンドルを含むEAP_SESSIONID構造体へのポインター。
[out] ppEapError
EAP_ERROR構造体のアドレスへのポインター。 この関数を呼び出す前に、アドレスを NULL に設定する必要があります。 エラー データが使用可能な場合は、この関数呼び出しの実行中に発生したエラーを含む EAP_ERROR 構造体のアドレスへのポインターが受信されます。 エラー データを使用した後、 EapHostPeerFreeEapError を呼び出してこのメモリを解放します。
戻り値
なし
解説
EAPHost サプリカントが NAP に参加している場合、サプリカントはネットワーク正常性の状態の変化に応答します。 その状態が変更された場合、サプリカントは次のように再認証セッションを開始する必要があります。
- 再認証が行われるときに現在のセッションがある場合、サプリカントは EapHostPeerEndSession を呼び出して現在のセッションを破棄し、 EapHostPeerBeginSession を呼び出して新しいセッションを開始する必要があります。
- 再認証が行われた現在のセッションがない場合、または EapHostPeerEndSession を呼び出して前のセッションが既に終了している場合、サプリカントは EapHostPeerBeginSession を呼び出して新しいセッションを開始するだけで済みます。
EapHostPeerBeginSession は接続を登録するための有効な GUID を提供できるため、複数のセッションにわたって接続を保持できます。 EapHostPeerEndSession が呼び出されると、現在のセッションのみが終了します。 GUID への登録は終了しないため、 EapHostPeerBeginSession による元の登録はそのまま残ります。 したがって、登録は複数のセッションにわたって有効です。
要件
| サポートされている最小のクライアント | Windows Vista [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows Server 2008 [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | eappapis.h |
| Library | Eappprxy.lib |
| [DLL] | Eappprxy.dll |