[ Home |
Alpha index |
Topic index |
Tutorials |
Download |
Feedback ]
The OS/2 API Project
PrfReset
[ Syntax |
Params |
Returns |
Include |
Usage |
Structs |
Gotchas |
Code |
Also ]
Syntax
bRC = PrfReset( hab,
pprfProfile );
Parameters
-
HAB hab (input)
-
Handle to an anchor block. This is a return value from WinInitialize().
-
PPRFPROFILE pprfProfile (input)
-
Pointer to a PRFPROFILE structure. This will contain the names of the new
profiles to be used. This may contain any valid filename. If a filename isn't
fully qualified, it is assumed to reside in the current working directory. See
the 'Relevant structures' section below for more details. If a file doesn't
exist, it is created by this API call.
Returns
-
BOOL bRC
-
This return value is always either:
TRUE Success
FALSE Error occurred
If FALSE, you may use WinGetLastError() to find out what went wrong.
There is only one possible error PrfReset() may generate:
PMERR_OPENING_INI_FILE 0x1301 Due to an error, the files could
not be opened. This may be due
to a lack of disk space, or
something similar.
Include Info
#define INCL_WINSHELLDATA
or
#define INCL_WIN
or
#define INCL_PM
#include <os2.h>
Usage Explanation
This API changes the default profiles being used by the system. The reason for
this is to allow applications, such as a login program, to change system
defaults to accomodate a new user. The user profile contains settings for
various programs, as well as Presentation Manager preferences (color schemes,
the desktop, etc...). The system profile contains computer-specific variables.
For this reason, PrfReset() will only let you change the user profile. When the
profiles are changed, PrfReset() broadcasts a PL_ALTERED window message to all
running applications. This notifies the program that the profiles have been
changed, and they should re-read them to get the default values for the new
user. (Although there is no guarantee all programs will process this message.
DOS, Windows, and Text-based OS/2 programs do not recieve this message, either.
Relevant Structures
-
PRFPROFILE
-
-
ULONG cchUserName;
-
This is the size, in bytes, of the buffer pointed to by the pszUserName field
(described below).
-
PSZ pszUserName;
-
This points to a buffer holding the name of the new user profile. (in other
Prf* API calls, the user profile handle is specified as HINI_USERPROFILE). This
is a null-terminated (ASCIIZ) string.
-
ULONG cchSysName;
-
This is the size, in bytes, of the buffer pointed to by the pszSysName field
(described below). You should let PrfQueryProfile() set this field for you.
-
PSZ pszSysName;
-
This points to a buffer holding the name of the new system profile. (in other
Prf* API calls, the system profile handle is specified as HINI_SYSTEMPROFILE).
This is a null-terminated (ASCIIZ) string. Again, you should let
PrfQueryProfile() set this field for you.
-
PPRFPROFILE
-
A pointer to a PRFPROFILE structure. Same as (PRFPROFILE *).
Gotchas
First, don't expect all the applications running at any given time to be certain
to process a PL_ALTERED message. Second, you must pass the current system
profile to this function, since you aren't allowed to change it. Usually it is
OS2SYS.INI, but a different filename may be specified in the config.sys. Hence,
you must also call PrfQueryProfile() twice before PrfReset() to get that
information. And since you need a handle to an anchor block, this call may only
be issued from inside a Presentation Manager program. Third, it has been my
experience that the WorkPlace Shell crashes (this is with Warp without Windows
and no fixpak, though.) sometimes when it recieves the PL_ALTERED message.
I've also run out of stack space in this call (although this could be a symptom
of the WPS, and not the code). So, to be safe, don't shirk on the stack space.
If the WPS crashes, after the standard error message, it will reload without a
need to reboot. Fourth, you can SEVERELY frighten the unsuspecting user when
all his icons either change or vanish due to this API. Be careful in how you
use it, or you might have people reboot/format/reinstall from scratch if they
don't know what's going on.
Sample Code
<![CDATA[
/*
* This program merely changes the user profile without any fanfare. It'll
* beep the speaker on error.
*
* Note that since you probably do NOT have a file named 'os2new.ini' on
* your system, running this code will wipe out your desktop. Don't panic.
* It doesn't affect your original files at all, so a simple reboot will
* bring your desktop back. This is because when the WorkPlace Shell gets
* the PL_ALTERED window message, it tries to get the new desktop and
* backgrounds from the file you specified...which, in this case, has
* nothing to offer. Specifying your current user profile (usually found in
* C:\os2\os2.ini), will make your desktop appear to do nothing more than
* redraw.
*/
#define INCL_WIN
#define INCL_DOS
#include <os2.h>
#include <stdlib.h>
int main(void)
{
HAB hab;
PRFPROFILE prfproProf;
UCHAR ucUserProfile[] = "OS2NEW.INI";
hab = WinInitialize(0);
prfproProf.cchUserName = prfproProf.cchSysName = 0;
if (PrfQueryProfile(hab, &prfproProf) == FALSE)
{
DosBeep(300, 500);
return(1);
} /* if */
prfproProf.cchUserName = 0; /* set to zero for 2nd call. */
prfproProf.pszSysName = malloc(prfproProf.cchSysName);
if (prfproProf.pszSysName == NULL)
{
DosBeep(300, 500);
return(1);
} /* if */
/* call 2nd time, with fields initialized. */
if (PrfQueryProfile(hab, &prfproProf) == FALSE)
{
DosBeep(300, 500);
return(1);
} /* if */
/* set up user fields. */
prfproProf.cchUserName = sizeof (ucUserProfile);
prfproProf.pszUserName = ucUserProfile;
if (PrfReset(hab, &prfproProf) == FALSE)
{
DosBeep(300, 500);
return(1);
} /* if */
free(prfproProf.pszSysName);
return(0);
} /* main */
]]>
See Also
WinInitialize,
PrfQueryProfile
Author
Ryan C. Gordon -
warped42@ix.netcom.com
Additions
Last modified September 21/1996
Please send all errors, comments, and suggestions to:
timur@vnet.ibm.com
The OS/2 API Project |
PrfReset |