able/windows-nt
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
windows-nt/Source/XPSP1/NT/admin/netui/common/h/newprof.h
CryptoAlgo Inc b3cac27891 Add source files
2020-09-26 16:20:57 +08:00

591 lines
19 KiB
C
Raw Blame History

/********************************************************************/
/** Microsoft LAN Manager **/
/** Copyright(c) Microsoft Corp., 1990,1991 **/
/********************************************************************/
/*
newprof.h
C-language wrappers for ini-file-handling classes
FILE HISTORY:
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
05/28/91 jonn Restructured to allow preferences in LMUSER.INI
*/
#ifndef _NEWPROF_H_
#define _NEWPROF_H_
/****************************************************************************
MODULE: NewProf.h
PURPOSE: Handles low-level manipulation of user preference files
FUNCTIONS:
UserPreferenceRead() - Reads the preferences from permanent storage
into a file image, for future UserPreference or
UserPref calls.
UserPreferenceWrite() - Writes the preferences from a file image
into permanent storage.
UserPreferenceFree() - Frees memory claimed by a file image.
UserPrefStringQuery() - queries a single user preference string.
UserPrefStringSet() - saves a single user preference string.
It is generally advisable to immediately precede
this call with UserPreferenceRead, and to
immediately follow it with UserPreferenceSet.
UserPrefBoolQuery() - queries a single user preference bool value.
UserPrefBoolSet() - saves a single user preference bool value.
Same usage recommendations as UserPrefStringSet.
UserPrefProfileQuery() - Returns one device connection from a file
image.
UserPrefProfileEnum() - Lists all device connections in a file image.
UserPrefProfileSet() - Changes a device connection in a file image.
Same usage recommendations as UserPrefStringSet.
UserPrefProfileTrim() - Trims all components in a file image
which are not relevant to device connections.
COMMENTS:
These APIs are wrappers to the C++ INI-file handling classes defined
in newprof.hxx. Most clients will prefer to use the wrapper APIs,
including all C clients. These wrapper APIs provide almost all
the functionality of the C++ APIs. The C++ APIs are more subject to
change with changing implementation (NT configuration manager, DS)
than are these C-language wrappers.
UserPreference routines:
Under LM21, these routines read and write the local LMUSER.INI.
These sticky values are therefore all local to the workstation;
this mechanism is not intended for values associated with a user.
Under LM30, the preferences in LMUSER.INI will only be used if the
preferences stored in the DS (NT Configuration Manager?) are
unavailable. Some preferences, such as default username, will be
stored in LMUSER.INI regardless.
UserPreferenceRead returns a PFILEIMAGE which the UserPreference APIs
can interpret as an image of the LMUSER.INI file. This PFILEIMAGE
must be passed through to UserPreferenceWrite and to the
UserPrefProfile, UserPrefBool etc. APIs. When this image is no
longer needed, it should be freed with UserPreferenceFree.
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 UserPreferenceRead, make the change in the
cache with UserPrefBoolSet (et al), and immediately rewrite the
profile with UserPreferenceWrite; this reduces the chance that
another user's changes will be lost.
When successful, these APIs return NERR_Success (0). The following
are the error codes returned by the UserPref APIs:
NERR_CfgCompNotFound: the specified component is not in the file
NERR_CfgParamNotFound: the specified parameter is not in the file,
or it is in the file but is not valid for a parameter of
this type.
NERR_InvalidDevice: bad devicename argument
ERROR_BAD_NET_NAME: bad remotename argument
ERROR_NOT_ENOUGH_MEMORY: lack of global memory
other file read and file write errors
UserPref routines:
These routines read and write one particular type of sticky
values. For example, the UserPrefProfile APIs read and write
device profile entries, while UserPrefBool APis read and write
boolean-valued entries. Client programs must still read the file
image first with UserPreferenceRead, save the changes with
UserPreferenceWrite, and free the file image with UserPreferenceFree.
Use UserPrefProfileTrim when you intend to keep the file image
around for a long time (e.g. in a cache), and are not iterested
in entries other than device connections. Do not write such a
trimmed file image, you will lose the other entries!
Use UserPrefStringSet(pfileimage,usKey,NULL) to remove both
string-valued parameters and boolean-valued parameters.
CAVEATS:
These routines take PSZ and CPSZ buffers because these are
explicitly far for C programs (in particular lui\profile.c), but
do not generate errors under C++.
****************************************************************************/
/* returncodes: */
/* global macros */
#include <newprofc.h>
/* typedefs: */
typedef PVOID PFILEIMAGE;
typedef PFILEIMAGE FAR * PPFILEIMAGE;
/* functions: */
/*************************************************************************
NAME: UserPreferenceRead
SYNOPSIS: UserPreferenceRead attempts to read the user's profile from
permanent storage (<cpszLanroot>\LMUSER.INI for LM21).
It returns a PFILEIMAGE which serves as a "file image" for use
of the other APIs.
INTERFACE: UserPreferenceRead( ppFileImage )
ppFileImage - returns pointer to a file image.
Return values are:
NERR_Success
ERROR_NOT_ENOUGH_MEMORY
errors in NetWkstaGetInfo[1]
file read errors
USES: Use to obtain a file image for use in the UserPref APIs.
NOTES: Currently, the values are stored in LANMAN.INI, and hence
each value is per machine.
Use UserPreferenceFree to release the file image when
it is no longer needed.
Some users may choose to ignore ERROR_FILE_NOT_FOUND.
The file image must be freed regardless of the return
code.
HISTORY:
jonn 10/11/90 Created
jonn 05/28/91 Restructured to allow preferences in LMUSER.INI
jonn 06/26/91 No longer takes LANROOT parameter
**************************************************************************/
APIERR UserPreferenceRead(
PPFILEIMAGE ppFileImage
) ;
/*************************************************************************
NAME: UserPreferenceWrite
SYNOPSIS: UserPreferenceWrite attempts to write the user's profile
back to permanent storage.
INTERFACE: UserPreferenceWrite( pFileImage )
pFileImage - a file image originally obtained from
UserPreferenceRead.
Return values are:
NERR_Success
ERROR_NOT_ENOUGH_MEMORY
file write errors
USES: Use to write out changes to the preferences in a file image.
HISTORY:
jonn 10/11/90 Created
jonn 05/28/91 Restructured to allow preferences in LMUSER.INI
jonn 06/26/91 No longer takes LANROOT parameter
**************************************************************************/
APIERR UserPreferenceWrite(
PFILEIMAGE pFileImage
) ;
/*************************************************************************
NAME: UserPreferenceFree
SYNOPSIS: UserPreferenceFree releases a file image.
INTERFACE: UserPreferenceFree( pFileImage )
pFileImage - a file image originally obtained from
UserPreferenceRead.
RETURNS: NERR_Success
USES: Use when a file image is no longer needed. File images
use a considerable amount of memory, so be sure to free
them.
NOTES: It is permitted to free a null file image pointer.
CAVEATS: Do not use the file image after it has been freed.
HISTORY:
jonn 10/11/90 Created
jonn 05/28/91 Restructured to allow preferences in LMUSER.INI
**************************************************************************/
APIERR UserPreferenceFree(
PFILEIMAGE pFileImage
) ;
/*************************************************************************
NAME: UserPrefStringQuery
SYNOPSIS: Queries a user preference (i.e. remembered string).
INTERFACE: UserPrefStringQuery( pFileImage, usKey, pszBuffer, cbBuffer )
pFileImage - as obtained from UserPreferenceRead
usKey - will indicate which value we want, as defined
in newprofc.h.
pszBuffer - pointer to buffer that will receive value
cbBuffer - size of buffer in bytes
return values are:
NERR_Success
NERR_CfgCompNotFound
NERR_CfgParamNotFound
ERROR_INVALID_PARAMETER: bad usKey
NERR_BufTooSmall
ERROR_NOT_ENOUGH_MEMORY
USES: Use to recall string-valued parameters, normally things
like default logon name. Do not use for boolean-valued
parameters -- for those, use UserPrefBool instead.
NOTES: Currently, the values are stored in LANMAN.INI, and hence
each value is per machine.
A buffer of size MAXPATHLEN+1 is guaranteed to be large enough.
HISTORY:
chuckc 03/07/91 Created
jonn 05/28/91 Restructured to allow preferences in LMUSER.INI
**************************************************************************/
APIERR UserPrefStringQuery( PFILEIMAGE pFileImage,
USHORT usKey,
PSZ pszBuffer,
USHORT cbBuffer) ;
/*************************************************************************
NAME: UserPrefStringSet
SYNOPSIS: Sets a user preference (i.e. remembered string).
INTERFACE: UserPrefStringSet( pFileImage, usKey, pszValue )
pFileImage - as obtained from UserPreferenceRead
usKey - will indicate which value we want, as defined
in newprofc.h.
pszValue - pointer to null-terminated string to be remembered
return values are:
NERR_Success
ERROR_INVALID_PARAMETER: bad usKey
ERROR_NOT_ENOUGH_MEMORY
USES: Use to create or change string-valued parameters,
normally things like default logon name, etc. Do not use
for boolean-valued parameters -- for those, use UserPrefBool
instead.
CAVEATS: Note that this API only modifies the file image; you must
call UserPreferenceWrite to save the change in permanent
storage.
NOTES: Currently, the values are stored in LANMAN.INI, and hence
each value is per machine.
Also used to delete boolean-valued parameters.
HISTORY:
chuckc 03/07/91 Created
jonn 05/28/91 Restructured to allow preferences in LMUSER.INI
**************************************************************************/
APIERR UserPrefStringSet( PFILEIMAGE pFileImage,
USHORT usKey,
CPSZ cpszValue) ;
/*************************************************************************
NAME: UserPrefBoolQuery
SYNOPSIS: Queries a boolean user preference
INTERFACE: UserPrefBoolQuery( pFileImage, usKey, pfValue )
pFileImage - as obtained from UserPreferenceRead
usKey - will indicate which value we want, as defined
in newprofc.h.
pfValue - pointer to BOOL that will contain value
return values as UserPrefStringQuery
USES: as UserPrefStringQuery for boolean-valued parameters
CAVEATS: as UserPrefStringQuery for boolean-valued parameters
NOTES: as UserPrefStringQuery for boolean-valued parameters
We take USERPREF_YES to be true, USERPREF_NO to be false
(case-insensitive); other values are invalid.
os2def.h defines PBOOL as BOOL FAR *.
HISTORY:
chuckc 03/07/91 Created
jonn 05/28/91 Restructured to allow preferences in LMUSER.INI
**************************************************************************/
APIERR UserPrefBoolQuery( PFILEIMAGE pFileImage,
USHORT usKey,
PBOOL pfValue) ;
/*************************************************************************
NAME: UserPrefBoolSet
SYNOPSIS: Sets a boolean user preference
INTERFACE: UserPrefBoolSet( pFileImage, usKey, fValue )
pFileImage - as obtained from UserPreferenceRead
usKey - will indicate which value we want, as defined
in newprofc.h.
fValue - BOOL value, true or false
return values as UserPrefStringSet
USES: as UserPrefStringSet for boolean-valued parameters
CAVEATS: as UserPrefStringSet for boolean-valued parameters
NOTES: as UserPrefStringSet for boolean-valued parameters
We write USERPREF_YES for TRUE, USERPREF_NO for FALSE.
Use UserPrefStringSet to delete boolean-valued parameters.
HISTORY:
chuckc 03/07/91 Created
jonn 05/28/91 Restructured to allow preferences in LMUSER.INI
**************************************************************************/
APIERR UserPrefBoolSet( PFILEIMAGE pFileImage,
USHORT usKey,
BOOL fValue) ;
/*************************************************************************
NAME: UserPrefProfileQuery
SYNOPSIS: Queries a device-connection user preference
INTERFACE: UserPrefProfileQuery( pFileImage, cpszDeviceName,
pszBuffer, cbBuffer, psAsgType, pusResType )
pFileImage - as obtained from UserPreferenceRead
cpszDeviceName - indicates which device we want
pszBuffer - buffer into which to store remote name
cbBuffer - length of buffer in bytes
psAsgType - returns asgType of remote device
pusResType - returns resType of remote device
return values as UserPrefStringQuery
ERROR_INVALID_PARAMETER: bad cpszDeviceName
USES: as UserPrefStringQuery for device-connection parameters
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 those return values.
CAVEATS: as UserPrefStringQuery for device-connection parameters
Note that it is the caller's reponsibility to deal with
the case where the user is not logged on and should therefore
see no unavailable connections.
NOTES: as UserPrefStringQuery for device-connection parameters
os2def.h defines PSHORT and PUSHORT as explicitly FAR.
HISTORY:
chuckc 03/07/91 Created
jonn 05/28/91 Restructured to allow preferences in LMUSER.INI
**************************************************************************/
APIERR UserPrefProfileQuery(
PFILEIMAGE pFileImage,
CPSZ cpszDeviceName,
PSZ pszBuffer, // returns UNC, alias or domain name
USHORT cbBuffer, // length of above buffer in bytes
PSHORT psAsgType, // as ui1_asg_type / ui2_asg_type
// ignored if NULL
PUSHORT pusResType // ignore / as ui2_res_type
// ignored if NULL
) ;
/*************************************************************************
NAME: UserPrefProfileEnum
SYNOPSIS: Lists all device-connection user preferences
INTERFACE: UserPrefProfileEnum( pFileImage, pszBuffer, cbBuffer );
pFileImage - as obtained from UserPreferenceRead
pszBuffer - buffer into which to store list of device names
cbBuffer - length of buffer in bytes
return values are:
ERROR_NOT_ENOUGH_MEMORY
NERR_BufTooSmall
USES: Returns a list of all devices for which the file image
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)
CAVEATS: Note that it is the caller's reponsibility to deal with
the case where the user is not logged on and should therefore
see no unavailable connections.
HISTORY:
chuckc 03/07/91 Created
jonn 05/28/91 Restructured to allow preferences in LMUSER.INI
**************************************************************************/
APIERR UserPrefProfileEnum(
PFILEIMAGE pFileImage,
PSZ pszBuffer, // returns NULL-NULL list of device names
USHORT cbBuffer // length of above buffer in bytes
) ;
/*************************************************************************
NAME: UserPrefProfileSet
SYNOPSIS: Sets a device-connection user preference
INTERFACE: UserPrefProfileSet( pFileImage, cpszDeviceName,
cpszRemoteName, sAsgType, usResType )
pFileImage - as obtained from UserPreferenceRead
cpszDeviceName - Device to associate with remote resource
cpszRemoteName - name of remote resource (UNCname for LM21)
Use NULL to delete entries
sAsgType - asgType of remote device
usResType - resType of remote device (ignored for LM21)
return values as UserPrefStringSet
ERROR_INVALID_PARAMETER: bad cpszDeviceName
USES: as UserPrefStringSet for device-connection parameters
CAVEATS: as UserPrefStringSet for device-connection parameters
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.
Note that it is the caller's reponsibility to deal with
the case where the user is not logged on and should therefore
see no unavailable connections.
NOTES: as UserPrefStringSet for device-connection parameters
LM21 programs should pass 0 for usResType
Pass cpszRemoteName==NULL to delete device-connection
parameters.
HISTORY:
chuckc 03/07/91 Created
jonn 05/28/91 Restructured to allow preferences in LMUSER.INI
**************************************************************************/
APIERR UserPrefProfileSet(
PFILEIMAGE pFileImage,
CPSZ cpszDeviceName,
CPSZ cpszRemoteName,
short sAsgType, // as ui1_asg_type / ui2_asg_type
unsigned short usResType // as ui2_res_type
) ;
/*************************************************************************
NAME: UserPrefProfileTrim
SYNOPSIS: Trims an file image to contain only device-connection
components.
INTERFACE: UserPrefProfileTrim( pFileImage )
pFileImage - as obtained from UserPreferenceRead
USES: This is meant for use where a "cache" of device
connection parameters will be held for a long time.
RETURNS: NERR_NOT_ENOUGH_MEMORY
Does not fail if component not found
CAVEATS: Do not write a trimmed file image -- this will destroy all
parameters which are not device connections!
NOTES: Free the file image if this API fails.
HISTORY:
jonn 06/26/91 Created
**************************************************************************/
APIERR UserPrefProfileTrim(
PFILEIMAGE pFileImage
) ;
#endif // _NEWPROF_H_
Reference in a new issue View git blame Copy permalink