RasGetEapUserIdentityA function (ras.h)
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).
Syntax
DWORD RasGetEapUserIdentityA(
[in] LPCSTR pszPhonebook,
[in] LPCSTR pszEntry,
[in] DWORD dwFlags,
[in] HWND hwnd,
[out] LPRASEAPUSERIDENTITYA *ppRasEapUserIdentity
);
Parameters
[in] pszPhonebook
Pointer to a null-terminated string that specifies the full path of the phone-book (PBK) file. If this parameter is NULL, the function uses the system phone book.
[in] pszEntry
Pointer to a null-terminated string that specifies an existing entry name.
[in] dwFlags
Specifies zero or more of the following flags that qualify the authentication process.
[in] hwnd
Handle to the parent window for the UI dialog. If the fInvokeUI parameter is FALSE, then hwnd should be NULL.
[out] ppRasEapUserIdentity
Pointer to a pointer that, on successful return, receives the address of the RASEAPUSERIDENTITY structure that contains EAP user identity information. RasGetEapUserIdentity allocates the memory buffer for the RASEAPUSERIDENTITY structure. Free this memory by calling RasFreeEapUserIdentity.
Return value
If the function succeeds, the return value is ERROR_SUCCESS.
If the function fails, the return value is one of the following error codes or a value from Routing and Remote Access Error Codes or Winerror.h.
| Value | Meaning |
|---|---|
|
The pcbEapUserIdentity parameter is NULL. |
|
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. |
|
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. |
|
The Remote Access Service failed to initialize properly. |
|
Use FormatMessage to retrieve the system error message that corresponds to the error code returned. |
Remarks
RasGetEapUserIdentity 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 RASEAPUSERIDENTITY structure pointed to by the ppRasEapUserIdentity parameter to the RASDIALPARAMS and RASDIALEXTENSIONS structures used in the call to RasDial.
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.
Note
The ras.h header defines RasGetEapUserIdentity as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional [desktop apps only] |
| Minimum supported server | Windows 2000 Server [desktop apps only] |
| Target Platform | Windows |
| Header | ras.h |
| Library | Rasapi32.lib |
| DLL | Rasapi32.dll |