Platform SDK: RAS/Routing and RAS

RasGetEapUserIdentity

The RasGetEapUserIdentity function retrieves identity information for the current user. Use this information to call RasDial with a phone-book entry that requires Extensible Authentication Protocol (EAP).

DWORD RasGetEapUserIdentity(
  LPCSTR pszPhonebook,     // path to phone book to use
  LPCSTR pszEntry,         // name of entry in phone book
  DWORD dwFlags,          // flags that qualify 
                           // authentication 
  HWND hwnd,               // handle to UI parent 
  LPRASEAPUSERIDENTITY * ppRasEapUserIdentity, 
                           // identity info
);

Parameters

pszPhonebook

Pointer to a null-terminated string containing the full path of the phone-book (PBK) file. If this parameter is NULL, the function will use the system phone book.

pszEntry

Pointer to a null-terminated string containing an existing entry name.

dwFlags

Specifies zero or more of the following flags that qualify the authentication process.

Flag	Description
RASEAPF_NonInteractive	Specifies that the authentication protocol should not bring up a graphical user-interface. If this flag is not present, it is okay for the protocol to display a user interface.
RASEAPF_Logon	Specifies that the user data is obtained from Winlogon.
RASEAPF_Preview	Specifies that the user should be prompted for identity information before dialing.

hwnd

Handle to the parent window for the UI dialog. If the fInvokeUI parameter is FALSE, then hwnd should be NULL.

ppRasEapUserIdentity

Pointer to a pointer that, on successful return, points to a RASEAPUSERIDENTITY structure containing EAP user identity information. RasGetEapUserIdentity will allocate the memory buffer for the RASEAPUSERIDENTITY structure. Free this memory by calling RasFreeEapUserIdentity.

Return Values

If the function succeeds, the return value is NO_ERROR.

Otherwise, the function will return one of the following error codes.

Value	Meaning
E_INVALID_ARG	The pcbEapUserIdentity parameter is NULL.
ERROR_INTERACTIVE_MODE	The function was called with the RASEAPF_NonInteractive flag. However, the authentication protocol must display a UI in order to obtain the required identity information from the user.
ERROR_INVALID_FUNCTION_FOR_ENTRY	Either the authentication method for this phone-book entry is not EAP, or the authentication method is EAP but the protocol uses the standard Windows NT/Windows 2000 credentials dialog to obtain user identity information. In either case, the caller does not need to pass EAP identity information to RasDial.
ERROR_RASMAN_CANNOT_INITIALIZE	The Remote Access Service failed to initialize properly.
Other	Use FormatMessage to retrieve the system error message that corresponds to the error code returned.

Remarks

RasGetEapUserIdentiy calls the RAS function RasGetEapUserData and the EAP function RasEapGetIdentity. RasEapGetIdentity is implemented by the authentication protocol.

If the function succeeds, that is the return value is NO_ERROR, the caller should copy the EAP identity information from the structure pointed to by ppRasEapUserIdentity to the RASDIALPARAMS and RASDIALEXTENSIONS structures used in the call to RasDial. The following sample code demonstrates how to copy the identity information.

lstrcpy(DialParms.szUserName, pRasEapUserIdentity->szUserName);
pDialExts->RasEapInfo.dwSizeofEapInfo = pRasEapUserIdentity->dwSizeofEapInfo;
pDialExts->RasEapInfo.pbEapInfo = pRasEapUserIdentity->pbEapInfo;

If the remote access application being developed has a graphical user interface, the caller of RasGetEapUserIdentity should not specify the RASEAPF_NonInteractive flag. If the application has a command-line user interface, the caller may want to specify the RASEAPF_NonInteractive flag to prevent the authentication protocol from displaying a graphical user interface.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Unsupported.
  Header: Declared in Ras.h.
  Library: Use Rasapi32.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows 2000.

RasGetEapUserIdentity

Parameters

Return Values

Remarks

Requirements

See Also