Loads the specified user's profile. The profile can be a
local user profile or a
roaming user profile.
Syntax
BOOL WINAPI LoadUserProfile(
HANDLE hToken,
LPPROFILEINFO lpProfileInfo
);
Parameters
- hToken
-
[in] Token for the user, which is returned by the LogonUser, CreateRestrictedToken, DuplicateToken, OpenProcessToken, or OpenThreadToken function. The token must have TOKEN_QUERY and TOKEN_IMPERSONATE and TOKEN_DUPLICATE access. For more information, see Access Rights for Access-Token Objects.
- lpProfileInfo
-
[in, out] Pointer to a PROFILEINFO structure. LoadUserProfile fails and returns ERROR_INVALID_PARAMETER if the dwSize member of the structure is not set to
sizeof(PROFILEINFO) or if the lpUserName member is NULL. For more information, see Remarks.
Return Value
TRUE if successful; otherwise, FALSE. To get extended error information, call GetLastError.
The function fails and returns ERROR_INVALID_PARAMETER if the dwSize member of the structure at lpProfileInfo is not set to sizeof(PROFILEINFO) or if the lpUserName member is NULL.
Remarks
When a user logs on interactively, the system automatically loads the user's profile. If a service or an application impersonates a user, the system does not load the user's profile. Therefore, the service or application should load the user's profile with LoadUserProfile.
Services and applications that call LoadUserProfile should check to see if the user has a roaming profile. If the user has a roaming profile, specify its path as the lpProfilePath member of
PROFILEINFO. To retrieve the user's roaming profile path, you can call the
NetUserGetInfo function, specifying information level 3 or 4.
Upon successful return, the hProfile member of PROFILEINFO is a registry key handle opened to the root of the user's hive. It has been opened with full access (KEY_ALL_ACCESS). If a service that is impersonating a user needs to read or write to the user's registry file, use this handle instead of HKEY_CURRENT_USER
. Do not close the hProfile handle. Instead, pass it to the
UnloadUserProfile function. This function closes the handle. You should ensure that all handles to keys in the user's registry hive are closed. If you do not close all open registry handles, the user's profile fails to unload. For more information, see
Registry Key Security and Access Rights and Registry Hives.
Note that it is your responsibility to load the user's registry hive into the HKEY_USERS
registry key with the LoadUserProfile function before you call CreateProcessAsUser. This is because CreateProcessAsUser does not load the specified user's profile into HKEY_USERS
. This means that access to information in the HKEY_CURRENT_USER
registry key may not produce results consistent with a normal interactive logon.
The calling process must have the SE_RESTORE_NAME and SE_BACKUP_NAME privileges. For more information, see Running with Special Privileges.
Starting with Windows XP Service Pack 2 (SP2) and Microsoft Windows Server 2003, the caller must be an administrator or the LocalSystem account. It is not sufficient for the caller to merely impersonate the administrator or LocalSystem account.
Function Information
| Minimum DLL Version | Userenv.dll |
|---|
| Custom Implementation | No |
|---|
| Header | Userenv.h |
|---|
| Import library | Userenv.lib |
|---|
| Minimum operating systems |
Windows NT 4.0 |
|---|
| Unicode | Implemented as
ANSI and Unicode versions. |
|---|
See Also