[ Home | Alpha index | Topic index | Tutorials | Download | Feedback ]

The OS/2 API Project

PrfQueryProfile

[ Syntax | Params | Returns | Include | Usage | Structs | Gotchas | Code | Also ]

Syntax

 bRC = PrfQueryProfile( hab, pprfproProfile );

Parameters
HAB hab (input)
Handle to an Anchor Block returned by WinInitialize().

PPRFPROFILE pprfproProfile (input/output)
Pointer to a PRFPROFILE structure. See 'Relevant structures' for more details.

Returns
BOOL bRC
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.

Relevant Structures
PRFPROFILE
ULONG cchUserName;
On input, this field should be the number of allocated bytes pointed to by pszUserName. If 0, pszUserName isn't touched. On output, this field is set to the number of bytes needed to fit the entire user profile name, regardless of how much was written to pszUserName.
PSZ pszUserName;
On input, this field should point to allocated memory (if cchUserName is not zero) to hold the profile name. On output, the buffer pointed to by this field is written to.
ULONG cchSysName;
On input, this field should be the number of allocated bytes pointed to by pszSysName. If 0, pszSysName isn't touched. On output, this field is set to the number of bytes needed to fit the entire system profile name, regardless of how much was written to pszSysName.
PSZ pszSysName;
On input, this field should point to allocated memory (if cchSysName is not zero) to hold the profile name. On output, the buffer pointed to by this field is written to.
PPRFPROFILE
A pointer to a PRFPROFILE structure. Same as (PRFPROFILE *).

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 */

See Also

 PrfReset

Author

Ryan C. Gordon - warped42@ix.netcom.com

Additions

Last modified April 29/1996
Please send all errors, comments, and suggestions to: timur@vnet.ibm.com

The OS/2 API Project

PrfQueryProfile