RasEapGetIdentity (Compact 2013)

3/26/2014

This function is called by RAS to obtain identity information for the user requesting authentication.

Syntax

DWORD RasEapGetIdentity(
  DWORD dwEapTypeId, 
  HWND  hwndParent, 
  DWORD dwFlags, 
  const WCHAR* pwszPhonebook, 
  const WCHAR* pwszEntry, 
  BYTE* pConnectionDataIn, 
  DWORD  dwSizeOfConnectionDataIn, 
  BYTE* pUserDataIn, 
  DWORD  dwSizeOfUserDataIn, 
  BYTE** ppUserDataOut, 
  DWORD* pdwSizeOfUserDataOut, 
  WCHAR** ppwszIdentity
);

Parameters

• dwEapTypeId
  [in] Authentication protocol for which to invoke the identity user interface (UI).

• hwndParent
  [in] Handle to the parent window for the UI dialog box. If the dwFlags parameter contains the RAS_EAP_FLAG_NON_INTERACTIVE flag, hwndParent is NULL.

• dwFlags
  [in] Specifies zero or more of the following flags that qualify the authentication process.

  Flag	Description
  RAS_EAP_FLAG_ROUTER	Specifies that the computer that is dialing in is a router. Not having this flag indicates that the computer dialing in is a RAS client.
  RAS_EAP_FLAG_NON_INTERACTIVE	Specifies that the authentication protocol should not display a UI. If the authentication protocol is unable to determine the identity from the data supplied, it should return an error. If this flag is specified, the hwndParent parameter will be NULL.
  RAS_EAP_FLAG_LOGON	Specifies that the user data is obtained when you log on to the local system, that is from Winlogon.exe.
  RAS_EAP_FLAG_PREVIEW	Specifies that the user should be prompted for identity information before dialing.
  RAS_EAP_FLAG_FIRST_LINK	Indicates that this connection is the first link in a multilink connection.

• pwszPhonebook
  [in] Pointer to a Unicode string that specifies the full path of the phone-book (PBK) file. If this parameter is NULL, the function uses the system telephone book.

• pwszEntry
  [in] Pointer to a Unicode string that specifies an existing entry name.

• pConnectionDataIn
  [in] Pointer to the connection-specific data currently stored in the phone-book entry.

• dwSizeOfConnectionDataIn
  [in] Specifies the size of the connection-specific data currently stored in the phone-book entry.

• pUserDataIn
  [in] Pointer to the user-specific data currently stored for this user in the registry.

• dwSizeOfUserDataIn
  [in] Specifies the size of the user-specific data currently stored for this user in the registry.

• ppUserDataOut
  [out] Pointer to a pointer that, on successful return, points to the identity data for the user. This data will be passed to the authentication protocol in the pUserData member of the PPP_EAP_INPUT structure during the call to the RasEapBegin function

  The authentication protocol should allocate the memory buffer for the identity data. RAS will free this memory by calling the RasEapFreeMemory function.

• pdwSizeOfUserDataOut
  [out] Pointer to a DWORD variable that receives the size of the data pointed to by the ppUserDataOut parameter.

• ppwszIdentity
  [out] Pointer to a pointer that, on successful return, points to a Unicode string that identifies the user requesting authentication. This string will be passed to the authentication protocol in the pszIdentity member of PPP_EAP_INPUT during the call to RasEapBegin.

Return Value

If the function call succeeds, the return value is NO_ERROR.

If the function is unable to allocate memory for the user data, it will return ERROR_NOT_ENOUGH_MEMORY.

If the function is called by using the RAS_EAP_FLAG_NON_INTERACTIVE flag, but must invoke a user interface to determine the user's identity, the function should return ERROR_INTERACTIVE_MODE.

If the function call fails in some other way, it returns an appropriate error code from Winerror.h, Raserror.h, or Mprerror.h.

Remarks

The DLL that implements the RasEapGetIdentity and RasEapFreeMemory functions can support more than one authentication protocol. The dwEapTypeId parameter specifies for which protocol to invoke the identity user interface.

The authentication protocol receives the data returned from RasEapGetIdentity in the pUserData member of the PPP_EAP_INPUT structure during the call to RasEapBegin. To store the data for this user in the registry, the authentication protocol should set the pUserData member of the PPP_EAP_OUTPUT structure to point to the data, and the fSaveUserData member of PPP_EAP_OUTPUT to TRUE.

This function is called by the RasGetEapUserIdentity function.

If RasEapGetIdentity displays a user interface, the user interface must support WMCOMMAND messages where LOWORD (wParam) equals IDCANCEL.

Requirements

See Also

Reference

EAP Functions
RasEapFreeMemory
RasEapMakeMessage
PPP_EAP_INPUT