PrfQueryProfileData

This function is used to obtain a binary data string from the requested profile file.

Syntax

PrfQueryProfileData( HINI hini, PSZ pszAppName, PSZ pszKeyWord, PVOID pBuffer, PULONG pulBufSize )

Parameters

hini (HINI) - input

Handle to profile to be searched for data. This may be one of the following:

HINI_PROFILE - Search both the USER and SYSTEM profiles

HINI_USERPROFILE - Search only the USER profile

HINI_SYSTEMPROFILE - Search only the SYSTEM profile

a variable - Search a program-defined profile. This is a HINI returned by PrfOpenProfile()

pszAppName (PSZ) - input

Pointer to a null-terminated string that holds the application name to search for within the profile. This parameter may be:

NULL - Specifying NULL for this parameter will return, in pBuffer, a list of all application names in the specified profile. Each name will be null-terminated, and the final name will have two null characters appended to it. If NULL is specified, then pulBufSize will not count the final null character in the return value, and pszKeyWord is ignored.

a variable - This is a specific case-dependent application name to search for

pszKeyWord (PSZ) - input

Pointer to a null-terminated string that holds the keyword name to search for within the application name specified. This parameter may be:

NULL - Specifying NULL for this parameter will return, in pBuffer, a list of all keywords associated with the specified profile. Each name will be null-terminated, and the final name will have two null characters appended to it. If NULL is specified, then pulBufSize will not count the final null character in the return value

a variable - This is a specific case-dependent application name to search for

pBuffer (PVOID) - output

Pointer to buffer that PrfQueryProfileData() will fill with return data.

pulBufSize (PULONG) - input/output

Pointer to a unsigned long that holds, upon calling, the size of pBuffer in bytes. If successful, PrfQueryProfileData() will put in pulBufSize the total size, in bytes, that was written to pBuffer.

Returns

bRC (BOOL) - return

This return value is always either:

TRUE

success

FALSE

Error occurred

If FALSE, you may use WinGetLastError() to find out what went wrong. Possible errors PrfQueryProfileData() may incur:

PMERR_INVALID_PARM         0x1303  One of the parameters to PrfQueryProfileData() was invalid
PMERR_NOT_IN_IDX           0x1304  The application name, keyword, program handle was not found
PMERR_CAN_NOT_CALL_SPOOLER 0x130D  An error related to the spooler occurred. (?)

Include Info

#define INCL_WINSHELLDATA

or

#define INCL_WIN

or

#define INCL_PM
#include <os2.h>

Usage Explanation

This function is handy for retrieving previously stored data about a program. If this API call returns FALSE, it will not touch pBuffer. Therefore, you may initialize a structure to a default configuration, call PrfQueryProfileData() and not concern yourself with whether the Appname/Keyword pair exists, as you will have a valid structure whether you've run the program before or not. See the example code for a clearer explanation of this. Even though you need to #define INCL_WIN (or one of the others) to use this API, it may be used in non-Presentation Manager programs.

Gotchas

Both the application name and the keyword is CASE SENSITIVE. It is recommended that all your references to these strings come from a single source, such as a #define or a global variable, so as not to get tripped up on this. The returned data will be truncated to fit your buffer if it is larger than pulBufSize bytes. If you aren't sure how much space the data is going to consume, call PrfQueryProfileSize(), then allocate space for the data before calling PrfQueryProfileData(). If you specify NULL for either the application name or the keyword, and your buffer isn't large enough, the truncated data will not end with two null characters.

Sample Code

#define INCL_WINSHELLDATA
#include <os2.h>
#include <stdio.h>

static UCHAR szAppName[] = "MyProg";   /* Appname/Keyword declared global. */
static UCHAR szKeyWord[] = "SETTINGS";

struct progdata {
   UCHAR data1[10];
   UINT data2;
}; /* struct progdata */

int main(void) {
   struct progdata prg;
   ULONG siz = sizeof (prg);

   /* Initialized to default data (in case appname/keyword don't exist.) */
   strcpy(prg.data1, "Default");
   prg.data2 = 0;

   if (PrfQueryProfileData(HINI_PROFILE, szAppName, szKeyWord, &prg, &siz))
       printf("PrfQueryProfileData returned TRUE.\n");
   else
       printf("PrfQueryProfileData returned FALSE. Defaults used.\n");

   printf("prg.data1 == %s\n", prg.data1);
   printf("prg.data2 == %d\n", prg.data2);

   return(0);
} /* main */

See Also

• PrfOpenProfile
• PrfQueryProfileSize
• PrfWriteProfileData