|
|
/**********************************************************************//** Microsoft LAN Manager **//** Copyright(c) Microsoft Corp., 1990 **//**********************************************************************/
/*
winprof.hxx High-level profile APIs (PROFILE object)
The PROFILE class contains a higher-level interface to the UserProfile APIs. It is meant solely for use by WINNET. All WINNET modules should use the PROFILE APIs rather than going directly to the UserProfile APIs. Applications other than WINNET will have to use the UserProfile APIs.
The PROFILE class adds the following to the basic UserProfile APIs:
- Establishes connections as specified in profile, including prompting for password
- Displays error popups as appropriate during profile load
Note that the UserProfile APIs which the PROFILE class accesses use access global variables. For this reason, it never makes sense to have more than one PROFILE object, and it is generally not desirable to have a PROFILE object of other than global scope.
Those PROFILE APIs which take an HWND parameter may give control to Windows or call Windows APIs, but those which do not take an HWND parameter will never do either. Thus, of the exported APIs, only PROFILE::Load is liable to compact memory.
Several PROFILE methods take a UINT *puWnErr parameter in order to return an auxiliary WN_ error code. In these cases, the following combinations of error codes are possible: Return code: Auxiliary: Meaning NERR_Success WN_SUCCESS Operation was successful NERR_Success WN_CANCEL Operation cancelled, error already displayed NERR_Success WN_CONTINUE Error occurred, error already displayed <other> <other> Error has not been displayed
PROFILE::Init
Initializes the PROFILE object. Call this before calling any other PROFILE method. Call this method while in the (DS register) context of the shell rather than the context of any application.
Return Values: NERR_Success Success ERROR_NOT_ENOUGH_MEMORY Out of memory
PROFILE::Free
Releases the PROFILE object. Call this after calling all other PROFILE methods.
Return Values: NERR_Success Success
PROFILE::Load
Loads one device connection from the user profile, or loads all device connections from the user profile. Also returns an advisory parameter indicating whether the connection was cancelled, or whether some error has already been reported; note that the return code is NERR_Success if the dialog is cancelled.
Return Values: NERR_Success Success ERROR_NOT_ENOUGH_MEMORY Out of memory other Misc. net error
PROFILE::Query
Asks about a specific connection in the user profile.
If PROFILE::Query returns NERR_Success, the other fields are valid.
sResourceType is one of the values of field use_info_1.ui1_arg_type.
sResourceName_Type is one of the values of field use_info_2.ui1_res_type.
Return Values: NERR_Success Success NERR_UseNotFound Connection not in profile ERROR_NOT_ENOUGH_MEMORY Out of memory other Misc. net error
PROFILE::Enum
Lists all connections in the user profile. This list appears as a list of null-terminated strings with NULL-NULL at the end, e.g.
D:\0G:\0LPT1\0E:\0\0
The list is in no defined order. Pass only a valid pointer to a BUFFER object.
If PROFILE::Enum returns WN_SUCCESS, the bufDeviceList field is valid.
Return Values: NERR_Success Success ERROR_INSUFFICIENT_BUFFER The pbufDeviceList buffer is too small. ERROR_NOT_ENOUGH_MEMORY Out of memory other Misc. net error
PROFILE::Change
Saves a connection into the user profile, or removes a connection from the user profile. PROFILE::Change will prompt the user before creating a new profile entry.
If cnlsResourceName.strlen() == 0, PROFILE::Change will remove an existing profile entry.
sResourceType is one of the values of field use_info_1.ui1_arg_type.
usResourceName_Type is one of the values of field use_info_2.ui1_res_type.
Return Values: NERR_Success Success ERROR_NOT_ENOUGH_MEMORY Out of memory other Misc. net error
PROFILE::Remove
Removes a <device,remote> association from the profile. If the given device is associated with a different remote name than the one passed as a parameter, this method does nothing but return success.
This method is intended to be used in disconnect operations. Then, if the the profile contained a previously unavailable device, which was left in the profile when a new connection was established on top of the unavailable device, the profile will be unchanged. Thus, the previously "covered" or "hidden" unavailable device, now becomes what the local device is "connected" to again.
cnlsDeviceName is the local device name in the <device,remote> pair.
cnlsResourceName is the remote name in the <device,remote> pair. This name is typically that DEVICE::QueryRemoteName returns before DEVICE::Disconnect is called.
Return Values: NERR_Success Success other Misc. net error
PROFILE::MapNetError
Miscallaneous utility routine to help convert an NERR_ error code to a WN_ error code.
PROFILE::DisplayChangeError
Displays an error popup for a failure to change the profile. This routine should only be used for SYS and NET error codes, not for IERR error codes.
PROFILE::DisplayLoadError
Displays an error popup for a failure to load some connecion in the profile. This routine should only be used for SYS and NET error codes, not for IERR error codes. If you pass fAllowCancel then the user will also be able to press a cancel button. If they did press cancel, then *pfDidCancel will be TRUE, otherwise *pfDidCancel will be FALSE. Note it is only valid to check pfDidCancel if fAllowCancel is TRUE.
FILE HISTORY:
jonn 06-Dec-1990 Created jonn 27-Dec-1990 Updated to CDD version 0.4 jonn 02-Jan-1991 Integrated into SHELL jonn 07-Jan-1991 All methods become static jonn 10-Jan-1991 Removed PSHORT, PUSHORT jonn 25-Feb-1991 Changed to return NERR error codes jonn 06-Mar-1991 Added Display[Read|Change]Error jonn 11-Mar-1991 Modified Display[Load|Change]Error jonn 14-Mar-1991 Provide LogonUser to UPQuery rustanl 10-Apr-1991 Added PROFILE::Remove jonn 22-May-1991 Removed PROFILE_CANCELLED return code JohnL 18-Jun-1991 Allow user to cancel loading profiles (added flags to DisplayLoadError & LoadOne). Yi-HsinS 31-Dec-1991 Unicode work - change char to TCHAR beng 06-Apr-1992 More Unicode work
*/
#ifndef _WINPROF_HXX
#define _WINPROF_HXX
#include <miscapis.hxx> // for USE_RES_DEFAULT
class BUFFER; // declared in uibuffer.hxx
class PROFILE {
public:
/* no constructor or destructor */
static APIERR Init( );
static APIERR Free( );
static BOOL ConfirmUsername( const TCHAR * cpszUsername );
static APIERR Load( UINT * puWnErr, HWND hParent, NLS_STR *pnlsDeviceName );
static APIERR Query( const NLS_STR& cnlsDeviceName, NLS_STR& nlsResourceName, short * psResourceType, unsigned short *pusResourceName_Type = NULL // LM21 programs should use default
);
static APIERR Enum( BUFFER * pbufDeviceList );
static APIERR Change( const NLS_STR& cnlsDeviceName, const NLS_STR& cnlsResourceName, short sResourceType, unsigned short usResourceName_Type = USE_RES_DEFAULT // LM21 programs should use default
// defined in miscapis.hxx
);
static APIERR Remove( const NLS_STR & cnlsDeviceName, const NLS_STR & cnlsResourceName );
static UINT MapNetError( APIERR errNetErr );
static void DisplayChangeError( HWND hwndParent, APIERR errProfErr );
static void DisplayLoadError( HWND hwndParent, APIERR errProfErr, const TCHAR * pchDevice, const TCHAR * pchResource, BOOL fAllowCancel = FALSE, BOOL *pfDidCancel = NULL );
protected:
/*
* PROFILE::Read * * Reads user profile into cache for the use of the other internal * profile functions. * * Return Values: * NERR_Success Success * ERROR_NOT_ENOUGH_MEMORY Out of memory * other Misc. error */
static APIERR Read();
/*
* PROFILE::LoadOne * * Loads one device connection from the user profile. Used only by * PROFILE::Load(). * * Return Values: * NERR_Success Success * ERROR_NOT_ENOUGH_MEMORY Out of memory * other Misc. error */
static APIERR LoadOne( UINT * puWnErr, HWND hParent, const TCHAR * cpszLogonUser, NLS_STR nlsDeviceName, BOOL fAllowCancel = FALSE, BOOL *pfDidCancel = NULL );
/*
* PROFILE::LoadAll * * Loads all device connections from the user profile. Used only by * PROFILE::Load(). * * Return Values: * NERR_Success Success * ERROR_NOT_ENOUGH_MEMORY Out of memory * other Misc. error */
static APIERR LoadAll( UINT * puWnErr, HWND hParent, const TCHAR * cpszLogonUser );
/*
* PROFILE::DisplayError * * Internal routine for the user of DisplayChangeError and DisplayReadError */
static void DisplayError( HWND hwndParent, MSGID msgidMsgNum, APIERR errProfErr, ULONG ulHelpTopic, const TCHAR * pchDevice, const TCHAR * pchResource, BOOL fAllowCancel = FALSE, BOOL *pfDidCancel = NULL );
}; // end of class PROFILE
#endif // _WINPROF_HXX
|
