Share via


RasEapGetIdentity

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

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. If the dwFlags parameter contains the RAS_EAP_FLAG_NON_INTERACTIVE flag, then 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. The absence of this flag indicates that the computer dialing in is a RAS client.

    RAS_EAP_FLAG_NON_INTERACTIVE

    Specifies that the authentication protocol should not bring up 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 logging onto 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 phone 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 with 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 dynamic-link library (DLL) that implements the RasEapGetIdentity and RasEapFreeMemory functions may 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.

Note

This function is called by the EAP module, not by the application. Therefore, no link library is exposed. For more information, see EAP Implementation Details.

Requirements

Header raseapif.h
Windows Embedded CE Windows CE .NET 4.0 and later
Windows Mobile Windows Mobile Version 5.0 and later
Note This function is called by the EAP module, not by the application. Therefore, no link library is exposed. For more information see EAP Implementation Details.

See Also

Reference

RasEapFreeMemory
RasEapMakeMessage
PPP_EAP_INPUT

Concepts

Obtaining Identity Information