428 lines
15 KiB
C
428 lines
15 KiB
C
|
/********************************************************************/
|
||
|
|
/** Microsoft LAN Manager **/
|
||
|
|
/** Copyright(c) Microsoft Corp., 1987-1990 **/
|
||
|
|
/********************************************************************/
|
||
|
|
|
||
|
|
/*
|
||
|
|
* FILE STATUS:
|
||
|
|
* 10/11/90 jonn created
|
||
|
|
* 01/10/91 jonn removed PSHORT, PUSHORT
|
||
|
|
* 01/27/91 jonn changed from CFGFILE, added UserProfileInit/Free
|
||
|
|
* 02/02/91 jonn added UserProfileWrite/Clear, removed Confirm,
|
||
|
|
* redefined Set.
|
||
|
|
* 02/04/91 jonn added cpszUsername param to Query, Enum, Set
|
||
|
|
* 03/08/91 chuckc added UserPreferenceXXX() calls.
|
||
|
|
* 04/16/91 jonn added USERPREF_CONFIRMATION and USERPREF_ADMINMENUS
|
||
|
|
* 05/08/91 jonn Added canonicalization of netnames, canonicalize
|
||
|
|
* on read
|
||
|
|
* 06-Apr-92 beng Nuked PSZ and CPSZ types (Unicode pass)
|
||
|
|
*/
|
||
|
|
|
||
|
|
/****************************************************************************
|
||
|
|
|
||
|
|
MODULE: UIProf.h
|
||
|
|
|
||
|
|
PURPOSE: Handles low-level manipulation of user profile files
|
||
|
|
Handles user preferences (saved info)
|
||
|
|
|
||
|
|
FUNCTIONS:
|
||
|
|
|
||
|
|
UserProfileInit() - Initializes the user profile module. The
|
||
|
|
cached profile is initially empty.
|
||
|
|
UserProfileFree() - Frees memory used by the user profile module.
|
||
|
|
UserProfileRead() - Caches the profile for the specified user from
|
||
|
|
permanent storage into a global data structure,
|
||
|
|
for future UserProfileQuery/Enum calls.
|
||
|
|
Call with NULL to clear the cached profile.
|
||
|
|
UserProfileWrite() - Writes the cached profile into permanent storage.
|
||
|
|
UserProfileQuery() - Returns one entry from the cached profile.
|
||
|
|
UserProfileEnum() - Lists all entries in the cached profile.
|
||
|
|
UserProfileSet() - Changes the cached profile. It is generally
|
||
|
|
advisable to immediately precede this call with
|
||
|
|
UserProfileRead, and immediately follow it with
|
||
|
|
UserProfileWrite.
|
||
|
|
|
||
|
|
|
||
|
|
UserPreferenceQuery() - queries a single user preference string.
|
||
|
|
UserPreferenceSet() - saves a single user preference string.
|
||
|
|
UserPreferenceQueryBool() - queries a user preference bool value.
|
||
|
|
UserPreferenceSetBool() - saves a user preference bool value.
|
||
|
|
|
||
|
|
COMMENTS:
|
||
|
|
|
||
|
|
|
||
|
|
UserProfile routines:
|
||
|
|
|
||
|
|
Under LM30, the profile in $(LANROOT) will only be used if the
|
||
|
|
profile stored in the DS is unavailable.
|
||
|
|
|
||
|
|
Be sure to cache a user's profile before calling
|
||
|
|
UserProfileQuery, UserProfileEnum or UserProfileSet. These
|
||
|
|
routines will fail if no profile is currently cached.
|
||
|
|
|
||
|
|
The cpszUsername argument is handled differently from different
|
||
|
|
APIs. UserProfileRead and UserProfileWrite use it to specify the
|
||
|
|
user profile to read or write. UserProfileRead will also remember
|
||
|
|
the last username in a static variable whether the call succeeds
|
||
|
|
or not. Null or empty user names clear the stored profile in
|
||
|
|
UserProfileRead, and return NERR_BadUsername in
|
||
|
|
UserProfileWrite.
|
||
|
|
UserProfileQuery, Enum and Set compare cpszUsername with the
|
||
|
|
last username remembered by UserProfileRead. If UserProfileRead
|
||
|
|
has never been called, or if it was last called with a different
|
||
|
|
username (NULL and empty string are equivalent), these calls
|
||
|
|
fail with ERROR_GEN_FAILURE. In this way, you can use the
|
||
|
|
cpszUsername parameter to check whether the correct profile is
|
||
|
|
loaded, or you can use it to check whether your module has just
|
||
|
|
started and should perform the initial UserProfileRead. Note that
|
||
|
|
UserProfileRead(NULL) will prevent the ERROR_GEN_FAILURE return
|
||
|
|
code when cpszUsername==NULL.
|
||
|
|
|
||
|
|
Remember that a user may be logged on from several different
|
||
|
|
machines, and that the cached profile is not automatically
|
||
|
|
updated. When the profile is to be changed in permanent
|
||
|
|
storage, it is generally advisable to reread the profile from
|
||
|
|
permanent storage with UserProfileRead, make the change in the
|
||
|
|
cache with userProfileSet, and immediately rewrite the profile
|
||
|
|
with UserProfileWrite; this reduces the chance that another
|
||
|
|
user's changes will be lost.
|
||
|
|
|
||
|
|
When successful, the UserProfile APIs return NO_ERROR (0). The
|
||
|
|
following are the error codes returned by the UserProfile APIs:
|
||
|
|
|
||
|
|
NERR_BadUsername: bad username argument
|
||
|
|
NERR_InvalidDevice: bad devicename argument
|
||
|
|
ERROR_BAD_NETPATH: bad lanroot argument
|
||
|
|
ERROR_BAD_NET_NAME: bad remotename argument
|
||
|
|
NERR_UseNotFound: the specified device is not listed in the profile
|
||
|
|
ERROR_NOT_ENOUGH_MEMORY: lack of global memory or overfull profile
|
||
|
|
ERROR_GET_FAILURE: username mismatch
|
||
|
|
ERROR_FILE_NOT_FOUND: any file read error
|
||
|
|
ERROR_WRITE_FAULT: any file write error
|
||
|
|
|
||
|
|
BUGBUG We must determine correct behavior when no user is logged on.
|
||
|
|
BUGBUG Do we return ERROR_GEN_FAILURE? NO_ERROR? what?
|
||
|
|
|
||
|
|
|
||
|
|
User preferences routines:
|
||
|
|
|
||
|
|
These routines read and write sticky values in some section
|
||
|
|
of the local LANMAN.INI. These sticky values are therefore
|
||
|
|
all local to the workstation; this mechanism is not intended
|
||
|
|
for values associated with a user. Unlike the UserProfile
|
||
|
|
routines, these routines do not cache any data.
|
||
|
|
|
||
|
|
|
||
|
|
****************************************************************************/
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
/* returncodes: */
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
/* global macros */
|
||
|
|
#define PROFILE_DEFAULTFILE "LMUSER.INI"
|
||
|
|
|
||
|
|
#define USERPREF_MAX 256 // arbitrary limit to ease mem alloc
|
||
|
|
|
||
|
|
#define USERPREF_YES "yes" // this is not internationalized.
|
||
|
|
#define USERPREF_NO "no" // ditto
|
||
|
|
|
||
|
|
#define USERPREF_NONE 0 // no such value
|
||
|
|
#define USERPREF_AUTOLOGON 0x1 // auto logon
|
||
|
|
#define USERPREF_AUTORESTORE 0x2 // auto restore profile
|
||
|
|
#define USERPREF_SAVECONNECTIONS 0x3 // auto save connections
|
||
|
|
#define USERPREF_USERNAME 0x4 // user name
|
||
|
|
#define USERPREF_CONFIRMATION 0x5 // confirm actions?
|
||
|
|
#define USERPREF_ADMINMENUS 0x6 // Admin menus (PrintMgr)
|
||
|
|
|
||
|
|
#ifdef __cplusplus
|
||
|
|
extern "C" {
|
||
|
|
#endif
|
||
|
|
|
||
|
|
/* functions: */
|
||
|
|
|
||
|
|
|
||
|
|
/*
|
||
|
|
* UserProfileInit prepares the profile library. This API must be
|
||
|
|
* called exactly once, and before any other UserProfile APIs.
|
||
|
|
*
|
||
|
|
* error returns:
|
||
|
|
* ERROR_NOT_ENOUGH_MEMORY
|
||
|
|
*/
|
||
|
|
USHORT UserProfileInit( void
|
||
|
|
);
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
/*
|
||
|
|
* UserProfileFree releases memory claimed by the profile library.
|
||
|
|
* Do not call UserProfileFree unless the profile library is initialized.
|
||
|
|
* After UserProfileFree, the only permissible UserProfile call is
|
||
|
|
* userProfileInit.
|
||
|
|
*
|
||
|
|
* error returns:
|
||
|
|
* <none>
|
||
|
|
*/
|
||
|
|
USHORT UserProfileFree( void
|
||
|
|
);
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
/*
|
||
|
|
* UserProfileRead attempt to cache the user's profile as stored in
|
||
|
|
* permanent storage (<cpszLanroot>\LMUSER.INI, or the DS for LM30).
|
||
|
|
*
|
||
|
|
* Call with cpszUsername==NULL or cpszUsername=="" to clear cached profile.
|
||
|
|
* In this case, cpszLanroot is ignored.
|
||
|
|
*
|
||
|
|
* UserProfileRead updates the username associated with the current
|
||
|
|
* profile, for use by UserProfileQuery/Enum/Set.
|
||
|
|
*
|
||
|
|
* error returns:
|
||
|
|
* NERR_BadUsername
|
||
|
|
* ERROR_BAD_NETPATH
|
||
|
|
* ERROR_NOT_ENOUGH_MEMORY: includes "profile full" state
|
||
|
|
* ERROR_FILE_NOT_FOUND
|
||
|
|
*/
|
||
|
|
USHORT UserProfileRead(
|
||
|
|
const TCHAR * pszUsername,
|
||
|
|
const TCHAR * pszLanroot
|
||
|
|
);
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
/*
|
||
|
|
* UserProfileWrite attempts to write the user's profile back to
|
||
|
|
* permanent storage (<cpszLanroot>\LMUSER.INI, or the DS for LM30).
|
||
|
|
*
|
||
|
|
* error returns:
|
||
|
|
* NERR_BadUsername
|
||
|
|
* ERROR_BAD_NETPATH
|
||
|
|
* ERROR_NOT_ENOUGH_MEMORY
|
||
|
|
* ERROR_WRITE_FAULT
|
||
|
|
*/
|
||
|
|
USHORT UserProfileWrite(
|
||
|
|
const TCHAR * pszUsername,
|
||
|
|
const TCHAR * pszLanroot
|
||
|
|
);
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
/*
|
||
|
|
* psAsgType returns the device type as in use_info_1 or (LM30) use_info_2
|
||
|
|
* fields ui1_asg_type or (LM30) ui2_asg_type. pusResType returns
|
||
|
|
* the device name type (e.g. UNC, alias, DFS, DS) as in the
|
||
|
|
* use_info_2 ui1_res_type field. Either of these parameters may be
|
||
|
|
* passed as NULL by programs which do not care about the return value.
|
||
|
|
*
|
||
|
|
* cpszUsername is used to confirm that the cached profile is for the
|
||
|
|
* named user. Pass NULL to accept any cached profile (but still
|
||
|
|
* reject if UserProfileRead has not been called).
|
||
|
|
*
|
||
|
|
* error returns:
|
||
|
|
* ERROR_GEN_FAILURE: cached profile is not for the named user
|
||
|
|
* NERR_BadUsername
|
||
|
|
* NERR_InvalidDevice
|
||
|
|
* NERR_UseNotFound
|
||
|
|
* ERROR_NOT_ENOUGH_MEMORY
|
||
|
|
* ERROR_INSUFFICIENT_BUFFER
|
||
|
|
*/
|
||
|
|
USHORT UserProfileQuery(
|
||
|
|
const TCHAR * pszUsername,
|
||
|
|
const TCHAR * pszDeviceName,
|
||
|
|
TCHAR * pszBuffer, // returns UNC, alias or domain name
|
||
|
|
USHORT usBufferSize, // length of above buffer
|
||
|
|
short far * psAsgType, // as ui1_asg_type / ui2_asg_type
|
||
|
|
// ignored if NULL
|
||
|
|
unsigned short far * pusResType // ignore / as ui2_res_type
|
||
|
|
// ignored if NULL
|
||
|
|
);
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
/*
|
||
|
|
* Returns a list of all devices for which the cached profile lists a
|
||
|
|
* connection, separated by nulls, with a null-null at the end.
|
||
|
|
* For example, "LPT1:\0D:\0F:\0" (don't forget the extra '\0'
|
||
|
|
* implicit in "" strings)
|
||
|
|
*
|
||
|
|
* cpszUsername is used to confirm that the cached profile is for the
|
||
|
|
* named user. Pass NULL to accept any cached profile (but still
|
||
|
|
* reject if UserProfileRead has not been called).
|
||
|
|
*
|
||
|
|
* error returns:
|
||
|
|
* NERR_BadUsername
|
||
|
|
* ERROR_NOT_ENOUGH_MEMORY
|
||
|
|
* ERROR_INSUFFICIENT_BUFFER
|
||
|
|
*/
|
||
|
|
USHORT UserProfileEnum(
|
||
|
|
const TCHAR * pszUsername,
|
||
|
|
TCHAR * pszBuffer, // returns NULL-NULL list of device names
|
||
|
|
USHORT usBufferSize // length of above buffer
|
||
|
|
);
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
/*
|
||
|
|
* Changes the cached profile. Follow this call with a call to
|
||
|
|
* UserProfileWrite to write the profile to permanent storage.
|
||
|
|
*
|
||
|
|
* The user is expected to ensure that usResType corresponds to
|
||
|
|
* the type of the remote resource, and that device pszDeviceName
|
||
|
|
* can be connected to a resource of that type.
|
||
|
|
*
|
||
|
|
* Does not canonicalize cpszCanonRemoteName, caller must do this
|
||
|
|
*
|
||
|
|
* cpszUsername is used to confirm that the cached profile is for the
|
||
|
|
* named user. Pass NULL to accept any cached profile (but still
|
||
|
|
* reject if no user profile is cached).
|
||
|
|
*
|
||
|
|
* error returns:
|
||
|
|
* ERROR_GEN_FAILURE: cached profile is not for the named user
|
||
|
|
* NERR_InvalidDevice: bad cpszDeviceName
|
||
|
|
* ERROR_BAD_NET_NAME: bad cpszRemoteName
|
||
|
|
* ERROR_NOT_ENOUGH_MEMORY: includes "profile full" state
|
||
|
|
*/
|
||
|
|
USHORT UserProfileSet(
|
||
|
|
const TCHAR * pszUsername,
|
||
|
|
const TCHAR * pszDeviceName,
|
||
|
|
const TCHAR * pszRemoteName,
|
||
|
|
short sAsgType, // as ui2_asg_type
|
||
|
|
unsigned short usResType // as ui2_res_type
|
||
|
|
);
|
||
|
|
|
||
|
|
|
||
|
|
/*************************************************************************
|
||
|
|
|
||
|
|
NAME: UserPreferenceQuery
|
||
|
|
|
||
|
|
SYNOPSIS: Queries a user preference (ie remembered string).
|
||
|
|
|
||
|
|
INTERFACE: UserPreferenceQuery( usKey, pchValue, cbLen )
|
||
|
|
usKey - will indicate which value we want, as defined
|
||
|
|
in uiprof.h.
|
||
|
|
pchValue - pointer to buffer that will receive value
|
||
|
|
cbLen - size of buffer
|
||
|
|
|
||
|
|
return value is NERR_Success, ERROR_INAVALID_PARAMETER,
|
||
|
|
or NetConfigGet2 error.
|
||
|
|
|
||
|
|
USES: Use to recall values saved by UserPrefenceSet(), normally
|
||
|
|
things like default logon name, etc.
|
||
|
|
|
||
|
|
CAVEATS:
|
||
|
|
|
||
|
|
NOTES: Currently, the values are stored in LANMAN.INI, and hence
|
||
|
|
each value is per machine.
|
||
|
|
|
||
|
|
HISTORY:
|
||
|
|
chuckc 7-Mar-1991 Created
|
||
|
|
|
||
|
|
**************************************************************************/
|
||
|
|
|
||
|
|
USHORT UserPreferenceQuery( USHORT usKey,
|
||
|
|
TCHAR FAR * pchValue,
|
||
|
|
USHORT cbLen);
|
||
|
|
|
||
|
|
/*************************************************************************
|
||
|
|
|
||
|
|
NAME: UserPreferenceSet
|
||
|
|
|
||
|
|
SYNOPSIS: Sets a user preference (remembers a string).
|
||
|
|
|
||
|
|
INTERFACE: UserPreferenceSet( usKey, pchValue )
|
||
|
|
usKey - will indicate which value we want, as defined
|
||
|
|
in uiprof.h.
|
||
|
|
pchValue - pointer to null terminates string to be remembered
|
||
|
|
|
||
|
|
return value is NERR_Success, ERROR_INAVALID_PARAMETER,
|
||
|
|
or NetConfigSet error.
|
||
|
|
|
||
|
|
USES: Use to save values to be retrieved by UserPrefenceQuery(),
|
||
|
|
normally things like default logon name, etc.
|
||
|
|
|
||
|
|
CAVEATS:
|
||
|
|
|
||
|
|
NOTES: Currently, the values are stored in LANMAN.INI, and hence
|
||
|
|
each value is per machine.
|
||
|
|
|
||
|
|
HISTORY:
|
||
|
|
chuckc 7-Mar-1991 Created
|
||
|
|
|
||
|
|
**************************************************************************/
|
||
|
|
|
||
|
|
USHORT UserPreferenceSet( USHORT usKey,
|
||
|
|
TCHAR FAR * pchValue);
|
||
|
|
|
||
|
|
/*************************************************************************
|
||
|
|
|
||
|
|
NAME: UserPreferenceQueryBool
|
||
|
|
|
||
|
|
SYNOPSIS: Queries a BOOL a user preference (remembered flag).
|
||
|
|
|
||
|
|
INTERFACE: UserPreferenceQueryBool( usKey, pfValue )
|
||
|
|
usKey - will indicate which value we want, as defined
|
||
|
|
in uiprof.h.
|
||
|
|
pfValue - pointer to BOOL that will contain value
|
||
|
|
|
||
|
|
return value is NERR_Success, ERROR_INAVALID_PARAMETER,
|
||
|
|
or UserPreferenceQuery error.
|
||
|
|
|
||
|
|
USES: Use to retrieve flags set by by UserPrefenceSetBool(),
|
||
|
|
normally things like auto logon, etc.
|
||
|
|
|
||
|
|
CAVEATS:
|
||
|
|
|
||
|
|
NOTES: Currently, the values are stored in LANMAN.INI, and hence
|
||
|
|
each value is per machine. This func calls
|
||
|
|
UserPreferenceQuery(), taking "yes" or "YES" to be
|
||
|
|
true, "no" or "NO" to be false.
|
||
|
|
|
||
|
|
HISTORY:
|
||
|
|
chuckc 7-Mar-1991 Created
|
||
|
|
|
||
|
|
**************************************************************************/
|
||
|
|
|
||
|
|
|
||
|
|
USHORT UserPreferenceQueryBool( USHORT usKey,
|
||
|
|
BOOL FAR * pfValue) ;
|
||
|
|
|
||
|
|
/*************************************************************************
|
||
|
|
|
||
|
|
NAME: UserPreferenceSetBool
|
||
|
|
|
||
|
|
SYNOPSIS: Sets a user preference flag
|
||
|
|
|
||
|
|
INTERFACE: UserPreferenceSetBool( usKey, fValue )
|
||
|
|
usKey - will indicate which value we want, as defined
|
||
|
|
in uiprof.h.
|
||
|
|
fValue - BOOL value, true or false
|
||
|
|
|
||
|
|
return value is NERR_Success, ERROR_INAVALID_PARAMETER,
|
||
|
|
or UserPreferenceSet error.
|
||
|
|
|
||
|
|
USES: Use to save values to be retrieved by UserPrefenceQueryBool(),
|
||
|
|
normally flags like autologon, etc.
|
||
|
|
|
||
|
|
CAVEATS:
|
||
|
|
|
||
|
|
NOTES: Currently, the values are stored in LANMAN.INI, and hence
|
||
|
|
each value is per machine. This func calls
|
||
|
|
UserPreferenceSet(), taking "yes" or "YES" to be
|
||
|
|
true, "no" or "NO" to be false.
|
||
|
|
We also restrict values to length of < USERPREF_MAX.
|
||
|
|
|
||
|
|
HISTORY:
|
||
|
|
chuckc 7-Mar-1991 Created
|
||
|
|
|
||
|
|
**************************************************************************/
|
||
|
|
|
||
|
|
USHORT UserPreferenceSetBool( USHORT usKey,
|
||
|
|
BOOL fValue);
|
||
|
|
|
||
|
|
#ifdef __cplusplus
|
||
|
|
}
|
||
|
|
#endif
|