Home Library Learn Downloads Support Community
Sign in | United States - English | |
2 out of 7 rated this helpful - Rate this topic

LoadUserProfile function

Applies to: desktop apps only

Loads the specified user's profile. The profile can be a local user profile or a roaming user profile.

Syntax

Copy 
BOOL WINAPI LoadUserProfile(
  __in     HANDLE hToken,
  __inout  LPPROFILEINFO lpProfileInfo
);

Parameters

hToken [in]

Type: HANDLE

Token for the user, which is returned by the LogonUser, CreateRestrictedToken, DuplicateToken, OpenProcessToken, or OpenThreadToken function. The token must have TOKEN_QUERY, TOKEN_IMPERSONATE, and TOKEN_DUPLICATE access. For more information, see Access Rights for Access-Token Objects.

lpProfileInfo [in, out]

Type: LPPROFILEINFO

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

Type: BOOL

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 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.

Requirements

Minimum supported client

Windows 2000 Professional

Minimum supported server

Windows 2000 Server

Header
Userenv.h

Library
Userenv.lib

DLL
Userenv.dll

Unicode and ANSI names

LoadUserProfileW (Unicode) and LoadUserProfileA (ANSI)

See also

User Profiles Overview
User Profiles Reference
PROFILEINFO
UnloadUserProfile

 

 

Send comments about this topic to Microsoft

Build date: 3/7/2012

Did you find this helpful?
(1500 characters remaining)
Community Content Add
Annotations FAQ
Don't include the domain name in the "lpUserName" field of PROFILEINFO.
Passing domainname\username will appear to work if the already has a profile created on the local machine. However, if the user does not have a profile on the local machine then the string in "lpUserName" will be used to create a directory to contain the new profile. If the string contains a "\" then the path cannot be created and the function will fail. Instead, simply pass the username without the domain as returned by GetUserName().
History
Roaming Profiles
See comments with ProfileInfo.
History
Returns success, but seems to have failed.

I call this function, and it returns TRUE.  The hProfile handle looks good.  I then call CreateProcessAsUser(), and it returns TRUE.  But the first time that created process tries to read from HKEY_CURRENT_USER, it gets Access denied.

This code used to work on XP.  I only see this misbehavior on Vista.

const BOOL logon_succeeded =
LogonUser(name, domain, password, LOGON32_LOGON_INTERACTIVE,
LOGON32_PROVIDER_DEFAULT, &logon);
if (!logon_succeeded) {
ReportEvent(log, EVENTLOG_ERROR_TYPE, 
IDS_LOGON_FAILED, name, domain, LastErrorString());
return false;
}
logon_ = logon;
// Load the user's profile.
PROFILEINFO profile = { sizeof(profile) };
profile.lpUserName = name.GetBuffer();
USER_INFO_4* user_info;
NET_API_STATUS const status =
NetUserGetInfo(domain, name, 4, (BYTE**)&user_info);
if (NERR_Success == status)
profile.lpProfilePath = user_info->usri4_profile;
const BOOL loaded_profile = LoadUserProfile(logon, &profile);
if (NERR_Success == status)
NetApiBufferFree(user_info);
name.ReleaseBuffer();
if (!loaded_profile) {
ReportEvent(log, EVENTLOG_ERROR_TYPE, 
IDS_LOADUSERPROFILE_FAILED, name, LastErrorString());
return false;
}
profile_ = profile.hProfile;

return CreateProcessAsUser(logon_, lpApplicationName, lpCommandLine,
lpProcessAttributes, lpThreadAttributes, bInheritHandles,
dwCreationFlags, lpEnvironment, lpCurrentDirectory, lpStartupInfo,
lpProcessInformation);
History