PrfQueryProfile
Gets the names of the current OS2SYS.INI and OS2.INI files.
Contents
Syntax
PrfQueryProfile ( HAB hab, PPRFPROFILE pprfproProfile )
Parameters
- hab (HAB) - input
- Handle to an Anchor Block returned by WinInitialize().
- pprfproProfile (PPRFPROFILE) - input/output
- Pointer to a PRFPROFILE structure.
Returns
- bRC (BOOL) - return
- This return value is always either:
- TRUE
- Success
- FALSE
- Error occurred. Some internal failure, or there was not enough space for the record names. This will cause the names to be truncated.
Include Info
#define INCL_WINSHELLDATA
or
#define INCL_WIN
or
#define INCL_PM #include
Usage Explanation
This function merely gives you the filenames of the current user and system profiles. If either ULONG field of the PRFPROFILE structure is zero, then rather than write to a buffer, PrfQueryProfile() will return in that ULONG the number of bytes required to hold the name. This will allow you to allocate memory for a second call. If those ULONGs are greater than zero, PrfQueryProfile() expects that there is sufficient memory allocated in the PSZ fields to store the file names. If there isn't, the names will be truncated to fit.
Gotchas
The biggest "gotcha" applying to this API call is memory management. You should ALWAYS call this function twice; first, with pprfproProfile->cchUserName and pprfproProfile->cchSysName equal to zero. then allocate enough memory based on their returns, and finally call PrfQueryProfile() again with the newly allocated buffers.
Sample Code
/* * This function assumes the existence of these two functions: * WhineAboutErrors(), which notifies the user of a problem and then * terminates the application, and RestOfProgram(), which will run * after our calls to PrfQueryProfile()... */ #define INCL_WIN #include <os2.h> #include <stdlib.h> int main(void) { HAB hab; PRFPROFILE prfproProf; hab = WinInitialize(0); /* Initialize to zero, so we can get the buffer size needed. */ prfproProf.cchUserName = prfproProf.cchSysName = 0; if (PrfQueryProfile(hab, &prfproProf) == FALSE) WhineAboutErrors("PrfQueryProfile failed."); prfproProf.pszUserName = malloc(prfproProf.cchUserName); prfproProf.pszSysName = malloc(prfproProf.cchSysName); if ((prfproProf.pszUserName == NULL) || (prfproProf.pszSysName == NULL)) WhineAboutErrors("Memory Allocation Error."); /* call 2nd time, with fields initialized. */ if (PrfQueryProfile(hab, &prfproProf) == FALSE) WhineAboutErrors("PrfQueryProfile failed."); RestOfProgram(); return(0); } /* main */