RasEapInvokeInteractiveUI

[This is preliminary documentation and subject to change.]

The RAS Connection Manager calls the RasEapInvokeInteractiveUI function to display a dialog to obtain authentication data from the user.

DWORD  RasEapInvokeInteractiveUI ( 
  DWORD     dwEapTypeId,               // identifies the protocol 
  HINSTANCE hInstance,                 // handle to DLL module 
  HWND      hwndParent,                // handle to parent window 
  PBYTE     pUIContextData,            // pointer to context data 
  DWORD     dwSizeofUIContextData,     // size of context data 
  PBYTE *   ppConnectionData,          // connection-specific data returned from UI
  DWORD *   lpdwSizeOfConnectionData,  // size of connection-specific data returned from UI
  PBYTE *   ppUserData,                // user-specific data returned from UI
  DWORD *   lpdwSizeOfUserData,        // size of user-specific data returned from UI
  LPSTR     szIdentity[UNLEN+DNLEN+2]  // identity of user 
);
 

Parameters

dwEapTypeId

Identifies the authentication protocol for which to invoke the interactive UI.

hInstance

Handle to the DLL module.

hwndParent

Handle to the parent window for the dialog.

pUIContextData

Pointer to context data for the interactive UI. The authentication protocol provides a pointer to this data as a member of the PPP_EAP_OUTPUT structure. The RAS Connection Manager receives the PPP_EAP_OUTPUT structure as an output parameter from the RasEapMakeMessage function.

dwSizeofUIContextData

Specifies the size of the context data. The authentication protocol provides the size as a member of the PPP_EAP_OUTPUT structure. The RAS Connection Manager receives the PPP_EAP_OUTPUT structure as an output parameter from the RasEapMakeMessage function.

ppConnectionData

Pointer to a pointer variable. On return, this pointer variable will point to a memory buffer that holds the connection-specific data obtained from the interactive UI. The interactive UI will allocate this memory buffer. The authentication protocol will free this memory by calling RasEapFreeInteractiveUIData.

If the interactive UI doesn't obtain any connection-specific data, the pointer that ppConnectionData points to should be set to NULL.

lpdwSizeOfConnectionData

Pointer to a DWORD variable to receive the size of the connection-specific data returned by the interactive UI. If the interactive UI doesn't obtain any data from the user, the DWORD variable should be set to zero.

ppUserData

Pointer to a pointer variable. On return, this pointer variable will point to a memory buffer that holds the user-specific data obtained by the interactive UI. The interactive UI will allocate this memory buffer. The authentication protocol will free this memory by calling RasEapFreeInteractiveUIData.

If the interactive UI doesn't obtain any user-specific data, the pointer that ppUserData points to should be set to NULL.

lpdwSizeOfUserData

Pointer to a DWORD variable to receive the size of the user-specific data returned from the interactive UI. If the interactive UI doesn't obtain any user-specific data, the DWORD variable should be set to zero.

szIdentity

Pointer to a buffer of length UNLEN+DNLEN+2. The authentication protocol may use this buffer to return a string that identifies the user requesting authentication.

Return Values

If the function succeeds, the return value is NO_ERROR. Check the ppConnectionData, lpdwSizeOfConnectionData, ppUserData and lpdwSizeOfUserData parameters to determine if the function returned data from the interactive UI.

If the function wasn't able to allocate memory for the connection-specific or user-specific data, the return value should be ERROR_NOT_ENOUGH_MEMORY.

If the function fails in some other way, the return value should be an appropriate error code from winerror.h, raserror.h, or mprerror.h.

Remarks

The DLL that implements the RasEapInvokeInteractiveUI and RasEapFreeInteractiveUIData functions may support more than one authentication protocol. The dwEapTypeId parameter specifies which authentication protocol to invoke the interactive UI for.

A pointer to the data returned from the interactive UI is passed back to the authentication protocol in the PPP_EAP_INPUT structure. The PPP_EAP_INPUT structure is passed as a parameter to the RasEapMakeMessage function.

See Also

RasEapFreeInteractiveUIData, RasEapInvokeConfigUI, RasEapMakeMessage, PPP_EAP_INPUT, PPP_EAP_OUTPUT