437 lines
19 KiB
C
437 lines
19 KiB
C
//*********************************************************************
|
|
//* Microsoft Internet Explorer **
|
|
//* Copyright (c) Microsoft Corporation. All rights reserved. **
|
|
//*********************************************************************
|
|
|
|
#ifndef _MSLUAPI_H_
|
|
#define _MSLUAPI_H_
|
|
|
|
#ifdef USER_SETTINGS_IMPLEMENTED
|
|
|
|
/************************************************************************
|
|
|
|
IUserSettings interface
|
|
|
|
This interface is used to manipulate the settings for a particular component,
|
|
corresponding to a local user account. An IUserSettings interface may be
|
|
obtained by CLSID or name, or through enumeration; in both cases, this is
|
|
relative to a particular user.
|
|
|
|
Member functions, other than IUnknown:
|
|
|
|
GetCLSID(CLSID *pclsidOut)
|
|
Returns the CLSID identifying the component. May be GUID_NULL if no
|
|
CLSID is defined for the component.
|
|
|
|
GetName(LPSTR pbBuffer, UINT cbBuffer)
|
|
Returns a unique name identifying the component. This may be used
|
|
instead of a CLSID if the component provider does not wish to provide
|
|
a COM server to help administer the settings.
|
|
|
|
GetDisplayName(LPSTR pbBuffer, UINT cbBuffer)
|
|
Returns a user-friendly name for the component, suitable for presentation
|
|
to the user.
|
|
|
|
QueryKey(HKEY *phkeyOut)
|
|
Returns a registry key where the component stores settings for the
|
|
specified user. The key is owned by the interface and must not be
|
|
closed by the application using RegCloseKey, otherwise changes will
|
|
not be propagated correctly.
|
|
|
|
((((
|
|
OpenKey(HKEY *phkeyOut, DWORD fdwAccess)
|
|
Returns a registry key where the component stores settings for the
|
|
specified user. The key MUST be closed using IUserSettings::CloseKey
|
|
so that changes will be propagated correctly. fdwAccess indicates
|
|
the type of access desired; valid values include GENERIC_READ and
|
|
GENERIC_WRITE.
|
|
|
|
CloseKey(HKEY hKey)
|
|
Closes a registry key obtained via IUserSettings::OpenKey.
|
|
|
|
Lock(BOOL fLock)
|
|
Locks or unlocks the settings for updates. Attempting to lock the
|
|
settings will fail if they are already locked. Locking the settings
|
|
does not, however, affect any of the other member functions
|
|
))))
|
|
************************************************************************/
|
|
|
|
DECLARE_INTERFACE_(IUserSettings, IUnknown)
|
|
{
|
|
// *** IUnknown methods ***
|
|
STDMETHOD(QueryInterface) (THIS_ REFIID riid, LPVOID * ppvObj) PURE;
|
|
STDMETHOD_(ULONG,AddRef) (THIS) PURE;
|
|
STDMETHOD_(ULONG,Release) (THIS) PURE;
|
|
|
|
STDMETHOD(GetCLSID) (THIS_ CLSID *pclsidOut) PURE;
|
|
STDMETHOD(GetName) (THIS_ LPSTR pbBuffer, LPDWORD pcbBuffer) PURE;
|
|
STDMETHOD(GetDisplayName) (THIS_ LPSTR pbBuffer, LPDWORD pcbBuffer) PURE;
|
|
|
|
STDMETHOD(QueryKey) (THIS_ HKEY *phkeyOut) PURE;
|
|
};
|
|
#endif /* USER_SETTINGS_IMPLEMENTED */
|
|
|
|
|
|
/************************************************************************
|
|
|
|
IUser interface
|
|
|
|
This interface is used to manipulate a local user account. It allows
|
|
various operations to be performed on a particular user. To obtain one
|
|
of these interfaces, the companion interface IUserDatabase must be
|
|
used -- its AddUser, GetUser, and GetCurrentUser member functions all
|
|
return IUser objects, as does IEnumUsers::Next.
|
|
|
|
In all descriptions here, "the user" refers to the user which this
|
|
ILocalUser object describes. "The current user" means the user who
|
|
is currently logged on at the workstation.
|
|
|
|
If the current user is a supervisor, all functions are allowed. Otherwise,
|
|
a more limited set of member functions is available if the IUser object
|
|
corresponds to the current user. If the current user is not a supervisor
|
|
and the IUser object refers to a different user, a still more limited set
|
|
of functions is allowed.
|
|
|
|
Member functions, other than IUnknown:
|
|
|
|
GetName(LPSTR pbBuffer, UINT cbBuffer)
|
|
Returns the user's logon name.
|
|
|
|
GetProfileDirectory(LPSTR pbBuffer, UINT cbBuffer)
|
|
Returns the user's local profile directory (e.g., C:\WINDOWS\PROFILES\gregj).
|
|
May fail if the user is the default user (doesn't really have a profile
|
|
directory as such).
|
|
|
|
IsSupervisor()
|
|
Returns whether the user is a supervisor or not. This is not a generic
|
|
property because it's actually based on the presence of security info
|
|
in the user's PWL (at least on win95).
|
|
|
|
SetSupervisorPrivilege(BOOL fMakeSupervisor, LPCSTR pszSupervisorPassword)
|
|
Grants or revokes supervisor privilege for the user. Only supervisors
|
|
can grant or revoke that privilege, of course. If pszSupervisorPassword
|
|
is not NULL, it is used to determine whether the current user is a
|
|
supervisor. If it is NULL, then the current user's password cache is
|
|
used instead. This allows making any user into a supervisor without
|
|
the current user being one.
|
|
|
|
MakeTempSupervisor(BOOL fMakeSupervisor, LPCSTR pszSupervisorPassword)
|
|
Grants or revokes supervisor privilege for the user, but only for the
|
|
lifetime of this IUser object. As soon as the object is destroyed,
|
|
the user is no longer considered a supervisor, and in fact other IUser
|
|
objects currently in existence which refer to the same user will not
|
|
indicate him as a supervisor.
|
|
|
|
Note that MakeTempSupervisor(FALSE) only revokes temporary-supervisor
|
|
privilege granted by MakeTempSupervisor(TRUE). If the user still has
|
|
the supervisor password in his PWL, he will still be considered a
|
|
supervisor.
|
|
|
|
AppearsSupervisor()
|
|
Returns whether or not the user should appear as a supervisor in a list
|
|
of users. This allows querying this property on each user for display
|
|
purposes without taking the large performance hit to locate each user's
|
|
PWL, open it up, get the supervisor key out, and validate it. Instead,
|
|
a registry value under the user's key is used to maintain this value.
|
|
It should NOT be used to determine whether the user has permission to
|
|
do something, because the simple registry value is not as secure.
|
|
|
|
Authenticate(LPCSTR pszPassword)
|
|
Attempts to authenticate the user using the given password. Returns
|
|
S_OK if the password is correct for the user, or an error otherwise.
|
|
No user interface is displayed by this function.
|
|
|
|
ChangePassword(LPCSTR pszOldPassword, LPCSTR pszNewPassword)
|
|
Attempts to change the user's password from the given old password
|
|
to the given new password. Returns an error code indicating success
|
|
or failure. If the current user is a supervisor, the old password
|
|
may be NULL, in which case the supervisor's credentials are used to
|
|
get the password via other means.
|
|
|
|
GetPasswordCache(LPCSTR pszPassword, LPHPWL phOut)
|
|
Returns a handle to the user's password cache, suitable for use with
|
|
the MSPWL32.DLL APIs. May fail, of course, if password caching is
|
|
disabled.
|
|
|
|
LoadProfile(LPHKEY phkeyUser)
|
|
Loads the user's profile into the registry and returns a handle to the
|
|
root key. The current user can always load his own profile (just returns
|
|
HKEY_CURRENT_USER); to load other users' profiles, the current user must
|
|
be a supervisor. IUser::UnloadProfile() should always be called when the
|
|
caller is done playing with the user's profile.
|
|
|
|
UnloadProfile(HKEY hkeyUser)
|
|
Unloads the user's profile from the registry if possible, and closes the
|
|
key handle returned by IUser::LoadProfile. If the specified user is the
|
|
current user, this function does nothing.
|
|
|
|
GetComponentSettings(REFCLSID clsidComponent, LPCSTR pszName,
|
|
IUnknown **ppOut, DWORD fdwAccess)
|
|
CURRENTLY NOT IMPLEMENTED
|
|
Returns an IUserSettings interface which can be used to access the
|
|
user's settings for a particular component. Either clsidComponent or
|
|
pszName may be used to refer to the component whose settings are to be
|
|
accessed. If pszName is not NULL, it takes precedence over clsidComponent.
|
|
fdwAccess specifies whether the caller wants read or write access to the
|
|
settings. If the component's settings are restricted and the current user
|
|
is not a supervisor, only GENERIC_READ access will be allowed;
|
|
GENERIC_WRITE will fail.
|
|
|
|
EnumerateComponentSettings(IEnumUnknown **ppOut, DWORD fdwAccess)
|
|
CURRENTLY NOT IMPLEMENTED
|
|
Returns an IEnumUnknown interface which can be used to enumerate all
|
|
components which have settings recorded for the user. fdwAccess
|
|
specifies the desired access, read or write. If the current user
|
|
is not a supervisor and the caller requests write access, the enumerator
|
|
will not return any components which do not permit such access.
|
|
|
|
************************************************************************/
|
|
|
|
DECLARE_INTERFACE_(IUser, IUnknown)
|
|
{
|
|
// *** IUnknown methods ***
|
|
STDMETHOD(QueryInterface) (THIS_ REFIID riid, LPVOID * ppvObj) PURE;
|
|
STDMETHOD_(ULONG,AddRef) (THIS) PURE;
|
|
STDMETHOD_(ULONG,Release) (THIS) PURE;
|
|
|
|
STDMETHOD(GetName) (THIS_ LPSTR pbBuffer, LPDWORD pcbBuffer) PURE;
|
|
STDMETHOD(GetProfileDirectory) (THIS_ LPSTR pbBuffer, LPDWORD pcbBuffer) PURE;
|
|
|
|
STDMETHOD(IsSupervisor) (THIS) PURE;
|
|
STDMETHOD(SetSupervisorPrivilege) (THIS_ BOOL fMakeSupervisor, LPCSTR pszSupervisorPassword) PURE;
|
|
STDMETHOD(MakeTempSupervisor) (THIS_ BOOL fMakeSupervisor, LPCSTR pszSupervisorPassword) PURE;
|
|
STDMETHOD(AppearsSupervisor) (THIS) PURE;
|
|
|
|
STDMETHOD(Authenticate) (THIS_ LPCSTR pszPassword) PURE;
|
|
STDMETHOD(ChangePassword) (THIS_ LPCSTR pszOldPassword, LPCSTR pszNewPassword) PURE;
|
|
STDMETHOD(GetPasswordCache) (THIS_ LPCSTR pszPassword, LPHANDLE phOut) PURE;
|
|
|
|
STDMETHOD(LoadProfile) (THIS_ HKEY *phkeyUser) PURE;
|
|
STDMETHOD(UnloadProfile) (THIS_ HKEY hkeyUser) PURE;
|
|
|
|
STDMETHOD(GetComponentSettings) (THIS_ REFCLSID clsidComponent,
|
|
LPCSTR pszName, IUnknown **ppOut,
|
|
DWORD fdwAccess) PURE;
|
|
STDMETHOD(EnumerateComponentSettings) (THIS_ IEnumUnknown **ppOut,
|
|
DWORD fdwAccess) PURE;
|
|
};
|
|
|
|
|
|
/************************************************************************
|
|
|
|
IUserProfileInit interface
|
|
|
|
This interface is a helper for IUserDatabase::Install and IUserDatabase::Create.
|
|
It allows the client of those functions to perform initialization of a new
|
|
user's profile before and after the new user's per-user folders are set up.
|
|
|
|
Member functions, other than IUnknown:
|
|
|
|
PreInitProfile(HKEY hkeyUser, LPCSTR pszProfileDir)
|
|
Called when the user's profile has been created, but no per-user folders
|
|
have been created or initialized yet. Here the implementer can add keys to
|
|
the user's profile which will affect the initialization of those per-user
|
|
folders. hkeyUser is the root of the user's profile, which would be
|
|
HKEY_CURRENT_USER if the user were currently logged on.
|
|
|
|
PostInitProfile(HKEY hkeyUser, LPCSTR pszProfileDir)
|
|
Called after the user's per-user folders have been created and initialized.
|
|
Here the implementer can add keys to the user's profile which will control
|
|
roaming of per-user folders, without causing the IUserDatabase profile
|
|
cloning code to want to initialize those folders from their default
|
|
locations.
|
|
|
|
************************************************************************/
|
|
|
|
DECLARE_INTERFACE_(IUserProfileInit, IUnknown)
|
|
{
|
|
// *** IUnknown methods ***
|
|
STDMETHOD(QueryInterface) (THIS_ REFIID riid, LPVOID * ppvObj) PURE;
|
|
STDMETHOD_(ULONG,AddRef) (THIS) PURE;
|
|
STDMETHOD_(ULONG,Release) (THIS) PURE;
|
|
|
|
STDMETHOD(PreInitProfile) (THIS_ HKEY hkeyUser, LPCSTR pszProfileDir) PURE;
|
|
STDMETHOD(PostInitProfile) (THIS_ HKEY hkeyUser, LPCSTR pszProfileDir) PURE;
|
|
};
|
|
|
|
|
|
/************************************************************************
|
|
|
|
IUserDatabase interface
|
|
|
|
This interface is used to manage the local user database as a whole. Any
|
|
activities which deal with the list of users in any way are done through
|
|
this interface; operations which deal with the properties (other than the
|
|
name) of an existing user are done through IUser.
|
|
|
|
Member functions, other than IUnknown:
|
|
|
|
Install(LPCSTR pszSupervisorName, LPCSTR pszSupervisorPassword,
|
|
LPCSTR pszRatingsPassword, IUserProfileInit *pInit)
|
|
Installs the user settings subsystem. This includes creating an account
|
|
for the supervisor. A separate member function is necessary for doing
|
|
this because all the others would insist that the current user already
|
|
be a supervisor. The pInit object (optional, may be NULL) is called
|
|
back to allow the installer to do initialization of the profile being
|
|
created, before and after its per-user files are copied.
|
|
|
|
AddUser(LPCSTR pszName, IUser *pSourceUser, IUserProfileInit *pInit,
|
|
IUser **ppOut)
|
|
Creates a new user on the system. This includes creating a profile
|
|
for the user. It does not, however, include creating a password list
|
|
file. IUser::ChangePassword can be used to configure the password
|
|
for the user. An IUser object is returned to the caller so that the
|
|
caller can configure the properties of the user. This function will
|
|
fail if the current user is not a supervisor. The caller can optionally
|
|
specify a user account to be cloned. The pInit object (optional, may be
|
|
NULL) is called back to allow the installer to do initialization of the
|
|
profile being created, before and after its per-user files are copied.
|
|
|
|
GetUser(LPCSTR pszName, IUser **ppOut)
|
|
Gets an IUser object corresponding to the specified user. The current
|
|
user need not be a supervisor to call this function, and any user's
|
|
name may be specified. The IUser interface will control what a non-
|
|
supervisor can and cannot do to the user object.
|
|
|
|
GetSpecialUser(DWORD nSpecialUserCode, IUser **ppOut)
|
|
Gets an IUser object corresponding to a special particular user.
|
|
Current values for nSpecialUserCode include GSU_CURRENT, meaning
|
|
the currently logged on user, and GSU_DEFAULT, meaning the default
|
|
user identity (i.e., the identity used when nobody is logged on,
|
|
also used as a template when creating new identities).
|
|
|
|
GetCurrentUser(IUser **ppOut)
|
|
Gets an IUser object corresponding to the currently logged on user.
|
|
Shorthand for GetSpecialUser(GSU_CURRENT, ppOut).
|
|
|
|
SetCurrentUser(IUser *pUser)
|
|
Sets this IUserDatabase object's idea of who the current user is.
|
|
The user must have previously been authenticated. This user object
|
|
is used for all checks which, for example, determine whether the
|
|
"current user" is a supervisor, or whether a user can access his
|
|
or her own settings, etc. SetCurrentUser does not AddRef the IUser
|
|
object passed.
|
|
|
|
DeleteUser(LPCSTR pszName)
|
|
Deletes the profile and password cache for the specified user,
|
|
effectively destroying that user's identity. This function may
|
|
only be called if the current user is a supervisor. Any existing
|
|
IUser objects which refer to the user are no longer useful, but
|
|
still must be destroyed in the ordinary way (Release()).
|
|
|
|
RenameUser(LPCSTR pszOldName, LPCSTR pszNewName)
|
|
Changes the username of a user. This function may only be called
|
|
if the current user is a supervisor.
|
|
|
|
EnumUsers(IEnumUnknown **ppOut)
|
|
Returns an IEnumUnknown object which the caller can use to enumerate
|
|
the local users on the system.
|
|
|
|
Authenticate(HWND hwndOwner, DWORD dwFlags, LPCSTR pszName, LPCSTR pszPassword,
|
|
IUser **ppOut)
|
|
Attempts to authenticate a user. dwFlags specifies whether or not
|
|
to prompt for credentials, and whether or not non-supervisors are
|
|
acceptable. If no dialog is to be displayed by the API, then the
|
|
pszName and pszPassword parameters are used instead. If the credentials
|
|
are authenticated succcessfully, S_OK is returned. The ppOut parameter,
|
|
if not NULL, is filled with a pointer to an IUser object describing the
|
|
user who was authenticated, in case the caller cares to find out about
|
|
who typed in their name and password.
|
|
|
|
The dwFlags parameter specifies whether UI will be displayed by the
|
|
function, and whether or not the credentials will be cached in memory
|
|
for use at the next logon.
|
|
|
|
InstallComponent(REFCLSID clsidComponent, LPCSTR pszName, DWORD dwFlags)
|
|
CURRENTLY NOT IMPLEMENTED
|
|
|
|
Installs a component into the settings database, so that it will appear
|
|
in the settings UI. clsidComponent or pszName can be used to refer to
|
|
the component being installed; use of a CLSID is preferable because
|
|
then the component can provide server code which renders the settings
|
|
UI for that component, and knows how to initialize the settings for a
|
|
new user.
|
|
|
|
The only bit currently defined for dwFlags is:
|
|
|
|
SETTINGS_NS_CAN_WRITE: Non-supervisors can change their own settings
|
|
for this component.
|
|
|
|
A component's settings for the current user can always be read, at least
|
|
programmatically -- there is no point in storing settings which can only
|
|
be accessed if the current user is a supervisor. If non-supervisors
|
|
should not be shown the UI for restricted settings (even a read-only UI),
|
|
that decision can be made at the UI level.
|
|
|
|
InstallComponent fails if the current user is not a supervisor.
|
|
|
|
RemoveComponent(REFCLSID clsidComponent, LPCSTR pszName)
|
|
CURRENTLY NOT IMPLEMENTED
|
|
|
|
Removes a component from the settings database, so that it will no longer
|
|
appear in the settings UI. This also removes this component's settings
|
|
from all user identities.
|
|
|
|
RemoveComponent fails if the current user is not a supervisor.
|
|
|
|
InstallWizard(HWND hwndParent)
|
|
Runs the wizard that switches to multiuser mode.
|
|
|
|
AddUserWizard(HWND hwndParent)
|
|
Runs the wizard that adds a new user, invoking the go-multiuser wizard
|
|
if necessary.
|
|
|
|
UserCPL(HWND hwndParent)
|
|
Invokes the general user management UI as seen in Control panel, invoking
|
|
the go-multiuser wizard if necessary.
|
|
|
|
************************************************************************/
|
|
|
|
DECLARE_INTERFACE_(IUserDatabase, IUnknown)
|
|
{
|
|
// *** IUnknown methods ***
|
|
STDMETHOD(QueryInterface) (THIS_ REFIID riid, LPVOID * ppvObj) PURE;
|
|
STDMETHOD_(ULONG,AddRef) (THIS) PURE;
|
|
STDMETHOD_(ULONG,Release) (THIS) PURE;
|
|
|
|
STDMETHOD(Install) (THIS_ LPCSTR pszSupervisorName, LPCSTR pszSupervisorPassword,
|
|
LPCSTR pszRatingsPassword, IUserProfileInit *pInit) PURE;
|
|
STDMETHOD(AddUser) (THIS_ LPCSTR pszName, IUser *pSourceUser,
|
|
IUserProfileInit *pInit, IUser **ppOut) PURE;
|
|
STDMETHOD(GetUser) (THIS_ LPCSTR pszName, IUser **ppOut) PURE;
|
|
STDMETHOD(GetSpecialUser) (THIS_ DWORD nSpecialUserCode, IUser **ppOut) PURE;
|
|
STDMETHOD(GetCurrentUser) (THIS_ IUser **ppOut) PURE;
|
|
STDMETHOD(SetCurrentUser) (THIS_ IUser *pUser) PURE;
|
|
STDMETHOD(DeleteUser) (THIS_ LPCSTR pszName) PURE;
|
|
STDMETHOD(RenameUser) (THIS_ LPCSTR pszOldName, LPCSTR pszNewName) PURE;
|
|
STDMETHOD(EnumUsers) (THIS_ IEnumUnknown **ppOut) PURE;
|
|
|
|
STDMETHOD(Authenticate) (THIS_ HWND hwndOwner, DWORD dwFlags,
|
|
LPCSTR pszName, LPCSTR pszPassword,
|
|
IUser **ppOut) PURE;
|
|
|
|
STDMETHOD(InstallComponent) (THIS_ REFCLSID clsidComponent, LPCSTR pszName,
|
|
DWORD dwFlags) PURE;
|
|
STDMETHOD(RemoveComponent) (THIS_ REFCLSID clsidComponent, LPCSTR pszName) PURE;
|
|
STDMETHOD(InstallWizard) (THIS_ HWND hwndParent) PURE;
|
|
STDMETHOD(AddUserWizard) (THIS_ HWND hwndParent) PURE;
|
|
|
|
STDMETHOD(UserCPL) (THIS_ HWND hwndParent) PURE;
|
|
};
|
|
|
|
// codes for IUserDatabase::GetSpecialUser
|
|
|
|
const DWORD GSU_CURRENT = 0; // current user
|
|
const DWORD GSU_DEFAULT = 1; // default user profile
|
|
|
|
// flags for IUserDatabase::Authenticate
|
|
const DWORD LUA_DIALOG = 0x00000001; // display dialog to get credentials
|
|
// otherwise use pszName, pszPassword
|
|
const DWORD LUA_SUPERVISORONLY = 0x00000002; // authenticate supervisors only
|
|
const DWORD LUA_FORNEXTLOGON = 0x00000004; // cache credentials for next logon
|
|
|
|
// flags for IUserDatabase::InstallComponent
|
|
const DWORD SETTINGS_NS_CAN_WRITE = 0x01; // non-supervisors can change their own settings
|
|
|
|
#endif // _MSLUAPI_H_
|