Platform SDK: Logon Authentication

WlxActivateUserShell

The WlxActivateUserShell function must be implemented by a replacement GINA DLL. Winlogon calls this function following a successful logon to request that the GINA activate the user's shell program.

BOOL WlxActivateUserShell(
  PVOID pWlxContext,
  PWSTR pszDesktopName,
  PWSTR pszMprLogonScript,
  PVOID pEnvironment
);

Parameters

pWlxContext: [in] Pointer to the GINA context associated with this window station. This is the context value that the GINA returns when Winlogon calls WlxInitialize for this station.
pszDesktopName: [in] Specifies the name of the desktop where the shell will start. Pass this string to the CreateProcess or CreateProcessAsUser functions through the lpDesktop member of the STARTUPINFO structure.
pszMprLogonScript: [in] Specifies any script names returned from the network provider DLLs. Network provider DLLs can return scripts to be executed during logon, however, the GINA may ignore them.
pEnvironment: [in] Specifies the initial environment variables for the process. Winlogon creates a copy of the environment and hands it off to the GINA. The GINA can modify this environment before using it to initialize the user's shell. The GINA should call VirtualFree to free the memory allocated for pEnvironment.

Return Values

TRUE: Return TRUE if the shell process was started.
FALSE: Return FALSE if the shell process could not be started. When FALSE is returned, Winlogon cancels the logon in process.

Remarks

Before calling WlxActivateUserShell, Winlogon sets the desktop and workstation states as follows.

Sets the	So that
Desktop state	The current desktop is the Winlogon desktop.
Workstation state	The desktop is locked.

Always activate the user shell program in WlxActivateUserShell rather than WlxLoggedOutSAS. This gives Winlogon a chance to update its state, including setting workstation and desktop protections, before any logged-on user processes are allowed to run.

Example Code

For an example of	See
WlxActivateUserShell	Implementing WlxActivateUserShell

Requirements