Winlogon API Available For Use By GINAs

Winlogon exports the following support fundtion to assist GINA DLLs. GINA DLLs are required to use Wlx dialog functions rather than generic Win32 functions for handling dialog calls to allow Winlogon timeouts to operate correctly.

Note like the rest of the GINA services, these functions are Unicode only.

WlxUseCtrlAltDel

This function allows a GINA to tell Winlogon to use the standard CTRL+ALT+DEL key combination as a secure attention sequence. If a GINA DLL uses this function, it is not required to use WlxSasNotify() below. However, if a GINA has other secure attention sequences in addition to CTRL+ALT+DEL, it must use WlxSasNotify() to deliver those additional secure attention sequences.

void
WINAPI
WlxUseCtrlAltDel(
    HANDLE        hWlx)

Parameters

hWlx

(IN parameter) Winlogon handle provided to GINA in the WlxInitialize() call.

Return Values

None

WlxSetContextPointer

This function allows a GINA DLL to specify the context pointer that Winlogon passes it as the first parameter to all the GINA functions. By using this function, a GINA can specify a new context pointer to update the one returned during WlxInitialize.

If a GINA DLL wishes to call WlxSasNotify during the processing of the WlxInitialize, this function must be called first, so as to associate any context with the GINA.

VOID
WINAPI
WlxSetContextPointer(
    HANDLE        hWlx,
    PVOID        pWlxContext)

Parameters

hWlx

(IN parameter) Winlogon handle provided to GINA in the WlxInitialize() call.

pWlxContext

(IN parameter) Context pointer that the GINA associates with.

Return Values

None.

WlxSasNotify

The GINA DLL calls this function to notify Winlogon of an SAS event.

VOID
WINAPI
WlxSasNotify(
    HANDLE        hWlx,
    DWORD        dwSasType)

Parameters

hWlx

(IN parameter) Winlogon handle provided to GINA in the WlxInitialize() call.

dwSasType

(IN parameter) A value indicating what type of secure attention sequence was entered. Values less than WLX_SAS_TYPE_MAX_MSFT_VALUE are used to define Microsoft standard secure attention sequences. Values above this value are for definition by GINA developers.

This value will be delivered to the GINA SAS service routine Winlogon calls (WlxLoggedOutSas(), WlxLoggedOnSas(), or WlxWkstaLockedSas()).

Return Values

None.

WlxSetTimeout

The GINA DLL calls this function to change the timeout associated with a dialog. There is some latitude in assigning timeouts, but the hard upper limit enforced by Winlogon is five minutes.

BOOL
WINAPI
WlxSetTimeout(
    HANDLE        hWlx,
    DWORD        dwTimeout)

Parameters

hWlx

Handle assigned by Winlogon during initialization.

dwTimeout

Requested timeout, in seconds.

Return Values

TRUE

Indicates the new timeout was accepted.

FALSE

Indicates the new timeout was not accepted.

WlxAssignShellProtection

The GINA DLL calls this function to have Winlogon assign protection to a newly logged on user's shell program. The shell process should be created suspended, then this routine should be called to apply the correct protection to the shell process. After Winlogon returns, the caller:

Makes a Primary Token duplicate of the token,
changes the protection on the token so that the new user may access it,
changes the protection on the new shell process so that the new user may access it, and
assigns the duplicate token as the primary token of the shell process.

If there are more than one top-level user shell processes, GINA must make a call for each one.

Note This is an optional call provided for the convenience of GINA developers.

int
WINAPI
WlxAssignShellProtection(
    HANDLE        hWlx,
    HANDLE        hToken,
    HANDLE        hProcess,
    HANDLE        hThread)

Parameters

hWlx

(IN parameter) Winlogon handle provided to GINA in the WlxInitialize() call.

hToken

(IN parameter) Handle to a primary token. This token will be used as the primary token for the process referred below. The token must be open for TOKEN_DUPLICATE access.

hProcess

(IN parameter) Handle to the process to modify. The process must be created in the suspended state, and this should be the handle returned in the PROCESS_INFORMATION structure.

hThread

(IN parameter) Handle to the initial thread of the process.

Return Values

Any errors encountered while trying to assign protection will be returned.

WlxMessageBox

This function duplicates the Win32 MessageBox() API, but allows for a timeout.

int
WlxMessageBox(
    HANDLE        hWlx,
    HWND        hwndOwner,
    LPWSTR        lpszText,
    LPWSTR        lpszTitle,
    UINT        fuStyle)

Parameters

as with MessageBox()

WlxDialogBox

This function duplicates the Win32 DialogBox() API, but allows for a timeout.

int
WlxDialogBox(
    HANDLE        hWlx,
    HANDLE        hInst,
    LPWSTR        lpszTemplate,
    HWND        hwndOwner,
    DLGPROC        dlgprc)

Parameters

As with DialogBox()

WlxDialogBoxIndirect

This function duplicates the Win32 DialogBoxIndirect() API, but allows for a timeout.

int
WlxDialogBoxIndirect(
    HANDLE            hWlx,
    HANDLE            hInst,
    LPCDLGTEMPLATE        hDialogTemplate,
    HWND            hwndOwner,
    DLGPROC            dlgprc)

Parameters

As with DialogBoxIndirect()

WlxDialogBoxParam

This function duplicates the Win32 DialogBoxParam() API, but allows for a timeout.

int
WlxDialogBoxParam(
    HANDLE        hWlx,
    HANDLE        hInst,
    LPWSTR        lpszTemplate,
    HWND        hwndOwner,
    DLGPROC        dlgprc,
    LPARAM        dwInitParam)

Parameters

As with DialogBoxIndirect()

WlxDialogBoxIndirectParam

This function duplicates the Win32 DialogBoxIndirectParam() API, but allows for a timeout.

int
WlxDialogBoxIndirectParam(
    HANDLE            hWlx,
    HANDLE            hInst,
    LPCDLGTEMPLATE        hDialogTemplate,
    HWND            hwndOwner,
    DLGPROC            dlgprc,
    LPARAM            dwInitParam)

Parameters

As with DialogBoxIndirectParam()

WlxSwitchDesktopToUser

This function allows the Gina DLL to switch between visual desktops. This function is only valid for the currently operating thread.

int
WINAPI
WlxSwitchDesktopToUser(
    HANDLE            hWlx)

Parameters

hWlx

(IN parameter) Winlogon handle provided to GINA in the WlxInitialize() call.

WlxSwitchDesktopToWinlogon

This function allows the Gina DLL to switch between visual desktops. This function is only valid for the currently operating thread.

int
WINAPI
WlxSwitchDesktopToWinlogon(
    HANDLE            hWlx)

Parameters

hWlx

(IN parameter) Winlogon handle provided to GINA in the WlxInitialize() call.

WlxChangePasswordNotify

This function should be called by GINA DLLs that have changed a password. This allows the other network providers on the machine to update their passwords as well.

int
WINAPI
WlxChangePasswordNotify(
    HANDLE            hWlx,
    PWLX_MPR_NOTIFY_INFO    pMprInfo,
    DWORD            dwChangeInfo)

Parameters

hWlx

(IN parameter) Winlogon handle provided to GINA in the WlxInitialize() call.

pMprInfo

(IN parameter) Completed MPR information. All pointers to memory in this structure will be freed through LocalFree(). Password pointers will be zeroed, then freed.

dwChangeInfo

Change info flags from Network Provider API.