PrfQueryProfile: Difference between revisions

Revision as of 14:18, 12 October 2018

Syntax

PrfQueryProfile ( hab, pprfproProfile )

Parameters

HAB hab (input): Handle to an Anchor Block returned by WinInitialize().
PPRFPROFILE pprfproProfile (input/output): Pointer to a PRFPROFILE structure.

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.

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

@@ Line 4: / Line 4: @@
 ===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.
+;PPRFPROFILE pprfproProfile (input/output): Pointer to a [[PRFPROFILE]] structure.
 ===Returns===
 ;BOOL bRC
 : This return value is always either:
-{| border="1"
+::TRUE Success
-|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.
-|-
-|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===
@@ Line 23: / Line 20: @@
   #include
-===Usage Explanation===
+==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===
+==Sample Code==
 <code>
   /*
@@ Line 84: / Line 68: @@
 </code>
-===See Also===
+==See Also==
 *[[PrfReset]]
 [[Category:Prf]]