|
|
//*********************************************************************
//* 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 beobtained by CLSID or name, or through enumeration; in both cases, this isrelative 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 allowsvarious operations to be performed on a particular user. To obtain oneof these interfaces, the companion interface IUserDatabase must beused -- its AddUser, GetUser, and GetCurrentUser member functions allreturn IUser objects, as does IEnumUsers::Next.
In all descriptions here, "the user" refers to the user which thisILocalUser object describes. "The current user" means the user whois 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 objectcorresponds to the current user. If the current user is not a supervisorand the IUser object refers to a different user, a still more limited setof 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 newuser'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. Anyactivities which deal with the list of users in any way are done throughthis interface; operations which deal with the properties (other than thename) 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_
|
